magpie.api.management.service.service_formats ============================================= .. py:module:: magpie.api.management.service.service_formats Attributes ---------- .. autoapisummary:: magpie.api.management.service.service_formats.SERVICE_TYPE_DICT Classes ------- .. autoapisummary:: magpie.api.management.service.service_formats.PermissionType Functions --------- .. autoapisummary:: magpie.api.management.service.service_formats.evaluate_call magpie.api.management.service.service_formats.format_resource_tree magpie.api.management.service.service_formats.crop_tree_with_permission magpie.api.management.service.service_formats.get_resource_children magpie.api.management.service.service_formats.format_permissions magpie.api.management.service.service_formats.get_twitcher_protected_service_url magpie.api.management.service.service_formats.format_service magpie.api.management.service.service_formats.format_service_resources magpie.api.management.service.service_formats.format_service_resource_type 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:: 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:: crop_tree_with_permission(children: magpie.typedefs.NestedResourceNodes, resource_id_list: List[int]) -> Tuple[magpie.typedefs.NestedResourceNodes, List[int]] Recursively prunes all children resources from the tree hierarchy *except* listed ones matched by ID. Input :paramref:`children` is expected to be a dictionary of resource nodes and children resources with their ID as keys:: { : { "node": , "children": { : { "node": , "children": { <...> } }, <...> }, <...> } :param children: full hierarchy of children resource nodes. :param resource_id_list: resource IDs of nodes to preserve. :return: pruned hierarchy of resource nodes. .. py:function:: get_resource_children(resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session, tree_service_builder: Optional[ziggurat_foundations.models.services.resource_tree.ResourceTreeService] = None, limit_depth: Optional[int] = None) -> magpie.typedefs.NestedResourceNodes Obtains the children resource node structure of the input service or resource. :param resource: Initial resource where to start building the tree from. :param db_session: Database connection to retrieve resources. :param tree_service_builder: Utility that build the tree (default: :py:data:`models.RESOURCE_TREE_SERVICE`). :param limit_depth: Maximum depth to look for children resources (very deep if not specified, could be slow). :returns: ``{node: Resource, children: {node_id: }}`` .. 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:: get_twitcher_protected_service_url(magpie_service_name: magpie.typedefs.Str, container: Optional[magpie.typedefs.AnySettingsContainer] = None, hostname: Optional[magpie.typedefs.Str] = None) -> magpie.typedefs.Str Obtains the protected service URL behind Twitcher Proxy based on combination of supported configuration settings. .. seealso:: Documentation section :ref:`config_twitcher` for available setting combinations. :param magpie_service_name: name of the service to employ in order to form the URL path behind the proxy. :param container: container that provides access to application settings. :param hostname: override literal hostname to generate the URL instead of resolving using settings. :return: resolved Twitcher Proxy protected service URL .. py:function:: format_service(service: magpie.models.Service, permissions: Optional[List[magpie.permissions.PermissionSet]] = None, permission_type: Optional[magpie.permissions.PermissionType] = None, show_private_url: bool = False, show_public_url: bool = True, show_resources_allowed: bool = False, show_configuration: bool = False, basic_info: bool = False, dotted: bool = False) -> magpie.typedefs.JSON Formats a :term:`Service` information into JSON. .. note:: Automatically finds :paramref:`permissions` of the :paramref:`service` if not specified. To preserve `empty` permissions such as during listing of `user`/`group` resource permissions, an empty ``list`` should be specified. :param service: :term:`Service` 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 show_private_url: Display the protected and private URL employed at service registration. :param show_public_url: Display the generated public URL from configured :ref:`config_twitcher`. :param show_resources_allowed: Display children resource details. :param show_configuration: Display the applicable configuration of the :term:`Service` if it supports it. :param basic_info: If ``True``, return only sufficient details to identify the service, without any additional details about :paramref:`permissions`, children resources or configuration information is returned. :param dotted: Employ a dot (``.``) instead of underscore (``_``) to separate :term:`Service` from its basic information. .. seealso:: :func:`magpie.api.management.resource.resource_formats.format_resource` .. py:function:: format_service_resources(service: magpie.models.Service, db_session: sqlalchemy.orm.session.Session, service_perms: Optional[List[magpie.permissions.PermissionSet]] = None, resources_perms_dict: Optional[magpie.typedefs.ResourcePermissionMap] = None, permission_type: Optional[magpie.permissions.PermissionType] = None, show_all_children: bool = False, show_private_url: bool = True) -> magpie.typedefs.JSON Formats the service and its children resource tree as a JSON body. :param service: service for which to display details with sub-resources :param db_session: database session :param service_perms: If provided, sets all :term:`Applied Permission` to display on the formatted :paramref:`service`. Otherwise, sets :term:`Allowed Permissions ` specific to the :paramref:`service`'s type. :param resources_perms_dict: If provided (not ``None``), set the :term:`Applied Permission` on each specified resource matched by ID. If ``None``, retrieve and set :term:`Allowed Permissions ` for the corresponding :term:`Resources ` under the :term:`Service`. To set empty :term:`Applied Permission` (e.g.: :term:`User` doesn't have permissions on that resource), provide an explicit empty dictionary instead. :param permission_type: Provide permission type being rendered. :param show_all_children: Display all children resources recursively, or only ones specified by ID with :paramref:`resources_perms_dict`. :param show_private_url: displays the :return: JSON body representation of the service resource tree .. py:function:: format_service_resource_type(resource_class: Type[magpie.models.Resource], service_class: Type[magpie.services.ServiceInterface]) -> magpie.typedefs.JSON