Server API

* Server API for sync API. * Server API for async API. * GetDB updates. * Linter updates. * Package version update. * Docs update.
iwatkot · Jan 6, 2025 · 98cc3aa · 98cc3aa
1 parent bdda244
commit 98cc3aa
Show file tree

Hide file tree

Showing 11 changed files with 339 additions and 13 deletions.
diff --git a/py3xui/api/README.md b/py3xui/api/README.md
@@ -1083,3 +1083,71 @@ specific inbound identified by its ID.
     api.inbound.reset_client_stats(inbound.id)
     ```
 
+<a id="api.api_server"></a>
+
+# api.api\_server
+
+This module contains the ServerApi class for handling server in the XUI API.
+
+<a id="api.api_server.ServerApi"></a>
+
+## ServerApi Objects
+
+```python
+class ServerApi(BaseApi)
+```
+
+This class provides methods to interact with the server in the XUI API.
+
+Attributes and Properties:
+host (str): The XUI host URL.
+username (str): The XUI username.
+password (str): The XUI password.
+token (str | None): The XUI secret token.
+use_tls_verify (bool): Whether to verify the server TLS certificate.
+custom_certificate_path (str | None): Path to a custom certificate file.
+session (requests.Session): The session object for the API.
+max_retries (int): The maximum number of retries for the API requests.
+
+Public Methods:
+get_db: Retrieves a database backup file and saves it to a specified path.
+
+**Examples**:
+
+    ```python
+    import py3xui
+
+    api = py3xui.Api.from_env()
+    api.login()
+
+    db_save_path = "db_backup.db"
+    api.server.get_db(db_save_path)
+    ```
+
+<a id="api.api_server.ServerApi.get_db"></a>
+
+#### get\_db
+
+```python
+def get_db(save_path: str) -> None
+```
+
+This route is used to retrieve a database backup file and save it to a specified path.
+
+**Arguments**:
+
+- `save_path` _str_ - The path to save the database backup file.
+
+
+**Examples**:
+
+    ```python
+    import py3xui
+
+    api = py3xui.Api.from_env()
+    api.login()
+
+    db_save_path = "db_backup.db"
+    api.server.get_db(db_save_path)
+    ```
+
diff --git a/py3xui/api/__init__.py b/py3xui/api/__init__.py
@@ -2,7 +2,4 @@
 from py3xui.api.api_client import ClientApi
 from py3xui.api.api_database import DatabaseApi
 from py3xui.api.api_inbound import InboundApi
-
-# from py3xui.async_api.async_api_client import AsyncClientApi
-# from py3xui.async_api.async_api_database import AsyncDatabaseApi
-# from py3xui.async_api.async_api_inbound import AsyncInboundApi
+from py3xui.api.api_server import ServerApi
diff --git a/py3xui/api/api.py b/py3xui/api/api.py
@@ -5,7 +5,7 @@
 
 from typing import Any
 
-from py3xui.api import ClientApi, DatabaseApi, InboundApi
+from py3xui.api import ClientApi, DatabaseApi, InboundApi, ServerApi
 from py3xui.utils import Logger, env
 
 
@@ -84,6 +84,9 @@ def __init__(
         self.database = DatabaseApi(
             host, username, password, token, use_tls_verify, custom_certificate_path, logger
         )
+        self.server = ServerApi(
+            host, username, password, token, use_tls_verify, custom_certificate_path, logger
+        )
         self._session: str | None = None
 
     @property
@@ -101,6 +104,7 @@ def session(self, value: str) -> None:
         self.client.session = value
         self.inbound.session = value
         self.database.session = value
+        self.server.session = value
 
     @classmethod
     def from_env(
@@ -170,4 +174,5 @@ def login(self) -> None:
         self._session = self.client.session
         self.inbound.session = self._session
         self.database.session = self._session
+        self.server.session = self._session
         self.logger.info("Logged in successfully.")
diff --git a/py3xui/api/api_server.py b/py3xui/api/api_server.py
@@ -0,0 +1,64 @@
+"""This module contains the ServerApi class for handling server in the XUI API."""
+
+from py3xui.api.api_base import BaseApi
+
+
+class ServerApi(BaseApi):
+    """This class provides methods to interact with the server in the XUI API.
+
+    Attributes and Properties:
+        host (str): The XUI host URL.
+        username (str): The XUI username.
+        password (str): The XUI password.
+        token (str | None): The XUI secret token.
+        use_tls_verify (bool): Whether to verify the server TLS certificate.
+        custom_certificate_path (str | None): Path to a custom certificate file.
+        session (requests.Session): The session object for the API.
+        max_retries (int): The maximum number of retries for the API requests.
+
+    Public Methods:
+        get_db: Retrieves a database backup file and saves it to a specified path.
+
+    Examples:
+        ```python
+        import py3xui
+
+        api = py3xui.Api.from_env()
+        api.login()
+
+        db_save_path = "db_backup.db"
+        api.server.get_db(db_save_path)
+        ```
+    """
+
+    def get_db(self, save_path: str) -> None:
+        """This route is used to retrieve a database backup file and save it to a specified path.
+
+        Arguments:
+            save_path (str): The path to save the database backup file.
+
+        Examples:
+            ```python
+            import py3xui
+
+            api = py3xui.Api.from_env()
+            api.login()
+
+            db_save_path = "db_backup.db"
+            api.server.get_db(db_save_path)
+            ```
+        """
+        endpoint = "server/getDb"
+        headers = {"Accept": "application/octet-stream"}
+        url = self._url(endpoint)
+        self.logger.info("Getting DB backup...")
+
+        response = self._get(url, headers, skip_check=True)
+
+        if response.status_code == 200:
+            with open(save_path, "wb") as file:
+                file.write(response.content)
+            self.logger.info(f"DB backup saved to {save_path}")
+        else:
+            self.logger.error(f"Failed to get DB backup: {response.text}")
+            response.raise_for_status()
diff --git a/py3xui/async_api/README.md b/py3xui/async_api/README.md
@@ -1075,3 +1075,72 @@ specific inbound identified by its ID.
     await api.inbound.reset_client_stats(inbound.id)
     ```
 
+<a id="async_api.async_api_server"></a>
+
+# async\_api.async\_api\_server
+
+This module contains the ServerApi class for handling server in the XUI API.
+
+<a id="async_api.async_api_server.AsyncServerApi"></a>
+
+## AsyncServerApi Objects
+
+```python
+class AsyncServerApi(AsyncBaseApi)
+```
+
+This class provides methods to interact with the server in the XUI API in an asynchronous
+manner.
+
+Attributes and Properties:
+host (str): The XUI host URL.
+username (str): The XUI username.
+password (str): The XUI password.
+token (str | None): The XUI secret token.
+use_tls_verify (bool): Whether to verify the server TLS certificate.
+custom_certificate_path (str | None): Path to a custom certificate file.
+session (requests.Session): The session object for the API.
+max_retries (int): The maximum number of retries for the API requests.
+
+Public Methods:
+get_db: Retrieves a database backup file and saves it to a specified path.
+
+**Examples**:
+
+    ```python
+    import py3xui
+
+    api = py3xui.AsyncApi.from_env()
+    await api.login()
+
+    db_save_path = "db_backup.db"
+    await api.server.get_db(db_save_path)
+    ```
+
+<a id="async_api.async_api_server.AsyncServerApi.get_db"></a>
+
+#### get\_db
+
+```python
+async def get_db(save_path: str) -> None
+```
+
+This route is used to retrieve a database backup file and save it to a specified path.
+
+**Arguments**:
+
+- `save_path` _str_ - The path to save the database backup file.
+
+
+**Examples**:
+
+    ```python
+    import py3xui
+
+    api = py3xui.AsyncApi.from_env()
+    await api.login()
+
+    db_save_path = "db_backup.db"
+    await api.server.get_db(db_save_path)
+    ```
+
diff --git a/py3xui/async_api/__init__.py b/py3xui/async_api/__init__.py
@@ -2,3 +2,4 @@
 from py3xui.async_api.async_api_client import AsyncClientApi
 from py3xui.async_api.async_api_database import AsyncDatabaseApi
 from py3xui.async_api.async_api_inbound import AsyncInboundApi
+from py3xui.async_api.async_api_server import AsyncServerApi
diff --git a/py3xui/async_api/async_api.py b/py3xui/async_api/async_api.py
@@ -5,7 +5,12 @@
 
 from typing import Any
 
-from py3xui.async_api import AsyncClientApi, AsyncDatabaseApi, AsyncInboundApi
+from py3xui.async_api import (
+    AsyncClientApi,
+    AsyncDatabaseApi,
+    AsyncInboundApi,
+    AsyncServerApi,
+)
 from py3xui.utils import Logger, env
 
 
@@ -84,6 +89,9 @@ def __init__(
         self.database = AsyncDatabaseApi(
             host, username, password, token, use_tls_verify, custom_certificate_path, logger
         )
+        self.server = AsyncServerApi(
+            host, username, password, token, use_tls_verify, custom_certificate_path, logger
+        )
         self._session: str | None = None
 
     @property
@@ -101,6 +109,7 @@ def session(self, value: str) -> None:
         self.client.session = value
         self.inbound.session = value
         self.database.session = value
+        self.server.session = value
 
     @classmethod
     def from_env(
@@ -170,4 +179,5 @@ async def login(self) -> None:
         self._session = self.client.session
         self.inbound.session = self._session
         self.database.session = self._session
+        self.server.session = self._session
         self.logger.info("Logged in successfully.")
diff --git a/py3xui/async_api/async_api_server.py b/py3xui/async_api/async_api_server.py
@@ -0,0 +1,66 @@
+"""This module contains the ServerApi class for handling server in the XUI API."""
+
+from py3xui.async_api.async_api_base import AsyncBaseApi
+
+
+class AsyncServerApi(AsyncBaseApi):
+    """This class provides methods to interact with the server in the XUI API in an asynchronous
+    manner.
+
+    Attributes and Properties:
+        host (str): The XUI host URL.
+        username (str): The XUI username.
+        password (str): The XUI password.
+        token (str | None): The XUI secret token.
+        use_tls_verify (bool): Whether to verify the server TLS certificate.
+        custom_certificate_path (str | None): Path to a custom certificate file.
+        session (requests.Session): The session object for the API.
+        max_retries (int): The maximum number of retries for the API requests.
+
+    Public Methods:
+        get_db: Retrieves a database backup file and saves it to a specified path.
+
+    Examples:
+        ```python
+        import py3xui
+
+        api = py3xui.AsyncApi.from_env()
+        await api.login()
+
+        db_save_path = "db_backup.db"
+        await api.server.get_db(db_save_path)
+        ```
+    """
+
+    # pylint: disable=R0801
+    async def get_db(self, save_path: str) -> None:
+        """This route is used to retrieve a database backup file and save it to a specified path.
+
+        Arguments:
+            save_path (str): The path to save the database backup file.
+
+        Examples:
+            ```python
+            import py3xui
+
+            api = py3xui.AsyncApi.from_env()
+            await api.login()
+
+            db_save_path = "db_backup.db"
+            await api.server.get_db(db_save_path)
+            ```
+        """
+        endpoint = "server/getDb"
+        headers = {"Accept": "application/octet-stream"}
+        url = self._url(endpoint)
+        self.logger.info("Getting DB backup...")
+
+        response = await self._get(url, headers, skip_check=True)
+
+        if response.status_code == 200:
+            with open(save_path, "wb") as file:
+                file.write(response.content)
+            self.logger.info(f"DB backup saved to {save_path}")
+        else:
+            self.logger.error(f"Failed to get DB backup: {response.text}")
+            response.raise_for_status()