magpie.api.requests =================== .. py:module:: magpie.api.requests Attributes ---------- .. autoapisummary:: magpie.api.requests.LOGGER Functions --------- .. autoapisummary:: magpie.api.requests.check_value magpie.api.requests.get_request_method_content magpie.api.requests.get_multiformat_body magpie.api.requests.get_permission_multiformat_body_checked magpie.api.requests.get_value_multiformat_body_checked magpie.api.requests.get_principals magpie.api.requests.has_admin_access magpie.api.requests.get_logged_user magpie.api.requests.get_user magpie.api.requests.get_user_matchdict_checked_or_logged magpie.api.requests.get_user_matchdict_checked magpie.api.requests.get_group_matchdict_checked magpie.api.requests.get_resource_matchdict_checked magpie.api.requests.get_service_matchdict_checked magpie.api.requests.get_permission_matchdict_checked magpie.api.requests.get_value_matchdict_checked magpie.api.requests.get_query_param magpie.api.requests.check_network_mode_enabled Module Contents --------------- .. py:data:: LOGGER .. py:function:: check_value(value: Any, param_name: magpie.typedefs.Str, check_type: Any = six.string_types, pattern: Optional[Union[magpie.typedefs.Str, bool]] = ax.PARAM_REGEX) -> None Validates the value against specified type and pattern. :param value: value to validate. :param check_type: verify that parameter value is of specified type. Set to ``None`` to disable check. :param pattern: regex pattern to validate the input with. If value evaluates to ``False``, skip this kind of validation (default: :py:data:`ax.PARAM_REGEX`). :param param_name: path variable key. :return: None. :raises HTTPUnprocessableEntity: if the key is not an applicable path variable for this request. .. py:function:: get_request_method_content(request: pyramid.request.Request) -> Dict[magpie.typedefs.Str, Any] Obtain request content from property according to submitted method. Requests with HTTP ``GET`` store content into ``GET`` property, while other methods are in ``POST`` property. .. py:function:: get_multiformat_body(request: pyramid.request.Request, key: magpie.typedefs.Str, default: Optional[Any] = None) -> Any Obtains the value of :paramref:`key` element from the request body according to specified `Content-Type` header. .. seealso:: - :func:`get_multiformat_body_checked` - :func:`get_permission_multiformat_body_checked` - :func:`get_value_multiformat_body_checked` .. py:function:: get_permission_multiformat_body_checked(request: pyramid.request.Request, service_or_resource: magpie.typedefs.ServiceOrResourceType) -> magpie.permissions.PermissionSet Retrieves the permission from the body and validates that it is allowed for the specified `service` or `resource`. Validation combines basic field checks followed by contextual values applicable for the `service` or `resource`. The permission can be provided either by literal string name (explicit or implicit format) or JSON object. .. seealso:: - :func:`get_value_multiformat_body_checked` .. py:function:: get_value_multiformat_body_checked(request: pyramid.request.Request, key: magpie.typedefs.Str, default: Any = None, check_type: Any = six.string_types, pattern: Optional[Union[magpie.typedefs.Str, bool]] = ax.PARAM_REGEX) -> magpie.typedefs.Str Obtains and validates the matched value under :paramref:`key` element from the request body. Parsing of the body is accomplished according to ``Content-Type`` header. :param request: request from which to retrieve the key. :param key: body key variable. :param default: value to return instead if not found. If this default is ``None``, it will raise. :param check_type: verify that parameter value is of specified type. Set to ``None`` to disable check. :param pattern: regex pattern to validate the input with. If value evaluates to ``False``, skip this kind of validation (default: :py:data:`magpie.api.exception.PARAM_REGEX`). :return: matched path variable value. :raises HTTPBadRequest: if the key could not be retrieved from the request body and has no provided default value. :raises HTTPUnprocessableEntity: if the retrieved value from the key is invalid for this request. .. seealso:: - :func:`get_multiformat_body` .. py:function:: get_principals(request: pyramid.request.Request) -> List[magpie.typedefs.AnyAccessPrincipalType] Obtains the list of effective principals according to detected request session user. .. py:function:: has_admin_access(request: pyramid.request.Request) -> bool Verifies if the authenticated user doing the request has administrative access. .. note:: Any request view that does not explicitly override ``permission`` by another value than the default :envvar:`MAGPIE_ADMIN_PERMISSION` will already automatically guarantee that the request user is an administrator since HTTP [403] Forbidden would have been otherwise replied. This method is indented for operations that are more permissive and require conditional validation of administrator access. .. seealso:: Definitions in :class:`magpie.models.RootFactory` and :class:`magpie.models.UserFactory` define conditional principals and :term:`ACL` based on the request. .. py:function:: get_logged_user(request: pyramid.request.Request) -> Optional[magpie.models.User] .. py:function:: get_user(request: pyramid.request.Request, user_name_or_token: Optional[magpie.typedefs.Str] = None, user_status: Optional[magpie.models.UserStatuses] = None) -> magpie.models.AnyUser Obtains the user corresponding to the provided user-name, token or via lookup of the logged user request session. :param request: request from which to obtain application settings and session user as applicable. :param user_name_or_token: reference value to employ for lookup of the user. :param user_status: filter search based on a user status. Ignored if no user name or token is provided. :returns: found user. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified user name or token does not correspond to any existing user. .. py:function:: get_user_matchdict_checked_or_logged(request: pyramid.request.Request, user_name_key: magpie.typedefs.Str = 'user_name', user_status: Optional[magpie.models.UserStatuses] = None) -> magpie.models.AnyUser Obtains either the explicit or logged user specified in the request path variable. :returns found user. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified user name or logged user keyword does not correspond to any existing user. .. py:function:: get_user_matchdict_checked(request: pyramid.request.Request, user_name_key: magpie.typedefs.Str = 'user_name', user_status: Optional[magpie.models.UserStatuses] = None) -> magpie.models.AnyUser Obtains the user matched against the specified request path variable. :returns: found user. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified user name does not correspond to any existing user. .. seealso:: - :func:`get_value_matchdict_checked` - :func:`get_user` .. py:function:: get_group_matchdict_checked(request: pyramid.request.Request, group_name_key: magpie.typedefs.Str = 'group_name') -> magpie.models.Group Obtains the group matched against the specified request path variable. :returns: found group. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified group name does not correspond to any existing group. .. py:function:: get_resource_matchdict_checked(request: pyramid.request.Request, resource_name_key: magpie.typedefs.Str = 'resource_id') -> magpie.models.Resource Obtains the resource matched against the specified request path variable. :returns: found resource. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified resource ID does not correspond to any existing resource. .. py:function:: get_service_matchdict_checked(request: pyramid.request.Request, service_name_key: magpie.typedefs.Str = 'service_name') -> magpie.models.Service Obtains the service matched against the specified request path variable. :returns: found service. :raises HTTPForbidden: if the requesting user does not have sufficient permission to execute this request. :raises HTTPNotFound: if the specified service name does not correspond to any existing service. .. py:function:: get_permission_matchdict_checked(request: pyramid.request.Request, service_or_resource: magpie.models.Resource) -> magpie.permissions.PermissionSet Obtains the permission specified in the request path variable and validates that :paramref:`service_or_resource` allows it. The :paramref:`service_or_resource` can be top-level `service` or a children `resource`. Allowed permissions correspond to the *direct* `service` permissions or restrained permissions of the `resource` under its root `service`. The permission name can be provided either by implicit or explicit string representation. :returns: found permission name if valid for the service/resource .. py:function:: get_value_matchdict_checked(request: pyramid.request.Request, key: magpie.typedefs.Str, check_type: Any = six.string_types, pattern: Optional[Union[magpie.typedefs.Str, bool]] = ax.PARAM_REGEX) -> magpie.typedefs.Str Obtains the matched value located at the expected position of the specified path variable. :param request: request from which to retrieve the key. :param key: path variable key. :param check_type: verify that parameter value is of specified type. Set to ``None`` to disable check. :param pattern: regex pattern to validate the input with. If value evaluates to ``False``, skip this kind of validation (default: :py:data:`ax.PARAM_REGEX`). :return: matched path variable value. :raises HTTPUnprocessableEntity: if the key is not an applicable path variable for this request. .. py:function:: get_query_param(request: pyramid.request.Request, case_insensitive_key: Union[magpie.typedefs.Str, Iterable[magpie.typedefs.Str]], default: Optional[Any] = None) -> Any Retrieves a query string value by name (case insensitive), or returns the default if not present. .. py:function:: check_network_mode_enabled(view_func: collections.abc.Callable) -> collections.abc.Callable Decorator for views that returns a :class:`HTTPNotImplemented` response if network mode is not enabled. This is intended to be used for all views that should only be accessed if network mode is enabled. Instead of decorating a view function directly, pass this function to the ``decorator`` argument of the ``view_config`` decorator. For example: .. code-block:: python @view_config(..., decorator=check_network_mode_enabled) def get_some_view(request): ...