1 

     2 

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

     4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

     5 

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

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

     8 

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

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

    11 

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

    13 

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

    15   user

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

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

    18 

    19 But also:

    20 

    21 :Session data handling:

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

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

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

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

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

    27 

    28 

    29 :Cookies handling:

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

    31     HTTP 'Cookie'

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

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

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

    35     window)

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

    37 

    38 :URL handling:

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

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

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

    42 

    43 :And more...:

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

    45     'Content-Type'

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

    47     of the HTTP request

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

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

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

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

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

    53     *while a request is executed*

    54 

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

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

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

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

    59 to the client.