magpie.api.management.user.user_formats ======================================= .. py:module:: magpie.api.management.user.user_formats Classes ------- .. autoapisummary:: magpie.api.management.user.user_formats.UserGroupStatus magpie.api.management.user.user_formats.UserStatuses Functions --------- .. autoapisummary:: magpie.api.management.user.user_formats.evaluate_call magpie.api.management.user.user_formats.get_constant magpie.api.management.user.user_formats.format_user Module Contents --------------- .. py:function:: evaluate_call(call: Callable[[], Any], fallback: Optional[Callable[[], None]] = None, http_error: Type[pyramid.httpexceptions.HTTPError] = HTTPInternalServerError, http_kwargs: Optional[magpie.typedefs.ParamsType] = None, msg_on_fail: magpie.typedefs.Str = '', content: Optional[magpie.typedefs.JSON] = None, content_type: magpie.typedefs.Str = CONTENT_TYPE_JSON, metadata: Optional[magpie.typedefs.JSON] = None) -> Any Evaluates the specified :paramref:`call` with a wrapped HTTP exception handling. On failure, tries to call. :paramref:`fallback` if specified, and finally raises the specified :paramref:`http_error`. Any potential error generated by :paramref:`fallback` or :paramref:`http_error` themselves are treated as :class:`HTTPInternalServerError`. Exceptions are generated using the standard output method formatted based on specified :paramref:`content_type`. Example: normal call:: try: res = func(args) except Exception as exc: fb_func() raise HTTPExcept(exc.message) wrapped call:: res = evaluate_call(lambda: func(args), fallback=lambda: fb_func(), http_error=HTTPExcept, **kwargs) :param call: function to call, *MUST* be specified as `lambda: ` :param fallback: function to call (if any) when `call` failed, *MUST* be `lambda: ` :param http_error: alternative exception to raise on `call` failure :param http_kwargs: additional keyword arguments to pass to `http_error` if called in case of HTTP exception :param msg_on_fail: message details to return in HTTP exception if `call` failed :param content: json formatted additional content to provide in case of exception :param content_type: format in which to return the exception (one of `magpie.common.SUPPORTED_ACCEPT_TYPES`) :param metadata: request metadata to add to the response body. (see: :func:`magpie.api.requests.get_request_info`) :raises http_error: on `call` failure :raises `HTTPInternalServerError`: on `fallback` failure :return: whichever return value `call` might have if no exception occurred .. py:function:: get_constant(constant_name: magpie.typedefs.Str, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None, settings_name: Optional[magpie.typedefs.Str] = None, default_value: Optional[magpie.typedefs.SettingValue] = None, raise_not_set: bool = True, raise_missing: bool = True, print_missing: bool = False, empty_missing: bool = False) -> magpie.typedefs.SettingValue Search in order for matched value of :paramref:`constant_name`: 1. search in :py:data:`MAGPIE_CONSTANTS` 2. search in settings if specified 3. search alternative setting names (see below) 4. search in :mod:`magpie.constants` definitions 5. search in environment variables Parameter :paramref:`constant_name` is expected to have the format ``MAGPIE_[VARIABLE_NAME]`` although any value can be passed to retrieve generic settings from all above-mentioned search locations. If :paramref:`settings_name` is provided as alternative name, it is used as is to search for results if :paramref:`constant_name` was not found. Otherwise, ``magpie.[variable_name]`` is used for additional search when the format ``MAGPIE_[VARIABLE_NAME]`` was used for :paramref:`constant_name` (i.e.: ``MAGPIE_ADMIN_USER`` will also search for ``magpie.admin_user`` and so on for corresponding constants). :param constant_name: key to search for a value :param settings_container: WSGI application settings container (if not provided, uses found one in current thread) :param settings_name: alternative name for `settings` if specified :param default_value: default value to be returned if not found anywhere, and exception raises are disabled. :param raise_not_set: raise an exception if the found key is ``None``, search until last case if others are ``None`` :param raise_missing: raise exception if key is not found anywhere :param print_missing: print message if key is not found anywhere, return ``None`` :param empty_missing: consider an empty value for an existing key as if it was missing (i.e.: as if not set). :returns: found value or `default_value` :raises ValueError: if resulting value is invalid based on options (by default raise missing/empty/``None`` value) :raises LookupError: if no appropriate value could be found from all search locations (according to options) .. py:class:: UserGroupStatus Bases: :py:obj:`magpie.utils.FlexibleNameEnum` Supported statuses of user-group relationships. .. py:attribute:: ALL :value: 'all' .. py:attribute:: ACTIVE :value: 'active' .. py:attribute:: PENDING :value: 'pending' .. py:method:: allowed() -> List[magpie.typedefs.Str] :classmethod: Returns all supported representation values that can be mapped to a valid status. .. py:class:: UserStatuses Bases: :py:obj:`enum.IntFlag`, :py:obj:`magpie.utils.FlexibleNameEnum` Values applicable to :term:`User` statues. Provides allowed values for the ``status`` search query of :class:`User` and :class:`UserPending` entries. Also, defines the possible values of :attr:`User.status` field, omitting :attr:`UserStatuses.Pending` reserved for objects defined by :class:`UserPending`. Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: OK :value: 1 .. py:attribute:: WebhookError :value: 2 .. py:attribute:: Pending :value: 4 .. py:method:: _get_one(status: AnyUserStatus) -> Optional[UserStatuses] :classmethod: .. py:method:: get(status: Union[None, int, magpie.typedefs.Str, UserStatuses, Iterable[None, int, magpie.typedefs.Str, UserStatuses]], default: Optional[UserStatuses] = None) -> Optional[UserStatuses] :classmethod: Obtains the combined flag :class:`UserStatuses` .. py:method:: allowed() -> List[Union[None, int, magpie.typedefs.Str]] :classmethod: Returns all supported representation values that can be mapped to a valid status for :class:`UserSearchService`. .. py:method:: all() -> UserStatuses :classmethod: Representation of all flags combined. .. py:method:: __or__(other: Union[UserStatuses, int]) -> UserStatuses Return self|value. .. py:method:: __and__(other: Union[UserStatuses, int]) -> UserStatuses Return self&value. .. py:method:: __xor__(other: Union[UserStatuses, int]) -> UserStatuses Return self^value. .. py:method:: __iter__() -> Iterable[UserStatuses] .. py:method:: __len__() .. py:function:: format_user(user: magpie.models.AnyUser, group_names: List[magpie.typedefs.Str] = None, basic_info: bool = False, dotted: bool = False) -> magpie.typedefs.JSON Formats a :term:`User` information into JSON. :param user: :term:`User` to be formatted. :param group_names: Override of group name listing to provide as user memberships. Retrieve the complete group membership listing from the :paramref:`user` if not provided. :param basic_info: If ``True``, return only sufficient details to identify the :term:`User`, without any additional group details. :param dotted: Employ a dot (``.``) instead of underscore (``_``) to separate :term:`User` from its basic information. .. seealso:: :func:`magpie.api.management.group.group_formats.format_group`