marzban 0.2.9__py3-none-any.whl → 0.3.1__py3-none-any.whl

marzban/__init__.py

@@ -63,4 +63,4 @@ __all__ = (
     "SystemStats"
 )
 
-__version__ = "0.2.9"
+__version__ = "0.3.1"

marzban/api.py

@@ -1,17 +1,120 @@
 import httpx
-from typing import Any, Dict, Optional, List
-from pydantic import BaseModel
+import paramiko
+from paramiko.ssh_exception import SSHException
+from sshtunnel import SSHTunnelForwarder
+
 from .models import *
 
+
 class MarzbanAPI:
-    def __init__(self, base_url: str, *, timeout: float = 10.0, verify: bool = False):
+    def __init__(self,
+                 base_url: str, *,
+                 timeout: float = 10.0, verify: bool = False,
+                 ssh_username: Optional[str] = None,
+                 ssh_host: Optional[str] = None,
+                 ssh_port: Optional[int] = 22,
+                 ssh_private_key_path: Optional[str] = None,
+                 ssh_key_passphrase: Optional[str] = None,
+                 ssh_password: Optional[str] = None,
+                 local_bind_host: str = '127.0.0.1',
+                 local_bind_port: int = 8000,
+                 remote_bind_host: str = '127.0.0.1',
+                 remote_bind_port: int = 8000
+                 ):
+        """
+        Initializes the MarzbanAPI client with optional SSH tunneling for secure remote access.
+
+        :param base_url: The base URL of the Marzban API.
+        :param timeout: The request timeout in seconds (default: 10.0).
+        :param verify: SSL verification flag; set to False to ignore SSL verification (default: False).
+        :param ssh_username: SSH username for tunnel authentication.
+        :param ssh_host: SSH server address for setting up the tunnel. If None, no SSH tunnel is used.
+        :param ssh_port: SSH port for connecting to the server (default: 22).
+        :param ssh_private_key_path: Path to the SSH private key file for authentication.
+        :param ssh_key_passphrase: Passphrase for the SSH private key, if applicable.
+        :param ssh_password: Password for SSH authentication. Use if no private key is provided.
+        :param local_bind_host: Local IP address for binding the SSH tunnel (default: '127.0.0.1').
+        :param local_bind_port: Local port for SSH tunnel binding (default: 8000).
+        :param remote_bind_host: Remote IP address for binding on the SSH server side (default: '127.0.0.1').
+        :param remote_bind_port: Remote port for the SSH server binding (default: 8000).
+
+        :raises ValueError: If SSH tunneling is requested but neither a private key nor password is provided.
+        """
+
         self.base_url = base_url
-        self.client = httpx.AsyncClient(base_url=base_url, verify=verify, timeout=timeout)
+        self.timeout = timeout
+        self.verify = verify
+        self.ssh_username = ssh_username
+        self.ssh_host = ssh_host
+        self.ssh_port = ssh_port
+        self.ssh_private_key_path = ssh_private_key_path
+        self.ssh_key_passphrase = ssh_key_passphrase
+        self.ssh_password = ssh_password
+        self.local_bind_host = local_bind_host
+        self.local_bind_port = local_bind_port
+        self.remote_bind_host = remote_bind_host
+        self.remote_bind_port = remote_bind_port
+        self.client = None
+        self._tunnel = None
+        self._forwarder = None
+        if ssh_host and not ssh_private_key_path and not ssh_password:
+            raise ValueError('For an SSH tunnel, you must specify either ssh_private_key_path or ssh_password')
+        if not ssh_host:
+            self.client = httpx.AsyncClient(base_url=self.base_url, verify=self.verify, timeout=self.timeout)
+
+    def _load_private_key(self, key_path, passphrase):
+        key_classes = [paramiko.RSAKey, paramiko.DSSKey, paramiko.ECDSAKey, paramiko.Ed25519Key]
+        for key_class in key_classes:
+            try:
+                if passphrase:
+                    pkey = key_class.from_private_key_file(
+                        key_path,
+                        password=passphrase
+                    )
+                else:
+                    pkey = key_class.from_private_key_file(key_path)
+                return pkey
+            except paramiko.ssh_exception.PasswordRequiredException:
+                print("Ошибка: Приватный ключ защищен паролем. Пожалуйста, укажите пароль.")
+            except SSHException:
+                continue
+        raise ValueError("Unsupported key format or incorrect passphrase.")
+
+    def _initialize(self):
+        """Initialization of the SSH tunnel and the HTTP client."""
+        if self.ssh_host:
+            if self._tunnel and self._tunnel.is_active:
+                return
+            # Uploading the key using paramiko
+            private_key = None
+            if self.ssh_private_key_path:
+                private_key = self._load_private_key(self.ssh_private_key_path, self.ssh_key_passphrase)
+            # Installing an SSH tunnel using sshtunnel
+            self._tunnel = SSHTunnelForwarder(
+                (self.ssh_host, self.ssh_port),
+                ssh_username=self.ssh_username,
+                ssh_password=self.ssh_password,
+                ssh_pkey=private_key,
+                remote_bind_address=(self.remote_bind_host, self.remote_bind_port),
+                local_bind_address=(self.local_bind_host, self.local_bind_port)
+            )
+            self._tunnel.start()
+            self.client = httpx.AsyncClient(
+                base_url=f"http://{self.local_bind_host}:{self.local_bind_port}",
+                timeout=self.timeout, verify=self.verify
+            )
+
+            # HTTP-client with local URL
 
     def _get_headers(self, token: str) -> Dict[str, str]:
         return {"Authorization": f"Bearer {token}"}
 
-    async def _request(self, method: str, url: str, token: Optional[str] = None, data: Optional[BaseModel] = None, params: Optional[Dict[str, Any]] = None) -> httpx.Response:
+    async def _request(self, method: str, url: str, token: Optional[str] = None, data: Optional[BaseModel] = None,
+                       params: Optional[Dict[str, Any]] = None) -> httpx.Response:
+        if self.ssh_host and (not self.client or not self._tunnel.is_active):
+            # Initialize the HTTP client and SSH tunnel if they are closed
+            self._initialize()
+            return await self._request(method, url, token, data, params)
         headers = self._get_headers(token) if token else {}
         json_data = data.model_dump(exclude_none=True) if data else None
         params = {k: v for k, v in (params or {}).items() if v is not None}
@@ -29,6 +132,10 @@ class MarzbanAPI:
             "client_id": "",
             "client_secret": ""
         }
+        if self.ssh_host and (not self.client or not self._tunnel.is_active):
+            # Initialize the HTTP client and SSH tunnel if they are closed
+            self._initialize()
+            return await self.get_token(username, password)
         response = await self.client.post(url, data=payload)
         response.raise_for_status()
         return Token(**response.json())
@@ -52,7 +159,8 @@ class MarzbanAPI:
         url = f"/api/admin/{username}"
         await self._request("DELETE", url, token)
 
-    async def get_admins(self, token: str, offset: Optional[int] = None, limit: Optional[int] = None, username: Optional[str] = None) -> List[Admin]:
+    async def get_admins(self, token: str, offset: Optional[int] = None, limit: Optional[int] = None,
+                         username: Optional[str] = None) -> List[Admin]:
         url = "/api/admins"
         params = {"offset": offset, "limit": limit, "username": username}
         response = await self._request("GET", url, token, params=params)
@@ -72,7 +180,7 @@ class MarzbanAPI:
         url = "/api/hosts"
         response = await self._request("GET", url, token)
         return response.json()
-    
+
     async def modify_hosts(self, hosts: Dict[str, List[ProxyHost]], token: str) -> Dict[str, List[ProxyHost]]:
         url = "/api/hosts"
         response = await self._request("PUT", url, token, data=hosts)
@@ -126,7 +234,9 @@ class MarzbanAPI:
         response = await self._request("POST", url, token)
         return UserResponse(**response.json())
 
-    async def get_users(self, token: str, offset: Optional[int] = None, limit: Optional[int] = None, username: Optional[List[str]] = None, status: Optional[str] = None, sort: Optional[str] = None) -> UsersResponse:
+    async def get_users(self, token: str, offset: Optional[int] = None, limit: Optional[int] = None,
+                        username: Optional[List[str]] = None, status: Optional[str] = None,
+                        sort: Optional[str] = None) -> UsersResponse:
         url = "/api/users"
         params = {"offset": offset, "limit": limit, "username": username, "status": status, "sort": sort}
         response = await self._request("GET", url, token, params=params)
@@ -136,7 +246,8 @@ class MarzbanAPI:
         url = "/api/users/reset"
         await self._request("POST", url, token)
 
-    async def get_user_usage(self, username: str, token: str, start: Optional[str] = None, end: Optional[str] = None) -> UserUsagesResponse:
+    async def get_user_usage(self, username: str, token: str, start: Optional[str] = None,
+                             end: Optional[str] = None) -> UserUsagesResponse:
         url = f"/api/user/{username}/usage"
         params = {"start": start, "end": end}
         response: httpx.Response = await self._request("GET", url, token, params=params)
@@ -147,19 +258,24 @@ class MarzbanAPI:
         response = await self._request("PUT", url, token)
         return UserResponse(**response.json())
 
-    async def get_expired_users(self, token: str, expired_before: Optional[str] = None, expired_after: Optional[str] = None) -> List[str]:
+    async def get_expired_users(self, token: str, expired_before: Optional[str] = None,
+                                expired_after: Optional[str] = None) -> List[str]:
         url = "/api/users/expired"
         params = {"expired_before": expired_before, "expired_after": expired_after}
         response = await self._request("GET", url, token, params=params)
         return response.json()
 
-    async def delete_expired_users(self, token: str, expired_before: Optional[str] = None, expired_after: Optional[str] = None) -> List[str]:
+    async def delete_expired_users(self, token: str, expired_before: Optional[str] = None,
+                                   expired_after: Optional[str] = None) -> List[str]:
         url = "/api/users/expired"
         params = {"expired_before": expired_before, "expired_after": expired_after}
         response = await self._request("DELETE", url, token, params=params)
         return response.json()
 
-    async def get_user_templates(self, token: str, offset: Optional[int] = None, limit: Optional[int] = None) -> List[UserTemplateResponse]:
+    async def get_user_templates(self,
+                                 token: str,
+                                 offset: Optional[int] = None,
+                                 limit: Optional[int] = None) -> List[UserTemplateResponse]:
         url = "/api/user_template"
         params = {"offset": offset, "limit": limit}
         response = await self._request("GET", url, token, params=params)
@@ -175,11 +291,12 @@ class MarzbanAPI:
         response = await self._request("GET", url, token)
         return UserTemplateResponse(**response.json())
 
-    async def modify_user_template(self, template_id: int, template: UserTemplateModify, token: str) -> UserTemplateResponse:
+    async def modify_user_template(self, template_id: int, template: UserTemplateModify,
+                                   token: str) -> UserTemplateResponse:
         url = f"/api/user_template/{template_id}"
         response = await self._request("PUT", url, token, data=template)
         return UserTemplateResponse(**response.json())
-    
+
     async def remove_user_template(self, template_id: int, token: str) -> None:
         url = f"/api/user_template/{template_id}"
         await self._request("DELETE", url, token)
@@ -232,11 +349,12 @@ class MarzbanAPI:
             final_url = f"/sub/{token}/info"
         else:
             raise ValueError("Either url or token must be provided")
-        
+
         response = await self._request("GET", final_url)
         return SubscriptionUserResponse(**response.json())
 
-    async def get_user_usage(self, url: str = None, token: str = None, start: Optional[str] = None, end: Optional[str] = None) -> Any:
+    async def get_user_usage(self, url: str = None, token: str = None, start: Optional[str] = None,
+                             end: Optional[str] = None) -> Any:
         if url:
             # Use the provided URL if it is given
             final_url = url + "/usage"
@@ -245,7 +363,6 @@ class MarzbanAPI:
             final_url = f"/sub/{token}/usage"
         else:
             raise ValueError("Either url or token must be provided")
-        
         params = {"start": start, "end": end}
         response = await self._request("GET", final_url, params=params)
         return response.json()
@@ -259,9 +376,13 @@ class MarzbanAPI:
             final_url = f"/sub/{token}/{client_type}"
         else:
             raise ValueError("Either url or token must be provided")
-        
+
         response = await self._request("GET", final_url)
         return response.json()
 
     async def close(self):
-        await self.client.aclose()
+        """Closing the HTTP client and SSH tunnel."""
+        if self.client:
+            await self.client.aclose()
+        if self._tunnel:
+            self._tunnel.stop()

marzban/models.py

@@ -1,32 +1,39 @@
 from pydantic import BaseModel, field_validator, ValidationInfo, AfterValidator, ValidationError
 from typing import Optional, List, Dict, Any, ClassVar, Annotated
 
+
 class Token(BaseModel):
     access_token: str
     token_type: str = "bearer"
 
+
 class Admin(BaseModel):
     username: str
     is_sudo: bool
     telegram_id: Optional[int] = None
     discord_webhook: Optional[str] = None
 
+
 class AdminCreate(Admin):
     password: str
 
+
 class AdminModify(BaseModel):
     is_sudo: bool
     password: Optional[str] = None
     telegram_id: Optional[int] = None
     discord_webhook: Optional[str] = None
 
+
 class HTTPValidationError(BaseModel):
     detail: Optional[List[Dict[str, Any]]] = None
 
+
 class ProxySettings(BaseModel):
     id: Optional[str] = None
     flow: Optional[str] = None
-    
+
+
 class UserCreate(BaseModel):
     username: str
     proxies: Optional[Dict[str, ProxySettings]] = {}
@@ -42,6 +49,7 @@ class UserCreate(BaseModel):
     on_hold_timeout: Optional[str] = None
     status: Optional[str] = "active"
 
+
 class UserResponse(BaseModel):
     username: Optional[str] = None
     proxies: Optional[Dict[str, ProxySettings]] = {}
@@ -64,12 +72,13 @@ class UserResponse(BaseModel):
     subscription_url: Optional[str] = None
     subscription_token: Optional[str] = None
     excluded_inbounds: Optional[Dict[str, List[str]]] = None
-    
+
     def __init__(self, **data):
         super().__init__(**data)
         if not self.subscription_token and self.subscription_url:
             self.subscription_token = self.subscription_url.split('/')[-1]
 
+
 class NodeCreate(BaseModel):
     name: str
     address: str
@@ -78,6 +87,7 @@ class NodeCreate(BaseModel):
     usage_coefficient: float = 1.0
     add_as_new_host: bool = True
 
+
 class NodeModify(BaseModel):
     name: Optional[str] = None
     address: Optional[str] = None
@@ -86,6 +96,7 @@ class NodeModify(BaseModel):
     usage_coefficient: Optional[float] = None
     status: Optional[str] = None
 
+
 class NodeResponse(BaseModel):
     name: str
     address: str
@@ -97,15 +108,18 @@ class NodeResponse(BaseModel):
     status: str
     message: Optional[str] = None
 
+
 class NodeUsageResponse(BaseModel):
     node_id: Optional[int] = None
     node_name: Optional[str] = None
     uplink: Optional[int] = None
     downlink: Optional[int] = None
 
+
 class NodesUsageResponse(BaseModel):
     usages: List[NodeUsageResponse]
 
+
 class ProxyHost(BaseModel):
     remark: str
     address: str
@@ -119,6 +133,7 @@ class ProxyHost(BaseModel):
     allowinsecure: bool
     is_disabled: bool
 
+
 class ProxyInbound(BaseModel):
     tag: str
     protocol: str
@@ -126,11 +141,13 @@ class ProxyInbound(BaseModel):
     tls: str
     port: Any
 
+
 class CoreStats(BaseModel):
     version: str
     started: bool
     logs_websocket: str
 
+
 class UserModify(BaseModel):
     proxies: Optional[Dict[str, ProxySettings]] = {}
     expire: Optional[int] = None
@@ -145,6 +162,7 @@ class UserModify(BaseModel):
     on_hold_timeout: Optional[str] = None
     status: Optional[str] = None
 
+
 class UserTemplateCreate(BaseModel):
     name: Optional[str] = None
     data_limit: int = 0
@@ -153,6 +171,7 @@ class UserTemplateCreate(BaseModel):
     username_suffix: Optional[str] = None
     inbounds: Optional[Dict[str, List[str]]] = {}
 
+
 class UserTemplateResponse(BaseModel):
     id: int
     name: Optional[str] = None
@@ -162,6 +181,7 @@ class UserTemplateResponse(BaseModel):
     username_suffix: Optional[str] = None
     inbounds: Dict[str, List[str]]
 
+
 class UserTemplateModify(BaseModel):
     name: Optional[str] = None
     data_limit: Optional[int] = None
@@ -170,27 +190,33 @@ class UserTemplateModify(BaseModel):
     username_suffix: Optional[str] = None
     inbounds: Optional[Dict[str, List[str]]] = None
 
+
 class UserUsageResponse(BaseModel):
     node_id: Optional[int]
     node_name: Optional[str]
     used_traffic: Optional[int]
 
+
 class UserUsagesResponse(BaseModel):
     username: str
     usages: List[UserUsageResponse]
 
+
 class UsersResponse(BaseModel):
     users: List[UserResponse]
     total: int
 
+
 class UserStatus(BaseModel):
     enum: ClassVar[List[str]] = ["active", "disabled", "limited", "expired", "on_hold"]
 
+
 class ValidationError(BaseModel):
     loc: List[Any]
     msg: str
     type: str
 
+
 class SubscriptionUserResponse(BaseModel):
     proxies: Dict[str, Any]
     expire: Optional[int] = None
@@ -213,7 +239,8 @@ class SubscriptionUserResponse(BaseModel):
     subscription_url: str = ""
     excluded_inbounds: Dict[str, List[str]] = {}
     admin: Optional[Admin] = None
-    
+
+
 class SystemStats(BaseModel):
     version: Optional[str] = None
     mem_total: Optional[int] = None
@@ -225,4 +252,4 @@ class SystemStats(BaseModel):
     incoming_bandwidth: Optional[int] = None
     outgoing_bandwidth: Optional[int] = None
     incoming_bandwidth_speed: Optional[int] = None
-    outgoing_bandwidth_speed: Optional[int] = None
+    outgoing_bandwidth_speed: Optional[int] = None

{marzban-0.2.9.dist-info → marzban-0.3.1.dist-info}/METADATA

@@ -1,10 +1,15 @@
 Metadata-Version: 2.1
 Name: marzban
-Version: 0.2.9
-Summary: Асинхронная библиотека Python для взаимодействия с MarzbanAPI
+Version: 0.3.1
+Summary: Асинхронная библиотека Python для взаимодействия с MarzbanAPI | Поддерживает работу через HTTPS/SSH
 Home-page: https://github.com/sm1ky/marzban_api
 Author: Artem
 Author-email: contant@sm1ky.com
+Project-URL: Homepage, https://github.com/sm1ky/marzban_api
+Project-URL: Documentation [EN], https://github.com/sm1ky/marzban_api/blob/development/.readme/README_en.md
+Project-URL: Documentation [RU], https://github.com/sm1ky/marzban_api/blob/development/.readme/README_ru.md
+Project-URL: Source, https://github.com/sm1ky/marzban_api
+Project-URL: Developer, https://t.me/sm1ky
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -13,10 +18,19 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx >=0.23.0
 Requires-Dist: pydantic >=1.10.0
+Requires-Dist: paramiko >=3.5.0
+Requires-Dist: sshtunnel >=0.4.0
 
 
 # MarzbanAPI Client
 
+[![Stars](https://img.shields.io/github/stars/sm1ky/marzban_api.svg?style=social)](https://github.com/sm1ky/marzban_api/stargazers)
+[![Forks](https://img.shields.io/github/forks/sm1ky/marzban_api.svg?style=social)](https://github.com/sm1ky/marzban_api/network/members)
+[![Issues](https://img.shields.io/github/issues/sm1ky/marzban_api.svg)](https://github.com/sm1ky/marzban_api/issues)
+[![Supported python versions](https://img.shields.io/pypi/pyversions/marzban.svg)](https://pypi.python.org/pypi/marzban)
+[![Downloads](https://img.shields.io/pypi/dm/marzban.svg)](https://pypi.python.org/pypi/marzban)
+[![PyPi Package Version](https://img.shields.io/pypi/v/marzban)](https://pypi.python.org/pypi/marzban)
+
 **MarzbanAPI Client** is an asynchronous Python library designed for interacting with [Marzban](https://github.com/Gozargah/Marzban). It provides comprehensive methods for managing administrators, users, nodes, and system statistics.
 
 ## Installation

marzban-0.3.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+marzban/__init__.py,sha256=zItcSPeCEd4rUrwdPSMAgsuyQAuUFekCf-IF3g7SMqI,1302
+marzban/api.py,sha256=nRVRyvWbFlKGh9w5HvfPvRqrTSKfiaEAHvC7qskZPTs,18267
+marzban/models.py,sha256=p9QWCmNcDJQZO1EZm4ihgwS7ZJpayaMjo4fFGOpW3cE,6947
+marzban-0.3.1.dist-info/LICENSE,sha256=e7OchdHfXoz2OZRHj8iltLIKYwdri9J4_9PMEnov418,1061
+marzban-0.3.1.dist-info/METADATA,sha256=C6qjMy5G6-LvjkjfuCrjIm_6d2A0obk6cq2Y-oPHcUs,3163
+marzban-0.3.1.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+marzban-0.3.1.dist-info/top_level.txt,sha256=KUmBWzTarBlzw2GZOuk-d-jM2GU4zPWo1iwvW_mXS-c,8
+marzban-0.3.1.dist-info/RECORD,,

{marzban-0.2.9.dist-info → marzban-0.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.1.0)
+Generator: setuptools (75.2.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

marzban-0.2.9.dist-info/RECORD

@@ -1,8 +0,0 @@
-marzban/__init__.py,sha256=x797eiZAH7Sr-2_dKKMOqSHbYF42FO410LKliHzTpPs,1302
-marzban/api.py,sha256=Do5W8v8yxMxb5-h6XHKSNM9B2zrCLDcfJIXi4fGmUYs,12474
-marzban/models.py,sha256=cNL3c_bfZKNp0EKuBDfPpO7vAFjQwK2e0VWqHjnJ64c,6931
-marzban-0.2.9.dist-info/LICENSE,sha256=e7OchdHfXoz2OZRHj8iltLIKYwdri9J4_9PMEnov418,1061
-marzban-0.2.9.dist-info/METADATA,sha256=OInLS2XnkrAJVuiLGc5HaT1IVL-GzYRwDot017IgI8s,1952
-marzban-0.2.9.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-marzban-0.2.9.dist-info/top_level.txt,sha256=KUmBWzTarBlzw2GZOuk-d-jM2GU4zPWo1iwvW_mXS-c,8
-marzban-0.2.9.dist-info/RECORD,,