Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

pyx3ui

Package Overview
Dependencies
Maintainers
0
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

pyx3ui

Sync and Async Object-oriented Python SDK for the 3x-ui app.

  • 0.1.2
  • PyPI
  • Socket score

Maintainers
0

Sync and Async Object-oriented Python SDK for the 3x-ui API.

OverviewQuick StartExamplesBugs and Feature Requests

GitHub release (latest SemVer) GitHub issues Build Status Checked with mypy
PyPI - Python Version PyPI - Downloads Maintainability Test Coverage

Overview

This SDK is designed to interact with the 3x-ui app in a more object-oriented way. It provides both synchronous and asynchronous methods to interact with the app. The SDK is designed to be as simple as possible to use, while still providing a lot of flexibility and uses Pydantic models to validate the data.
Used dependencies:

  • requests for synchronous API
  • httpx for asynchronous API
  • pydantic for models

Supported Python versions:

  • 3.11
  • 3.12

Quick Start

You can use both synchronous and asynchronous methods to interact with the 3x-ui app. Both APIs have the same methods and return the same data, so it's up to you to choose which one to use.
After installing the SDK, you can create a new instance of the SDK. When creating a new instance, you can either use environment variables or pass the credentials directly. It's strongly recommended to use environment variables to store the API credentials.
On creation, the Api won't connect to the 3x-ui app, so you can spawn new instances without spending resources. But after creating an instance, you'll need to call the login method to authenticate the user and save the cookie for future requests.

Installation

pip install py3xui

Create a new instance of the SDK

It's recommended to use an environment variable to store the API credentials:

import os

os.environ["XUI_HOST"] = "http://your-3x-ui-host.com:2053"
os.environ["XUI_USERNAME"] = "your-username"
os.environ["XUI_PASSWORD"] = "your-password"

To work synchronously:

from py3xui import Api

# Using environment variables:
api = Api.from_env()

# Or using the credentials directly:
api = Api("http://your-3x-ui-host.com:2053", "your-username", "your-password")

To work asynchronously:

from py3xui import AsyncApi

# Using environment variables:
api = AsyncApi.from_env()

# Or using the credentials directly:
api = AsyncApi("http://your-3x-ui-host.com:2053", "your-username", "your-password")

Login

No matter which API you're using or if was it created using environment variables or credentials, you'll need to call the login method to authenticate the user and save the cookie for future requests.

from py3xui import Api, AsyncApi

api = Api.from_env()
api.login()

async_api = AsyncApi.from_env()
await async_api.login()

Examples

You'll find detailed docs with usage examples for both APIs and for used models in the corresponding package directories:

In this section, you'll find some examples of how to use the SDK. In the examples, we'll use the synchronous API, but you can use the asynchronous API in the same way, just remember to use await before calling the methods.

Get inbounds list

from py3xui import Api, Inbound

api = Api.from_env()
api.login()
inbounds: List[Inbound] = api.inbound.get_list()

Add a new inbound

from py3xui import Api
from py3xui.inbound import Inbound, Settings, Sniffing, StreamSettings

api = Api.from_env()
api.login()

settings = Settings()
sniffing = Sniffing(enabled=True)

tcp_settings = {
    "acceptProxyProtocol": False,
    "header": {"type": "none"},
}
stream_settings = StreamSettings(security="reality", network="tcp", tcp_settings=tcp_settings)

inbound = Inbound(
    enable=True,
    port=443,
    protocol="vless",
    settings=settings,
    stream_settings=stream_settings,
    sniffing=sniffing,
    remark="test3",
)

api.inbound.add(inbound)

Get a client by email

from py3xui import Api, Client

api = Api.from_env()
api.login()

client: Client = api.client.get_by_email("some-email")

Add a new client

from py3xui import Api, Client

api = Api.from_env()
api.login()

new_client = Client(id=str(uuid.uuid4()), email="test", enable=True)
inbound_id = 1

api.client.add(inbound_id, [new_client])

Bugs and Feature Requests

If you find a bug or have a feature request, please open an issue on the GitHub repository.
You're also welcome to contribute to the project by opening a pull request.

Keywords

FAQs


Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc