core.decorators
===============

.. py:module:: core.decorators


Functions
---------

.. autoapisummary::

   core.decorators.exposed
   core.decorators.internal_exposed
   core.decorators.force_ssl
   core.decorators.force_post
   core.decorators.access
   core.decorators.skey
   core.decorators.cors


Module Contents
---------------

.. py:function:: exposed(func)

   Decorator, which marks a function as exposed.

   Only exposed functions are callable by http-requests.
   Can optionally receive a dict of language->translated name to make that function
   available under different names


.. py:function:: internal_exposed(func)

   Decorator, which marks a function as internal exposed.


.. py:function:: force_ssl(func)

   Decorator, which enforces usage of an encrypted channel for a given resource.
   Has no effect on development-servers.


.. py:function:: force_post(func)

   Decorator, which enforces usage of a http post request.


.. py:function:: access(*access, offer_login = False, message = None)

   Decorator, which performs an authentication and authorization check primarily based on the current user's access,
   which is defined via the `UserSkel.access`-bone. Additionally, a callable for individual access checking can be
   provided.

   In case no user is logged in, the decorator enforces to raise an HTTP error 401 - Unauthorized in case no user is
   logged in, otherwise it returns an HTTP error 403 - Forbidden when the specified access parameters prohibit to call
   the decorated method.

   :params access: Access configuration, either names of access rights or a callable for verification.
   :params offer_login: Offers a way to login; Either set it to True, to automatically redirect to /user/login,
       or set it to any other URL.
   :params message: A custom message to be printed when access is denied or unauthorized.

   To check on authenticated users with the access "root" or ("admin" and "file-edit") or "maintainer" use the
   decorator like this:

   .. code-block:: python
       from viur.core.decorators import access
       @access("root", ["admin", "file-edit"], ["maintainer"])
       def my_method(self):
           return "You're allowed!"

   Furthermore, instead of a list/tuple/set/str, a callable can be provided which performs custom access checking,
   and directly is checked on True for access grant.


.. py:function:: skey(func = None, *, allow_empty = False, forward_payload = None, message = None, name = 'skey', validate = None, **extra_kwargs)

   Decorator, which configures an exposed method for requiring a CSRF-security-key.
   The decorator enforces a raise of HTTP error 406 - Precondition failed in case the security-key is not provided
   or became invalid.

   :param allow_empty: Allows to call the method without a security-key when no other parameters where provided.
       This can also be a tuple or list of keys which are being ignored, or a callable taking args and kwargs, and
       programmatically decide whether security-key is required or not.
   :param forward_payload: Forwards the extracted payload of the security-key to the method under the key specified
       here as a value in kwargs.
   :param message: Allows to specify a custom error message in case a HTTP 406 is raised.
   :param name: Defaults to "skey", but allows also for another name passed to the method.
   :param validate: Allows to specify a Callable used to further evaluate the payload of the security-key.
       Security-keys can be equipped with further data, see the securitykey-module for details.
   :param extra_kwargs: Any provided extra_kwargs are being passed to securitykey.validate as kwargs.


.. py:function:: cors(allow_headers = ())

   Add additional CORS setting for a decorated :meth:`exposed` method.