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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.9.post2
+Version: 0.0.10
 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
@@ -28,15 +28,9 @@ 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.9 Release Notes</h2>
+<h2>0.0.10 Release Notes</h2>
 <ul>
-<li>Fix _request_update_client for it to actually work and NOT create "zombies"</li>
-<li>DTO un-split because fields reset when not provided, so full inbounds must be fetched</li>
-<li>New method: update_client_by_tgid</li>
-<li>Fixed test suite</li>
-<li>Fix from_response and from_list</li>
-<li>Remove obsolete and useless client fields from models</li>
-<li>Inbound settings actually get parsed properly into ClientsSettings</li>
-<li>New asyncio task management so they won't get destroyed when GCed</li>
-<li>XUIClient async_lru cache now binds to event loop at runtime, not in initialization</li>
+<li>HOTFIX: make models.SingleInboundClient default flow "", because turns out panel can not return it because of zombification...</li>
+<li>Add a custom uuid generator for XUIClient that <i>defaults</i> to method in util but you can make your own!</li>
+<li>Uncomplicate self.sub_gen into self._resolve_sub</li>
 </ul>

python_3xui-0.0.10/README.md

@@ -0,0 +1,10 @@
+<h1>Hi! This is my example python 3x-ui wrapper!</h1>
+<p>I'm not expecting much to be honest, so please feel free to fork it if I abandon the project and you need it!</p>
+<p>Also, if you REALLY want it I can give you the ownership if I step down, you can find my email in the pyproject.toml (I don't check it that much but trust me I do)</p>
+
+<h2>0.0.10 Release Notes</h2>
+<ul>
+<li>HOTFIX: make models.SingleInboundClient default flow "", because turns out panel can not return it because of zombification...</li>
+<li>Add a custom uuid generator for XUIClient that <i>defaults</i> to method in util but you can make your own!</li>
+<li>Uncomplicate self.sub_gen into self._resolve_sub</li>
+</ul>

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

@@ -1,6 +1,6 @@
 [project]
 name = "Python-3xui"
-version = "0.0.9r2"
+version = "0.0.10"
 authors = [
   { name="JustMe_001", email="justme001.causation755@passinbox.com" },
 ]

{python_3xui-0.0.9.post2 → python_3xui-0.0.10}/python_3xui/__init__.py

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

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

@@ -64,7 +64,8 @@ class XUIClient:
         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.
+        sub_gen: Callable/Awaitable used to derive subscription IDs from Telegram IDs.
+        uuid_gen: Callable/Awaitable used to derive UUIDs from Telegram IDs.
         server_end: Server endpoint handler.
         clients_end: Clients endpoint handler.
         inbounds_end: Inbounds endpoint handler.
@@ -76,6 +77,8 @@ class XUIClient:
                  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,
+                 custom_uuid_generator: Callable[[int], str] | Callable[[int], Awaitable[str]] = util.get_uuid_from_tgid,
+                 panel_id: Any = None
                  ) -> None:
         """Initialize the XUIClient.
 
@@ -93,6 +96,9 @@ class XUIClient:
             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.
+            custom_uuid_generator: Sync or async callable that receives a
+                Telegram ID and returns the UUID for new clients.
+            panel_id: this is solely for user's purposes to increase logging and accounting clarity. Default is None.
         """
         self.connected: bool = False
         self.PROD_STRING = re.compile(custom_prod_string)
@@ -110,6 +116,8 @@ class XUIClient:
         self.max_retries: int = max_retries
         self.retry_delay: int = retry_delay
         self.sub_gen = custom_sub_generator
+        self.uuid_gen = custom_uuid_generator
+        self.panel_id: int | str | Any = panel_id
         # endpoints
         self.server_end = endpoints.Server(self)
         self.clients_end = endpoints.Clients(self)
@@ -198,7 +206,7 @@ class XUIClient:
                 if resp.status_code == 404:
                     now: float = datetime.now(UTC).timestamp()
                     if self.session_start is None or now - self.session_start > self.session_duration:
-                        logging.info("Client with IP/Domain %s is not logged in, logging in...", self.base_host)
+                        logging.info("Client (panel: %s) is not logged in, logging in...", self.panel_id or self.base_host)
                         await self.login()
                         continue
                     else:
@@ -322,7 +330,7 @@ class XUIClient:
             if 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)
+        logging.info("Client is logging in (panel: %s)", self.panel_id or self.base_host)
         resp = await self.session.post("/login", data=payload)
         if resp.status_code == 200:
             resp_json = resp.json()
@@ -343,7 +351,7 @@ class XUIClient:
         Returns:
             Self: The XUIClient instance.
         """
-        logging.log(DEBUG, "Client connected with IP/domain %s", self.base_url)
+        logging.log(DEBUG, "Client connected (panel: %s)", self.panel_id or self.base_url)
         self.session = AsyncClient(base_url=self.base_url)
         self.connected = True
         return self
@@ -373,9 +381,10 @@ class XUIClient:
         """
         self.connect()
         await self.login()
-        self._cache_cleaner_task = asyncio.create_task(
-            self._clear_prod_inbound_cache_task(), name=f"inb_cache_clearer_for_{self.base_url}"
-        )
+        if not self._cache_cleaner_task:
+            self._cache_cleaner_task = asyncio.create_task(
+                self._clear_prod_inbound_cache_task(create_new=True), name=f"inb_cache_clearer_for_{self.base_url}"
+            )
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
@@ -390,15 +399,34 @@ class XUIClient:
             exc_tb: The exception traceback, if an exception occurred.
         """
         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)
+            logging.info("Client is disconnecting (panel: %s)", self.panel_id or self.base_host)
         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_info=exc_tb)
-        print(f"Client is disconnecting: {self.base_host}")
+        print(f"Client is disconnecting: {self.panel_id or self.base_host}")
         await self.disconnect()
         return
 
+    #=========================="meta" methods==========================
+    async def _resolve_uuid(self, telegram_id: int) -> str:
+        """Resolve a Telegram ID to a UUID via ``self.uuid_gen``.
+
+        Handles both sync and async callables.
+        """
+        if iscoroutinefunction(self.uuid_gen):
+            return await self.uuid_gen(telegram_id)
+        return self.uuid_gen(telegram_id)
+
+    async def _resolve_sub(self, telegram_id: int) -> str:
+        """Resolve the subscription ID from a telegram id via ``self.sub_gen``
+
+        Handles both sync and async callables.
+        """
+        if iscoroutinefunction(self.sub_gen):
+            return await self.sub_gen(telegram_id)
+        return self.sub_gen(telegram_id)
+
     #========================inbound management========================
     async def _get_production_inbounds_impl(self) -> tuple[Inbound, ...]:
         """Retrieve production inbounds.
@@ -424,16 +452,20 @@ class XUIClient:
 
         return tuple(usable_inbounds)
 
-    async def _clear_prod_inbound_cache_task(self):
+    async def _clear_prod_inbound_cache_task(self, *, create_new: bool = False):
         """Refresh the production inbound cache in the background.
 
         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.
+
+        create_new param is kw-only and for people who know what they're doing, so they won't get the warning.
         """
-        if self._cache_cleaner_task is not None:
+        if (self._cache_cleaner_task is not None) and (not create_new):
             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.")
+            return
+        logging.info("Initializing cache cleaner task for %s", self.panel_id)
         while self.connected:
             self.get_production_inbounds.cache_clear()
             await self.get_production_inbounds()  # fill the cache
@@ -462,7 +494,7 @@ class XUIClient:
             email = util.generate_email_from_tgid_inbid(tgid, inbound_id)
             resp = [await self.clients_end.get_client_with_email(email)]
             return resp
-        uuid = util.get_uuid_from_tgid(tgid)
+        uuid = await self._resolve_uuid(tgid)
         resp = await self.clients_end.get_client_with_uuid(uuid)
         return resp
 
@@ -498,14 +530,12 @@ class XUIClient:
 
         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)
+        custom_sub = await self._resolve_sub(telegram_id)
+        uuid = await self._resolve_uuid(telegram_id)
         for inb in production_inbounds:
             tmp_email = util.generate_email_from_tgid_inbid(telegram_id, inb.id)
             client = SingleInboundClient(
-                uuid=util.get_uuid_from_tgid(telegram_id),
+                uuid=uuid,
                 flow="",
                 email=tmp_email,
                 limit_gb=0,
@@ -525,7 +555,8 @@ class XUIClient:
                 raise custom_exceptions.ClientEmailAlreadyExistsError(json_resp["msg"])
         return responses
 
-    async def _find_client_in_inbound(self, client_uuid: str, inbound_id: int, use_cache=False) -> SingleInboundClient | None:
+    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
@@ -615,18 +646,19 @@ class XUIClient:
                                 expiry_time)
 
         _to_exec: list[Task] = []
+        client_uuid = await self._resolve_uuid(telegram_id)
         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)
+            found_client = util.get_inbound_in_client(client_uuid, 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)
+                        new_client, inbound.id, original_uuid=client_uuid
                     ))
                 )
         responses = await asyncio.gather(*_to_exec)
@@ -642,6 +674,7 @@ class XUIClient:
                                           enable: bool | None = None,
                                           sub_id: str | None = None,
                                           comment: str | None = None,
+                                          email: str | None = None,
                                           verbose: bool = True) -> Response:
         """
         Update a client in a specific inbound by Telegram ID. NOT optimized for multiple inbounds.
@@ -658,6 +691,7 @@ class XUIClient:
             enable: Whether the client is enabled (optional)
             sub_id: Subscription ID (optional)
             comment: Client comment/note (optional)
+            email: New client email (optional). USE WITH CAUTION BECAUSE THE PANEL WILL NOT TRACK THE NEW EMAIL.
 
         Returns:
             Response from the API
@@ -670,10 +704,12 @@ class XUIClient:
                                 "If you want to disable this message, set verbose=false.",
                                 expiry_time)
 
+        client_uuid = await self._resolve_uuid(telegram_id)
         resp = await self.clients_end.update_single_client(
-            inbound_id=inbound_id, client_uuid=util.get_uuid_from_tgid(telegram_id),
+            inbound_id=inbound_id, client_uuid=client_uuid,
             security=security,
             password=password,
+            email=email,
             flow=flow,
             limit_ip=limit_ip,
             limit_gb=limit_gb,

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

@@ -9,6 +9,7 @@ from . import util
 if TYPE_CHECKING:
     from .api import XUIClient
 
+
 class BaseModel(pydantic.BaseModel):
     """Base model for all 3X-UI API data models.
 
@@ -22,13 +23,12 @@ class BaseModel(pydantic.BaseModel):
     ERROR_RETRIES: ClassVar[int] = 5
     ERROR_RETRY_COOLDOWN: ClassVar[int] = 1
 
-    model_config = pydantic.ConfigDict(ignored_types=(cached_property, ), validate_by_name=True, validate_by_alias=True)
+    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")
     #     ...
 
-
     @classmethod
     def from_list(cls, args: List[Dict[str, Any]],
                   ) -> List[Self]:
@@ -50,7 +50,7 @@ class BaseModel(pydantic.BaseModel):
             cls,
             response: httpx.Response,
             client: "XUIClient",
-            expect: list|dict,
+            expect: list | dict,
             auto_retry: bool = True
     ) -> Union[Self, List[Self]]:
         """Create model instance(s) from an HTTP response.

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

@@ -57,13 +57,14 @@ class SingleInboundClient(base_model.BaseModel):
     uuid: Annotated[str, Field(alias="id")]  #yes they really did that...
     security: str = ""
     password: str = ""
-    flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"]
+    # turns out panel can (not return it)
+    flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] = ""
     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.
+    # Interestingly, the API expects this value to be called GB but it's actually bytes.
     # 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
+    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")] = ""
@@ -88,15 +89,15 @@ class SingleInboundClient(base_model.BaseModel):
 
     @field_serializer("limit_gb")
     @classmethod
-    def serialize_total_gb(cls, value: int | float) -> int:
+    def serialize_total_gb(cls, value: int) -> 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:
+    def parse_total_gb(cls, value: int) -> int:
         #Python wants an int/float of GB.
-        return value / (1024 ** 3)
+        return value // (1024 ** 3)
 
 
 class ClientsSettings(base_model.BaseModel):
@@ -295,7 +296,7 @@ class Inbound(base_model.BaseModel):
     def parse_settings(cls, value: str) -> ClientsSettings:
         if value == "":
             return ClientsSettings(clients=[])
-        return ClientsSettings.model_validate_json(value, by_alias=True, extra="forbid")
+        return ClientsSettings.model_validate_json(value, by_alias=True, extra="ignore")
 
     @field_serializer("settings")
     @classmethod

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

@@ -8,6 +8,7 @@ including:
 - Telegram ID-based UUID/email generation
 - Response validation
 """
+from __future__ import annotations
 
 import asyncio
 import base64

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

@@ -6,7 +6,7 @@ from pydantic import ValidationError
 
 from python_3xui.api import XUIClient
 from python_3xui.models import SingleInboundClient, ClientStats
-from python_3xui.util import get_uuid_from_tgid, datetime_now_ms, generate_email_from_tgid_inbid
+from python_3xui.util import datetime_now_ms, generate_email_from_tgid_inbid
 
 
 class TestClientsEndpoint:
@@ -54,10 +54,11 @@ class TestClientsEndpoint:
 
         # Generate unique test data
         timestamp = datetime_now_ms(UTC)
-        test_uuid = get_uuid_from_tgid(TestClientsEndpoint.test_telegram_id)
+        test_uuid = await xui_client._resolve_uuid(TestClientsEndpoint.test_telegram_id)
         test_email = f"testclient_{timestamp}@example.com"
 
         # Create a test client
+        custom_sub = await xui_client._resolve_sub(TestClientsEndpoint.test_telegram_id)
         test_client = SingleInboundClient.model_construct(
             id=test_uuid,  # Using alias 'id' for 'uuid'
             security="",
@@ -69,7 +70,7 @@ class TestClientsEndpoint:
             expiryTime=timestamp + 86400*1000,  # Using alias 'expiryTime' for 'expiry_time'
             enable=True,
             tgId="",  # Using alias 'tgId' for 'tg_id'
-            subId=xui_client.sub_gen(TestClientsEndpoint.test_telegram_id),  # Using alias 'subId' for 'subscription_id'
+            subId=custom_sub,  # Using alias 'subId' for 'subscription_id'
             comment=f"Test client created at {timestamp}, TEST SUITE",
             created_at=timestamp,
             updated_at=timestamp
@@ -150,7 +151,7 @@ class TestClientsEndpoint:
 
         # Generate new test data
         timestamp = datetime_now_ms(UTC)
-        test_uuid = get_uuid_from_tgid(TestClientsEndpoint.test_telegram_id + 1)  # Different UUID
+        test_uuid = await xui_client._resolve_uuid(TestClientsEndpoint.test_telegram_id + 1)  # Different UUID
         test_email = f"testclient_uuid_{timestamp}@example.com"
 
         # Create a new test client
@@ -202,7 +203,7 @@ class TestClientsEndpoint:
         TEST_TELEGRAM_ID = 420
 
         timestamp = datetime_now_ms(UTC)
-        test_uuid = get_uuid_from_tgid(TEST_TELEGRAM_ID)
+        test_uuid = await xui_client._resolve_uuid(TEST_TELEGRAM_ID)
 
         template_client = SingleInboundClient.model_construct(
             id=test_uuid,  # Using alias 'id' for 'uuid'

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

@@ -19,7 +19,7 @@ from python_3xui.custom_exceptions import ClientEmailAlreadyExistsError
 from python_3xui.models import ClientStats
 from python_3xui.util import (
     generate_email_from_tgid_inbid,
-    get_uuid_from_tgid,
+
 )
 
 
@@ -101,7 +101,7 @@ class TestXUIClientHelpers:
             # inbound_id=None -> uses UUID, returns one entry per production inbound.
             by_uuid = await xui_client.get_client_with_tgid(_TGID_GET)
             assert isinstance(by_uuid, list)
-            expected_uuid = get_uuid_from_tgid(_TGID_GET)
+            expected_uuid = await xui_client._resolve_uuid(_TGID_GET)
             assert all(isinstance(c, ClientStats) for c in by_uuid)
             assert all(c.uuid == expected_uuid for c in by_uuid)
             prod_ids = {inb.id for inb in production_inbounds}

python_3xui-0.0.9.post2/README.md

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