magpie.api.management.resource.resource_formats
===============================================

.. py:module:: magpie.api.management.resource.resource_formats


Functions
---------

.. autoapisummary::

   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:: 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 <Inherited Permission>`)
       actual permissions, or even the :term:`Effective Permissions <Effective Permission>`, according to parent
       caller function's context.
       Otherwise (``None``), defaults to extracting :term:`Allowed Permissions <Allowed Permission>` 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.