marzban-api-client

A client library for accessing MarzbanAPI

Table of Contents

• Installation
• Getting Started
• Usage
• Contributing
• License

Installation

You can install this library using pip:

pip install marzban-api-client

Getting Started

Before you can start using this library, you need to obtain an access token by logging in. use the following code to get access token:

from marzban_api_client import Client
from marzban_api_client.api.admin import admin_token
from marzban_api_client.models.body_admin_token_api_admin_token_post import (
    BodyAdminTokenApiAdminTokenPost,
)
from marzban_api_client.models.token import Token
from marzban_api_client.types import Response

login_data = BodyAdminTokenApiAdminTokenPost(
    username="USERNAME",
    password="PASSWORD",
)

client = Client(base_url="BASE_URL")

with client as client:
    token: Token = admin_token.sync(
        client=client,
        body=login_data,
    )
    access_token = token.access_token
    print(f"your admin token is: {access_token}")
    # or if you need more info (e.g. status_code)
    response: Response[Token] = admin_token.sync_detailed(
        client=client,
        body=login_data,
    )
    print(response)

Replace BASE_URL, USERNAME, and PASSWORD with the actual URL of your Marzban API, your username and your password. After executing this code, you will have an access_token that you can use for authenticated requests.

Usage

Now that you have obtained an access token, you can use the AuthenticatedClient to make authenticated API requests. Here's an example of how to use it:

from marzban_api_client import AuthenticatedClient
from marzban_api_client.api.user_template import add_user_template
from marzban_api_client.models.user_template_create import UserTemplateCreate
from marzban_api_client.models.user_template_response import UserTemplateResponse

user_template = UserTemplateCreate(
    name="template_1",
    data_limit=320000000000,
    expire_duration=2592000,
    username_prefix="USER_",
)

client = AuthenticatedClient(
    base_url="BASE_URL",
    token="ACCESS_TOKEN",
)

with client as client:
    response: UserTemplateResponse = add_user_template.sync(
        client=client,
        body=user_template,
    )

print(response)

Replace BASE_URL and ACCESS_TOKEN with the actual URL of your Marzban API and and access_token. you can also do the same thing with an async version:

import asyncio

from marzban_api_client import AuthenticatedClient
from marzban_api_client.api.user_template import add_user_template
from marzban_api_client.models.user_template_create import UserTemplateCreate
from marzban_api_client.models.user_template_response import UserTemplateResponse


async def main():
    user_template = UserTemplateCreate(
        name="template_2",
        data_limit=320000000000,
        expire_duration=2592000,
        username_prefix="USER_",
    )

    client = AuthenticatedClient(
        base_url="BASE_URL",
        token="ACCESS_TOKEN",
    )

    async with client as client:
        response: UserTemplateResponse = await add_user_template.asyncio(
            client=client,
            body=user_template,
        )

    print(response)


if __name__ == "__main__":
    asyncio.run(main())

By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.

client = AuthenticatedClient(
    base_url="https://internal_api.example.com", 
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)

You can also disable certificate validation altogether, but beware that this is a security risk.

client = AuthenticatedClient(
    base_url="https://internal_api.example.com", 
    token="SuperSecretToken", 
    verify_ssl=False
)

Things to know:

1. Every path/method combo becomes a Python module with four functions:

   1. sync: Blocking request that returns parsed data (if successful) or None
   2. sync_detailed: Blocking request that always returns a Request, optionally with parsed set if the request was successful.
   3. asyncio: Like sync but async instead of blocking
   4. asyncio_detailed: Like sync_detailed but async instead of blocking

2. All path/query params, and bodies become method arguments.

Advanced customizations

There are more settings on the generated Client class which let you control more runtime behavior, check out the docstring on that class for more info. You can also customize the underlying httpx.Client or httpx.AsyncClient (depending on your use-case):

from marzban_api_client import Client

def log_request(request):
    print(f"Request event hook: {request.method} {request.url} - Waiting for response")

def log_response(response):
    request = response.request
    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")

client = Client(
    base_url="https://api.example.com",
    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
)

# Or get the underlying httpx client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()

You can even set the httpx client directly, but beware that this will override any existing settings (e.g., base_url):

import httpx
from marzban_api_client import Client

client = Client(
    base_url="https://api.example.com",
)
# Note that base_url needs to be re-set, as would any shared cookies, headers, etc.
client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxies="http://localhost:8030"))

Examples

You can find more usage examples in the example folder. These examples cover various scenarios and use cases to help you get started with this library.

Feel free to explore the examples and adapt them to your own project requirements.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.