mud_server.admin_gradio.api.settings
====================================

.. py:module:: mud_server.admin_gradio.api.settings

.. autoapi-nested-parse::

   Settings API client for MUD Server.

   This module handles user settings and server management operations:
   - Password changes
   - Server control (stop server)

   All functions follow a consistent pattern:
       - Validate session state and permissions
       - Validate input
       - Make API request using BaseAPIClient
       - Return standardized response dictionaries

   Response Format:
       All functions return dictionaries with:
       {
           "success": bool,         # Whether operation succeeded
           "message": str,          # User-facing message
           "data": None,
           "error": str | None,     # Error details if failed
       }



Classes
-------

.. autoapisummary::

   mud_server.admin_gradio.api.settings.SettingsAPIClient


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

.. py:class:: SettingsAPIClient(server_url = None)

   Bases: :py:obj:`mud_server.admin_gradio.api.base.BaseAPIClient`


   API client for settings and server management operations.

   This client handles password changes and server control operations.

   .. admonition:: Example

      >>> client = SettingsAPIClient()
      >>> result = client.change_password(
      ...     session_id="abc123",
      ...     old_password="old123",
      ...     new_password="new456",
      ...     confirm_password="new456"
      ... )
      >>> if result["success"]:
      ...     print("Password changed successfully")

   Initialize the base API client.

   :param server_url: Optional server URL override. If not provided,
                      uses MUD_SERVER_URL environment variable or defaults
                      to http://localhost:8000


   .. py:method:: change_password(session_id, old_password, new_password, confirm_password)

      Change the current user's password.

      Validates passwords, sends change request to backend, and returns
      confirmation or error message.

      :param session_id: User's session ID from login
      :param old_password: Current password (for verification)
      :param new_password: Desired new password
      :param confirm_password: New password confirmation

      :returns:

                {
                    "success": bool,
                    "message": str,
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = SettingsAPIClient()
         >>> result = client.change_password(
         ...     session_id="abc123",
         ...     old_password="old123",
         ...     new_password="new456789",
         ...     confirm_password="new456789"
         ... )
         >>> result["success"]
         True



   .. py:method:: stop_server(session_id, role)

      Stop the backend server (Admin/Superuser only).

      This operation requires admin or superuser permissions. The server
      will shut down gracefully after responding to this request.

      :param session_id: User's session ID from login
      :param role: User's role (for permission checking)

      :returns:

                {
                    "success": bool,
                    "message": str,
                    "data": None,
                    "error": str | None,
                }
      :rtype: Dictionary with structure

      .. admonition:: Examples

         >>> client = SettingsAPIClient()
         >>> result = client.stop_server(session_id="abc123", role="admin")
         >>> if result["success"]:
         ...     print("Server shutting down")