Python-3xui 0.0.7__tar.gz → 0.0.8.post1__tar.gz

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.7
+Version: 0.0.8.post1
 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,9 +28,7 @@ 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.7 Release Notes</h2>
+<h2>0.0.81 Release Notes</h2>
 <ul>
-<li>Purge prints and replace them with logging (except when absolutely needed)</li>
-<li>Make prod_string regEx</li>
-<li>Change the test suite</li>
+<li>Minor change: make custom sub generators available instead of the default one</li>
 </ul>

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/README.md

@@ -2,9 +2,7 @@
 <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.7 Release Notes</h2>
+<h2>0.0.81 Release Notes</h2>
 <ul>
-<li>Purge prints and replace them with logging (except when absolutely needed)</li>
-<li>Make prod_string regEx</li>
-<li>Change the test suite</li>
+<li>Minor change: make custom sub generators available instead of the default one</li>
 </ul>

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Python-3xui"
-version = "0.0.7"
+version = "0.0.8r1"
 authors = [
   { name="JustMe_001", email="justme001.causation755@passinbox.com" },
 ]
@@ -56,4 +56,4 @@ exclude = [
 
 
 [[tool.hatch.envs.hatch-test.matrix]]
-python = ["3.12", "3.11"]
+python = ["3.13", "3.12", "3.11"]

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/python_3xui/api.py

@@ -1,9 +1,11 @@
+import json
 import logging
 import re
 import time
 from collections.abc import Sequence, Mapping
+from inspect import isawaitable
 from logging import DEBUG
-from typing import Self, Optional, Dict, Iterable, AsyncIterable, Type, Union, Any, List, Tuple, Literal
+from typing import Self, Optional, Dict, Iterable, AsyncIterable, Type, Union, Any, List, Tuple, Literal, Callable, Awaitable, Coroutine
 from datetime import datetime, UTC
 
 import pyotp
@@ -14,7 +16,7 @@ import httpx
 
 from . import util
 from .models import Inbound, SingleInboundClient, ClientStats
-from .util import JsonType, async_range
+from .util import JsonType, async_range, check_xui_response
 
 DataType: Type[str | bytes | Iterable[bytes] | AsyncIterable[bytes]] = Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]
 PrimitiveData = Optional[Union[str, int, float, bool]]
@@ -66,7 +68,9 @@ class XUIClient:
     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",
+                 custom_sub_generator: Callable[[int], str]|Callable[[int], Awaitable[str]] = util.default_sub_from_tgid
+                 ) -> None:
         """Initialize the XUIClient.
 
         Args:
@@ -78,7 +82,7 @@ class XUIClient:
             two_fac_code: Two-factor authentication code (if enabled).
             session_duration: Maximum session duration in seconds. Defaults to 3600.
         """
-        from . import endpoints # look, I know it's bad, but we need to evade cyclical imports
+        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
@@ -94,6 +98,7 @@ class XUIClient:
         self.totp: pyotp.TOTP | None = None
         self.max_retries: int = 5
         self.retry_delay: int = 1
+        self.sub_gen = custom_sub_generator
         # endpoints
         self.server_end = endpoints.Server(self)
         self.clients_end = endpoints.Clients(self)
@@ -142,19 +147,19 @@ class XUIClient:
                         raise RuntimeError("""Server returned a 404, and the session should still be valid, likely it's a REAL 404""")
                 else:
                     logging.error("Server returned a status code of %s", resp.status_code)
-                    raise RuntimeError(f"Wrong status code: {resp.status_code}")
+                    resp.raise_for_status()
 
-            status = await util.check_xui_response_validity(resp)
+            status = await util.check_xui_response(resp)
             if status == "OK":
                 return resp
             elif status == "DB_LOCKED":
                 if attempt + 1 >= self.max_retries:
-                    # resp.status_code = 518 # so the error can simply be handled as a "bad request"
-                    # return resp
                     raise RuntimeError("Too many retries")
                 await asyncio.sleep(self.retry_delay)
                 continue
             else:
+                logging.error("A %s request was unsuccessful (code 200, but success=false).\nPayload: %s",
+                              method, json.dumps(resp.json()))
                 return resp
         raise RuntimeError(f"For some reason safe_request didn't exit, dump:\nmethod:\n{method}\n{kwargs}")
 
@@ -252,7 +257,7 @@ class XUIClient:
         }
         if self.totp:
             if self.totp.interval - datetime.now().timestamp() % self.totp.interval < 3:
-                await asyncio.sleep(3.1) # just to not submit an invalid code
+                await asyncio.sleep(3.1)  # just to not submit an invalid code
             payload["twoFactorCode"] = self.totp.now()
         else:
             if self.two_fac_secret:
@@ -266,7 +271,7 @@ class XUIClient:
                 self.session_start: float = (datetime.now(UTC).timestamp())
                 return
             else:
-                raise ValueError("Error: wrong credentials or failed login")
+                raise ValueError("Error: wrong credentials (including status code) or failed login.")
         else:
             raise RuntimeError(f"Error: server returned a status code of {resp.status_code}")
 
@@ -317,7 +322,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:
+        if exc_type is None or exc_type == 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):"
@@ -328,7 +333,7 @@ class XUIClient:
         return
 
     #========================inbound management========================
-    @alru_cache
+    @alru_cache()
     async def get_production_inbounds(self) -> Tuple[Inbound, ...]:
         """Retrieve production inbounds.
 
@@ -364,8 +369,8 @@ class XUIClient:
         """
         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]:
@@ -394,7 +399,12 @@ class XUIClient:
         resp = await self.clients_end.get_client_with_uuid(uuid)
         return resp
 
-    async def create_and_add_prod_client(self, telegram_id: int, additional_remark: str = None):
+    async def create_and_add_prod_client(self, telegram_id: int, *,
+                                         additional_remark: str | None = None,
+                                         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
@@ -405,6 +415,8 @@ class XUIClient:
         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)
 
         Returns:
             List[Response]: A list of responses from the server for each
@@ -412,20 +424,35 @@ class XUIClient:
         """
         production_inbounds: List[Inbound] = await self.get_production_inbounds()
 
-        responses = []
+        tasks = []
+        custom_sub: str
+        if isawaitable(self.sub_gen(telegram_id)):
+            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(
                 uuid=util.get_uuid_from_tgid(telegram_id),
                 flow="",
-                email=util.generate_email_from_tgid_inbid(telegram_id, inb.id),
+                email=tmp_email,
                 limit_gb=0,
                 enable=True,
-                subscription_id=util.sub_from_tgid(telegram_id),
-                comment=f"{additional_remark}, created at {datetime.now(UTC)}")
-            responses.append(await self.clients_end.add_client(client, inb.id))
+                subscription_id=custom_sub,
+                comment=f"{additional_remark}, 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)
+        if exist_ok:
+            return responses
+        for resp in responses:
+            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"])
         return responses
 
-    async def update_client_by_tgid(self, telegram_id: int, inbound_id: int, /,
+    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,
@@ -434,28 +461,36 @@ class XUIClient:
                                     expiry_time: int | None = None,
                                     enable: bool | None = None,
                                     sub_id: str | None = None,
-                                    comment: str | None = None) -> Response:
+                                    comment: str | None = None,
+                                    verbose: bool=True) -> Response:
         """
         Update a client in a specific inbound by Telegram ID.
 
         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:
+                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)
 
         resp = await self.clients_end.update_single_client(
             SingleInboundClient.model_validate(existing_client.model_dump()),
@@ -486,7 +521,7 @@ class XUIClient:
         resp = await self.clients_end.delete_client_by_email(email, inbound_id)
         return resp
 
-    async def delete_client_by_tgid_all_inbounds(self, telegram_id: int) -> List[Response]:
+    async def revoke_client_by_tgid_all_inbounds(self, telegram_id: int) -> List[Response]:
         """Delete a client from all production inbounds by Telegram ID.
 
         Args:
@@ -505,4 +540,3 @@ class XUIClient:
         logging.info("Clients of of tgid %s deleted", telegram_id)
 
         return responses
-

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/python_3xui/base_model.py

@@ -83,7 +83,7 @@ class BaseModel(pydantic.BaseModel):
             inbounds = await Inbound.from_response(response, client, list)
         """
         json_resp: util.JsonType = response.json()
-        valid = util.check_xui_response_validity(json_resp)
+        valid = util.check_xui_response(json_resp)
         if valid == "OK":
             obj = json_resp["obj"]
             if expect is list:
@@ -91,4 +91,4 @@ class BaseModel(pydantic.BaseModel):
             if expect is dict:
                 return cls(**obj, client=client)
         else:
-            raise ValueError(f"Invalid 3X-UI response, code {valid}")
+            raise ValueError(f"Invalid 3X-UI response, code {valid}. Don't use from_response on failed requests.")

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/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
+from typing import TypeAlias, Union, Dict, Any, List, dataclass_transform
 
 import httpx
 
@@ -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:
@@ -180,7 +180,7 @@ def generate_new_subscription(length: int = 16):
     return s
 
 
-async def check_xui_response_validity(response: JsonType | httpx.Response) -> str:
+async def check_xui_response(response: JsonType | httpx.Response) -> str:
     """Validate a 3X-UI API response.
 
     Checks if the response follows the expected 3X-UI API format with
@@ -193,17 +193,18 @@ async def check_xui_response_validity(response: JsonType | httpx.Response) -> st
         str: One of three status strings:
             - "OK": Response is valid and successful.
             - "DB_LOCKED": Database is locked, operation should be retried.
-            - "ERROR": Operation was unsuccessful.
+            - "FAIL": Operation was unsuccessful.
 
     Raises:
         RuntimeError: If the response doesn't match the expected 3X-UI format.
 
     Examples:
-        >>> check_xui_response_validity({"success": True, "msg": "", "obj": {}})
+        >>> check_xui_response({"success": True, "msg": "", "obj": {}})
         'OK'
-        >>> check_xui_response_validity({"success": False, "msg": "database is locked", "obj": None})
+        >>> check_xui_response({"success": False, "msg": "database is locked", "obj": None})
         'DB_LOCKED'
     """
+    #TODO: this is trying to do too much. We'll just check if DB is locked, and then use case-to-case basis to see how they are.
     if isinstance(response, httpx.Response):
         json_resp = response.json()
     else:
@@ -218,11 +219,9 @@ async def check_xui_response_validity(response: JsonType | httpx.Response) -> st
             if "database" in msg.lower() and "locked" in msg.lower() and not success:
                 logging.log(logging.WARNING, "Database is locked, retrying...")
                 return "DB_LOCKED"
-            logging.warning("Unsuccessful operation (status code 200, success = false)! Message: %s", json_resp["msg"])
-            return "ERROR"
+            return "FAIL"
     raise RuntimeError("Validator got something very unexpected (Please don't shove responses with non-20X status codes in here...)")
 
-
 def get_days_until_expiry(expiry_time: int) -> float:
     """Calculate the number of days until a client expires.
 
@@ -231,16 +230,16 @@ def get_days_until_expiry(expiry_time: int) -> float:
 
     Returns:
         Number of days until expiry. Returns negative value if already expired.
-        Returns a very large number (infinity) if expiry_time is 0 (no expiry).
+        Returns a very 0 if expiry_time is 0 (no expiry).
 
     Examples:
-        >>> get_days_until_expiry(int(datetime.now(UTC).timestamp_seconds()) + 86400)  # 1 day from now
+        >>> get_days_until_expiry(int(datetime.now(UTC).timestamp()) + 86400)  # 1 day from now
         1.0
         >>> get_days_until_expiry(0)  # No expiry
         inf
     """
     if expiry_time == 0:
-        return float('inf')
+        return 0
 
     current_timestamp = datetime.now(UTC).timestamp()
     seconds_remaining = expiry_time - current_timestamp

{python_3xui-0.0.7 → python_3xui-0.0.8.post1}/tests/test_non_idempotent_endpoints_clients.py

@@ -8,7 +8,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, sub_from_tgid, s_to_ms_timestamp, datetime_now_ms, generate_email_from_tgid_inbid, \
+from python_3xui.util import get_uuid_from_tgid, s_to_ms_timestamp, datetime_now_ms, generate_email_from_tgid_inbid, \
     generate_random_email
 
 
@@ -72,7 +72,7 @@ class TestClientsEndpoint:
             expiryTime=timestamp + 86400*1000,  # Using alias 'expiryTime' for 'expiry_time'
             enable=True,
             tgId="",  # Using alias 'tgId' for 'tg_id'
-            subId=sub_from_tgid(TestClientsEndpoint.test_telegram_id),  # Using alias 'subId' for 'subscription_id'
+            subId=xui_client.sub_gen(TestClientsEndpoint.test_telegram_id),  # Using alias 'subId' for 'subscription_id'
             comment=f"Test client created at {timestamp}, TEST SUITE",
             created_at=timestamp,
             updated_at=timestamp
@@ -242,7 +242,7 @@ class TestClientsEndpoint:
         print(f"Added test client with email: {test_email}, UUID: {test_uuid} to {len(production_inbounds)} production inbounds")
 
         # Now delete the client from all production inbounds by Telegram ID
-        responses = await xui_client.delete_client_by_tgid_all_inbounds(TEST_TELEGRAM_ID)
+        responses = await xui_client.revoke_client_by_tgid_all_inbounds(TEST_TELEGRAM_ID)
 
         # Validate responses
         assert len(responses) == len(production_inbounds)