# XUIClient
A rich-feature and easy-to-use Python library to control your XUI-Panel.
> If you have ideas, bugs, ..., please issues for us
**features**:
- Very fast
- Very easy to use
- Supported all of protocols such as **VMess**, **VLess**, **Shadowsocks**, **Dokodemo-door**, ...
- Supported all of transmissions such as **tcp**, **kcp**, **ws**, ...
**Content**:
- [Install](#install)
- [Simple Example](#simple-example)
- [Usage](#usage)
- [Methods](#methods)
- [How to get protocols link](#how-to-get-protocols-link)
## Install
```bash
pip3 install -U xuiclient
```
### Simple example
```python
from xuiclient import Client, types, protocols
cli = Client("http://127.0.0.1:54321", cookie_file=".cookie")
cli.login("admin", "admin")
id = cli.add_inbound(
protocols.VMessProtocol(
remark="NAME",
total_traffic=types.GIGABYTE*10, # 10G
)
)
for p in cli.get_all_inbounds():
print(p)
```
## Usage
First create Client and login:
> We use '127.0.0.1:54321' for server address in this example.
```python
from xuiclient import Client
cli = Client("http://127.0.0.1:54321", cookie_file=".cookie")
cli.login("username", "password")
```
**What is cookie_file parameter?** If you set this parameter, the client will save session cookie into that
to prevent logging again. with this, you don't need to logout.
### Methods
Now you can control your panel. we have 15 functions for this:
#### get_status
Returns your server status.
```python
status = cli.get_status()
print(status)
# Status(cpu=10.012515644560525, mem=StatusInfo(current=1708163072, total=4011470848), ...)
```
#### get_settings
Returns settings information.
```python
settings = cli.get_settings()
print(settings)
```
#### get_lastest_xray_version
Returns latest XRay service version.
```python
version = cli.get_lastest_xray_version()
print(version)
# 6.0.0
```
#### is_xray_latest_version
Returns `True` if your xray version is latest.
```python
ok = cli.is_xray_latest_version()
print(ok)
```
#### install_new_xray_service
Installs new XRay service.
```python
cli.install_new_xray_service("6.0.0")
```
#### update_settings
Updates settings.
*Recommend to use `get_settings()` and use `Settings` type to update settings.
With this function may loss data.
```python
setting = cli.get_settings()
# your changes
cli.update_settings(setting)
```
#### update_user
Updates username and password.
*After update, it tries to logout and login with new username and password to avoid some problems.
```python
cli.update_user("username", "password", "newuser", "newpass")
```
#### get_email_ips
Returns IPs of an email.
```python
print(cli.get_email_ips("awolverp@gmail.com"))
# ["92.32.32.9", ...]
```
#### clear_email_ips
Clears IPs of an email.
```python
cli.clear_email_ips("awolverp@gmail.com")
```
#### get_all_inbounds
Returns all inbounds.
```python
for p in cli.get_all_inbounds():
print(p)
# xuiclient.protocols.VMessProtocol(id=1, remark='NAME', enabled=True)
# ...
```
#### get_inbound
*Only 'NidukaAkalanka/x-ui-english' supported this.
Returns the inbound which has specified id.
Returns `None` if not exists.
```python
print(cli.get_inbound(1))
# xuiclient.protocols.VMessProtocol(id=1, remark='NAME', enabled=True)
```
#### delete_inbound
Deletes inbound which has specified id.
```python
cli.delete_inbound(1)
```
#### add_inbound
Adds new inbound and returns id of that.
```python
from xuiclient import protocols, types
from datetime import datetime, timedelta
cli.add_inbound(
protocols.VLessProtocol(
remark="TEST",
port=12345,
expiry_time=datetime.now()+timedelta(days=30), # 30 days
total_traffic=100*types.GIGABYTE, # 10GiB
transmission=protocols.WSTransmission(),
tls=protocols.XTLS(),
clients=[protocols.ProtocolClient(email="awolverp@gmail.com")],
)
)
```
#### add_inbounds_many
Shorthand for `for p in protocols: cli.add_inbound(p)`.
```python
from xuiclient import protocols
cli.add_inbounds_many(
protocols.VLessProtocol(
remark="TEST",
port=12345
),
protocols.SocksProtocol(
remark="TEST",
port=12346
),
protocols.DokodemoDoor(
remark="TEST",
port=12347
)
)
```
#### update_inbound
Changes one inbound which has specified id to another that you specified.
```python
cli.update_inbound(
1,
protocols.VLessProtocol(
remark="TEST",
port=12345
),
)
```
### How to get protocols link?
use `generate_access_link` method.
example:
```python
for p in cli.get_all_inbounds():
print(p.generate_access_link(cli.hostname))
# Or create manually:
p = protocols.VMessProtocol(
remark="NAME", port=10382,
)
print(p.generate_access_link(cli.hostname))
```
Or if you have multi-user protocol and want to generate link for each user, can follow this way:
```python
for p in cli.get_all_inbounds():
try:
clients_len = len(p.clients)
except AttributeError:
# some protocols not supported multi-user
print(p.generate_access_link(cli.hostname))
else:
for i in range(clients_len):
print(p.generate_access_link(cli.hostname, client_index=i))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/awolverp/xuiclient",
"name": "xuiclient",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "awolverp",
"author_email": "awolverp@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/f1/f7125d643de6ed0b459773a31154bef7719e17ce20e78b8bac58133c516a/xuiclient-1.0.0.tar.gz",
"platform": null,
"description": "# XUIClient\nA rich-feature and easy-to-use Python library to control your XUI-Panel.\n\n> If you have ideas, bugs, ..., please issues for us\n\n**features**:\n- Very fast\n- Very easy to use\n- Supported all of protocols such as **VMess**, **VLess**, **Shadowsocks**, **Dokodemo-door**, ...\n- Supported all of transmissions such as **tcp**, **kcp**, **ws**, ...\n\n**Content**:\n- [Install](#install)\n- [Simple Example](#simple-example)\n- [Usage](#usage)\n - [Methods](#methods)\n - [How to get protocols link](#how-to-get-protocols-link)\n\n## Install\n```bash\npip3 install -U xuiclient\n```\n\n### Simple example\n```python\nfrom xuiclient import Client, types, protocols\n\ncli = Client(\"http://127.0.0.1:54321\", cookie_file=\".cookie\")\n\ncli.login(\"admin\", \"admin\")\n\nid = cli.add_inbound(\n protocols.VMessProtocol(\n remark=\"NAME\",\n total_traffic=types.GIGABYTE*10, # 10G\n )\n)\n\nfor p in cli.get_all_inbounds():\n print(p)\n```\n\n## Usage\nFirst create Client and login:\n\n> We use '127.0.0.1:54321' for server address in this example.\n\n```python\nfrom xuiclient import Client\n\ncli = Client(\"http://127.0.0.1:54321\", cookie_file=\".cookie\")\ncli.login(\"username\", \"password\")\n```\n\n**What is cookie_file parameter?** If you set this parameter, the client will save session cookie into that\nto prevent logging again. with this, you don't need to logout.\n\n### Methods\nNow you can control your panel. we have 15 functions for this:\n\n#### get_status\nReturns your server status.\n\n```python\nstatus = cli.get_status()\nprint(status)\n# Status(cpu=10.012515644560525, mem=StatusInfo(current=1708163072, total=4011470848), ...)\n```\n\n#### get_settings\nReturns settings information.\n\n```python\nsettings = cli.get_settings()\nprint(settings)\n```\n\n#### get_lastest_xray_version\nReturns latest XRay service version.\n\n```python\nversion = cli.get_lastest_xray_version()\nprint(version)\n# 6.0.0\n```\n\n#### is_xray_latest_version\nReturns `True` if your xray version is latest.\n\n```python\nok = cli.is_xray_latest_version()\nprint(ok)\n```\n\n#### install_new_xray_service\nInstalls new XRay service.\n\n```python\ncli.install_new_xray_service(\"6.0.0\")\n```\n\n#### update_settings\nUpdates settings.\n\n*Recommend to use `get_settings()` and use `Settings` type to update settings.\nWith this function may loss data.\n\n```python\nsetting = cli.get_settings()\n# your changes\ncli.update_settings(setting)\n```\n\n#### update_user\nUpdates username and password.\n\n*After update, it tries to logout and login with new username and password to avoid some problems.\n\n```python\ncli.update_user(\"username\", \"password\", \"newuser\", \"newpass\")\n```\n\n#### get_email_ips\nReturns IPs of an email.\n\n```python\nprint(cli.get_email_ips(\"awolverp@gmail.com\"))\n# [\"92.32.32.9\", ...]\n```\n\n#### clear_email_ips\nClears IPs of an email.\n\n```python\ncli.clear_email_ips(\"awolverp@gmail.com\")\n```\n\n#### get_all_inbounds\nReturns all inbounds.\n\n```python\nfor p in cli.get_all_inbounds():\n print(p)\n# xuiclient.protocols.VMessProtocol(id=1, remark='NAME', enabled=True)\n# ...\n```\n\n#### get_inbound\n*Only 'NidukaAkalanka/x-ui-english' supported this.\n\nReturns the inbound which has specified id.\n\nReturns `None` if not exists.\n\n```python\nprint(cli.get_inbound(1))\n# xuiclient.protocols.VMessProtocol(id=1, remark='NAME', enabled=True)\n```\n\n#### delete_inbound\nDeletes inbound which has specified id.\n\n```python\ncli.delete_inbound(1)\n```\n\n#### add_inbound\nAdds new inbound and returns id of that.\n\n```python\nfrom xuiclient import protocols, types\nfrom datetime import datetime, timedelta\n\ncli.add_inbound(\n protocols.VLessProtocol(\n remark=\"TEST\",\n port=12345,\n expiry_time=datetime.now()+timedelta(days=30), # 30 days\n total_traffic=100*types.GIGABYTE, # 10GiB\n transmission=protocols.WSTransmission(),\n tls=protocols.XTLS(),\n clients=[protocols.ProtocolClient(email=\"awolverp@gmail.com\")],\n )\n)\n```\n\n#### add_inbounds_many\nShorthand for `for p in protocols: cli.add_inbound(p)`.\n\n```python\nfrom xuiclient import protocols\n\ncli.add_inbounds_many(\n protocols.VLessProtocol(\n remark=\"TEST\",\n port=12345\n ),\n protocols.SocksProtocol(\n remark=\"TEST\",\n port=12346\n ),\n protocols.DokodemoDoor(\n remark=\"TEST\",\n port=12347\n )\n)\n```\n\n#### update_inbound\nChanges one inbound which has specified id to another that you specified.\n\n```python\ncli.update_inbound(\n 1,\n protocols.VLessProtocol(\n remark=\"TEST\",\n port=12345\n ),\n)\n```\n\n### How to get protocols link?\nuse `generate_access_link` method.\nexample:\n\n```python\nfor p in cli.get_all_inbounds():\n print(p.generate_access_link(cli.hostname))\n\n# Or create manually:\n\np = protocols.VMessProtocol(\n remark=\"NAME\", port=10382,\n)\nprint(p.generate_access_link(cli.hostname))\n```\n\nOr if you have multi-user protocol and want to generate link for each user, can follow this way:\n```python\nfor p in cli.get_all_inbounds():\n \n try:\n clients_len = len(p.clients)\n except AttributeError:\n # some protocols not supported multi-user\n print(p.generate_access_link(cli.hostname))\n \n else:\n for i in range(clients_len):\n print(p.generate_access_link(cli.hostname, client_index=i))\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Rich-feature and easy-to-use XUI client",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/awolverp/xuiclient"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec6dbe036e992ebe7ea24b9ff468e173edac2c4d4168ed5f7535adcd0cffc3b6",
"md5": "f33ff1fa4d1263abe00e124356fc34aa",
"sha256": "df929b36376103f825242a84ccd98ab3e06460cb124c92d0182dfb6bf7bbc515"
},
"downloads": -1,
"filename": "xuiclient-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f33ff1fa4d1263abe00e124356fc34aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15832,
"upload_time": "2023-05-05T14:17:49",
"upload_time_iso_8601": "2023-05-05T14:17:49.638569Z",
"url": "https://files.pythonhosted.org/packages/ec/6d/be036e992ebe7ea24b9ff468e173edac2c4d4168ed5f7535adcd0cffc3b6/xuiclient-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94f1f7125d643de6ed0b459773a31154bef7719e17ce20e78b8bac58133c516a",
"md5": "5fc53a013ce06aeabd8e46e899d3a820",
"sha256": "19977b32145aefa33d908f054dcc5e217fde7d03ebf2803abeadb836d2ff3f76"
},
"downloads": -1,
"filename": "xuiclient-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5fc53a013ce06aeabd8e46e899d3a820",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15508,
"upload_time": "2023-05-05T14:17:52",
"upload_time_iso_8601": "2023-05-05T14:17:52.239417Z",
"url": "https://files.pythonhosted.org/packages/94/f1/f7125d643de6ed0b459773a31154bef7719e17ce20e78b8bac58133c516a/xuiclient-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-05 14:17:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awolverp",
"github_project": "xuiclient",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xuiclient"
}
JSON
