Python-3xui 0.0.8__tar.gz → 0.0.9__tar.gz

{python_3xui-0.0.8 → python_3xui-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.8
+Version: 0.0.9
 Summary: 3x-ui wrapper for python
 Project-URL: Homepage, https://github.com/Artem-Potapov/3x-py
 Project-URL: Issues, https://github.com/Artem-Potapov/3x-py/issues
@@ -12,11 +12,12 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
-Requires-Dist: async-lru~=2.2.0
+Requires-Dist: async-lru~=2.3.0
 Requires-Dist: dotenv~=0.9.9
 Requires-Dist: httpx~=0.28.1
 Requires-Dist: pydantic<3,~=2.12.5
 Requires-Dist: pyotp~=2.9.0
+Requires-Dist: python-dotenv
 Provides-Extra: testing
 Requires-Dist: pytest; extra == 'testing'
 Requires-Dist: pytest-asyncio; extra == 'testing'
@@ -28,9 +29,15 @@ Description-Content-Type: text/markdown
 <p>I'm not expecting much to be honest, so please feel free to fork it if I abandon the project and you need it!</p>
 <p>Also, if you REALLY want it I can give you the ownership if I step down, you can find my email in the pyproject.toml (I don't check it that much but trust me I do)</p>
 
-<h2>0.0.8 Release Notes</h2>
+<h2>0.0.9 Release Notes</h2>
 <ul>
-<li>Improve create_and_add_prod_client to have an expiry_time</li>
-<li>delete_client_by_tgid_all_inbounds -> revoke_client_by_tgid_all_inbounds</li>
-<li>Change vulnerable requirements</li>
+<li>Fix _request_update_client for it to actually work and NOT create "zombies"</li>
+<li>DTO un-split because fields reset when not provided, so full inbounds must be fetched</li>
+<li>New method: update_client_by_tgid</li>
+<li>Fixed test suite</li>
+<li>Fix from_response and from_list</li>
+<li>Remove obsolete and useless client fields from models</li>
+<li>Inbound settings actually get parsed properly into ClientsSettings</li>
+<li>New asyncio task management so they won't get destroyed when GCed</li>
+<li>XUIClient async_lru cache now binds to event loop at runtime, not in initialization</li>
 </ul>

python_3xui-0.0.9/README.md

@@ -0,0 +1,16 @@
+<h1>Hi! This is my example python 3x-ui wrapper!</h1>
+<p>I'm not expecting much to be honest, so please feel free to fork it if I abandon the project and you need it!</p>
+<p>Also, if you REALLY want it I can give you the ownership if I step down, you can find my email in the pyproject.toml (I don't check it that much but trust me I do)</p>
+
+<h2>0.0.9 Release Notes</h2>
+<ul>
+<li>Fix _request_update_client for it to actually work and NOT create "zombies"</li>
+<li>DTO un-split because fields reset when not provided, so full inbounds must be fetched</li>
+<li>New method: update_client_by_tgid</li>
+<li>Fixed test suite</li>
+<li>Fix from_response and from_list</li>
+<li>Remove obsolete and useless client fields from models</li>
+<li>Inbound settings actually get parsed properly into ClientsSettings</li>
+<li>New asyncio task management so they won't get destroyed when GCed</li>
+<li>XUIClient async_lru cache now binds to event loop at runtime, not in initialization</li>
+</ul>

{python_3xui-0.0.8 → python_3xui-0.0.9}/pyproject.toml

@@ -1,59 +1,60 @@
-[project]
-name = "Python-3xui"
-version = "0.0.8"
-authors = [
-  { name="JustMe_001", email="justme001.causation755@passinbox.com" },
-]
-description = "3x-ui wrapper for python"
-readme = "README.md"
-
-requires-python = ">=3.11"
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Operating System :: OS Independent",
-
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Developers",
-]
-
-license = "Apache-2.0"
-license-files = ["LICEN[CS]E*"]
-
-dependencies = [
-    "pydantic ~= 2.12.5, < 3",
-    "httpx ~=0.28.1",
-    "dotenv ~= 0.9.9",
-    "async_lru ~= 2.2.0",
-    "pyotp ~= 2.9.0"
-]
-
-
-[project.optional-dependencies]
-testing = ["requests", "pytest", "pytest-asyncio", "pytest-dependency"]
-
-
-[project.urls]
-Homepage = "https://github.com/Artem-Potapov/3x-py"
-Issues = "https://github.com/Artem-Potapov/3x-py/issues"
-
-
-[build-system]
-requires = ["hatchling >= 1.26"]
-build-backend = "hatchling.build"
-
-
-[tool.hatch.build.targets.sdist]
-include = [
-    "python_3xui/*.py",
-    "/tests/*.py",
-    "/tests/pytest.ini"
-]
-exclude = [
-    "requirements.txt",
-    "main.py",
-    ".env"
-]
-
-
-[[tool.hatch.envs.hatch-test.matrix]]
-python = ["3.12", "3.11"]
+[project]
+name = "Python-3xui"
+version = "0.0.9"
+authors = [
+  { name="JustMe_001", email="justme001.causation755@passinbox.com" },
+]
+description = "3x-ui wrapper for python"
+readme = "README.md"
+
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+]
+
+license = "Apache-2.0"
+license-files = ["LICEN[CS]E*"]
+
+dependencies = [
+    "pydantic ~= 2.12.5, < 3",
+    "httpx ~=0.28.1",
+    "dotenv ~= 0.9.9",
+    "python-dotenv",
+    "async_lru ~= 2.3.0",
+    "pyotp ~= 2.9.0"
+]
+
+
+[project.optional-dependencies]
+testing = ["requests", "pytest", "pytest-asyncio", "pytest-dependency"]
+
+
+[project.urls]
+Homepage = "https://github.com/Artem-Potapov/3x-py"
+Issues = "https://github.com/Artem-Potapov/3x-py/issues"
+
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "python_3xui/*.py",
+    "/tests/*.py",
+    "/tests/pytest.ini"
+]
+exclude = [
+    "requirements.txt",
+    "main.py",
+    ".env"
+]
+
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.13", "3.12", "3.11"]

{python_3xui-0.0.8 → python_3xui-0.0.9}/python_3xui/__init__.py

@@ -1,5 +1,7 @@
 from .api import XUIClient
 
 __author__ = "JustMe_001"
-__version__ = "0.0.1"
-__email__ = ""
+__version__ = "0.0.9"
+__email__ = ""
+
+

{python_3xui-0.0.8 → python_3xui-0.0.9}/python_3xui/api.py

@@ -1,21 +1,24 @@
+import asyncio
 import json
 import logging
 import re
-import time
+from asyncio import Task
 from collections.abc import Sequence, Mapping
-from logging import DEBUG
-from typing import Self, Optional, Dict, Iterable, AsyncIterable, Type, Union, Any, List, Tuple, Literal
 from datetime import datetime, UTC
+from inspect import iscoroutinefunction
+from logging import DEBUG
+from typing import Self, Optional, Dict, Iterable, AsyncIterable, Type, Union, Any, List, Tuple, Literal, Callable, Awaitable, overload
 
+import httpx
 import pyotp
-from httpx import Response, AsyncClient
 from async_lru import alru_cache
-import asyncio
-import httpx
+from httpx import Response, AsyncClient, Request
+from pydantic import SecretStr
 
+from . import custom_exceptions
 from . import util
 from .models import Inbound, SingleInboundClient, ClientStats
-from .util import JsonType, async_range, check_xui_response
+from .util import JsonType, async_range
 
 DataType: Type[str | bytes | Iterable[bytes] | AsyncIterable[bytes]] = Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]
 PrimitiveData = Optional[Union[str, int, float, bool]]
@@ -41,9 +44,6 @@ class XUIClient:
     This class provides methods for authenticating with the 3X-UI panel,
     managing sessions, and performing operations on inbounds and clients.
 
-    The client implements a singleton pattern to ensure only one instance
-    exists at a time.
-
     Attributes:
         PROD_STRING: String used to identify production inbounds.
         session: The async HTTP client session.
@@ -62,12 +62,14 @@ class XUIClient:
         clients_end: Clients endpoint handler.
         inbounds_end: Inbounds endpoint handler.
     """
-    _instance = None
 
     def __init__(self, base_website: str, base_port: int, base_path: str,
                  *, username: str | None = None, password: str | None = None,
                  two_fac_code: str | None = None, session_duration: int = 3600,
-                 custom_prod_string: str = "testing") -> None:
+                 custom_prod_string: str = "testing",
+                 max_retries: int = 5, retry_delay = 1,
+                 custom_sub_generator: Callable[[int], str]|Callable[[int], Awaitable[str]] = util.default_sub_from_tgid,
+                 ) -> None:
         """Initialize the XUIClient.
 
         Args:
@@ -91,27 +93,43 @@ class XUIClient:
         self.session_duration: int = session_duration
         self.xui_username: str | None = username
         self.xui_password: str | None = password
-        self.two_fac_secret: str | None = two_fac_code
+        self.two_fac_secret: SecretStr | None = SecretStr(two_fac_code) if two_fac_code is not None else None
         self.totp: pyotp.TOTP | None = None
-        self.max_retries: int = 5
-        self.retry_delay: int = 1
+        self.max_retries: int = max_retries
+        self.retry_delay: int = retry_delay
+        self.sub_gen = custom_sub_generator
         # endpoints
         self.server_end = endpoints.Server(self)
         self.clients_end = endpoints.Clients(self)
         self.inbounds_end = endpoints.Inbounds(self)
+        # Per-instance cache wrapper. Using a class-level @alru_cache() on the underlying coroutine binds the cache to
+        # the first event loop that touches it (see async_lru._check_loop), which breaks any caller that creates
+        # a new XUIClient on a fresh loop (e.g. each pytest-asyncio test). Building the wrapper here gives every
+        # instance its own cache bound to its own loop.
+        self.get_production_inbounds = alru_cache(maxsize=128)(self._get_production_inbounds_impl)
+        self._cache_cleaner_task: Task|None = None
         #init self.totp
         if self.two_fac_secret:
-            if self.two_fac_secret.isdigit() and len(self.two_fac_secret) <= 8:
+            if len(self.two_fac_secret.get_secret_value()) <= 8:
                 print("WARNING: You seem to have entered a 2FA **code**, not a 2FA secret."
                       "Although entering the secret is dangerous, there is no other way to provide a consistent way"
                       "for continuous login. This code will only work for this specific login.")
                 self.totp = None
             else:
-                self.totp = pyotp.TOTP(self.two_fac_secret)
+                self.totp = pyotp.TOTP(self.two_fac_secret.get_secret_value())
 
     #========================request stuffs========================
+    @overload
+    async def _safe_request(self, *, request_to_send: httpx.Request) -> Response:
+        ...
+
+    @overload
+    async def _safe_request(self, method: Literal["get", "post", "patch", "delete", "put"],
+                            **kwargs) -> Response:
+        ...
+
     async def _safe_request(self,
-                            method: Literal["get", "post", "patch", "delete", "put"],
+                            method: Literal["get", "post", "patch", "delete", "put"]|None=None,
                             **kwargs) -> Response:
         """Execute an HTTP request with automatic retry on database lock.
 
@@ -128,9 +146,23 @@ class XUIClient:
         Raises:
             RuntimeError: If max retries exceeded or session is invalid.
         """
-        logging.debug("Safe request is running to %s%s", str(self.session.base_url), str(kwargs["url"]))
+        if "request_to_send" in kwargs and len(kwargs.keys()) != 1:
+            raise ValueError("It's either a predetermined a request or args to build your own.")
+        if not "request_to_send" in kwargs:
+            if method is None:
+                raise ValueError("If there's no prebuilt request, you must provide a method.")
+
+        #FIXME: make it also extract JSON out of a ready request
+        logging.info("Safe %s is running to %s%s\nJSON Payload: %s",
+                      method, str(self.session.base_url), str(kwargs["url"]) or kwargs["request_to_send"].url,
+                      json.dumps(kwargs["json"]) if "json" in kwargs.keys() else "(no payload)")
         async for attempt in async_range(self.max_retries):
-            resp = await self.session.request(method=method, **kwargs)
+            if "request_to_send" in kwargs:
+                _request: Request = kwargs["request_to_send"]
+                resp = await self.session.send(_request)
+            else:
+                # noinspection PyTypeChecker
+                resp = await self.session.request(method, **kwargs)
             if resp.status_code // 100 != 2:  #because it can return either 201 or 202
                 if resp.status_code == 404:
                     now: float = datetime.now(UTC).timestamp()
@@ -257,7 +289,7 @@ class XUIClient:
             payload["twoFactorCode"] = self.totp.now()
         else:
             if self.two_fac_secret:
-                payload["twoFactorCode"] = self.two_fac_secret
+                payload["twoFactorCode"] = self.two_fac_secret.get_secret_value()
 
         logging.info("Client is logging in with IP/Domain: %s", self.base_host)
         resp = await self.session.post("/login", data=payload)
@@ -289,8 +321,12 @@ class XUIClient:
 
         This method closes the async HTTP client session.
         """
+        if self._cache_cleaner_task is not None:
+            self._cache_cleaner_task.cancel("Panel is exiting.")
         self.connected = False
-        await self.session.aclose()
+
+        if self.session is not None:
+            await self.session.aclose()
 
     async def __aenter__(self) -> Self:
         """Enter the async context manager.
@@ -304,7 +340,9 @@ class XUIClient:
         """
         self.connect()
         await self.login()
-        asyncio.create_task(self.clear_prod_inbound_cache())
+        self._cache_cleaner_task = asyncio.create_task(
+            self.clear_prod_inbound_cache(), name=f"inb_cache_clearer_for_{self.base_url}"
+        )
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
@@ -323,21 +361,22 @@ class XUIClient:
         else:
             logging.warning("Client is disconnecting due to an error (may be unrelated):"
                             "\n%s, with value %s\nStacktrace:%s",
-                            exc_type, exc_val, exc_tb)
+                            exc_type, exc_val, exc_tb, exc_info=exc_tb)
         print(f"Client is disconnecting: {self.base_host}")
         await self.disconnect()
         return
 
     #========================inbound management========================
-    @alru_cache()
-    async def get_production_inbounds(self) -> Tuple[Inbound, ...]:
+    async def _get_production_inbounds_impl(self) -> tuple[Inbound, ...]:
         """Retrieve production inbounds.
 
         This method fetches all inbounds and filters them based on the
-        production string. It is cached for efficiency.
+        production string. It is wrapped in a per-instance ``alru_cache``
+        in ``__init__`` and exposed as ``get_production_inbounds``; do not
+        call this method directly outside of that wrapper.
 
         Returns:
-            List[Inbound]: A list of production inbounds.
+            tuple[Inbound]: A list of production inbounds.
 
         Raises:
             RuntimeError: If no production inbounds are found.
@@ -400,7 +439,6 @@ class XUIClient:
                                          expiry_time: int=0,
                                          exist_ok: bool = False
                                          ) -> list[Response]:
-        #TODO: add exist_ok flag
         """Create and add a production client.
 
         This method creates a new client with the given Telegram ID and
@@ -418,9 +456,14 @@ class XUIClient:
             List[Response]: A list of responses from the server for each
             inbound the client was added to.
         """
-        production_inbounds: List[Inbound] = await self.get_production_inbounds()
+        production_inbounds: tuple[Inbound, ...] = await self.get_production_inbounds()
 
         tasks = []
+        custom_sub: str
+        if iscoroutinefunction(self.sub_gen):
+            custom_sub = await self.sub_gen(telegram_id)
+        else:
+            custom_sub = self.sub_gen(telegram_id)
         for inb in production_inbounds:
             tmp_email = util.generate_email_from_tgid_inbid(telegram_id, inb.id)
             client = SingleInboundClient.model_construct(
@@ -429,7 +472,7 @@ class XUIClient:
                 email=tmp_email,
                 limit_gb=0,
                 enable=True,
-                subscription_id=util.sub_from_tgid(telegram_id),
+                subscription_id=custom_sub,
                 comment=f"{additional_remark}, created at {datetime.now(UTC)}",
                 expiry_time=expiry_time * 1000
             )
@@ -441,8 +484,29 @@ class XUIClient:
             json_resp = resp.json()
             if "duplicate email" in json_resp["msg"].lower():
                 logging.error("ERROR: Client already exists and exist_ok not set: %s", json_resp["msg"])
+                raise custom_exceptions.ClientEmailAlreadyExistsError(json_resp["msg"])
         return responses
 
+    async def _find_client_in_inbound(self, client_uuid: str, inbound_id: int) -> SingleInboundClient|None:
+        prod_inbs = await self.get_production_inbounds() #check production first since they're all cached
+        prod_inb_index = None
+        for i, prod_inb in enumerate(prod_inbs):  # see if inbound is production
+            if inbound_id == prod_inb.id:
+                prod_inb_index = i
+
+        if prod_inb_index is not None:
+            needed_inb: Inbound = prod_inbs[prod_inb_index]
+            for client in needed_inb.settings.clients:
+                if client.uuid == client_uuid:
+                    return client
+            self.get_production_inbounds.cache_clear() # this means client is in a prod inbound but it's not refreshed
+
+        inb = await self.inbounds_end.get_specific_inbound(inbound_id)
+        for client in inb.settings.clients:
+            if client.uuid == client_uuid:
+                return client
+        return None
+
     async def update_client_by_tgid(self, telegram_id: int, inbound_id: int, /, *,
                                     security: str | None = None,
                                     password: str | None = None,
@@ -460,23 +524,21 @@ class XUIClient:
         Args:
             telegram_id: The Telegram ID of the client
             inbound_id: The ID of the inbound where the client exists
-            security: Client security setting
-            password: Client password
-            flow: VLESS flow type
-            limit_ip: IP connection limit
-            limit_gb: Data limit in GB
-            expiry_time: Client expiry time (UNIX timestamp)
-            enable: Whether the client is enabled
-            sub_id: Subscription ID
-            comment: Client comment/note
+            security: Client security setting (optional)
+            password: Client password (optional)
+            flow: VLESS flow type (optional)
+            limit_ip: IP connection limit (optional)
+            limit_gb: Data limit in GB (optional)
+            expiry_time: Client expiry time (UNIX timestamp) (optional)
+            enable: Whether the client is enabled (optional)
+            sub_id: Subscription ID (optional)
+            comment: Client comment/note (optional)
 
         Returns:
             Response from the API
         """
-        email = util.generate_email_from_tgid_inbid(telegram_id, inbound_id)
-        existing_client = await self.clients_end.get_client_with_email(email)
         if verbose:
-            if expiry_time < 1e9:
+            if expiry_time and expiry_time < 1e9:
                 logging.warning("Warning: You're trying to update a client with expiry time %s. "
                                 "You set it to expire before 2001, likely because you provided the DURATION. "
                                 "You need to provide a TIMESTAMP. "
@@ -484,8 +546,7 @@ class XUIClient:
                                 expiry_time)
 
         resp = await self.clients_end.update_single_client(
-            SingleInboundClient.model_validate(existing_client.model_dump()),
-            inbound_id,
+            inbound_id=inbound_id, client_uuid=util.get_uuid_from_tgid(telegram_id),
             security=security,
             password=password,
             flow=flow,

{python_3xui-0.0.8 → python_3xui-0.0.9}/python_3xui/base_model.py

@@ -1,12 +1,9 @@
-import asyncio
-import logging
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Type, Union, overload, Self, ClassVar, Annotated, Literal, Callable
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Dict, List, Union, Self, ClassVar
 
-import pydantic
 import httpx
-from functools import cached_property
+import pydantic
 
-from . import models
 from . import util
 
 if TYPE_CHECKING:
@@ -34,13 +31,11 @@ class BaseModel(pydantic.BaseModel):
 
     @classmethod
     def from_list(cls, args: List[Dict[str, Any]],
-                  client: "XUIClient"
                   ) -> List[Self]:
         """Create a list of model instances from a list of dictionaries.
 
         Args:
             args: A list of dictionaries containing model data.
-            client: The XUIClient instance to associate with each model.
 
         Returns:
             A list of model instances initialized with the provided data.
@@ -83,12 +78,14 @@ class BaseModel(pydantic.BaseModel):
             inbounds = await Inbound.from_response(response, client, list)
         """
         json_resp: util.JsonType = response.json()
-        valid = util.check_xui_response(json_resp)
+        valid = await util.check_xui_response(json_resp)
         if valid == "OK":
             obj = json_resp["obj"]
             if expect is list:
-                return cls.from_list(obj, client=client)
+                return cls.from_list(obj)
             if expect is dict:
-                return cls(**obj, client=client)
+                return cls(**obj)
         else:
-            raise ValueError(f"Invalid 3X-UI response, code {valid}. Don't use from_response on failed requests.")
+            req = response.request
+            new_resp = await client._safe_request(request_to_send=req)
+            return await cls.from_response(new_resp, client=client, expect=expect, auto_retry=False)

python_3xui-0.0.9/python_3xui/custom_exceptions.py

@@ -0,0 +1,12 @@
+
+class ClientEmailAlreadyExistsError(Exception):
+    def __init__(self, *args):
+        super().__init__(args[0] if len(args) == 0 else args)
+
+class EmailNotExistsError(Exception):
+    def __init__(self, *args):
+        super().__init__(args[0] if len(args) == 0 else args)
+
+class ClientDoesNotExistError(Exception):
+    def __init__(self, *args):
+        super().__init__(args[0] if len(args) == 0 else args)