Web Controllers

Controllers

Controllers need to provide extensibility, much like Model, but can’t use the same mechanism as the pre-requisites (a database with loaded modules) may not be available yet (e.g. no database created, or no database selected).

Controllers thus provide their own extension mechanism, separate from that of models:

Controllers are created by inheriting from Controller. Routes are defined through methods decorated with route():

class MyController(odoo.http.Controller):
    @route('/some_url', auth='public')
    def handler(self):
        return stuff()

To override a controller, inherit from its class and override relevant methods, re-exposing them if necessary:

class Extension(MyController):
    @route()
    def handler(self):
        do_before()
        return super(Extension, self).handler()

• decorating with route() is necessary to keep the method (and route) visible: if the method is redefined without decorating, it will be “unpublished”

• the decorators of all methods are combined, if the overriding method’s decorator has no argument all previous ones will be kept, any provided argument will override previously defined ones e.g.:

  class Restrict(MyController):
      @route(auth='user')
      def handler(self):
          return super(Restrict, self).handler()
  

  will change /some_url from public authentication to user (requiring a log-in)

API

Routing

@odoo.http.route(route=None, **routing)

Decorate a controller method in order to route incoming requests matching the given URL and options to the decorated method.

Warning

It is mandatory to re-decorate any method that is overridden in controller extensions but the arguments can be omitted. See Controller for more details.

Parameters

• route (Union[str, Iterable[str]]) – The paths that the decorated method is serving. Incoming HTTP request paths matching this route will be routed to this decorated method. See werkzeug routing documentation for the format of route expressions.

• type (str) – The type of request, either 'jsonrpc' or 'http'. It describes where to find the request parameters and how to serialize the response.

• auth (str) –

  The authentication method, one of the following:

  • 'user': The user must be authenticated and the current request will be executed using the rights of the user.

  • 'bearer': The user is authenticated using an “Authorization” request header, using the Bearer scheme with an API token. The request will be executed with the permissions of the corresponding user. If the header is missing, the request must belong to an authentication session, as for the “user” authentication method.

  • 'public': The user may or may not be authenticated. If he isn’t, the current request will be executed using the shared Public user.

  • 'none': The method is always active, even if there is no database. Mainly used by the framework and authentication modules. The request code will not have any facilities to access the current user.

• methods (Iterable[str]) – A list of http methods (verbs) this route applies to. If not specified, all methods are allowed.

• cors (str) – The Access-Control-Allow-Origin cors directive value.

• csrf (bool) – Whether CSRF protection should be enabled for the route. Enabled by default for 'http'-type requests, disabled by default for 'jsonrpc'-type requests.

• readonly (Union[bool, Callable[[registry, request], bool]]) – Whether this endpoint should open a cursor on a read-only replica instead of (by default) the primary read/write database.

• handle_params_access_error (Callable[[Exception], Response]) – Implement a custom behavior if an error occurred when retrieving the record from the URL parameters (access error or missing error).

• captcha (str) – The action name of the captcha. When set the request will be validated against a captcha implementation. Upon failing these requests will return a UserError.

• save_session (bool) – Whether it should set a session_id cookie on the http response and save dirty session on disk. False by default for auth='bearer'. True by default otherwise.

Request

The request object is automatically set on odoo.http.request at the start of the request.

class odoo.http.requestlib.Request(httprequest)

Wrapper around the incoming HTTP request with deserialized request parameters, session utilities and request dispatching logic.

update_env(user=None, context=None, su=None)

Update the environment of the current request.

Parameters

• user (int or res.users record) – optional user/user id to change the current user

• context (dict) – optional context dictionary to change the current context

• su (bool) – optional boolean to change the superuser mode

update_context(**overrides)

Override the environment context of the current request with the values of overrides. To replace the entire context, please use update_env() instead.

csrf_token(time_limit=None)

Generates and returns a CSRF token for the current session

Parameters

time_limit (Optional[int]) – the CSRF token should only be valid for the specified duration (in second), by default 48h, None for the token to be valid as long as the current user’s session is.

Returns

ASCII token string

Return type

str

validate_csrf(csrf)

Is the given csrf token valid ?

Parameters

csrf (str) – The token to validate.

Returns

True when valid, False when not.

Return type

bool

default_lang()

Returns default user language according to request specification

Returns

Preferred language if specified or ‘en_US’

Return type

str

get_http_params()

Extract key=value pairs from the query string and the forms present in the body (both application/x-www-form-urlencoded and multipart/form-data).

Returns

The merged key-value pairs.

Return type

dict

make_response(data, headers=None, cookies=None, status=200)

Helper for non-HTML responses, or HTML responses with custom response headers or cookies.

While handlers can just return the HTML markup of a page they want to send as a string if non-HTML data is returned they need to create a complete response object, or the returned data will not be correctly interpreted by the clients.

Parameters

• data (str) – response body

• status (int) – http status code

• headers ([(name, value)]) – HTTP headers to set on the response

• cookies (collections.abc.Mapping) – cookies to set on the client

Returns

a response object.

Return type

Response

make_json_response(data, headers=None, cookies=None, status=200)

Helper for JSON responses, it json-serializes data and sets the Content-Type header accordingly if none is provided.

Parameters

• data – the data that will be json-serialized into the response body

• status (int) – http status code

• headers (List[(str, str)]) – HTTP headers to set on the response

• cookies (collections.abc.Mapping) – cookies to set on the client

Return type

Response

not_found(description=None)

Shortcut for a HTTP 404 (Not Found) response

render(template, qcontext=None, lazy=True, **kw)

Lazy render of a QWeb template.

The actual rendering of the given template will occur at then end of the dispatching. Meanwhile, the template and/or qcontext can be altered or even replaced by a static response.

Parameters

• template (str) – template to render

• qcontext (dict) – Rendering context to use

• lazy (bool) – whether the template rendering should be deferred until the last possible moment

• kw (dict) – forwarded to werkzeug’s Response object

reroute(path, query_string=None)

Rewrite the current request URL using the new path and query string. This act as a light redirection, it does not return a 3xx responses to the browser but still change the current URL.

class odoo.http.dispatcher.JsonRPCDispatcher(request)

classmethod is_compatible_with(request)

Determine if the current request is compatible with this dispatcher.

dispatch(endpoint, args)

JSON-RPC 2 over HTTP.

Our implementation differs from the specification on two points:

1. The method member of the JSON-RPC request payload is ignored as the HTTP path is already used to route the request to the controller.

2. We only support parameter structures by-name, i.e. the params member of the JSON-RPC request payload MUST be a JSON Object and not a JSON Array.

In addition, it is possible to pass a context that replaces the session context via a special context argument that is removed prior to calling the endpoint.

Successful request:

--> {"jsonrpc": "2.0", "method": "call", "params": {"arg1": "val1" }, "id": null}

<-- {"jsonrpc": "2.0", "result": { "res1": "val1" }, "id": null}

Request producing a error:

--> {"jsonrpc": "2.0", "method": "call", "params": {"arg1": "val1" }, "id": null}

<-- {"jsonrpc": "2.0", "error": {"code": 1, "message": "End user error message.", "data": {"code": "codestring", "debug": "traceback" } }, "id": null}

handle_error(exc)

Handle any exception that occurred while dispatching a request to a type='jsonrpc' route. Also handle exceptions that occurred when no route matched the request path, that no fallback page could be delivered and that the request Content-Type was json.

Parameters

exc – the exception that occurred.

Returns

a WSGI application

class odoo.http.dispatcher.HttpDispatcher(request)

classmethod is_compatible_with(request)

Determine if the current request is compatible with this dispatcher.

dispatch(endpoint, args)

Perform http-related actions such as deserializing the request body and query-string and checking cors/csrf while dispatching a request to a type='http' route.

See load() method for the compatible endpoint return types.

handle_error(exc)

Handle any exception that occurred while dispatching a request to a type='http' route. Also handle exceptions that occurred when no route matched the request path, when no fallback page could be delivered and that the request Content-Type was not json.

Parameters

exc (Exception) – the exception that occurred.

Returns

a WSGI application

Response

class odoo.http.Response(*args, **kwargs)

Outgoing HTTP response with body, status, headers and qweb support. In addition to the werkzeug.wrappers.Response parameters, this class’s constructor can take the following additional parameters for QWeb Lazy Rendering.

Parameters

• template (str) – template to render

• qcontext (dict) – Rendering context to use

• uid (int) – User id to use for the ir.ui.view render call, None to use the request’s user (the default)

these attributes are available as parameters on the Response object and can be altered at any time before rendering

Also exposes all the attributes and methods of werkzeug.wrappers.Response.

classmethod load(fname='<function>')

Convert the return value of an endpoint into a Response.

Parameters

• result (Union[Response, werkzeug.wrappers.BaseResponse, werkzeug.exceptions.HTTPException, str, bytes, NoneType]) – The endpoint return value to load the Response from.

• fname (str) – The endpoint function name wherefrom the result emanated, used for logging.

Returns

The created Response.

Return type

Response

Raises

TypeError – When result type is none of the above- mentioned type.

render()

Renders the Response’s template, returns the result.

flatten()

Forces the rendering of the response’s template, sets the result as response body and unsets template

set_cookie(key, value='', max_age=None, expires=- 1, path='/', domain=None, secure=False, httponly=False, samesite=None, cookie_type='required')

The default expires in Werkzeug is None, which means a session cookie. We want to continue to support the session cookie, but not by default. Now the default is arbitrary 1 year. So if you want a cookie of session, you have to explicitly pass expires=None.

add_etag(overwrite: bool = False, weak: bool = False) → None

Add an etag for the current response if there is none yet.

Changed in version 2.0: SHA-1 is used to generate the value. MD5 may not be available in some environments.

call_on_close(func: Callable[[], Any]) → Callable[[], Any]

Adds a function to the internal list of functions that should be called as part of closing down the response. Since 0.7 this function also returns the function that was passed so that this can be used as a decorator.

New in version 0.6.

delete_cookie(key: str, path: str | None = '/', domain: str | None = None, secure: bool = False, httponly: bool = False, samesite: str | None = None) → None

Delete a cookie. Fails silently if key doesn’t exist.

Parameters

• key – the key (name) of the cookie to be deleted.

• path – if the cookie that should be deleted was limited to a path, the path has to be defined here.

• domain – if the cookie that should be deleted was limited to a domain, that domain has to be defined here.

• secure – If True, the cookie will only be available via HTTPS.

• httponly – Disallow JavaScript access to the cookie.

• samesite – Limit the scope of the cookie to only be attached to requests that are “same-site”.

classmethod force_type(environ: WSGIEnvironment | None = None) → Response

Enforce that the WSGI response is a response object of the current type. Werkzeug will use the Response internally in many situations like the exceptions. If you call get_response() on an exception you will get back a regular Response object, even if you are using a custom subclass.

This method can enforce a given response type, and it will also convert arbitrary WSGI callables into response objects if an environ is provided:

# convert a Werkzeug response object into an instance of the
# MyResponseClass subclass.
response = MyResponseClass.force_type(response)

# convert any WSGI application into a response object
response = MyResponseClass.force_type(response, environ)

This is especially useful if you want to post-process responses in the main dispatcher and use functionality provided by your subclass.

Keep in mind that this will modify response objects in place if possible!

Parameters

• response – a response object or wsgi application.

• environ – a WSGI environment object.

Returns

a response object.

freeze() → None

Make the response object ready to be pickled. Does the following:

• Buffer the response into a list, ignoring implicity_sequence_conversion and direct_passthrough.

• Set the Content-Length header.

• Generate an ETag header if one is not already set.

Changed in version 2.1: Removed the no_etag parameter.

Changed in version 2.0: An ETag header is always added.

Changed in version 0.6: The Content-Length header is set.

get_data(as_text: bool = False) → bytes | str

The string representation of the response body. Whenever you call this property the response iterable is encoded and flattened. This can lead to unwanted behavior if you stream big data.

This behavior can be disabled by setting implicit_sequence_conversion to False.

If as_text is set to True the return value will be a decoded string.

New in version 0.9.

get_etag() → tuple[str, bool] | tuple[None, None]

Return a tuple in the form (etag, is_weak). If there is no ETag the return value is (None, None).

get_json(force: bool = False, silent: bool = False) → Any | None

Parse data as JSON. Useful during testing.

If the mimetype does not indicate JSON (application/json, see is_json), this returns None.

Unlike Request.get_json(), the result is not cached.

Parameters

• force – Ignore the mimetype and always try to parse JSON.

• silent – Silence parsing errors and return None instead.

iter_encoded() → Iterator[bytes]

Iter the response encoded with the encoding of the response. If the response object is invoked as WSGI application the return value of this method is used as application iterator unless direct_passthrough was activated.

make_conditional(request_or_environ: WSGIEnvironment | Request, accept_ranges: bool | str = False, complete_length: int | None = None) → Response

Make the response conditional to the request. This method works best if an etag was defined for the response already. The add_etag method can be used to do that. If called without etag just the date header is set.

This does nothing if the request method in the request or environ is anything but GET or HEAD.

For optimal performance when handling range requests, it’s recommended that your response data object implements seekable, seek and tell methods as described by io.IOBase. Objects returned by wrap_file() automatically implement those methods.

It does not remove the body of the response because that’s something the __call__() function does for us automatically.

Returns self so that you can do return resp.make_conditional(req) but modifies the object in-place.

Parameters

• request_or_environ – a request object or WSGI environment to be used to make the response conditional against.

• accept_ranges – This parameter dictates the value of Accept-Ranges header. If False (default), the header is not set. If True, it will be set to "bytes". If it’s a string, it will use this value.

• complete_length – Will be used only in valid Range Requests. It will set Content-Range complete length value and compute Content-Length real value. This parameter is mandatory for successful Range Requests completion.

Raises

RequestedRangeNotSatisfiable if Range header could not be parsed or satisfied.

Changed in version 2.0: Range processing is skipped if length is 0 instead of raising a 416 Range Not Satisfiable error.

make_sequence() → None

Converts the response iterator in a list. By default this happens automatically if required. If implicit_sequence_conversion is disabled, this method is not automatically called and some properties might raise exceptions. This also encodes all the items.

New in version 0.6.

set_data(value: bytes | str) → None

Sets a new string as response. The value must be a string or bytes. If a string is set it’s encoded to the charset of the response (utf-8 by default).

New in version 0.9.

set_etag(etag: str, weak: bool = False) → None

Set the etag, and override the old one if there was one.