magpie.api.management.group.group_formats
=========================================

.. py:module:: magpie.api.management.group.group_formats


Functions
---------

.. autoapisummary::

   magpie.api.management.group.group_formats.evaluate_call
   magpie.api.management.group.group_formats.format_group


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: <function_call>`
   :param fallback: function to call (if any) when `call` failed, *MUST* be `lambda: <function_call>`
   :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_group(group: magpie.models.Group, basic_info: bool = False, public_info: bool = False, dotted: bool = False, db_session: Optional[sqlalchemy.orm.session.Session] = None) -> magpie.typedefs.JSON

   Obtains the JSON formatted :term:`Group` definition according to field selection flags.

   :param group: Group for which to provide details.
   :param basic_info:
       If ``True``, return only sufficient details to identify the group (useful for routes that refer to a group,
       but that are not requesting it specifically), or return full details (for routes that specifically request
       its information, e.g.: ``GET /groups/{grp}``).
   :param public_info:
       Indicate if the returned details are intended for public information (``True``) or admin-only (``False``).
       Only higher level users should be provided additional details to avoid leaking potentially sensitive parameters.
   :param dotted:
       Employ a dot (``.``) instead of underscore (``_``) to separate :term:`Group` from its basic information.
   :param db_session: Database connection to retrieve additional details (required when ``public_info=False``).