Metadata-Version: 2.4
Name: pasarguard-panel-api
Version: 0.1.9.2
Summary: Small sync/async SDK for the Pasarguard panel
Project-URL: Homepage, https://github.com/PlushkaNet/pasarguard-panel-api
Project-URL: Repository, https://github.com/PlushkaNet/pasarguard-panel-api.git
Author: PlushkaNet
License: MIT
License-File: LICENSE
Keywords: api,pasarguard,pasarguard api,pasarguard panel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: httpx>=0.20.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

![python-versions-supported](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
![license](https://img.shields.io/badge/license-MIT-green)

# 🛠️ pasarguard-panel-api

## ✨ Sync & async simple python module for interacting with Pasarguard panel API

Uses httpx and pydantic for validation

### 🔥 Features
- Token autorenew

## Installation using git
```
pip install git+https://github.com/PlushkaNet/pasarguard-panel-api.git
```

## 🔑 Auth into Pasarguard panel (sync):
```
from os import getenv
from pasarguard_panel_api import Pasarguard
from dotenv import load_dotenv

load_dotenv() # load environment variables

pg = Pasarguard(
    getenv("host"),
    getenv("user"),
    getenv("password")
)

pg.auth()
```

## ✨ Async example:
```
from os import getenv
import asyncio
from pasarguard_panel_api import AsyncPasarguard
from dotenv import load_dotenv

load_dotenv() # load environment variables

pg = Pasarguard(
    getenv("host"),
    getenv("user"),
    getenv("password")
)

async def main():
    await pg.auth()

asyncio.run(main())
```

> Note: **The API interface is identical for both sync and async operations!**

## 👤 Create new user (sync)
```
from pasarguard_panel_api import NewUser, Status

# auth goes here

# get available groups first
groups = pg.get_groups()

user = pg.add_user(
    NewUser(
        username="new-user",
        status=Status.ACTIVE, # enum for convenient use
        group_ids=[groups.groups[0].id] # just first group from available
    )
)

print(user.subscription_url)
```

## ✨ Async example (almost the same)
```
from pasarguard_panel_api import NewUser, Status

# auth goes here

# first let's get avaliable groups
groups = await pg.get_groups()

user = await pg.add_user(
    NewUser(
        username="new-user",
        status=Status.ACTIVE, # enum for convenient use
        group_ids=[groups.groups[0].id] # just the first group from available
    )
)

print(user.subscription_url)
```

## 🔎 Search users (sync)
```
# auth goes here

# get a single user
user = pg.get_user("some-username")
print(user)

# or get list of search entries
users = pg.get_users(limit=10) # only 10 users
print(users)
```

## ✏️ Modify user (sync)
```
# auth goes here

from pasarguard_panel_api import Status

user = pg.get_user("some-username") # get any user
assert user is not None # check that user exists
user.status = Status.DISABLED # disable user
modified_user = pg.modify_user(user) # modify user
print(modified_user)
```

**Async example is almost the same**

### 📚 For more examples, check the [examples](./examples/) directory

## ℹ️ About

**What this SDK does**: It gives you a fast, simple way to interact with Pasarguard's user management endpoints, without the bloat of a full-feature implementation. The code is kept lean and readable. This is a **minimal** wrapper — not a complete API coverage.

## ✏️ Contributing

If you want to contribute, report a bug, or suggest feature, feel free to open issues and pull requests

**❤️ Special thanks for Pasarguard team for the wonderful panel that makes proxy management easier!**