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

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.9
+Version: 0.0.9.post2
 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
@@ -17,7 +17,6 @@ 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'

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

@@ -1,6 +1,6 @@
 [project]
 name = "Python-3xui"
-version = "0.0.9"
+version = "0.0.9r2"
 authors = [
   { name="JustMe_001", email="justme001.causation755@passinbox.com" },
 ]
@@ -23,7 +23,6 @@ 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"
 ]

python_3xui-0.0.9.post2/python_3xui/__init__.py

@@ -0,0 +1,9 @@
+"""Public package interface for the python_3xui API wrapper."""
+
+from .api import XUIClient
+
+__author__ = "JustMe_001"
+__version__ = "0.0.9r2"
+__email__ = ""
+
+

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

@@ -8,6 +8,7 @@ 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 contextlib
 
 import httpx
 import pyotp
@@ -17,19 +18,20 @@ from pydantic import SecretStr
 
 from . import custom_exceptions
 from . import util
+from . import endpoints
 from .models import Inbound, SingleInboundClient, ClientStats
-from .util import JsonType, async_range
+from .util import JsonType, async_range, get_inbound_in_client
 
 DataType: Type[str | bytes | Iterable[bytes] | AsyncIterable[bytes]] = Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]
 PrimitiveData = Optional[Union[str, int, float, bool]]
 ParamType = Union[
     Mapping[str, Union[PrimitiveData, Sequence[PrimitiveData]]],
-    List[Tuple[str, PrimitiveData]],
-    Tuple[Tuple[str, PrimitiveData], ...],
+    list[Tuple[str, PrimitiveData]],
+    tuple[Tuple[str, PrimitiveData], ...],
     str,
     bytes,
 ]
-CookieType = Union[Dict[str, str], List[Tuple[str, str]]]
+CookieType = Union[Dict[str, str], list[tuple[str, str]]]
 HeaderType = Union[
     Mapping[str, str],
     Mapping[bytes, bytes],
@@ -43,21 +45,26 @@ class XUIClient:
 
     This class provides methods for authenticating with the 3X-UI panel,
     managing sessions, and performing operations on inbounds and clients.
+    It also owns the endpoint handlers and the per-instance production
+    inbound cache.
 
     Attributes:
-        PROD_STRING: String used to identify production inbounds.
-        session: The async HTTP client session.
+        connected: Whether an HTTP session is currently open.
+        PROD_STRING: Compiled regex used to identify production inbounds.
+        session: The async HTTP client session, if connected.
         base_host: The server hostname.
         base_port: The server port.
         base_path: The base path for the API.
         base_url: The full base URL for API requests.
         session_start: Timestamp of when the session was created.
         session_duration: Maximum session duration in seconds.
-        username: Username for authentication.
-        password: Password for authentication.
-        two_fac_code: Two-factor authentication code (if enabled).
+        xui_username: Username for authentication.
+        xui_password: Password for authentication.
+        two_fac_secret: TOTP secret or one-shot 2FA code, if configured.
+        totp: TOTP generator used for repeated logins when a secret is provided.
         max_retries: Maximum number of retry attempts for failed requests.
         retry_delay: Delay in seconds between retries.
+        sub_gen: Callable used to derive subscription IDs from Telegram IDs.
         server_end: Server endpoint handler.
         clients_end: Clients endpoint handler.
         inbounds_end: Inbounds endpoint handler.
@@ -67,8 +74,8 @@ class XUIClient:
                  *, username: str | None = None, password: str | None = None,
                  two_fac_code: str | None = None, session_duration: int = 3600,
                  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,
+                 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.
 
@@ -78,10 +85,15 @@ class XUIClient:
             base_path: The base path for the API (e.g., "/panel").
             username: Username for authentication.
             password: Password for authentication.
-            two_fac_code: Two-factor authentication code (if enabled).
+            two_fac_code: TOTP secret for 2FA. Short one-shot codes are
+                accepted for the current login only.
             session_duration: Maximum session duration in seconds. Defaults to 3600.
+            custom_prod_string: Regex pattern used to select production inbounds.
+            max_retries: Maximum retries for database-lock responses.
+            retry_delay: Seconds to wait between database-lock retries.
+            custom_sub_generator: Sync or async callable that receives a
+                Telegram ID and returns the subscription ID for new clients.
         """
-        from . import endpoints  # look, I know it's bad, but we need to evade cyclical imports
         self.connected: bool = False
         self.PROD_STRING = re.compile(custom_prod_string)
         self.session: AsyncClient | None = None
@@ -107,7 +119,7 @@ class XUIClient:
         # 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
+        self._cache_cleaner_task: Task | None = None
         #init self.totp
         if self.two_fac_secret:
             if len(self.two_fac_secret.get_secret_value()) <= 8:
@@ -129,33 +141,52 @@ class XUIClient:
         ...
 
     async def _safe_request(self,
-                            method: Literal["get", "post", "patch", "delete", "put"]|None=None,
+                            method: Literal["get", "post", "patch", "delete", "put"] | None = None,
                             **kwargs) -> Response:
         """Execute an HTTP request with automatic retry on database lock.
 
-        This method handles automatic session refresh and retries when
-        the 3X-UI database is locked.
+        The request can be made either from a prebuilt ``request_to_send`` or
+        from an HTTP method plus keyword arguments accepted by ``httpx``.
+        The method handles automatic session refresh on expired 404 responses
+        and retries when the 3X-UI database is locked.
 
         Args:
-            method: The HTTP method to use.
-            **kwargs: Additional arguments passed to the HTTP request.
+            method: The HTTP method to use when building a new request.
+            **kwargs: Either ``request_to_send`` by itself, or request
+                arguments such as ``url``, ``json``, ``params``, and headers.
 
         Returns:
             The HTTP response.
 
         Raises:
-            RuntimeError: If max retries exceeded or session is invalid.
+            ValueError: If neither a method nor a prebuilt request is provided,
+                or both request styles are mixed.
+            RuntimeError: If max retries are exceeded or a valid session gets
+                an unexpected 404 response.
         """
         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.")
+            raise ValueError("Provide either a prebuilt request or arguments to build one.")
         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
+        url = kwargs["url"] if "url" in kwargs.keys() else kwargs["request_to_send"].url
+        if "json" in kwargs:
+            json_payload = kwargs["json"]
+        elif "request_to_send" in kwargs:
+            _req = kwargs["request_to_send"]
+            if _req.content:
+                try:
+                    json_payload = json.loads(_req.content.decode())
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    json_payload = None
+            else:
+                json_payload = None
+        else:
+            json_payload = None
         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)")
+                     method, str(self.session.base_url), str(url),
+                     json.dumps(json_payload) if json_payload is not None else "(no payload)")
         async for attempt in async_range(self.max_retries):
             if "request_to_send" in kwargs:
                 _request: Request = kwargs["request_to_send"]
@@ -295,11 +326,12 @@ class XUIClient:
         resp = await self.session.post("/login", data=payload)
         if resp.status_code == 200:
             resp_json = resp.json()
-            if resp_json["success"]:
-                self.session_start: float = (datetime.now(UTC).timestamp())
-                return
-            else:
+            if "success" not in resp_json:
+                raise RuntimeError(f"Error: server returned a status code of {resp.status_code} but the response is not valid: {resp_json}")
+            if not resp_json["success"]:
                 raise ValueError("Error: wrong credentials (including status code) or failed login.")
+            self.session_start: float = (datetime.now(UTC).timestamp())
+            return
         else:
             raise RuntimeError(f"Error: server returned a status code of {resp.status_code}")
 
@@ -322,7 +354,8 @@ 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.")
+            with contextlib.suppress(asyncio.CancelledError):
+                self._cache_cleaner_task.cancel("Panel is exiting.")
         self.connected = False
 
         if self.session is not None:
@@ -341,7 +374,7 @@ class XUIClient:
         self.connect()
         await self.login()
         self._cache_cleaner_task = asyncio.create_task(
-            self.clear_prod_inbound_cache(), name=f"inb_cache_clearer_for_{self.base_url}"
+            self._clear_prod_inbound_cache_task(), name=f"inb_cache_clearer_for_{self.base_url}"
         )
         return self
 
@@ -356,7 +389,7 @@ class XUIClient:
             exc_val: The exception value, if an exception occurred.
             exc_tb: The exception traceback, if an exception occurred.
         """
-        if exc_type is None or exc_type == asyncio.exceptions.CancelledError:
+        if exc_type is None or exc_type is asyncio.exceptions.CancelledError:
             logging.info("Client is disconnecting at time with IP/Domain %s", self.base_host)
         else:
             logging.warning("Client is disconnecting due to an error (may be unrelated):"
@@ -391,24 +424,23 @@ class XUIClient:
 
         return tuple(usable_inbounds)
 
-    async def clear_prod_inbound_cache(self):
-        """Clear the production inbound cache.
+    async def _clear_prod_inbound_cache_task(self):
+        """Refresh the production inbound cache in the background.
 
-        This method clears the cache of production inbounds and refills it
-        by fetching the inbounds again. It is intended to be run as a
-        background task.
-
-        Note:
-            This method currently runs every 10 seconds. Please change the
-            timer from 5 to 60*60*24 in the code.
+        The async context manager starts this loop after login. Each cycle
+        clears the cached production inbound list, repopulates it from the
+        panel, and then waits before refreshing again.
         """
+        if self._cache_cleaner_task is not None:
+            logging.warning("You're trying to create another cache cleaner task, which is a FaF (Fire-And-Forget)."
+                            "Please destroy the previous task and set _cache_cleaner_task to None, if you know what you're doing.")
         while self.connected:
             self.get_production_inbounds.cache_clear()
-            await self.get_production_inbounds()  #fill the cache
-            await asyncio.sleep(3600)  #update every 1h
+            await self.get_production_inbounds()  # fill the cache
+            await asyncio.sleep(3600)  # update every 1h
 
     #========================clients management========================
-    async def get_client_with_tgid(self, tgid: int, inbound_id: int | None = None) -> List[ClientStats]:
+    async def get_client_with_tgid(self, tgid: int, inbound_id: int | None = None) -> list[ClientStats]:
         """Retrieve client information by Telegram ID.
 
         This method fetches client information using the Telegram ID. If
@@ -436,25 +468,31 @@ class XUIClient:
 
     async def create_and_add_prod_client(self, telegram_id: int, *,
                                          additional_remark: str | None = None,
-                                         expiry_time: int=0,
+                                         expiry_time: int = 0,
                                          exist_ok: bool = False
                                          ) -> list[Response]:
         """Create and add a production client.
 
         This method creates a new client with the given Telegram ID and
         adds it to the production inbounds. The client is configured with
-        default settings and the additional remark.
-        Note that the sub id is created by util.generate_email_from_tgid_inbid, so use that to retrieve.
+        default settings and the additional remark. The subscription ID is
+        created by ``self.sub_gen``; by default this is
+        ``util.default_sub_from_tgid``.
 
         Args:
             telegram_id: The Telegram ID of the client.
             additional_remark: An optional additional remark for the client.
             expiry_time: Expiry time in SECONDS as a UNIX timestamp.
-            exist_ok: Don't raise any errors if the client is already there (good if you need a refresh job)
+            exist_ok: If True, return API responses even when the panel reports
+                a duplicate email.
 
         Returns:
             List[Response]: A list of responses from the server for each
             inbound the client was added to.
+
+        Raises:
+            ClientEmailAlreadyExistsError: If a duplicate client is reported
+                and ``exist_ok`` is False.
         """
         production_inbounds: tuple[Inbound, ...] = await self.get_production_inbounds()
 
@@ -466,15 +504,15 @@ class XUIClient:
             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(
+            client = SingleInboundClient(
                 uuid=util.get_uuid_from_tgid(telegram_id),
                 flow="",
                 email=tmp_email,
                 limit_gb=0,
                 enable=True,
                 subscription_id=custom_sub,
-                comment=f"{additional_remark}, created at {datetime.now(UTC)}",
-                expiry_time=expiry_time * 1000
+                comment=f"{additional_remark + ", " if additional_remark else ""}created at {datetime.now(UTC)}",
+                expiry_time=expiry_time * 1000,
             )
             tasks.append(asyncio.create_task(self.clients_end.add_client(client, inb.id)))
         responses: list[Response] = await asyncio.gather(*tasks)
@@ -487,19 +525,28 @@ class XUIClient:
                 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
+    async def _find_client_in_inbound(self, client_uuid: str, inbound_id: int, use_cache=False) -> SingleInboundClient | None:
+        """Note:
+            Cached production inbounds can be stale because the panel may be
+            changed by another actor. If a cached production inbound misses the
+            client, the production cache is cleared and fetched once more
+            before falling back to a direct inbound lookup.
+        """
+        if use_cache:
+            prod_inbs = await self.get_production_inbounds()
+            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]
+                result = get_inbound_in_client(client_uuid, needed_inb)
+                if result is None:
+                    self.get_production_inbounds.cache_clear()  # this means client is in a prod inbound but it's not refreshed
+                    new_inb = (await self.get_production_inbounds())[prod_inb_index]
+                    new_result = get_inbound_in_client(client_uuid, new_inb)
+                    return new_result
 
         inb = await self.inbounds_end.get_specific_inbound(inbound_id)
         for client in inb.settings.clients:
@@ -507,19 +554,97 @@ class XUIClient:
                 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,
-                                    flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
-                                    limit_ip: int | None = None,
-                                    limit_gb: int | None = None,
-                                    expiry_time: int | None = None,
-                                    enable: bool | None = None,
-                                    sub_id: str | None = None,
-                                    comment: str | None = None,
-                                    verbose: bool=True) -> Response:
+    async def update_client_by_tgid_only(self, telegram_id: int, prod_only: bool, /, *,
+                                         security: str | None = None,
+                                         password: str | None = None,
+                                         flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
+                                         limit_ip: int | None = None,
+                                         limit_gb: int | None = None,
+                                         expiry_time: int | None = None,
+                                         enable: bool | None = None,
+                                         sub_id: str | None = None,
+                                         comment: str | None = None,
+                                         verbose: bool = True
+                                         ) -> list[Response]:
+        """Update every matching client found by Telegram ID.
+
+        The client UUID is derived from ``telegram_id`` and searched across
+        either production inbounds or all inbounds. Only keyword arguments with
+        non-None values are applied to the client model before sending update
+        requests.
+
+        Args:
+            telegram_id: Telegram ID used to derive the client UUID.
+            prod_only: If True, search only production inbounds. If False,
+                search every inbound returned by the panel.
+            security: New security setting.
+            password: New password.
+            flow: New VLESS flow value.
+            limit_ip: New simultaneous IP connection limit.
+            limit_gb: New traffic limit in gigabytes.
+            expiry_time: New expiry timestamp in seconds.
+            enable: New enabled state.
+            sub_id: New subscription ID.
+            comment: New client comment.
+            verbose: If True, warn when ``expiry_time`` looks like a duration
+                instead of a UNIX timestamp.
+
+        Returns:
+            Responses from each inbound where a matching client was updated.
+        """
+        updates = {
+            "security": security,
+            "password": password,
+            "flow": flow,
+            "limit_ip": limit_ip,
+            "limit_gb": limit_gb,
+            "expiry_time": expiry_time,
+            "enable": enable,
+            "sub_id": sub_id,
+            "comment": comment,
+        }
+        # remove None values
+        updates = {k: v for k, v in updates.items() if v is not None}
+
+        if verbose:
+            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. "
+                                "If you want to disable this message, set verbose=false.",
+                                expiry_time)
+
+        _to_exec: list[Task] = []
+        if prod_only:
+            self.get_production_inbounds.cache_clear()
+            inbounds = await self.get_production_inbounds()
+        else:
+            inbounds = await self.inbounds_end.get_all()
+        for inbound in inbounds:
+            found_client = util.get_inbound_in_client(util.get_uuid_from_tgid(telegram_id), inbound)
+            if found_client:
+                new_client = found_client.model_copy(update=updates, deep=True)
+                _to_exec.append(
+                    asyncio.create_task(self.clients_end.request_update_client(
+                        new_client, inbound.id, original_uuid=util.get_uuid_from_tgid(telegram_id)
+                    ))
+                )
+        responses = await asyncio.gather(*_to_exec)
+        return responses
+
+    async def update_client_by_tgid_inbid(self, telegram_id: int, inbound_id: int, /, *,
+                                          security: str | None = None,
+                                          password: str | None = None,
+                                          flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
+                                          limit_ip: int | None = None,
+                                          limit_gb: int | None = None,
+                                          expiry_time: int | None = None,
+                                          enable: bool | None = None,
+                                          sub_id: str | None = None,
+                                          comment: str | None = None,
+                                          verbose: bool = True) -> Response:
         """
-        Update a client in a specific inbound by Telegram ID.
+        Update a client in a specific inbound by Telegram ID. NOT optimized for multiple inbounds.
 
         Args:
             telegram_id: The Telegram ID of the client
@@ -583,12 +708,12 @@ class XUIClient:
             List of Response objects from each deletion attempt
         """
         production_inbounds = await self.get_production_inbounds()
-        responses = []
-
+        _to_exec: list[Task] = []
         for inbound in production_inbounds:
             email = util.generate_email_from_tgid_inbid(telegram_id, inbound.id)
-            resp = await self.clients_end.delete_client_by_email(email, inbound.id)
-            responses.append(resp)
-        logging.info("Clients of of tgid %s deleted", telegram_id)
-
+            _to_exec.append(
+                asyncio.create_task(self.clients_end.delete_client_by_email(email, inbound.id))
+            )
+            logging.info("Clients of of tgid %s pending deletion", telegram_id)
+        responses = await asyncio.gather(*_to_exec)
         return responses

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

@@ -7,7 +7,7 @@ import pydantic
 from . import util
 
 if TYPE_CHECKING:
-    from api import XUIClient
+    from .api import XUIClient
 
 class BaseModel(pydantic.BaseModel):
     """Base model for all 3X-UI API data models.
@@ -22,7 +22,7 @@ class BaseModel(pydantic.BaseModel):
     ERROR_RETRIES: ClassVar[int] = 5
     ERROR_RETRY_COOLDOWN: ClassVar[int] = 1
 
-    model_config = pydantic.ConfigDict(ignored_types=(cached_property, ))
+    model_config = pydantic.ConfigDict(ignored_types=(cached_property, ), validate_by_name=True, validate_by_alias=True)
 
     # def model_post_init(self, context: Any, /) -> None:
     #     #print(f"Model {self.__class__}, {self} initialized")
@@ -41,7 +41,7 @@ class BaseModel(pydantic.BaseModel):
             A list of model instances initialized with the provided data.
 
         Examples:
-            inbounds = Inbound.from_list([{"id": 1}, {"id": 2}], client=xui_client)
+            inbounds = Inbound.from_list([{"id": 1}, {"id": 2}])
         """
         return [cls(**obj) for obj in args]
 
@@ -86,6 +86,9 @@ class BaseModel(pydantic.BaseModel):
             if expect is dict:
                 return cls(**obj)
         else:
-            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)
+            if auto_retry:
+                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)
+            else:
+                raise util.DBLockedError("Failed to create model instance from response")

python_3xui-0.0.9.post2/python_3xui/custom_exceptions.py

@@ -0,0 +1,27 @@
+
+class ClientEmailAlreadyExistsError(Exception):
+    """Raised when the panel rejects a new client because its email exists."""
+
+    def __init__(self, *args):
+        if len(args) == 1:
+            super().__init__(args[0])
+        else:
+            super().__init__(*args)
+
+class EmailNotExistsError(Exception):
+    """Raised when a requested client email cannot be found on the panel."""
+
+    def __init__(self, *args):
+        if len(args) == 1:
+            super().__init__(args[0])
+        else:
+            super().__init__(*args)
+
+class ClientDoesNotExistError(Exception):
+    """Raised when a requested client UUID is absent from the target inbound."""
+
+    def __init__(self, *args):
+        if len(args) == 1:
+            super().__init__(args[0])
+        else:
+            super().__init__(*args)

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/python_3xui/endpoints.py

@@ -1,17 +1,21 @@
 import json
 import logging
 from datetime import datetime, UTC
-from typing import Generic, Literal, List, Dict
+from typing import Generic, Literal, List, Dict, TypeVar, TYPE_CHECKING
 
 from httpx import Response
-from pydantic import ValidationError
-from pydantic.main import ModelT
+from pydantic import ValidationError, BaseModel
 
-from .api import XUIClient
+import pydantic
+
+if TYPE_CHECKING:
+    from .api import XUIClient
 from .custom_exceptions import ClientDoesNotExistError
 from .models import Inbound, SingleInboundClient, ClientStats, InboundClients, timestamp_seconds, ClientsSettings
 from .util import JsonType
 
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
 
 class BaseEndpoint(Generic[ModelT]):
     """Base class for API endpoint handlers.
@@ -120,7 +124,7 @@ class Inbounds(BaseEndpoint):
     """
     _url = "panel/api/inbounds"
 
-    async def get_all(self) -> List[Inbound]:
+    async def get_all(self) -> list[Inbound]:
         """Retrieve all inbounds from the server.
 
         Returns:
@@ -131,7 +135,7 @@ class Inbounds(BaseEndpoint):
         inbounds = Inbound.from_list(json_resp)
         return inbounds
 
-    async def get_specific_inbound(self, inbound_id) -> Inbound:
+    async def get_specific_inbound(self, inbound_id: int) -> Inbound:
         """Retrieve a specific inbound by ID.
 
         Args:
@@ -159,7 +163,7 @@ class Clients(BaseEndpoint):
         - /panel/api/inbounds/delDepletedClients/{inbound_id}
         - /panel/api/inbounds/{inbound_id}/delClient/{email|uuid}
     """
-    _url = "panel/api/inbounds/"
+    _url = "panel/api/inbounds"
 
     #although it's the same url, they should be differentiated
 
@@ -172,11 +176,11 @@ class Clients(BaseEndpoint):
         Returns:
             A ClientStats model instance with the client's statistics.
         """
-        endpoint = f"getClientTraffics/{email}"
+        endpoint = f"/getClientTraffics/{email}"
         resp = await self._simple_get(endpoint)
         return ClientStats.model_validate(resp)
 
-    async def get_client_with_uuid(self, uuid: str) -> List[ClientStats]:
+    async def get_client_with_uuid(self, uuid: str) -> list[ClientStats]:
         """Retrieve client statistics by UUID.
 
         Args:
@@ -185,7 +189,7 @@ class Clients(BaseEndpoint):
         Returns:
             A list of ClientStats model instances matching the UUID.
         """
-        endpoint = f"getClientTrafficsById/{uuid}"
+        endpoint = f"/getClientTrafficsById/{uuid}"
         resp = await self._simple_get(endpoint)
         client_stats = ClientStats.from_list(resp)
         return client_stats
@@ -209,8 +213,8 @@ class Clients(BaseEndpoint):
             ValueError: If a single client is provided without an inbound_id.
             TypeError: If the client type is not supported.
         """
-        endpoint = f"addClient"
-        if isinstance(client, Dict):
+        endpoint = f"/addClient"
+        if isinstance(client, dict):
             try:
                 final = InboundClients.model_validate(client)
             except ValidationError:
@@ -222,6 +226,8 @@ class Clients(BaseEndpoint):
                 else:
                     raise ValueError("A single client was provided to be added but no parent inbound id")
         elif isinstance(client, SingleInboundClient):
+            if not inbound_id:
+                raise ValueError("A single client was provided to be added but no parent inbound id")
             final = InboundClients(id=inbound_id,
                                    settings=ClientsSettings(clients=[client]))
         elif isinstance(client, InboundClients):
@@ -236,33 +242,31 @@ class Clients(BaseEndpoint):
         #YOU NEED TO PASS SETTINGS AS A STRING, NOT AS A DICT, YOU IDIOT!
         return resp
 
-    async def _request_update_client(self, client: InboundClients | SingleInboundClient,
-                                     inbound_id: int | None = None,
-                                     *, original_uuid: str | None = None) -> Response:
+    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 or ClientUpdatePayload.
+                Required if client is a SingleInboundClient.
             original_uuid: The original UUID of the client to update.
-                Required if client is a SingleInboundClient or ClientUpdatePayload.
+                Required by the 3X-UI update endpoint.
 
         Returns:
             The HTTP response from the API.
         """
         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}"
-        #we have to do this because if we do model.dump() it will return a Settings **OBJECT** which we DON'T want.
+        _endpoint = f"/updateClient/{original_uuid}"
+        # 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, inbound_id: int, client_uuid: str, *,
                                    security: str | None = None,
                                    password: str | None = None,
@@ -278,15 +282,15 @@ class Clients(BaseEndpoint):
         """Update an existing client's details.
 
         Args:
-            client_uuid: The UUID of the original client.
             inbound_id: The ID of the inbound the client belongs to.
+            client_uuid: The UUID of the original client.
             security: New security settings (optional).
             password: New password (optional).
             flow: New flow settings (optional).
             email: New email address (optional).
             limit_ip: New IP limit (optional).
-            limit_gb: New GB limit (optional).
-            expiry_time: New expiry time (optional).
+            limit_gb: New traffic limit in gigabytes (optional).
+            expiry_time: New expiry time as a UNIX timestamp in seconds (optional).
             enable: New enable status (optional).
             sub_id: New subscription ID (optional).
             comment: New comment (optional).
@@ -306,8 +310,9 @@ class Clients(BaseEndpoint):
             raise ClientDoesNotExistError(f"The target inbound was checked but client {client_uuid} was not found.")
 
         changes["updated_at"] = int(datetime.now(UTC).timestamp())
+        #TODO: see if model_copy actually does validation
         updated = found_inbound.model_copy(update=changes)
-        resp = await self._request_update_client(updated, inbound_id)
+        resp = await self.request_update_client(updated, inbound_id, original_uuid=client_uuid)
         return resp
 
     async def delete_expired_clients(self, inbound_id: int) -> Response:
@@ -319,7 +324,7 @@ class Clients(BaseEndpoint):
         Returns:
             The HTTP response from the API.
         """
-        _endpoint = f"delDepletedClients/"
+        _endpoint = f"/delDepletedClients/"
         resp = await self.client.safe_post(f"{self._url}{_endpoint}{inbound_id}")
         return resp
 
@@ -333,7 +338,7 @@ class Clients(BaseEndpoint):
         Returns:
             The HTTP response from the API.
         """
-        _endpoint = f"{inbound_id}/delClientByEmail/{email}"
+        _endpoint = f"/{inbound_id}/delClientByEmail/{email}"
         resp = await self.client.safe_post(f"{self._url}{_endpoint}")
         return resp
 
@@ -347,6 +352,6 @@ class Clients(BaseEndpoint):
         Returns:
             The HTTP response from the API.
         """
-        _endpoint = f"{inbound_id}/delClient/{uuid}"
+        _endpoint = f"/{inbound_id}/delClient/{uuid}"
         resp = await self.client.safe_post(f"{self._url}{_endpoint}")
         return resp

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/python_3xui/models.py

@@ -2,7 +2,6 @@ import json
 from datetime import datetime, UTC
 from typing import Union, TypeAlias, Any, Annotated, Literal, List, Dict, ClassVar
 
-import pydantic
 from pydantic import field_validator, Field, field_serializer
 from typing_extensions import TypeVar
 
@@ -31,7 +30,8 @@ def exclude_if_none(field) -> bool:
 _IntNone = TypeVar("_IntNone", bound=int | None)
 
 
-class SingleInboundClient(pydantic.BaseModel):
+# noinspection PyNestedDecorators
+class SingleInboundClient(base_model.BaseModel):
     """Represents a single client within a VLESS/VMess inbound.
 
     This model represents an individual VPN client with all its configuration
@@ -58,11 +58,12 @@ class SingleInboundClient(pydantic.BaseModel):
     security: str = ""
     password: str = ""
     flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"]
-    email: Annotated[str, Field(alias="email")]
+    email: str
     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")] = 0  # total flow
+    # I want the pythonic side to be in GB (hence why floats, i.e. 2.5GB), but the API expects bytes.
+    limit_gb: Annotated[int | float, 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")] = ""
@@ -75,26 +76,30 @@ class SingleInboundClient(pydantic.BaseModel):
         default_factory=(lambda: int(datetime.now(UTC).timestamp())))
     ]
 
-    # noinspection PyNestedDecorators
     @field_validator(TIME_FIELDS[0], *TIME_FIELDS[1:], mode="after")
     @classmethod
     def ensure_s_timestamp(cls, value: _IntNone) -> _IntNone:
         return auto_ms_to_s_timestamp(value)
 
-    # noinspection PyNestedDecorators
     @field_serializer(TIME_FIELDS[0], *TIME_FIELDS[1:])
     @classmethod
-    def serialize_ms_timestamp(cls, value: _IntNone) -> _IntNone:
-        return auto_s_to_ms_timestamp(value) if value is not None else None
+    def serialize_ms_timestamp(cls, value: int) -> int:
+        return auto_s_to_ms_timestamp(value)
 
-    # noinspection PyNestedDecorators
     @field_serializer("limit_gb")
     @classmethod
-    def serialize_total_gb(cls, value: _IntNone) -> _IntNone:
-        return value * (1024 ** 3) if value is not None else None
+    def serialize_total_gb(cls, value: int | float) -> int:
+        #API expects an integer of bytes.
+        return value * (1024 ** 3)
 
+    @field_validator("limit_gb", mode="after")
+    @classmethod
+    def parse_total_gb(cls, value: int) -> int | float:
+        #Python wants an int/float of GB.
+        return value / (1024 ** 3)
 
-class ClientsSettings(pydantic.BaseModel):
+
+class ClientsSettings(base_model.BaseModel):
     """Settings container for inbound clients.
 
     Attributes:
@@ -103,10 +108,10 @@ class ClientsSettings(pydantic.BaseModel):
     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
+    fallbacks: Annotated[list | None, Field(exclude_if=exclude_if_none)] = None
 
 
-class InboundClients(pydantic.BaseModel):
+class InboundClients(base_model.BaseModel):
     """Represents a collection of clients for an inbound connection.
 
     This model is used when adding or updating clients on an inbound,
@@ -187,6 +192,7 @@ class InboundClients(pydantic.BaseModel):
 #     external_proxy: Annotated[list[ExternalProxy], Field(alias="externalProxy")]
 #     tcp_settings: TCPSettings
 
+# noinspection PyNestedDecorators
 class ClientStats(base_model.BaseModel):
     """Statistics and configuration for a VPN client.
 
@@ -203,10 +209,12 @@ class ClientStats(base_model.BaseModel):
         up: Total uploaded bytes.
         down: Total downloaded bytes.
         allTime: Total bytes transferred (up + down).
-        expiryTime: Client expiry time as UNIX timestamp in MILLISECONDS.
+        expiryTime: Client expiry time as a UNIX timestamp in seconds on the
+            Python model, serialized to milliseconds for the API.
         total: Total data limit in bytes.
         reset: Counter for traffic resets.
-        lastOnline: UNIX timestamp of last connection.
+        lastOnline: UNIX timestamp of last connection in seconds on the
+            Python model, serialized to milliseconds for the API.
     """
     TIME_FIELDS: ClassVar[List[str]] = ["expiryTime", "lastOnline"]
     id: int
@@ -223,17 +231,18 @@ class ClientStats(base_model.BaseModel):
     reset: int
     lastOnline: timestamp_seconds
 
-    @classmethod
     @field_validator(TIME_FIELDS[0], *TIME_FIELDS[1:], mode="after")
+    @classmethod
     def ensure_s_timestamp(cls, value: int) -> int:
         return auto_ms_to_s_timestamp(value)
 
-    @classmethod
     @field_serializer(TIME_FIELDS[0], *TIME_FIELDS[1:])
+    @classmethod
     def serialize_ms_timestamp(cls, value: int) -> int:
         return auto_s_to_ms_timestamp(value)
 
 
+# noinspection PyNestedDecorators
 class Inbound(base_model.BaseModel):
     """Represents a VPN inbound connection configuration.
 
@@ -274,7 +283,8 @@ class Inbound(base_model.BaseModel):
     clientStats: list[ClientStats] | None
     listen: str
     port: int
-    protocol: Literal["vless", "vmess", "trojan", "shadowsocks", "wireguard"]  # note: there are some "deprecated" like wireguard
+    #TODO: add trojan, shadowsocks, wireguard back in when they are supported by the API
+    protocol: Literal["vless", "vmess"]  #"trojan", "shadowsocks", "wireguard"]  # note: there are some "deprecated" like wireguard
     settings: ClientsSettings  # JSON packed value, stringified
     streamSettings: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
     tag: str
@@ -315,12 +325,12 @@ class Inbound(base_model.BaseModel):
             return ""
         return json.dumps(value, ensure_ascii=False)
 
-    @classmethod
     @field_validator(TIME_FIELDS[0], *TIME_FIELDS[1:], mode="after")
+    @classmethod
     def ensure_s_timestamp(cls, value: int) -> int:
         return auto_ms_to_s_timestamp(value)
 
-    @classmethod
     @field_serializer(TIME_FIELDS[0], *TIME_FIELDS[1:])
+    @classmethod
     def serialize_ms_timestamp(cls, value: int) -> int:
         return auto_s_to_ms_timestamp(value)

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/python_3xui/util.py

@@ -1,6 +1,7 @@
-"""Utility functions and helpers for the VPNAPIHandler.
+"""Utility functions and helpers for the python_3xui package.
 
-This module provides common utilities used across the API handler including:
+This module provides common utilities used across the 3X-UI API wrapper,
+including:
 - String conversion helpers (camelCase to snake_case)
 - Async generators
 - Base64 encoding utilities
@@ -14,10 +15,13 @@ import logging
 import random
 import re
 from datetime import UTC, datetime, tzinfo
-from typing import TypeAlias, Union, Dict, Any, List
+from typing import TYPE_CHECKING, TypeAlias, Union, Dict, Any, List
 
 import httpx
 
+if TYPE_CHECKING:
+    from python_3xui.models import Inbound, SingleInboundClient
+
 JsonType: TypeAlias = Union[Dict[Any, Any], List[Any]]
 
 _RE_CAMEL_TO_SNAKE1 = re.compile("(.)([A-Z][a-z]+)")
@@ -57,13 +61,12 @@ async def async_range(start: int, stop: int|None=None, step: int=1):
     Yields:
         int: The next value in the range sequence.
     """
-    if stop:
+    if stop is not None:
         range_ = range(start, stop, step)
     else:
         range_ = range(start)
     for i in range_:
         yield i
-        await asyncio.sleep(0)
 
 
 def base64_from_string(string: str, omit_trailing_equals: bool = False) -> str:
@@ -71,10 +74,12 @@ def base64_from_string(string: str, omit_trailing_equals: bool = False) -> str:
 
     Args:
         string: The input string to encode.
-        omit_trailing_equals: If True, removes trailing '=' padding characters.
+        omit_trailing_equals: Reserved for callers that do not want trailing
+            ``=`` padding. The current implementation returns standard padded
+            base64 output.
 
     Returns:
-        The base64 encoded string.
+        The base64-encoded string.
     """
     return base64.b64encode(bytes(str(string).encode("utf-8"))).decode()
 
@@ -124,7 +129,15 @@ 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):
+def random_string(length: int) -> str:
+    """Generate a random alphanumeric string.
+
+    Args:
+        length: Number of characters to generate.
+
+    Returns:
+        A string made from ASCII letters and digits.
+    """
     s = "".join([random.choice(
         "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") for _ in range(length)
     ])
@@ -145,6 +158,22 @@ def generate_random_email(length: int = 8) -> str:
     return random_string(length)
 
 
+def get_inbound_in_client(client_uuid: str, inbound: Inbound) -> SingleInboundClient|None:
+    """Find a client inside an inbound by UUID.
+
+    Args:
+        client_uuid: UUID of the client to find.
+        inbound: Inbound model whose client list should be searched.
+
+    Returns:
+        The matching client, or None if the inbound does not contain it.
+    """
+    for client in inbound.settings.clients:
+        if client.uuid == client_uuid:
+            return client
+    return None
+
+
 def generate_email_from_tgid_inbid(telegram_id: int, /, inbound_id: int) -> str:
     """Generate a deterministic email from Telegram ID and inbound ID.
 
@@ -165,7 +194,7 @@ def generate_email_from_tgid_inbid(telegram_id: int, /, inbound_id: int) -> str:
     return f"TG{telegram_id}IB{inbound_id}"
 
 
-def generate_new_subscription(length: int = 16):
+def generate_new_subscription(length: int = 16) -> str:
     """Generate a random subscription ID.
 
     Args:
@@ -180,7 +209,7 @@ def generate_new_subscription(length: int = 16):
     return random_string(length)
 
 
-async def check_xui_response(response: JsonType | httpx.Response) -> str:
+async def check_xui_response(response: dict | httpx.Response) -> str:
     """Validate a 3X-UI API response.
 
     Checks if the response follows the expected 3X-UI API format with
@@ -209,7 +238,7 @@ async def check_xui_response(response: JsonType | httpx.Response) -> str:
         json_resp = response.json()
     else:
         json_resp = response
-
+    
     if len(json_resp) == 3:
         if tuple(json_resp.keys()) == ("success", "msg", "obj"):
             success: bool = json_resp["success"]
@@ -285,4 +314,4 @@ def auto_ms_to_s_timestamp(ms_or_s: int) -> 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
+    return int(datetime.now(tzinfo).timestamp() * 1000) 

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/tests/conftest.py

@@ -62,5 +62,5 @@ async def xui_client() -> XUIClient:
     try:
         await client.disconnect()
     except Exception:
-        pass
+        raise
 

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/tests/test_non_idempotent_endpoints_clients.py

@@ -33,7 +33,7 @@ class TestClientsEndpoint:
         # Try to find a suitable inbound (preferably with PROD_STRING in remark)
         test_inbound = None
         for inbound in all_inbounds:
-            if xui_client.PROD_STRING.search(inbound.remark.lower()):
+            if xui_client.PROD_STRING.search(inbound.remark):
                 test_inbound = inbound
                 break
 

{python_3xui-0.0.9 → python_3xui-0.0.9.post2}/tests/test_xuiclient_helpers.py

@@ -129,7 +129,7 @@ class TestXUIClientHelpers:
             before = await xui_client.clients_end.get_client_with_email(email)
             assert before.enable is True, "Newly created client should start enabled"
 
-            resp = await xui_client.update_client_by_tgid(
+            resp = await xui_client.update_client_by_tgid_inbid(
                 _TGID_UPDATE, target_inbound.id, verbose=False, sub_id=_TEST_SUB_ID,
             )
             assert resp.status_code == 200

python_3xui-0.0.9/python_3xui/__init__.py

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

python_3xui-0.0.9/python_3xui/custom_exceptions.py

@@ -1,12 +0,0 @@
-
-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)