magpie.api.management.resource.resource_formats =============================================== .. py:module:: magpie.api.management.resource.resource_formats Attributes ---------- .. autoapisummary:: magpie.api.management.resource.resource_formats.SERVICE_TYPE_DICT Classes ------- .. autoapisummary:: magpie.api.management.resource.resource_formats.PermissionType Functions --------- .. autoapisummary:: magpie.api.management.resource.resource_formats.evaluate_call magpie.api.management.resource.resource_formats.format_permissions magpie.api.management.resource.resource_formats.format_resource magpie.api.management.resource.resource_formats.format_resource_tree magpie.api.management.resource.resource_formats.format_resources_listed magpie.api.management.resource.resource_formats.format_resources_nested 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:class:: PermissionType Bases: :py:obj:`magpie.utils.ExtendedEnum` Applicable types of :term:`Permission` according to context. .. py:attribute:: ACCESS :value: 'access' .. py:attribute:: ALLOWED :value: 'allowed' .. py:attribute:: APPLIED :value: 'applied' .. py:attribute:: DIRECT :value: 'direct' .. py:attribute:: INHERITED :value: 'inherited' .. py:attribute:: EFFECTIVE :value: 'effective' .. py:attribute:: OWNED :value: 'owned' .. py:function:: format_permissions(permissions: Optional[Collection[magpie.typedefs.AnyPermissionType]], permission_type: Optional[PermissionType] = None, force_unique: bool = True) -> Dict[magpie.typedefs.Str, Union[List[magpie.typedefs.Str], magpie.typedefs.PermissionDict, magpie.typedefs.Str]] Obtains the formatted permission representations after validation that each of their name is a known member of :class:`Permission` enum, and optionally with modifiers as defined by :class:`PermissionSet`. The returned lists are sorted alphabetically by permission *name*, and then in order of resolution priority (from highest to lowest) for each subset or corresponding *name*. The permissions are cleaned from any duplicate entries, unless :paramref:`force_unique` is specified to allow it. If no or empty :paramref:`permissions` is provided, empty lists are returned. .. note:: Field ``permission_names`` provides both the *older* implicit permission names and the *newer* explicit name representation. For this reason, there will be semantically "duplicate" permissions in that list, but there will not be any literal string duplicates. Implicit names are immediately followed by their explicit name, unless implicit names do not apply for the given permission (e.g.: when :attr:`Access.DENY` did not exist). Only detailed and explicit JSON representations are provided in the ``permissions`` list. When :paramref:`permission_type` is equal to :attr:`PermissionType.ALLOWED`, the collection of every applicable :class:`PermissionSet` is automatically generated by expanding all combinations of :class:`Access` and :class:`Scope` with every provided :class:`Permission` name in :paramref:`permissions`. This allows more concise definition of allowed permissions under :class:`magpie.services.Services` and their children :term:`Resource` by only defining :class:`Permission` names without manually listing all variations of :class:`PermissionSet`. For other :paramref:`permission_type` values, which represent :term:`Applied Permission` only explicitly provided :paramref:`permissions` are returned, to effectively return the collection of *active* permissions. :param permissions: multiple permissions of any implementation and type, to be rendered both as names and JSON. :param permission_type: indication of the represented permissions to be formatted, for informative indication. :param force_unique: whether to remove duplicate entries by association of name, access and scope or not. :returns: JSON with the permissions listed as implicit+explicit names, as permission set objects, and their type. .. py:data:: SERVICE_TYPE_DICT .. py:function:: format_resource(resource: magpie.models.Resource, permissions: Optional[Collection[magpie.typedefs.AnyPermissionType]] = None, permission_type: Optional[magpie.permissions.PermissionType] = None, basic_info: bool = False, dotted: bool = False) -> magpie.typedefs.JSON Formats a :term:`Resource` information into JSON. :param resource: :term:`Resource` to be formatted. :param permissions: Permissions to list along with the :paramref:`resource`. By default, these are the applicable permissions for that corresponding resource type. :param permission_type: Override indication of provenance to apply to :paramref:`permissions`. Only applicable when they are provided. :param basic_info: If ``True``, return only sufficient details to identify the resource, without any additional :paramref:`permissions` detail, nor hierarchical :paramref:`resource` information is returned. :param dotted: Employ a dot (``.``) instead of underscore (``_``) to separate :term:`Resource` from its basic information. .. seealso:: :func:`magpie.api.management.service.service_formats.format_service` .. py:function:: format_resource_tree(nested_resources: magpie.typedefs.NestedResourceNodes, db_session: sqlalchemy.orm.session.Session, resources_perms_dict: Optional[magpie.typedefs.ResourcePermissionMap] = None, permission_type: Optional[magpie.permissions.PermissionType] = None, nesting_key: magpie.typedefs.NestingKeyType = 'children') -> magpie.typedefs.JSON Generates the formatted resource tree under the provided nested resources. For all of the nested resources, formatting is applied by calling :func:`format_resource` recursively on them. Apply specific resource permissions as defined by :paramref:`resources_perms_dict` if provided. :param nested_resources: Service or resource for which to generate the formatted resource tree. :param db_session: Connection to database. :param resources_perms_dict: Any pre-established :term:`Applied Permission` to set to corresponding resources by ID. When provided, these will define the :term:`User`, :term:`Group` or both (i.e.: :term:`Inherited Permissions `) actual permissions, or even the :term:`Effective Permissions `, according to parent caller function's context. Otherwise (``None``), defaults to extracting :term:`Allowed Permissions ` for the given :term:`Resource` scoped under the corresponding root :term:`Service`. :param permission_type: Override :term:`Permission` type to indicate its provenance. Type is applied recursively for all resources in the generated nested resource tree. :param nesting_key: Key to employ for nesting the formatted sub-tree resources according to the provided nested resources. :return: Formatted nested resource tree with their details and permissions. .. py:function:: format_resources_listed(resources: List[magpie.typedefs.ServiceOrResourceType], db_session: sqlalchemy.orm.session.Session) -> List[magpie.typedefs.JSON] Obtains the formatted :term:`Resource` list with their applicable permissions. .. py:function:: format_resources_nested(resource: magpie.typedefs.ServiceOrResourceType, nested_resources: magpie.typedefs.NestedResourceNodes, nesting_key: magpie.typedefs.NestingKeyType, db_session: sqlalchemy.orm.session.Session) -> magpie.typedefs.JSON Obtains the formatted :term:`Resource` tree with all its formatted children hierarchy.