remnawave-client 2.0.8__tar.gz

remnawave_client-2.0.8/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: remnawave-client
+Version: 2.0.8
+Summary: Sync and async client for the Remnawave API
+License-Expression: MIT
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: adaptix>=3.0.0b12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# remnawave-client
+
+Sync and async client for the [Remnawave](https://docs.rw) API, generated from
+the panel's OpenAPI specification.
+
+- Every endpoint typed end to end — `mypy --strict` clean, `py.typed` shipped
+- The same surface synchronously and asynchronously
+- Listings walked lazily through `iter_*`
+- Webhook events parsed and their signatures verified
+- Transport, serializer, auth and retry policy are all replaceable
+
+```bash
+pip install remnawave-client
+```
+
+Requires Python 3.11 or newer.
+
+## Versions
+
+The library version equals the API version it was generated from. A tag exists
+for every minor release of the panel from 2.0 onwards, so pin the one matching
+your deployment:
+
+```bash
+pip install remnawave-client==3.0.0
+```
+
+```
+2.0.8  2.1.19  2.2.6  2.3.2  2.4.4  2.5.7  2.6.4
+2.7.4  2.8.1   3.0.0  3.1.0  3.2.3  3.3.2  3.4.3
+```
+
+## Quick start
+
+```python
+from remnawave import Remnawave
+
+with Remnawave("https://panel.example.com", token) as rw:
+    user = rw.users.get_user_by_username("zen")
+    print(user.username, user.status, user.expire_at)
+
+    for u in rw.users.iter_users():
+        print(u.username)
+```
+
+The async client mirrors it:
+
+```python
+import asyncio
+
+from remnawave import AsyncRemnawave
+
+async def main() -> None:
+    async with AsyncRemnawave("https://panel.example.com", token) as rw:
+        stats = rw.system.get_stats()
+        nodes = rw.nodes.get_nodes()
+        async for user in rw.users.iter_users():
+            print(user.username)
+
+asyncio.run(main())
+```
+
+More in [`examples/`](examples/): pagination, partial updates, error handling,
+webhooks and swapping out the client's parts.
+
+## Errors
+
+Everything the library raises inherits from `RemnawaveError`. Below it the
+hierarchy splits by cause: `ApiError` for anything the panel answered with,
+`TransportError` when the request never got a reply, `SerializationError` when
+the payload did not match the schema.
+
+```python
+from remnawave.exceptions import NotFoundError
+
+try:
+    rw.users.get_user_by_id(42)
+except NotFoundError as error:
+    print(error.status, error.error_code)  # 404 'A025'
+```
+
+`error_code` is the panel's own code and is more specific than the HTTP
+status — branch on it when you need to tell cases apart.
+
+## Webhooks
+
+```python
+from remnawave.webhooks import SIGNATURE_HEADER, WebhookReceiver
+
+hooks = WebhookReceiver(secret=os.environ["WEBHOOK_SECRET_HEADER"])
+event = hooks.receive(request.body, request.headers[SIGNATURE_HEADER])
+
+if event.scope == "user":
+    print(event.event, event.data.username)
+```
+
+Pass the raw request body: the signature covers those exact bytes, so
+re-serialising parsed JSON breaks verification.
+
+## Regenerating
+
+`src/remnawave/_generated/` is machine-written and must not be edited by hand.
+To target another panel version, drop its specification into `specs/` and run:
+
+```bash
+python -m tools.codegen 3.4.3
+```
+
+Where the specification is wrong or awkward, `overlay.yaml` patches it before
+generation: type names, forced field types, fields kept out of `repr`. Editing
+the generated code directly would be lost on the next run; editing the vendored
+specification would be lost on the next update.

remnawave_client-2.0.8/README.md

@@ -0,0 +1,112 @@
+# remnawave-client
+
+Sync and async client for the [Remnawave](https://docs.rw) API, generated from
+the panel's OpenAPI specification.
+
+- Every endpoint typed end to end — `mypy --strict` clean, `py.typed` shipped
+- The same surface synchronously and asynchronously
+- Listings walked lazily through `iter_*`
+- Webhook events parsed and their signatures verified
+- Transport, serializer, auth and retry policy are all replaceable
+
+```bash
+pip install remnawave-client
+```
+
+Requires Python 3.11 or newer.
+
+## Versions
+
+The library version equals the API version it was generated from. A tag exists
+for every minor release of the panel from 2.0 onwards, so pin the one matching
+your deployment:
+
+```bash
+pip install remnawave-client==3.0.0
+```
+
+```
+2.0.8  2.1.19  2.2.6  2.3.2  2.4.4  2.5.7  2.6.4
+2.7.4  2.8.1   3.0.0  3.1.0  3.2.3  3.3.2  3.4.3
+```
+
+## Quick start
+
+```python
+from remnawave import Remnawave
+
+with Remnawave("https://panel.example.com", token) as rw:
+    user = rw.users.get_user_by_username("zen")
+    print(user.username, user.status, user.expire_at)
+
+    for u in rw.users.iter_users():
+        print(u.username)
+```
+
+The async client mirrors it:
+
+```python
+import asyncio
+
+from remnawave import AsyncRemnawave
+
+async def main() -> None:
+    async with AsyncRemnawave("https://panel.example.com", token) as rw:
+        stats = rw.system.get_stats()
+        nodes = rw.nodes.get_nodes()
+        async for user in rw.users.iter_users():
+            print(user.username)
+
+asyncio.run(main())
+```
+
+More in [`examples/`](examples/): pagination, partial updates, error handling,
+webhooks and swapping out the client's parts.
+
+## Errors
+
+Everything the library raises inherits from `RemnawaveError`. Below it the
+hierarchy splits by cause: `ApiError` for anything the panel answered with,
+`TransportError` when the request never got a reply, `SerializationError` when
+the payload did not match the schema.
+
+```python
+from remnawave.exceptions import NotFoundError
+
+try:
+    rw.users.get_user_by_id(42)
+except NotFoundError as error:
+    print(error.status, error.error_code)  # 404 'A025'
+```
+
+`error_code` is the panel's own code and is more specific than the HTTP
+status — branch on it when you need to tell cases apart.
+
+## Webhooks
+
+```python
+from remnawave.webhooks import SIGNATURE_HEADER, WebhookReceiver
+
+hooks = WebhookReceiver(secret=os.environ["WEBHOOK_SECRET_HEADER"])
+event = hooks.receive(request.body, request.headers[SIGNATURE_HEADER])
+
+if event.scope == "user":
+    print(event.event, event.data.username)
+```
+
+Pass the raw request body: the signature covers those exact bytes, so
+re-serialising parsed JSON breaks verification.
+
+## Regenerating
+
+`src/remnawave/_generated/` is machine-written and must not be edited by hand.
+To target another panel version, drop its specification into `specs/` and run:
+
+```bash
+python -m tools.codegen 3.4.3
+```
+
+Where the specification is wrong or awkward, `overlay.yaml` patches it before
+generation: type names, forced field types, fields kept out of `repr`. Editing
+the generated code directly would be lost on the next run; editing the vendored
+specification would be lost on the next update.

remnawave_client-2.0.8/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "remnawave-client"
+version = "2.0.8"
+description = "Sync and async client for the Remnawave API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "httpx>=0.28.1",
+    "adaptix>=3.0.0b12",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "mypy>=2.3.1",
+    "ruff>=0.16.4",
+    "jinja2>=3.1",
+    "pyyaml>=6.0",
+    "types-PyYAML>=6.0",
+    "pytest-cov>=6.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# Пакет называется remnawave, а дистрибутив remnawave-client,
+# поэтому имя модуля задаём явно.
+module-name = "remnawave"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+source = ["src/remnawave"]
+omit = ["src/remnawave/_generated/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    ': \.\.\.$',  # Protocols/overloads
+]
+
+[tool.ruff]
+line-length = 80
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "CPY001",
+    "D",
+    "COM812",
+    "ASYNC109",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/remnawave/_generated/**" = ["PLR0913", "ANN401", "S105"]
+"examples/**" = ["T201", "INP001"]
+"src/remnawave/types/**" = ["E501"]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "EM101",
+    "TRY003",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests", "tools", "examples"]

remnawave_client-2.0.8/src/remnawave/__init__.py

@@ -0,0 +1,9 @@
+from remnawave.client import (
+    AsyncRemnawave as AsyncRemnawave,
+)
+from remnawave.client import (
+    Remnawave as Remnawave,
+)
+
+__version__ = "2.0.8"
+API_VERSION = "2.0.8"

remnawave_client-2.0.8/src/remnawave/_generated/__init__.py

@@ -0,0 +1 @@
+# @generated by tools/codegen -- do not edit

remnawave_client-2.0.8/src/remnawave/_generated/enums.py

@@ -0,0 +1,68 @@
+# @generated by tools/codegen -- do not edit
+from enum import StrEnum
+
+
+class OAuth2CallbackRequestProvider(StrEnum):
+    GITHUB = "github"
+    POCKETID = "pocketid"
+    YANDEX = "yandex"
+
+
+class UserStatus(StrEnum):
+    ACTIVE = "ACTIVE"
+    DISABLED = "DISABLED"
+    LIMITED = "LIMITED"
+    EXPIRED = "EXPIRED"
+
+
+class UserTrafficLimitStrategy(StrEnum):
+    NO_RESET = "NO_RESET"
+    DAY = "DAY"
+    WEEK = "WEEK"
+    MONTH = "MONTH"
+
+
+class SubscriptionControllerGetSubscriptionByClientType(StrEnum):
+    STASH = "stash"
+    SINGBOX = "singbox"
+    SINGBOX_LEGACY = "singbox-legacy"
+    MIHOMO = "mihomo"
+    JSON = "json"
+    V2RAY_JSON = "v2ray-json"
+    CLASH = "clash"
+
+
+class TemplateTemplateType(StrEnum):
+    STASH = "STASH"
+    SINGBOX = "SINGBOX"
+    SINGBOX_LEGACY = "SINGBOX_LEGACY"
+    MIHOMO = "MIHOMO"
+    XRAY_JSON = "XRAY_JSON"
+    CLASH = "CLASH"
+
+
+class HostSecurityLayer(StrEnum):
+    DEFAULT = "DEFAULT"
+    TLS = "TLS"
+    NONE = "NONE"
+
+
+class CreateHostRequestAlpn(StrEnum):
+    H3 = "h3"
+    H2 = "h2"
+    HTTP_1_1 = "http/1.1"
+    H2_HTTP_1_1 = "h2,http/1.1"
+    H3_H2_HTTP_1_1 = "h3,h2,http/1.1"
+    H3_H2 = "h3,h2"
+
+
+class CreateHostRequestFingerprint(StrEnum):
+    CHROME = "chrome"
+    FIREFOX = "firefox"
+    SAFARI = "safari"
+    IOS = "ios"
+    ANDROID = "android"
+    EDGE = "edge"
+    QQ = "qq"
+    RANDOM = "random"
+    RANDOMIZED = "randomized"

remnawave_client-2.0.8/src/remnawave/_generated/groups.py

@@ -0,0 +1,165 @@
+# @generated by tools/codegen -- do not edit
+
+from remnawave._generated.methods.api_tokens_management import (
+    ApiTokensManagementApi,
+    AsyncApiTokensManagementApi,
+)
+from remnawave._generated.methods.auth import (
+    AsyncAuthApi,
+    AuthApi,
+)
+from remnawave._generated.methods.bandwidth_stats import (
+    AsyncBandwidthStatsApi,
+    BandwidthStatsApi,
+)
+from remnawave._generated.methods.config_profiles import (
+    AsyncConfigProfilesApi,
+    ConfigProfilesApi,
+)
+from remnawave._generated.methods.hosts import (
+    AsyncHostsApi,
+    HostsApi,
+)
+from remnawave._generated.methods.hosts_bulk_actions import (
+    AsyncHostsBulkActionsApi,
+    HostsBulkActionsApi,
+)
+from remnawave._generated.methods.hwid_user_devices import (
+    AsyncHwidUserDevicesApi,
+    HwidUserDevicesApi,
+)
+from remnawave._generated.methods.infra_billing import (
+    AsyncInfraBillingApi,
+    InfraBillingApi,
+)
+from remnawave._generated.methods.internal_squads import (
+    AsyncInternalSquadsApi,
+    InternalSquadsApi,
+)
+from remnawave._generated.methods.keygen import (
+    AsyncKeygenApi,
+    KeygenApi,
+)
+from remnawave._generated.methods.nodes import (
+    AsyncNodesApi,
+    NodesApi,
+)
+from remnawave._generated.methods.subscription import (
+    AsyncSubscriptionApi,
+    SubscriptionApi,
+)
+from remnawave._generated.methods.subscriptions import (
+    AsyncSubscriptionsApi,
+    SubscriptionsApi,
+)
+from remnawave._generated.methods.subscriptions_settings import (
+    AsyncSubscriptionsSettingsApi,
+    SubscriptionsSettingsApi,
+)
+from remnawave._generated.methods.subscriptions_template import (
+    AsyncSubscriptionsTemplateApi,
+    SubscriptionsTemplateApi,
+)
+from remnawave._generated.methods.system import (
+    AsyncSystemApi,
+    SystemApi,
+)
+from remnawave._generated.methods.users import (
+    AsyncUsersApi,
+    UsersApi,
+)
+from remnawave._generated.methods.users_bulk_actions import (
+    AsyncUsersBulkActionsApi,
+    UsersBulkActionsApi,
+)
+from remnawave._generated.methods.users_stats import (
+    AsyncUsersStatsApi,
+    UsersStatsApi,
+)
+from remnawave.execution import AsyncExecutor, SyncExecutor
+
+
+class SyncGroups:
+    api_tokens_management: ApiTokensManagementApi
+    auth: AuthApi
+    bandwidth_stats: BandwidthStatsApi
+    config_profiles: ConfigProfilesApi
+    hosts: HostsApi
+    hosts_bulk_actions: HostsBulkActionsApi
+    hwid_user_devices: HwidUserDevicesApi
+    infra_billing: InfraBillingApi
+    internal_squads: InternalSquadsApi
+    keygen: KeygenApi
+    nodes: NodesApi
+    subscription: SubscriptionApi
+    subscriptions: SubscriptionsApi
+    subscriptions_settings: SubscriptionsSettingsApi
+    subscriptions_template: SubscriptionsTemplateApi
+    system: SystemApi
+    users: UsersApi
+    users_bulk_actions: UsersBulkActionsApi
+    users_stats: UsersStatsApi
+
+    def _attach(self, executor: SyncExecutor) -> None:
+        self.api_tokens_management = ApiTokensManagementApi(executor)
+        self.auth = AuthApi(executor)
+        self.bandwidth_stats = BandwidthStatsApi(executor)
+        self.config_profiles = ConfigProfilesApi(executor)
+        self.hosts = HostsApi(executor)
+        self.hosts_bulk_actions = HostsBulkActionsApi(executor)
+        self.hwid_user_devices = HwidUserDevicesApi(executor)
+        self.infra_billing = InfraBillingApi(executor)
+        self.internal_squads = InternalSquadsApi(executor)
+        self.keygen = KeygenApi(executor)
+        self.nodes = NodesApi(executor)
+        self.subscription = SubscriptionApi(executor)
+        self.subscriptions = SubscriptionsApi(executor)
+        self.subscriptions_settings = SubscriptionsSettingsApi(executor)
+        self.subscriptions_template = SubscriptionsTemplateApi(executor)
+        self.system = SystemApi(executor)
+        self.users = UsersApi(executor)
+        self.users_bulk_actions = UsersBulkActionsApi(executor)
+        self.users_stats = UsersStatsApi(executor)
+
+
+class AsyncGroups:
+    api_tokens_management: AsyncApiTokensManagementApi
+    auth: AsyncAuthApi
+    bandwidth_stats: AsyncBandwidthStatsApi
+    config_profiles: AsyncConfigProfilesApi
+    hosts: AsyncHostsApi
+    hosts_bulk_actions: AsyncHostsBulkActionsApi
+    hwid_user_devices: AsyncHwidUserDevicesApi
+    infra_billing: AsyncInfraBillingApi
+    internal_squads: AsyncInternalSquadsApi
+    keygen: AsyncKeygenApi
+    nodes: AsyncNodesApi
+    subscription: AsyncSubscriptionApi
+    subscriptions: AsyncSubscriptionsApi
+    subscriptions_settings: AsyncSubscriptionsSettingsApi
+    subscriptions_template: AsyncSubscriptionsTemplateApi
+    system: AsyncSystemApi
+    users: AsyncUsersApi
+    users_bulk_actions: AsyncUsersBulkActionsApi
+    users_stats: AsyncUsersStatsApi
+
+    def _attach(self, executor: AsyncExecutor) -> None:
+        self.api_tokens_management = AsyncApiTokensManagementApi(executor)
+        self.auth = AsyncAuthApi(executor)
+        self.bandwidth_stats = AsyncBandwidthStatsApi(executor)
+        self.config_profiles = AsyncConfigProfilesApi(executor)
+        self.hosts = AsyncHostsApi(executor)
+        self.hosts_bulk_actions = AsyncHostsBulkActionsApi(executor)
+        self.hwid_user_devices = AsyncHwidUserDevicesApi(executor)
+        self.infra_billing = AsyncInfraBillingApi(executor)
+        self.internal_squads = AsyncInternalSquadsApi(executor)
+        self.keygen = AsyncKeygenApi(executor)
+        self.nodes = AsyncNodesApi(executor)
+        self.subscription = AsyncSubscriptionApi(executor)
+        self.subscriptions = AsyncSubscriptionsApi(executor)
+        self.subscriptions_settings = AsyncSubscriptionsSettingsApi(executor)
+        self.subscriptions_template = AsyncSubscriptionsTemplateApi(executor)
+        self.system = AsyncSystemApi(executor)
+        self.users = AsyncUsersApi(executor)
+        self.users_bulk_actions = AsyncUsersBulkActionsApi(executor)
+        self.users_stats = AsyncUsersStatsApi(executor)

remnawave_client-2.0.8/src/remnawave/_generated/methods/__init__.py

@@ -0,0 +1 @@
+# @generated by tools/codegen -- do not edit

remnawave_client-2.0.8/src/remnawave/_generated/methods/api_tokens_management.py

@@ -0,0 +1,56 @@
+# @generated by tools/codegen -- do not edit
+"""API Tokens Management."""
+
+from remnawave._generated.models import (
+    ApiToken,
+    CreateApiTokenRequest,
+    FindAllApiTokens,
+)
+from remnawave.execution import AsyncGroup, SyncGroup
+from remnawave.operations import (
+    Operation,
+)
+
+CREATE: Operation[ApiToken] = Operation(
+    "POST",
+    "/api/tokens",
+    ApiToken,
+)
+FIND_ALL: Operation[FindAllApiTokens] = Operation(
+    "GET",
+    "/api/tokens",
+    FindAllApiTokens,
+)
+DELETE: Operation[bool] = Operation(
+    "DELETE",
+    "/api/tokens/{uuid}",
+    bool,
+)
+
+
+class ApiTokensManagementApi(SyncGroup):
+    def create(self, body: CreateApiTokenRequest) -> ApiToken:
+        """Create a new API token."""
+        return self._executor.execute(CREATE, body=body)
+
+    def find_all(self) -> FindAllApiTokens:
+        """Get all API tokens."""
+        return self._executor.execute(FIND_ALL)
+
+    def delete(self, uuid: str) -> bool:
+        """Delete an API token by UUID."""
+        return self._executor.execute(DELETE, path={"uuid": uuid})
+
+
+class AsyncApiTokensManagementApi(AsyncGroup):
+    async def create(self, body: CreateApiTokenRequest) -> ApiToken:
+        """Create a new API token."""
+        return await self._executor.execute(CREATE, body=body)
+
+    async def find_all(self) -> FindAllApiTokens:
+        """Get all API tokens."""
+        return await self._executor.execute(FIND_ALL)
+
+    async def delete(self, uuid: str) -> bool:
+        """Delete an API token by UUID."""
+        return await self._executor.execute(DELETE, path={"uuid": uuid})