magpie.api.management.resource.resource_formats

Attributes

SERVICE_TYPE_DICT

Classes

PermissionType

Applicable types of Permission according to context.

Functions

evaluate_call(→ Any)

Evaluates the specified call with a wrapped HTTP exception handling. On failure, tries to call.

format_permissions(→ Dict[magpie.typedefs.Str, ...)

Obtains the formatted permission representations after validation that each of their name is a known member of

format_resource(→ magpie.typedefs.JSON)

Formats a Resource information into JSON.

format_resource_tree(→ magpie.typedefs.JSON)

Generates the formatted resource tree under the provided nested resources.

format_resources_listed(→ List[magpie.typedefs.JSON])

Obtains the formatted Resource list with their applicable permissions.

format_resources_nested(→ magpie.typedefs.JSON)

Obtains the formatted Resource tree with all its formatted children hierarchy.

Module Contents

magpie.api.management.resource.resource_formats.evaluate_call(call: Callable[[], Any], fallback: Callable[[], None] | None = None, http_error: Type[pyramid.httpexceptions.HTTPError] = HTTPInternalServerError, http_kwargs: magpie.typedefs.ParamsType | None = None, msg_on_fail: magpie.typedefs.Str = '', content: magpie.typedefs.JSON | None = None, content_type: magpie.typedefs.Str = CONTENT_TYPE_JSON, metadata: magpie.typedefs.JSON | None = None) → Any[source]

Evaluates the specified call with a wrapped HTTP exception handling. On failure, tries to call.

fallback if specified, and finally raises the specified http_error.

Any potential error generated by fallback or http_error themselves are treated as HTTPInternalServerError.

Exceptions are generated using the standard output method formatted based on specified 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)
Parameters:

  • call – function to call, MUST be specified as lambda: <function_call>

  • fallback – function to call (if any) when call failed, MUST be lambda: <function_call>

  • http_error – alternative exception to raise on call failure

  • http_kwargs – additional keyword arguments to pass to http_error if called in case of HTTP exception

  • msg_on_fail – message details to return in HTTP exception if call failed

  • content – json formatted additional content to provide in case of exception

  • content_type – format in which to return the exception (one of magpie.common.SUPPORTED_ACCEPT_TYPES)

  • metadata – request metadata to add to the response body. (see: magpie.api.requests.get_request_info())

Raises:

  • http_error – on call failure

  • HTTPInternalServerError – on fallback failure

Returns:

whichever return value call might have if no exception occurred

class magpie.api.management.resource.resource_formats.PermissionType[source]

Bases: magpie.utils.ExtendedEnum

Applicable types of Permission according to context.

ACCESS = 'access'
ALLOWED = 'allowed'
APPLIED = 'applied'
DIRECT = 'direct'
INHERITED = 'inherited'
EFFECTIVE = 'effective'
OWNED = 'owned'
magpie.api.management.resource.resource_formats.format_permissions(permissions: Collection[magpie.typedefs.AnyPermissionType] | None, permission_type: PermissionType | None = None, force_unique: bool = True) → Dict[magpie.typedefs.Str, List[magpie.typedefs.Str] | magpie.typedefs.PermissionDict | magpie.typedefs.Str][source]

Obtains the formatted permission representations after validation that each of their name is a known member of Permission enum, and optionally with modifiers as defined by 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 force_unique is specified to allow it. If no or empty 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 Access.DENY did not exist). Only detailed and explicit JSON representations are provided in the permissions list.

When permission_type is equal to PermissionType.ALLOWED, the collection of every applicable PermissionSet is automatically generated by expanding all combinations of Access and Scope with every provided Permission name in permissions. This allows more concise definition of allowed permissions under magpie.services.Services and their children Resource by only defining Permission names without manually listing all variations of PermissionSet.

For other permission_type values, which represent Applied Permission only explicitly provided permissions are returned, to effectively return the collection of active permissions.

Parameters:

  • permissions – multiple permissions of any implementation and type, to be rendered both as names and JSON.

  • permission_type – indication of the represented permissions to be formatted, for informative indication.

  • 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.

magpie.api.management.resource.resource_formats.SERVICE_TYPE_DICT[source]
magpie.api.management.resource.resource_formats.format_resource(resource: magpie.models.Resource, permissions: Collection[magpie.typedefs.AnyPermissionType] | None = None, permission_type: magpie.permissions.PermissionType | None = None, basic_info: bool = False, dotted: bool = False) → magpie.typedefs.JSON[source]

Formats a Resource information into JSON.

Parameters:

  • resource – Resource to be formatted.

  • permissions – Permissions to list along with the resource. By default, these are the applicable permissions for that corresponding resource type.

  • permission_type – Override indication of provenance to apply to permissions. Only applicable when they are provided.

  • basic_info – If True, return only sufficient details to identify the resource, without any additional permissions detail, nor hierarchical resource information is returned.

  • dotted – Employ a dot (.) instead of underscore (_) to separate Resource from its basic information.

See also

magpie.api.management.service.service_formats.format_service()

magpie.api.management.resource.resource_formats.format_resource_tree(nested_resources: magpie.typedefs.NestedResourceNodes, db_session: sqlalchemy.orm.session.Session, resources_perms_dict: magpie.typedefs.ResourcePermissionMap | None = None, permission_type: magpie.permissions.PermissionType | None = None, nesting_key: magpie.typedefs.NestingKeyType = 'children') → magpie.typedefs.JSON[source]

Generates the formatted resource tree under the provided nested resources.

For all of the nested resources, formatting is applied by calling format_resource() recursively on them. Apply specific resource permissions as defined by resources_perms_dict if provided.

Parameters:

  • nested_resources – Service or resource for which to generate the formatted resource tree.

  • db_session – Connection to database.

  • resources_perms_dict – Any pre-established Applied Permission to set to corresponding resources by ID. When provided, these will define the User, Group or both (i.e.: Inherited Permissions) actual permissions, or even the Effective Permissions, according to parent caller function’s context. Otherwise (None), defaults to extracting Allowed Permissions for the given Resource scoped under the corresponding root Service.

  • permission_type – Override Permission type to indicate its provenance. Type is applied recursively for all resources in the generated nested resource tree.

  • nesting_key – Key to employ for nesting the formatted sub-tree resources according to the provided nested resources.

Returns:

Formatted nested resource tree with their details and permissions.

magpie.api.management.resource.resource_formats.format_resources_listed(resources: List[magpie.typedefs.ServiceOrResourceType], db_session: sqlalchemy.orm.session.Session) → List[magpie.typedefs.JSON][source]

Obtains the formatted Resource list with their applicable permissions.

magpie.api.management.resource.resource_formats.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[source]

Obtains the formatted Resource tree with all its formatted children hierarchy.