Python-3xui 0.0.8__py3-none-any.whl → 0.0.9__py3-none-any.whl

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/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/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/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)

python_3xui/endpoints.py

@@ -7,9 +7,9 @@ from httpx import Response
 from pydantic import ValidationError
 from pydantic.main import ModelT
 
-from . import models
 from .api import XUIClient
-from .models import Inbound, SingleInboundClient
+from .custom_exceptions import ClientDoesNotExistError
+from .models import Inbound, SingleInboundClient, ClientStats, InboundClients, timestamp_seconds, ClientsSettings
 from .util import JsonType
 
 
@@ -127,22 +127,22 @@ class Inbounds(BaseEndpoint):
             A list of Inbound model instances.
         """
         endpoint = "/list"
-        json = await self._simple_get(f"{endpoint}")
-        inbounds = Inbound.from_list(json, client=self.client)
+        json_resp = await self._simple_get(f"{endpoint}")
+        inbounds = Inbound.from_list(json_resp)
         return inbounds
 
-    async def get_specific_inbound(self, id) -> Inbound:
+    async def get_specific_inbound(self, inbound_id) -> Inbound:
         """Retrieve a specific inbound by ID.
 
         Args:
-            id: The ID of the inbound to retrieve.
+            inbound_id: The ID of the inbound to retrieve.
 
         Returns:
             An Inbound model instance for the specified ID.
         """
-        endpoint = f"/get/{id}"
+        endpoint = f"/get/{inbound_id}"
         json = await self._simple_get(f"{endpoint}")
-        inbound = Inbound(client=self.client, **json)
+        inbound = Inbound(**json)
         return inbound
 
 
@@ -163,7 +163,7 @@ class Clients(BaseEndpoint):
 
     #although it's the same url, they should be differentiated
 
-    async def get_client_with_email(self, email: str) -> models.ClientStats:
+    async def get_client_with_email(self, email: str) -> ClientStats:
         """Retrieve client statistics by email.
 
         Args:
@@ -174,9 +174,9 @@ class Clients(BaseEndpoint):
         """
         endpoint = f"getClientTraffics/{email}"
         resp = await self._simple_get(endpoint)
-        return models.ClientStats.model_validate(resp)
+        return ClientStats.model_validate(resp)
 
-    async def get_client_with_uuid(self, uuid: str) -> List[models.ClientStats]:
+    async def get_client_with_uuid(self, uuid: str) -> List[ClientStats]:
         """Retrieve client statistics by UUID.
 
         Args:
@@ -187,11 +187,10 @@ class Clients(BaseEndpoint):
         """
         endpoint = f"getClientTrafficsById/{uuid}"
         resp = await self._simple_get(endpoint)
-        client_stats = models.ClientStats.from_list(resp, client=self.client)
+        client_stats = ClientStats.from_list(resp)
         return client_stats
 
-
-    async def add_client(self, client: models.InboundClients | models.SingleInboundClient | Dict,
+    async def add_client(self, client: InboundClients | SingleInboundClient | Dict,
                          inbound_id: int | None = None) -> Response:
         """Add a new client to an inbound.
 
@@ -213,78 +212,73 @@ class Clients(BaseEndpoint):
         endpoint = f"addClient"
         if isinstance(client, Dict):
             try:
-                client = str(client)
-                final = models.InboundClients.model_validate_json(client)
+                final = InboundClients.model_validate(client)
             except ValidationError:
-                # if there is in fact an error, I want it to raise
-                tmp = models.SingleInboundClient.model_validate_json(client)
+                # Check the SingleInboundClient now...
+                tmp = SingleInboundClient.model_validate(client)
                 if inbound_id:
-                    final = models.InboundClients(id=inbound_id,
-                                                  settings=models.InboundClients.Settings(clients=[tmp]))
+                    final = InboundClients(id=inbound_id,
+                                           settings=ClientsSettings(clients=[tmp]))
                 else:
                     raise ValueError("A single client was provided to be added but no parent inbound id")
-        elif isinstance(client, models.SingleInboundClient):
-            final = models.InboundClients(id=inbound_id,
-                                          settings=models.InboundClients.Settings(clients=[client]))
-        elif isinstance(client, models.InboundClients):
+        elif isinstance(client, SingleInboundClient):
+            final = InboundClients(id=inbound_id,
+                                   settings=ClientsSettings(clients=[client]))
+        elif isinstance(client, InboundClients):
             final = client
             if inbound_id:
                 final.parent_id = inbound_id
         else:
             raise TypeError
         # send request
-        data = final.model_dump(by_alias=True)
-        resp = await self.client.safe_post(f"{self._url}{endpoint}", data=data)
-        #YOU NEED TO PASS SETTINGS AS A STRING, NOT AS A DICT, YOU FUCKING DUMBASS!
+        data = json.loads(final.model_dump_json(by_alias=True))
+        resp = await self.client.safe_post(f"{self._url}{endpoint}", json=data)
+        #YOU NEED TO PASS SETTINGS AS A STRING, NOT AS A DICT, YOU IDIOT!
         return resp
 
-    async def _request_update_client(self, client: models.InboundClients | models.SingleInboundClient,
+    async def _request_update_client(self, client: InboundClients | SingleInboundClient,
                                      inbound_id: int | None = None,
                                      *, original_uuid: str | None = None) -> Response:
         """Request to update an existing client.
 
         Args:
             client: The client data to update. Can be:
+                - A ClientUpdatePayload - Recommended (requires inbound_id)
                 - A SingleInboundClient (requires inbound_id)
                 - An InboundClients object (with one client)
             inbound_id: The ID of the inbound the client belongs to.
-                Required if client is a SingleInboundClient.
+                Required if client is a SingleInboundClient or ClientUpdatePayload.
             original_uuid: The original UUID of the client to update.
-                Required if client is a SingleInboundClient.
+                Required if client is a SingleInboundClient or ClientUpdatePayload.
 
         Returns:
             The HTTP response from the API.
         """
-        if isinstance(client, models.SingleInboundClient):
-            if inbound_id is None:
-                raise ValueError("Provide a parent inbound ID or pass models.InboundClients")
-            client = models.InboundClients(parent_id=inbound_id,
-                                           settings=models.InboundClients.Settings(clients=[client]))
-        else:
-            if len(client.settings.clients) != 1:
-                raise ValueError(f"You can only update 1 client at a time, instead got {len(client.settings.clients)}")
-
+        if isinstance(client, SingleInboundClient):
+            client = InboundClients(id=inbound_id, settings=ClientsSettings(clients=[client]))
         _endpoint = f"updateClient/{original_uuid if original_uuid else client.settings.clients[0].uuid}"
-        resp = await self.client.safe_post(f"{self._url}{_endpoint}", json=client.model_dump_json())
-
+        #we have to do this because if we do model.dump() it will return a Settings **OBJECT** which we DON'T want.
+        resp = await self.client.safe_post(f"{self._url}{_endpoint}",
+                                           json=json.loads(client.model_dump_json(exclude_none=True, by_alias=True)))
         return resp
 
-    async def update_single_client(self, existing_client: SingleInboundClient, inbound_id: int, /, *,
+
+    async def update_single_client(self, inbound_id: int, client_uuid: str, *,
                                    security: str | None = None,
                                    password: str | None = None,
                                    flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
                                    email: str | None = None,
                                    limit_ip: int | None = None,
                                    limit_gb: int | None = None,
-                                   expiry_time: models.timestamp_seconds | None = None,
+                                   expiry_time: timestamp_seconds | None = None,
                                    enable: bool | None = None,
                                    sub_id: str | None = None,
                                    comment: str | None = None,
-                                   ):
+                                   ) -> Response:
         """Update an existing client's details.
 
         Args:
-            existing_client: The existing client object to update.
+            client_uuid: The UUID of the original client.
             inbound_id: The ID of the inbound the client belongs to.
             security: New security settings (optional).
             password: New password (optional).
@@ -302,13 +296,17 @@ class Clients(BaseEndpoint):
         """
         # Collect only the arguments that were explicitly provided (not None)
         changes = {k: v for k, v in locals().items()
-                   if k != 'self' and k != 'existing_client' and v is not None}
+                   if k not in ("self", "inbound_id", "client_uuid", "changes") and v is not None}
         # Rename sub_id to subscription_id if needed
         if 'sub_id' in changes:
             changes['subscription_id'] = changes.pop('sub_id')
-        changes["updated_at"] = int(datetime.now(UTC).timestamp())
-        updated = existing_client.model_copy(update=changes)
 
+        found_inbound = await self.client._find_client_in_inbound(client_uuid, inbound_id)
+        if not found_inbound:
+            raise ClientDoesNotExistError(f"The target inbound was checked but client {client_uuid} was not found.")
+
+        changes["updated_at"] = int(datetime.now(UTC).timestamp())
+        updated = found_inbound.model_copy(update=changes)
         resp = await self._request_update_client(updated, inbound_id)
         return resp
 

python_3xui/models.py

@@ -4,6 +4,7 @@ from typing import Union, TypeAlias, Any, Annotated, Literal, List, Dict, ClassV
 
 import pydantic
 from pydantic import field_validator, Field, field_serializer
+from typing_extensions import TypeVar
 
 from . import base_model
 from .util import JsonType, auto_s_to_ms_timestamp, auto_ms_to_s_timestamp
@@ -12,6 +13,7 @@ timestamp_seconds: TypeAlias = int
 ip_address: TypeAlias = str
 json_string: TypeAlias = str
 
+
 def exclude_if_none(field) -> bool:
     """Check if a field value is None for exclusion purposes.
 
@@ -25,6 +27,10 @@ def exclude_if_none(field) -> bool:
         return True
     return False
 
+
+_IntNone = TypeVar("_IntNone", bound=int | None)
+
+
 class SingleInboundClient(pydantic.BaseModel):
     """Represents a single client within a VLESS/VMess inbound.
 
@@ -48,14 +54,15 @@ class SingleInboundClient(pydantic.BaseModel):
         updated_at: Timestamp of last client update.
     """
     TIME_FIELDS: ClassVar[List[str]] = ["expiry_time", "created_at", "updated_at"]
-    uuid:  Annotated[str, Field(alias="id")] #yes they really did that...
+    uuid: Annotated[str, Field(alias="id")]  #yes they really did that...
     security: str = ""
     password: str = ""
     flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"]
     email: Annotated[str, Field(alias="email")]
     limit_ip: Annotated[int, Field(alias="limitIp")] = 20
+    reset: int = 0
     #Interestingly, the API expects this value to be called GB but it's actually bytes.
-    limit_gb: Annotated[int, Field(alias="totalGB")] # total flow
+    limit_gb: Annotated[int, Field(alias="totalGB")] = 0  # total flow
     expiry_time: Annotated[timestamp_seconds, Field(alias="expiryTime")] = 0
     enable: bool = True
     tg_id: Annotated[Union[int, str], Field(alias="tgId")] = ""
@@ -68,19 +75,35 @@ class SingleInboundClient(pydantic.BaseModel):
         default_factory=(lambda: int(datetime.now(UTC).timestamp())))
     ]
 
-    @classmethod
+    # noinspection PyNestedDecorators
     @field_validator(TIME_FIELDS[0], *TIME_FIELDS[1:], mode="after")
-    def ensure_s_timestamp(cls, value: int) -> int:
+    @classmethod
+    def ensure_s_timestamp(cls, value: _IntNone) -> _IntNone:
         return auto_ms_to_s_timestamp(value)
 
-    @classmethod
+    # noinspection PyNestedDecorators
     @field_serializer(TIME_FIELDS[0], *TIME_FIELDS[1:])
-    def serialize_ms_timestamp(cls, value: int) -> int:
-        return auto_s_to_ms_timestamp(value)
+    @classmethod
+    def serialize_ms_timestamp(cls, value: _IntNone) -> _IntNone:
+        return auto_s_to_ms_timestamp(value) if value is not None else None
 
+    # noinspection PyNestedDecorators
     @field_serializer("limit_gb")
-    def serialize_total_gb(self, value: int) -> int:
-        return value * (1024 ** 2)  # Convert GB to bytes for API
+    @classmethod
+    def serialize_total_gb(cls, value: _IntNone) -> _IntNone:
+        return value * (1024 ** 3) if value is not None else None
+
+
+class ClientsSettings(pydantic.BaseModel):
+    """Settings container for inbound clients.
+
+    Attributes:
+        clients: List of SingleInboundClient objects.
+    """
+    clients: list[SingleInboundClient]
+    decryption: Annotated[str, Field(exclude_if=lambda x: x == "none")] = "none"
+    encryption: Annotated[str, Field(exclude_if=lambda x: x == "none")] = "none"
+    fallbacks: Annotated[list|None, Field(exclude_if=exclude_if_none)] = None
 
 
 class InboundClients(pydantic.BaseModel):
@@ -94,24 +117,16 @@ class InboundClients(pydantic.BaseModel):
         settings: The settings object containing the client list.
     """
 
-    class Settings(pydantic.BaseModel):
-        """Settings container for inbound clients.
-
-        Attributes:
-            clients: List of SingleInboundClient objects.
-        """
-        clients: list[SingleInboundClient]
-
-    parent_id: Annotated[int|None, Field(exclude_if=exclude_if_none, alias="id")] = None
-    settings: Settings
+    parent_id: Annotated[int | None, Field(exclude_if=exclude_if_none, alias="id")] = None
+    settings: ClientsSettings
 
     @field_serializer("settings")
-    def stringify_settings(self, value: Settings) -> str:
+    def stringify_settings(self, value: ClientsSettings) -> str:
         """Serialize the settings object to a JSON string.
 
         The 3X-UI API expects settings as a JSON string, not an object.
         """
-        return json.dumps(value.model_dump(by_alias=True), ensure_ascii=False)
+        return json.dumps(value.model_dump(by_alias=True, exclude_none=True), ensure_ascii=False)
 
 
 #class InboundSettings(base_model.BaseModel):
@@ -256,19 +271,30 @@ class Inbound(base_model.BaseModel):
     expiryTime: timestamp_seconds  # UNIX timestamp
     trafficReset: str  # "Never", "Weekly", "Monthly", "Daily"
     lastTrafficResetTime: timestamp_seconds  # UNIX timestamp
-    clientStats: Union[list[ClientStats], None]
+    clientStats: list[ClientStats] | None
     listen: str
     port: int
     protocol: Literal["vless", "vmess", "trojan", "shadowsocks", "wireguard"]  # note: there are some "deprecated" like wireguard
-    settings: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
+    settings: ClientsSettings  # JSON packed value, stringified
     streamSettings: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
     tag: str
     sniffing: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
 
-    # noinspection PyNestedDecorators
-    @field_validator('settings', 'streamSettings', 'sniffing', mode='after')
+    @field_validator("settings", mode="before")
     @classmethod
-    def parse_json_fields(cls, value: str) -> JsonType|Literal[""]:
+    def parse_settings(cls, value: str) -> ClientsSettings:
+        if value == "":
+            return ClientsSettings(clients=[])
+        return ClientsSettings.model_validate_json(value, by_alias=True, extra="forbid")
+
+    @field_serializer("settings")
+    @classmethod
+    def dump_settings(cls, value: ClientsSettings) -> str:
+        return value.model_dump_json(by_alias=True)
+
+    @field_validator('streamSettings', 'sniffing', mode='after')
+    @classmethod
+    def parse_json_fields(cls, value: str) -> JsonType | Literal[""]:
         """Parse JSON string fields into dictionaries.
 
         The 3X-UI API returns settings, streamSettings, and sniffing as
@@ -278,10 +304,9 @@ class Inbound(base_model.BaseModel):
             return ""
         return json.loads(value)
 
-    # noinspection PyNestedDecorators
-    @field_serializer("settings", "streamSettings", "sniffing")
+    @field_serializer("streamSettings", "sniffing")
     @classmethod
-    def stringify_json_fields(cls, value: Dict|Literal[""]) -> str:
+    def stringify_json_fields(cls, value: Dict | Literal[""]) -> str:
         """Serialize dictionary fields back to JSON strings.
 
         When sending data back to the API, these fields must be JSON strings.

python_3xui/util.py

@@ -14,7 +14,7 @@ import logging
 import random
 import re
 from datetime import UTC, datetime, tzinfo
-from typing import TypeAlias, Union, Dict, Any, List, dataclass_transform
+from typing import TypeAlias, Union, Dict, Any, List
 
 import httpx
 
@@ -43,7 +43,7 @@ def camel_to_snake(name: str) -> str:
     return re.sub(_RE_CAMEL_TO_SNAKE2, r"\1_\2", name).lower()
 
 
-async def async_range(start, stop=None, step=1):
+async def async_range(start: int, stop: int|None=None, step: int=1):
     """Async generator that yields values from a range.
 
     This is an async version of the built-in range() function that yields
@@ -79,7 +79,7 @@ def base64_from_string(string: str, omit_trailing_equals: bool = False) -> str:
     return base64.b64encode(bytes(str(string).encode("utf-8"))).decode()
 
 
-def sub_from_tgid(telegram_id: int) -> str:
+def default_sub_from_tgid(telegram_id: int) -> str:
     """Generate a subscription ID from a Telegram ID.
 
     Args:
@@ -124,6 +124,12 @@ def get_uuid_from_tgid(telegram_id: int, fixed: bool = True) -> str:
     return f"{now.year}{mon}{day}-{hr}{mn}-1111-1111-{resid}"
 
 
+def random_string(length: int):
+    s = "".join([random.choice(
+        "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") for _ in range(length)
+    ])
+    return s
+
 def generate_random_email(length: int = 8) -> str:
     """Generate a random alphanumeric email identifier.
 
@@ -136,10 +142,7 @@ def generate_random_email(length: int = 8) -> str:
     Examples:
         >>> generate_random_email(8)  # Random output like 'aB3xY9zQ'
     """
-    s = ""
-    for i in range(length):
-        s += random.choice("1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
-    return s
+    return random_string(length)
 
 
 def generate_email_from_tgid_inbid(telegram_id: int, /, inbound_id: int) -> str:
@@ -174,10 +177,7 @@ def generate_new_subscription(length: int = 16):
     Examples:
         >>> generate_new_subscription(16)  # Random output like 'aB3xY9zQmNpL2kJh'
     """
-    s = ""
-    for i in range(length):
-        s += random.choice("1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
-    return s
+    return random_string(length)
 
 
 async def check_xui_response(response: JsonType | httpx.Response) -> str:
@@ -230,13 +230,13 @@ def get_days_until_expiry(expiry_time: int) -> float:
 
     Returns:
         Number of days until expiry. Returns negative value if already expired.
-        Returns a very 0 if expiry_time is 0 (no expiry).
+        Returns a 0 if expiry_time is 0 (no expiry).
 
     Examples:
         >>> get_days_until_expiry(int(datetime.now(UTC).timestamp()) + 86400)  # 1 day from now
         1.0
         >>> get_days_until_expiry(0)  # No expiry
-        inf
+        0
     """
     if expiry_time == 0:
         return 0
@@ -283,6 +283,6 @@ def auto_ms_to_s_timestamp(ms_or_s: int) -> int:
         return ms_to_s_timestamp(ms_or_s)
     return ms_or_s
 
-def datetime_now_ms(tzinfo: tzinfo|None) -> int:
+def datetime_now_ms(tzinfo: tzinfo|None=UTC) -> int:
     """Get the current time as a UNIX timestamp in milliseconds."""
     return int(datetime.now(tzinfo).timestamp()) * 1000

{python_3xui-0.0.8.dist-info → python_3xui-0.0.9.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+python_3xui/__init__.py,sha256=tYFn1NixqukOf4c4JVsTFSXGvW-f_ErxqUbVJxYiJAU,100
+python_3xui/api.py,sha256=D-3tA0i09Rhhv1wHfTbdefGN81BT4ESxMvM699R-SRA,25892
+python_3xui/base_model.py,sha256=3jFVwPgMyVIck2W8vqzIz9cLookdleENUCCSIpdKISo,3211
+python_3xui/custom_exceptions.py,sha256=hf25_vHhhYaAThhuVW8z-pNznlzU0j6yayVixP9d3XY,410
+python_3xui/endpoints.py,sha256=HhO7z5IYp0gS0upKlfi3hcYwPPZWU17zWuElMwWOxnw,13391
+python_3xui/models.py,sha256=B0BxOYFffsFn61YWHPj27VIS-N0J9uL5rUsRzV1pW1c,12262
+python_3xui/util.py,sha256=SrOziaXxRj_YAHiUBjzmfRxWOKKLO80UgUUTnJ3tp-A,9239
+python_3xui-0.0.9.dist-info/METADATA,sha256=evF8LSqVGIrbO9z9el67KIC5NvHv6AJvNyp_Hyb9C_8,1957
+python_3xui-0.0.9.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_3xui-0.0.9.dist-info/licenses/LICENSE,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
+python_3xui-0.0.9.dist-info/RECORD,,

python_3xui-0.0.8.dist-info/RECORD

@@ -1,10 +0,0 @@
-python_3xui/__init__.py,sha256=Zb_-gNgvpe1LS95EKksaLFVM2wgWuXzoFb4pb3DZB_o,94
-python_3xui/api.py,sha256=w7vPgQrvxnymzZtkLOqZb8nYjwdCuMrhklVVxyEC8ts,22347
-python_3xui/base_model.py,sha256=qNQKS_oq5um5dAmpHSB5XhKy_06VJLXYu4eO9Jd50ac,3361
-python_3xui/endpoints.py,sha256=6F7bfMV8i-DnRJx186YLWTjSdTqocdfGHSpZ7NxAt7E,13352
-python_3xui/models.py,sha256=LjbzA9H6Zmrv3qRDQBIaxBiq7NACINiDpl0Uhvh_hK4,11369
-python_3xui/util.py,sha256=PgnlUPQrysThhB5_PpwVdsQb94BF0LTEGC-XuIEgNU8,9277
-python_3xui-0.0.8.dist-info/METADATA,sha256=nGsuWThDwbm4whPk-lBtZQeiJyFaD1MVjHfhPuVI4AY,1520
-python_3xui-0.0.8.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_3xui-0.0.8.dist-info/licenses/LICENSE,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-python_3xui-0.0.8.dist-info/RECORD,,