imaging_api.services.users
==========================

.. py:module:: imaging_api.services.users


Attributes
----------

.. autoapisummary::

   imaging_api.services.users.XNAT_URL


Functions
---------

.. autoapisummary::

   imaging_api.services.users.get_xnat_users
   imaging_api.services.users.to_create_imaging_user
   imaging_api.services.users.get_user_profile_by
   imaging_api.services.users.user_exists
   imaging_api.services.users.create_user_from_central_hub_user
   imaging_api.services.users.create_user
   imaging_api.services.users.add_user_to_project


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

.. py:data:: XNAT_URL

.. py:function:: get_xnat_users(headers: dict[str, str]) -> list[imaging_api.routers.schemas.User]

   Gets all users from XNAT.

   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: List of XNAT users.
   :rtype: list[imaging_api.routers.schemas.User]

   :raises Exception: If XNAT returns a non-200 response.


.. py:function:: to_create_imaging_user(user: imaging_api.routers.schemas.CentralHubUser, headers: dict[str, str]) -> imaging_api.routers.schemas.CreateUser

   Converts central hub user (mainly email) to an XNAT CreateUser object.

   XNAT usernames are unique, so we have to create a unique XNAT username from the email address.
   We first grab the part of the email before '@'.
   If the username already exists, we append a number suffix to make it unique.

   :param user: The user's details on the Central Hub.
   :type user: imaging_api.routers.schemas.CentralHubUser
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: XNAT user creation request object.
   :rtype: imaging_api.routers.schemas.CreateUser

   :raises Exception: If fetching existing XNAT users fails.


.. py:function:: get_user_profile_by(key: str, value: str, headers: dict[str, str]) -> imaging_api.routers.schemas.User

   Fetches a user profile from XNAT using the key and value.

   :param key: The key to search by. Can be 'username' or 'email'.
   :type key: str
   :param value: The value to search for.
   :type value: str
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: The user profile.
   :rtype: imaging_api.routers.schemas.User

   :raises AssertionError: If ``key`` is not ``"username"`` or ``"email"``.
   :raises imaging_api.utils.exceptions.NotFoundError: If no XNAT user matches ``value`` for the given ``key``.
   :raises Exception: If fetching XNAT users fails.


.. py:function:: user_exists(username: str, headers: dict[str, str]) -> bool

   Checks if a user exists in XNAT.

   In XNAT, username is unique, so it can be used to identify the user:
   `"ERROR: The username {username} is already in use. Please enter a different username value and try again."`

   :param username: The username to check.
   :type username: str
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: True if the user exists, False otherwise.
   :rtype: bool


.. py:function:: create_user_from_central_hub_user(central_hub_user: imaging_api.routers.schemas.CentralHubUser, headers: dict[str, str]) -> tuple[imaging_api.routers.schemas.CreatedUser, imaging_api.routers.schemas.User]

   Convert central hub user to XNAT CreateUser request object, and create user on XNAT.

   :param central_hub_user: The user's details on the Central Hub.
   :type central_hub_user: imaging_api.routers.schemas.CentralHubUser
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: The created user and the user
             profile.
   :rtype: tuple[imaging_api.routers.schemas.CreatedUser, imaging_api.routers.schemas.User]


.. py:function:: create_user(user: imaging_api.routers.schemas.CreateUser, headers: dict[str, str]) -> imaging_api.routers.schemas.User

   Core logic to create an XNAT user. Returns the newly created user profile.

   :param user: The user to create.
   :type user: imaging_api.routers.schemas.CreateUser
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: The created user profile.
   :rtype: imaging_api.routers.schemas.User

   :raises AlreadyExistsError: If a user with the same username already exists on XNAT (HTTP 409).
   :raises Exception: If XNAT returns any other non-201 response.


.. py:function:: add_user_to_project(user: imaging_api.routers.schemas.User, project_id: str, headers: dict[str, str]) -> imaging_api.routers.schemas.User

   Adds a user to a project in XNAT.

   :param user: The user to add.
   :type user: imaging_api.routers.schemas.User
   :param project_id: The project ID.
   :type project_id: str
   :param headers: XNAT authentication headers.
   :type headers: dict[str, str]

   :returns: The user profile.
   :rtype: imaging_api.routers.schemas.User

   :raises HTTPException: If there is an error during the addition of the user to the project.
   :raises imaging_api.utils.exceptions.NotFoundError: If the user or project is not found.