magpie.api.management.service.service_formats
=============================================

.. py:module:: magpie.api.management.service.service_formats


Functions
---------

.. autoapisummary::

   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:: 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 <Allowed Permission>` 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 <Allowed Permission>` for the corresponding
       :term:`Resources <Resource>` 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