| Name | py3xui JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | Sync and Async Object-oriented Python SDK for the 3x-ui app. |
| upload_time | 2024-06-22 01:19:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT License |
| keywords |
vpn
3x-ui
sdk
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center" markdown>
<img src="https://github.com/iwatkot/py3xui/assets/118521851/42c5d579-6202-4a9e-88f3-2d844fdd95b6">
Sync and Async Object-oriented Python SDK for the 3x-ui API.
<p align="center">
<a href="#Overview">Overview</a> •
<a href="#Quick-Start">Quick Start</a> •
<a href="#Examples">Examples</a> •
<a href="#Bugs-and-Feature-Requests">Bugs and Feature Requests</a>
</p>
[](https://github.com/iwatkot/py3xui/actions)
[](https://mypy-lang.org/)<br>
[](https://codeclimate.com/github/iwatkot/py3xui/maintainability)
[](https://codeclimate.com/github/iwatkot/py3xui/test_coverage)
</div>
## Overview
This SDK is designed to interact with the [3x-ui](https://github.com/MHSanaei/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.<br>
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.<br>
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.<br>
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
```bash
pip install py3xui
```
### Create a new instance of the SDK
It's recommended to use an environment variable to store the API credentials:
```python
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:
```python
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:
```python
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.
```python
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:
- [Synchronous API](py3xui/api/README.md)
- [Asynchronous API](py3xui/async_api/README.md)
- [Client](py3xui/client/README.md)
- [Inbound](py3xui/inbound/README.md)
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.<br>
### Get inbounds list
```python
from py3xui import Api, Inbound
api = Api.from_env()
api.login()
inbounds: List[Inbound] = api.inbound.get_list()
```
### Add a new inbound
```python
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
```python
from py3xui import Api, Client
api = Api.from_env()
api.login()
client: Client = api.client.get_by_email("some-email")
```
### Add a new client
```python
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.<br>
You're also welcome to contribute to the project by opening a pull request.
Raw data
{
"_id": null,
"home_page": null,
"name": "py3xui",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "vpn, 3x-ui, sdk, api",
"author": null,
"author_email": "iwatkot <iwatkot@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/ea/e74bea7eaf54e38d3086a07e639fed4fbbf8ab7167862d0b6f4083f568f4/py3xui-0.1.3.tar.gz",
"platform": null,
"description": "<div align=\"center\" markdown>\n<img src=\"https://github.com/iwatkot/py3xui/assets/118521851/42c5d579-6202-4a9e-88f3-2d844fdd95b6\">\n\nSync and Async Object-oriented Python SDK for the 3x-ui API.\n\n<p align=\"center\">\n <a href=\"#Overview\">Overview</a> \u2022 \n <a href=\"#Quick-Start\">Quick Start</a> \u2022 \n <a href=\"#Examples\">Examples</a> \u2022\n <a href=\"#Bugs-and-Feature-Requests\">Bugs and Feature Requests</a>\n</p>\n\n\n\n[](https://github.com/iwatkot/py3xui/actions)\n[](https://mypy-lang.org/)<br>\n\n\n[](https://codeclimate.com/github/iwatkot/py3xui/maintainability)\n[](https://codeclimate.com/github/iwatkot/py3xui/test_coverage)\n\n</div>\n\n## Overview\nThis SDK is designed to interact with the [3x-ui](https://github.com/MHSanaei/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.<br>\nUsed dependencies:\n- `requests` for synchronous API\n- `httpx` for asynchronous API\n- `pydantic` for models\n\nSupported Python versions:\n- 3.11\n- 3.12\n\n## Quick Start\nYou 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.<br>\nAfter 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.<br>\nOn 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.\n\n### Installation\n```bash\npip install py3xui\n```\n\n### Create a new instance of the SDK\nIt's recommended to use an environment variable to store the API credentials:\n```python\nimport os\n\nos.environ[\"XUI_HOST\"] = \"http://your-3x-ui-host.com:2053\"\nos.environ[\"XUI_USERNAME\"] = \"your-username\"\nos.environ[\"XUI_PASSWORD\"] = \"your-password\"\n```\n\nTo work synchronously:\n```python\nfrom py3xui import Api\n\n# Using environment variables:\napi = Api.from_env()\n\n# Or using the credentials directly:\napi = Api(\"http://your-3x-ui-host.com:2053\", \"your-username\", \"your-password\")\n```\n\nTo work asynchronously:\n```python\nfrom py3xui import AsyncApi\n\n# Using environment variables:\napi = AsyncApi.from_env()\n\n# Or using the credentials directly:\napi = AsyncApi(\"http://your-3x-ui-host.com:2053\", \"your-username\", \"your-password\")\n```\n\n### Login\nNo 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.\n```python\nfrom py3xui import Api, AsyncApi\n\napi = Api.from_env()\napi.login()\n\nasync_api = AsyncApi.from_env()\nawait async_api.login()\n```\n\n## Examples\nYou'll find detailed docs with usage examples for both APIs and for used models in the corresponding package directories:\n- [Synchronous API](py3xui/api/README.md)\n- [Asynchronous API](py3xui/async_api/README.md)\n- [Client](py3xui/client/README.md)\n- [Inbound](py3xui/inbound/README.md)\n\nIn 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.<br>\n\n### Get inbounds list\n```python\nfrom py3xui import Api, Inbound\n\napi = Api.from_env()\napi.login()\ninbounds: List[Inbound] = api.inbound.get_list()\n```\n\n### Add a new inbound\n```python\nfrom py3xui import Api\nfrom py3xui.inbound import Inbound, Settings, Sniffing, StreamSettings\n\napi = Api.from_env()\napi.login()\n\nsettings = Settings()\nsniffing = Sniffing(enabled=True)\n\ntcp_settings = {\n \"acceptProxyProtocol\": False,\n \"header\": {\"type\": \"none\"},\n}\nstream_settings = StreamSettings(security=\"reality\", network=\"tcp\", tcp_settings=tcp_settings)\n\ninbound = Inbound(\n enable=True,\n port=443,\n protocol=\"vless\",\n settings=settings,\n stream_settings=stream_settings,\n sniffing=sniffing,\n remark=\"test3\",\n)\n\napi.inbound.add(inbound)\n```\n\n### Get a client by email\n```python\nfrom py3xui import Api, Client\n\napi = Api.from_env()\napi.login()\n\nclient: Client = api.client.get_by_email(\"some-email\")\n```\n\n### Add a new client\n```python\nfrom py3xui import Api, Client\n\napi = Api.from_env()\napi.login()\n\nnew_client = Client(id=str(uuid.uuid4()), email=\"test\", enable=True)\ninbound_id = 1\n\napi.client.add(inbound_id, [new_client])\n```\n\n## Bugs and Feature Requests\nIf you find a bug or have a feature request, please open an issue on the GitHub repository.<br>\nYou're also welcome to contribute to the project by opening a pull request.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Sync and Async Object-oriented Python SDK for the 3x-ui app.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/iwatkot/py3xui",
"Repository": "https://github.com/iwatkot/py3xui"
},
"split_keywords": [
"vpn",
" 3x-ui",
" sdk",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4e108b639121f557054009b63b48999ef148dfe2d5bb36001e3d6162fcade405",
"md5": "e3c139a3d681edb81215385958bbc4da",
"sha256": "4d34d2aa31c636c2575c4a0786d768cc34bb641bed9b67ff9ed77b90cec256e6"
},
"downloads": -1,
"filename": "py3xui-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3c139a3d681edb81215385958bbc4da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30060,
"upload_time": "2024-06-22T01:19:09",
"upload_time_iso_8601": "2024-06-22T01:19:09.247763Z",
"url": "https://files.pythonhosted.org/packages/4e/10/8b639121f557054009b63b48999ef148dfe2d5bb36001e3d6162fcade405/py3xui-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5eae74bea7eaf54e38d3086a07e639fed4fbbf8ab7167862d0b6f4083f568f4",
"md5": "0fed6a2693b71f40069229cc2812a426",
"sha256": "91c665d9adf05c01521bd0c7e20ffac3a16083d2422e3f1f0faff98134c664ae"
},
"downloads": -1,
"filename": "py3xui-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "0fed6a2693b71f40069229cc2812a426",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23593,
"upload_time": "2024-06-22T01:19:11",
"upload_time_iso_8601": "2024-06-22T01:19:11.197251Z",
"url": "https://files.pythonhosted.org/packages/d5/ea/e74bea7eaf54e38d3086a07e639fed4fbbf8ab7167862d0b6f4083f568f4/py3xui-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-22 01:19:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iwatkot",
"github_project": "py3xui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "py3xui"
}
