Skip to main content

Pasarguard

PyPI Python License HTTPX Pydantic

Pasarguard is a modern, typed, async Python client for the PasarGuard Panel API.

فارسی

It provides a clean interface for authentication, users, admins, nodes, groups, hosts, templates, subscriptions, settings, system stats, and bulk operations. The client is powered by httpx.AsyncClient and Pydantic v2 models.

Installation

pip install pasarguard

Install SSH tunnel support only when needed:

pip install "pasarguard[ssh]"
uv add pasarguard

Features

  • Async-first API client.
  • Typed request and response models with Pydantic v2.
  • Bearer-token authentication.
  • Optional SSH tunnel support via the ssh extra.
  • User, admin, node, group, host, core, template, and subscription management.
  • Bulk operations for users, admins, nodes, groups, hosts, and templates.
  • Usage metrics, realtime node stats, inbound details, and worker health endpoints.

Compatibility

  • Python >=3.10,<3.15
  • Windows, macOS, and Linux
  • httpx>=0.28.1
  • pydantic>=2.4.1,<2.13

Quick Start

import asyncio
import os

from pasarguard import PasarguardAPI, Tools, UserCreate, UserStatus


async def main() -> None:
    async with PasarguardAPI(
        base_url=os.environ["PASARGUARD_BASE_URL"],
        verify=True,
        timeout=20.0,
    ) as api:
        token = await api.get_token(
            username=os.environ["PASARGUARD_ADMIN_USERNAME"],
            password=os.environ["PASARGUARD_ADMIN_PASSWORD"],
        )

        user = await api.create_user_in_all_groups(
            UserCreate(
                username=Tools.random_username(prefix="customer"),
                data_limit=Tools.gb(50),
                expire=Tools.days(30),
                status=UserStatus.ACTIVE,
                note="Created by automation",
            ),
            token=token.access_token,
        )

        print(user.id, user.username, user.subscription_url)


asyncio.run(main())

Convenience helpers

from pasarguard import Tools

username = Tools.random_username(prefix="trial")
traffic_limit = Tools.gb(20)          # 20 GiB in bytes
expire_at = Tools.days(30)            # Unix timestamp for 30 days from now

assert Tools.to_bytes("500MB") == 500 * 1024**2
assert Tools.to_timestamp("12h") > 0

Supported size helpers: Tools.mb(), Tools.gb(), Tools.tb(). Supported timestamp helpers: Tools.minutes(), Tools.hours(), Tools.days(), Tools.to_timestamp().

Authentication

token = await api.get_token(
    username=os.environ["PASARGUARD_ADMIN_USERNAME"],
    password=os.environ["PASARGUARD_ADMIN_PASSWORD"],
)

admin = await api.get_current_admin(token=token.access_token)
print(admin.username, admin.is_sudo)

admin_token() is also available as an alias for get_token().

Client Initialization

Basic client:

api = PasarguardAPI(
    base_url=os.environ["PASARGUARD_BASE_URL"],
    timeout=10.0,
    verify=True,
)

With an SSH tunnel:

api = PasarguardAPI(
    base_url="http://127.0.0.1:8000",
    ssh_host=os.environ["PASARGUARD_SSH_HOST"],
    ssh_username=os.environ["PASARGUARD_SSH_USERNAME"],
    ssh_private_key_path=os.environ["PASARGUARD_SSH_KEY_PATH"],
    local_bind_host="127.0.0.1",
    local_bind_port=8000,
    remote_bind_host="127.0.0.1",
    remote_bind_port=8000,
)

Common Usage

List Users

from pasarguard import UserStatus

users = await api.get_users(
    token=token,
    offset=0,
    limit=50,
    status=UserStatus.ACTIVE,
    load_sub=True,
)

for user in users.users:
    print(user.username, user.used_traffic)

Modify a User

from pasarguard import UserModify

user = await api.modify_user(
    username="customer-1001",
    user=UserModify(note="Renewed monthly plan"),
    token=token,
)

Bulk Disable Users

from pasarguard import BulkUsersSelection

result = await api.bulk_disable_users(
    BulkUsersSelection(ids=[101, 102, 103]),
    token=token,
)

print(result.count, result.users)

Subscription Info

from pasarguard import ConfigFormat

info = await api.user_subscription_info(token="subscription-token-value")
links = await api.get_user_subscription_with_client_type(
    token="subscription-token-value",
    client_type=ConfigFormat.LINKS,
)

print(info.username)
print("\n".join(links))

Node Stats

stats = await api.realtime_node_stats(node_id=1, token=token)
print(stats.cpu_usage, stats.mem_used)

Error Handling

Pasarguard uses httpx internally. HTTP errors are raised as httpx.HTTPStatusError.

import httpx

try:
    user = await api.get_user("customer-1001", token=token)
except httpx.HTTPStatusError as exc:
    print(exc.response.status_code)
    print(exc.response.text)
except httpx.RequestError as exc:
    print(f"Network error: {exc}")

Pagination

Endpoints that return lists commonly support offset and limit.

offset = 0
limit = 100

while True:
    page = await api.get_users(token=token, offset=offset, limit=limit)

    for user in page.users:
        print(user.username)

    offset += limit
    if offset >= page.total:
        break

API Overview

Main public client: PasarguardAPI

Important method groups:

  • Authentication: get_token(), admin_token()
  • Users: create_user(), get_user(), get_users(), modify_user(), remove_user()
  • User bulk actions: bulk_delete_users(), bulk_disable_users(), bulk_enable_users(), bulk_reset_users_data_usage()
  • Admins: get_current_admin(), create_admin(), get_admins(), modify_admin(), remove_admin()
  • Nodes: create_node(), get_nodes(), realtime_node_stats(), sync_node(), reconnect_node()
  • Groups: create_group(), get_all_groups(), modify_group(), remove_group()
  • Hosts: create_host(), get_hosts(), modify_host(), remove_host()
  • Cores: create_core_config(), get_all_cores(), restart_core()
  • Templates: create_user_template(), create_client_template()
  • Subscriptions: user_subscription_info(), user_subscription_with_client_type()
  • Settings and system: get_settings(), modify_settings(), get_system_stats(), get_workers_health()

Common public models:

  • UserCreate, UserModify, UserResponse, UsersResponse
  • AdminCreate, AdminModify, AdminDetails
  • NodeCreate, NodeModify, NodeResponse
  • GroupCreate, GroupModify, GroupResponse
  • CreateHost, BaseHost
  • CoreCreate, CoreResponse
  • SettingsSchema, SubscriptionUserResponse

Common enums:

  • UserStatus
  • Period
  • ConfigFormat
  • DataLimitResetStrategy
  • NodeStatus
  • NodeConnectionType
  • CoreType

License

This project is licensed under the MIT License. See LICENSE for details.

Metadata

Release files for pasarguard 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pasarguard 2.4.0
File Size Uploaded Provenance Actions
pasarguard-2.4.0.tar.gz 122.2 kB Without provenance Details for pasarguard-2.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pasarguard 2.4.0
File Interpreter ABI Platform Actions
pasarguard-2.4.0-py3-none-any.whl Python 3 none any Details for pasarguard-2.4.0-py3-none-any.whl

Total release size: 172.5 kB

Release files / pasarguard-2.4.0.tar.gz

Download URL pasarguard-2.4.0.tar.gz
Size 122.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7bbc4c5c2c220f66052256f324ab45ee498d597334c0b21417588a06ec600b8f
BLAKE2b-256 checksum
How to use checksums
9207ab6b8dbe0605e4afd670bcbe7facb31ae9364420e5288f70ff6697f73be4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / pasarguard-2.4.0-py3-none-any.whl

Download URL pasarguard-2.4.0-py3-none-any.whl
Size 50.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ec407c409941f331e109c483dc46245625f80028bd0d26931dde062c6f5e70f1
BLAKE2b-256 checksum
How to use checksums
afa9c3daf86e5f37a75a315fa4f0dd19dcc9b376e207ad4ae2c4dbbda206c361
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for pasarguard 2.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page