magpie.api.management.register.register_utils
=============================================

.. py:module:: magpie.api.management.register.register_utils


Attributes
----------

.. autoapisummary::

   magpie.api.management.register.register_utils.LOGGER


Functions
---------

.. autoapisummary::

   magpie.api.management.register.register_utils.handle_temporary_token
   magpie.api.management.register.register_utils.get_discoverable_groups
   magpie.api.management.register.register_utils.get_discoverable_group_by_name
   magpie.api.management.register.register_utils.register_pending_user
   magpie.api.management.register.register_utils.handle_user_registration_confirmation
   magpie.api.management.register.register_utils.request_admin_approval
   magpie.api.management.register.register_utils.handle_user_registration_admin_decision
   magpie.api.management.register.register_utils.complete_user_registration


Module Contents
---------------

.. py:data:: LOGGER

.. py:function:: handle_temporary_token(tmp_token: magpie.models.TemporaryToken, request: pyramid.request.Request) -> Union[pyramid.httpexceptions.HTTPException, pyramid.response.Response]

   Handles the operation according to the provided temporary token.

   :returns:
       Basic JSON response with successful indicate of correct handling of the token by default.
       If overridden, can be any HTML rendered response.


.. py:function:: get_discoverable_groups(db_session: sqlalchemy.orm.session.Session) -> List[magpie.models.Group]

   Get all existing group that are marked as publicly discoverable from the database.


.. py:function:: get_discoverable_group_by_name(group_name: magpie.typedefs.Str, db_session: sqlalchemy.orm.session.Session) -> magpie.models.Group

   Obtains the requested discoverable group by name.

   .. note::
       For security reason, an existing group that is **NOT** discoverable will return NotFound instead of Forbidden.
       Otherwise we give an indication to a potentially non-admin user that *some group* of that name exists.

   :return: found group matched by name
   :raises HTTPNotFound: if the group cannot be found or if matched group name is not discoverable.


.. py:function:: register_pending_user(user_name: magpie.typedefs.Str, email: magpie.typedefs.Str, password: magpie.typedefs.Str, request: pyramid.request.Request) -> pyramid.httpexceptions.HTTPException

   Registers a temporary user pending approval.

   Procedure and validation workflow is similar to normal user creation by an administrator, but employs reduced
   fields and different target table. Some operations are also simplified as they are not required for pending user.
   There is also no user creation :term:`Webhook` triggers as :term:`User` doesn't exist yet.

   .. seealso::
       See :func:`magpie.api.management.user.user_utils.create_user` for similarities and distinctions of
       operations between a *normal* :term:`User` and a :term:`Pending User`.

   Implements steps (1) and (2) of the user registration procedure.

   .. seealso::
       - See :ref:`proc_user_registration` for the procedure step details.
       - See :func:`request_admin_approval` and :func:`complete_user_registration` for following steps of
         the procedure following reception of the confirmation email.

   :return: HTTP created with relevant details if successful.
   :raises HTTPException: HTTP error with relevant details upon any failing condition.


.. py:function:: handle_user_registration_confirmation(tmp_token: magpie.models.TemporaryToken, request: pyramid.request.Request) -> pyramid.response.Response

   Applies the appropriate step of the user registration workflow following reception of the confirmation URL visit.

   Implements steps (3A) and (3B) redirection of the user registration procedure.
   Generates the appropriate response that will be displayed to the :term:`Pending User` that confirmed its email.

   .. seealso::
       - See :ref:`proc_user_registration` for the procedure step details.
       - See :ref:`request_admin_approval` for step 3B.
       - See :ref:`complete_user_registration` for step 5 (from 3A).


.. py:function:: request_admin_approval(tmp_token: magpie.models.TemporaryToken, request: pyramid.request.Request) -> None

   Sends the email to the administrator to approve or refuse the :term:`Pending User` registration.

   Implements step (3B) of the user registration procedure.

   .. seealso::
       - See :ref:`proc_user_registration` for the procedure step details.


.. py:function:: handle_user_registration_admin_decision(tmp_token: magpie.models.TemporaryToken, request: pyramid.request.Request) -> pyramid.response.Response

   Applies the appropriate operation according to the decision the administrator took for the pending registration.

   - *approved*: Moves to step (5)
   - *declined*: Removes the pending user request.

   Generates the appropriate response that will be displayed to the administrator.

   Implements step (4) of the user registration procedure.

   .. seealso::
       - See :ref:`proc_user_registration` for the procedure step details.
       - :func:`complete_user_registration` for step 5 following approval.


.. py:function:: complete_user_registration(tmp_token: magpie.models.TemporaryToken, approval_required: bool, request: pyramid.request.Request) -> None

   Completes the successful user registration following any required validation steps.

   Generates the :term:`User` from the :term:`Pending User`.
   Then, sends configured notification emails about successful :term:`User` creation.

   Implements steps (5) and (6) of the user registration procedure.

   .. seealso::
       - See :ref:`proc_user_registration` for the procedure step details.
       - :func:`register_pending_user` for initial steps that started the process.
       - :func:`request_admin_approval` for intermediate steps if approval feature was enabled.