py3xui Python SDK

py3xui is a Python SDK designed for interacting with the 3x-ui panel API. It abstracts the panel API complexities and provides a structured way to manage 3x-ui configurations using Python.

The SDK offers three primary components:

• Api: A synchronous client for standard blocking operations.
• AsyncApi: An asynchronous client for non-blocking, asyncio-compatible operations.
• Pydantic models: Structured data models for all request and response payloads, ensuring type safety and validation.

py3xui utilizes Pydantic models to handle API payload validation and parsing. These models ensure that data received from the upstream panel is correctly structured before it is used by the library.

The core models available for interacting with the API data are:

• Inbound: Represents inbound connection configurations.
• Client: Represents client/user information.
• ServerStatus: Represents the current operational status of the server.
• ServerConfig: Represents the server's configuration settings.

Note that while the underlying upstream panel response shapes may change, py3xui is designed to adapt its parsing logic to maintain stable public methods for these models.

The project maintains quality through a multi-layered strategy:

• Unit Tests: Cover both synchronous and asynchronous API behaviors.
• Type Checking: Uses mypy to prevent regressions in data shapes and API contracts.
• Linting: Uses pylint to enforce coding style and consistency.
• Live Validation: Performs live panel validation prior to any compatibility releases.

The py3xui Synchronous API is designed for blocking operations. This makes it ideal for:

• Automation scripts
• Cron jobs
• Simple service integrations where non-blocking I/O is not required.

The py3xui library is structured into three distinct layers to ensure stability and data integrity:

1. Base Transport Layer: Handles the underlying HTTP communication. It supports both synchronous operations using requests and asynchronous operations using httpx.
2. Domain API Groups: Organizes functionality into logical groups: inbound, client, server, and database.
3. Models: Uses Pydantic for strict model validation and data normalization, ensuring that API responses conform to expected schemas.

In version 0.7.0, several client methods have changed their underlying interaction with the 3x-ui panel API to accommodate the move to panel/api/clients/* routes:

• client.update(client_uuid, client): The upstream route now identifies the target by email. py3xui maintains the existing method signature for backward compatibility.
• client.delete(inbound_id, client_uuid): The upstream route requires an email. py3xui attempts to resolve the legacy inbound_id/client_uuid combination to an email automatically when possible.
• client.get_by_email(email): Now supports the modern nested response shape, returning obj.client and obj.inboundIds.
• get_traffic_by_id: This is now implemented via clients/list followed by local filtering to match the modern API context.

The py3xui SDK provides two distinct client styles depending on your application's execution model. Both clients expose the same high-level operations for managing inbounds, clients, servers, and databases.

• Use Api for blocking/synchronous workflows.
• Use AsyncApi for asynchronous, event-loop based workflows.

To begin using py3xui, follow this recommended learning path:

1. Understand the core concept: Read the introduction to learn what py3xui is and its purpose.
2. Initial Setup: Follow the Quick Start guide to get your first instance running.
3. Practical Application: Work through the provided Examples to see common usage patterns.
4. Choose an API Style: Decide between using the Synchronous API or the Asynchronous API based on your application's requirements.
5. Maintenance: If you are upgrading from an older version, consult the 0.7.0 Migration guide and review the 0.7.0 Release Notes.

To use username and password authentication, create an Api instance with your host, username, and password, then call the login() method to establish a session.

from py3xui import Api

api = Api("http://your-host:2053", "username", "password")
api.login()

To ensure code quality and compliance with project standards, run the following suite of local checks. This includes running unit tests with pytest, performing static type checking with mypy, and enforcing style consistency with pylint.

pytest
mypy py3xui
pylint py3xui