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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Python-3xui
-Version: 0.0.9.post2
+Version: 0.0.9.post3
 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,11 @@ 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.9-r3 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: the importing of util.py fixed with from __future__ import annotations</li>
+<li>Make panel_id for better accounting & logging clarity</li>
+<li>Fix __aenter__ in XUIClient to not log a warning</li>
+<li>Fix total_gb to be int and not float, since that would need refactoring which I don't have time for yet.</li>
+<li>ClientsSettings now has extra=ignore instead of extra=forbid.</li>
 </ul>

python_3xui-0.0.9.post3/README.md

@@ -0,0 +1,12 @@
+<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-r3 Release Notes</h2>
+<ul>
+<li>HOTFIX: the importing of util.py fixed with from __future__ import annotations</li>
+<li>Make panel_id for better accounting & logging clarity</li>
+<li>Fix __aenter__ in XUIClient to not log a warning</li>
+<li>Fix total_gb to be int and not float, since that would need refactoring which I don't have time for yet.</li>
+<li>ClientsSettings now has extra=ignore instead of extra=forbid.</li>
+</ul>

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

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

{python_3xui-0.0.9.post2 → python_3xui-0.0.9.post3}/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.9r3"
 __email__ = ""
 
 

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

@@ -76,6 +76,7 @@ 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,
+                 panel_id: Any = None
                  ) -> None:
         """Initialize the XUIClient.
 
@@ -93,6 +94,7 @@ 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.
+            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 +112,7 @@ class XUIClient:
         self.max_retries: int = max_retries
         self.retry_delay: int = retry_delay
         self.sub_gen = custom_sub_generator
+        self.panel_id: int | str | Any = panel_id
         # endpoints
         self.server_end = endpoints.Server(self)
         self.clients_end = endpoints.Clients(self)
@@ -198,7 +201,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 +325,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 +346,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 +376,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,12 +394,12 @@ 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
 
@@ -424,16 +428,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
@@ -525,7 +533,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
@@ -642,6 +651,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 +668,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
@@ -674,6 +685,7 @@ class XUIClient:
             inbound_id=inbound_id, client_uuid=util.get_uuid_from_tgid(telegram_id),
             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.9.post3}/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.9.post3}/python_3xui/models.py

@@ -63,7 +63,7 @@ class SingleInboundClient(base_model.BaseModel):
     reset: int = 0
     #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 +88,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 +295,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.9.post3}/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/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>