mud_server.admin_gradio.api.admin

Admin API client for MUD Server.

This module handles all administrative operations: - Database viewing (players, sessions, chat messages) - User management (role changes, ban/unban)

All functions require admin or superuser role and follow a consistent pattern:

Validate session state and admin 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 or formatted data “data”: None, “error”: str | None, # Error details if failed

}

Classes

AdminAPIClient

API client for administrative operations.

Module Contents

class mud_server.admin_gradio.api.admin.AdminAPIClient(server_url=None)[source]

Bases: mud_server.admin_gradio.api.base.BaseAPIClient

API client for administrative operations.

This client handles database viewing and user management operations that require admin or superuser permissions.

Example

>>> client = AdminAPIClient()
>>> result = client.get_database_players(
...     session_id="admin123",
...     role="admin"
... )
>>> if result["success"]:
...     print(result["message"])

Initialize the base API client.

Parameters:: server_url (str | None) – Optional server URL override. If not provided, uses MUD_SERVER_URL environment variable or defaults to http://localhost:8000

get_database_players(session_id, role)[source]

Fetch and format all users from database (Admin/Superuser only).

Returns detailed information about all accounts including: - ID, username, role, status - Character count and guest flags - Created date and last login - Password hash prefix

Parameters:

session_id (str | None) – User’s session ID from login
role (str) – User’s role (for permission checking)

Returns:

{: “success”: bool, “message”: str, # Formatted player table “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

>>> client = AdminAPIClient()
>>> result = client.get_database_players("admin123", "admin")
>>> result["success"]
True
>>> "PLAYERS TABLE" in result["message"]
True

get_database_sessions(session_id, role)[source]

Fetch and format all active sessions from database (Admin/Superuser only).

Returns information about all active sessions including: - Session ID and username - Connection time and last activity

Parameters:

session_id (str | None) – User’s session ID from login
role (str) – User’s role (for permission checking)

Returns:

{: “success”: bool, “message”: str, # Formatted sessions table “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

get_database_chat(session_id, role, limit=50)[source]

Fetch and format recent chat messages from database (Admin/Superuser only).

Returns recent chat messages from all rooms including: - Message ID, room, timestamp - Username and message content

Parameters:

session_id (str | None) – User’s session ID from login
role (str) – User’s role (for permission checking)
limit (int) – Maximum number of messages to retrieve (default: 50)

Returns:

{: “success”: bool, “message”: str, # Formatted chat messages “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

manage_user(session_id, role, target_username, action, new_role='')[source]

Perform user management actions (Admin/Superuser only).

Supported actions: - change_role: Change user’s role (requires new_role parameter) - ban: Ban/deactivate user account - unban: Unban/reactivate user account

Parameters:

session_id (str | None) – User’s session ID from login
role (str) – User’s role (for permission checking)
target_username (str) – Username of user to manage
action (str) – Action to perform (change_role, ban, unban)
new_role (str) – New role for change_role action (optional)

Returns:

{: “success”: bool, “message”: str, “data”: None, “error”: str | None,

}

Return type:

Dictionary with structure

Examples

>>> client = AdminAPIClient()
>>> result = client.manage_user(
...     session_id="admin123",
...     role="admin",
...     target_username="alice",
...     action="change_role",
...     new_role="worldbuilder"
... )
>>> result["success"]
True