1 The `Request` class (`cubicweb.web`)

     2 ------------------------------------

     3 

     4 Overview

     5 ````````

     6 

     7 A request instance is created when an HTTP request is sent to the web server.

     8 It contains informations such as form parameters, user authenticated, etc.

     9 

    10 **Globally, a request represents a user query, either through HTTP or not

    11 (we also talk about RQL queries on the server side for example).**

    12 

    13 An instance of `Request` has the following attributes:

    14 

    15 * `user`, instance of `cubicweb.common.utils.User` corresponding to the authenticated

    16   user

    17 * `form`, dictionary containing the values of a web form

    18 * `encoding`, character encoding to use in the response

    19 

    20 But also:

    21 

    22 * `Session data handling`

    23 

    24   * `session_data()`, returns a dictionary containing all the session data

    25   * `get_session_data(key, default=None)`, returns a value associated to the given

    26     key or the value `default` if the key is not defined

    27   * `set_session_data(key, value)`, assign a value to a key

    28   * `del_session_data(key)`,  suppress the value associated to a key

    29 

    30 *  `Cookies handling`

    31 

    32   * `get_cookie()`, returns a dictionary containing the value of the header

    33     HTTP 'Cookie'

    34   * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`,

    35     with a minimal 5 minutes length of duration by default (`maxage` = None

    36     returns a *session* cookie which will expire when the user closes the browser

    37     window)

    38   * `remove_cookie(cookie, key)`, forces a value to expire

    39 

    40 * `URL handling`

    41 

    42   * `url()`, returns the full URL of the HTTP request

    43   * `base_url()`, returns the root URL of the web application

    44   * `relative_path()`, returns the relative path of the request

    45 

    46 * `And more...`

    47 

    48   * `set_content_type(content_type, filename=None)`, adds the header HTTP

    49     'Content-Type'

    50   * `get_header(header)`, returns the value associated to an arbitrary header

    51     of the HTTP request

    52   * `set_header(header, value)`, adds an arbitrary header in the response

    53   * `cursor()` returns a RQL cursor on the session

    54   * `execute(*args, **kwargs)`, shortcut to ``.cursor().execute()``

    55   * `property_value(key)`, properties management (`CWProperty`)

    56   * dictionary `data` to store data to share informations between components

    57     *while a request is executed*

    58 

    59 Please note that this class is abstract and that a concrete implementation

    60 will be provided by the *frontend* web used (in particular *twisted* as of

    61 today). For the views or others that are executed on the server side,

    62 most of the interface of `Request` is defined in the session associated

    63 to the client.

    64 

    65 API

    66 ```

    67 

    68 The elements we gave in overview for above are built in three layers,

    69 from ``cubicweb.req.RequestSessionBase``, ``cubicweb.dbapi.DBAPIRequest`` and

    70 ``cubicweb.web.CubicWebRequestBase``.

    71 

    72 .. autoclass:: cubicweb.req.RequestSessionBase

    73    :members:

    74 

    75 .. autoclass:: cubicweb.dbapi.DBAPIRequest

    76    :members:

    77 

    78 .. autoclass:: cubicweb.web.request.CubicWebRequestBase

    79    :members: