| Name | pyoutlineapi JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic models. |
| upload_time | 2025-01-10 17:21:32 |
| maintainer | None |
| docs_url | None |
| author | Denis Rozhnovskiy |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
outline
vpn
api
manager
wrapper
asyncio
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PyOutlineAPI
A modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic
models.
[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)
[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)
[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)
[](https://github.com/orenlab/pyoutlineapi/actions/workflows/python_tests.yml)
[](https://codecov.io/gh/orenlab/pyoutlineapi)
## Features
- **Async-First Design**: Built with modern async/await patterns for optimal performance
- **Type Safety**: Full typing support with runtime validation via Pydantic
- **Comprehensive API Coverage**: Support for all Outline VPN Server
API [endpoints](https://github.com/Jigsaw-Code/outline-server/blob/master/src/shadowbox/server/api.yml)
- **Error Handling**: Robust error handling with custom exception types
- **SSL/TLS Security**: Certificate fingerprint verification for enhanced security
- **Flexible Response Format**: Choose between Pydantic models or JSON responses
- **Data Transfer Metrics**: Built-in support for monitoring server and key usage
- **Context Manager Support**: Clean resource management with async context managers
## Installation
Install via pip:
```bash
pip install pyoutlineapi
```
Or using Poetry:
```bash
poetry add pyoutlineapi
```
## Quick Start
Here's a simple example to get you started:
```python
import asyncio
from pyoutlineapi import AsyncOutlineClient
async def main():
async with AsyncOutlineClient(
api_url="https://your-outline-server:port/api",
cert_sha256="your-certificate-fingerprint"
) as client:
# Get server info
server = await client.get_server_info()
print(f"Connected to {server.name} running version {server.version}")
# Create a new access key
key = await client.create_access_key(name="TestUser")
print(f"Created key: {key.access_url}")
if __name__ == "__main__":
asyncio.run(main())
```
## Detailed Usage
### Client Configuration
The client can be configured with several options:
```python
from pyoutlineapi import AsyncOutlineClient
client = AsyncOutlineClient(
api_url="https://your-outline-server:port/api",
cert_sha256="your-certificate-fingerprint",
json_format=True, # Return JSON instead of Pydantic models
timeout=30.0 # Request timeout in seconds
)
```
### Managing Access Keys
Create and manage access keys:
```python
from pyoutlineapi import AsyncOutlineClient, DataLimit
async def manage_keys():
async with AsyncOutlineClient(...) as client:
# Create a key with data limit
key = await client.create_access_key(
name="Limited User",
port=8388,
limit=DataLimit(bytes=5 * 1024 ** 3) # 5 GB limit
)
# List all keys
keys = await client.get_access_keys()
for key in keys.access_keys:
print(f"Key {key.id}: {key.name or 'unnamed'}")
# Modify a key
await client.rename_access_key(1, "New Name")
await client.set_access_key_data_limit(1, 10 * 1024 ** 3) # 10 GB
# Delete a key
await client.delete_access_key(1)
```
### Server Management
Configure server settings:
```python
from pyoutlineapi import AsyncOutlineClient
async def configure_server():
async with AsyncOutlineClient(...) as client:
# Update server name
await client.rename_server("My VPN Server")
# Set hostname for access keys
await client.set_hostname("vpn.example.com")
# Configure default port for new keys
await client.set_default_port(8388)
```
### Metrics Collection
Monitor server usage:
```python
from pyoutlineapi import AsyncOutlineClient, MetricsPeriod
async def get_metrics():
async with AsyncOutlineClient(...) as client:
# Enable metrics collection
await client.set_metrics_status(True)
# Get transfer metrics
metrics = await client.get_transfer_metrics(MetricsPeriod.MONTHLY)
for user_id, bytes_transferred in metrics.bytes_transferred_by_user_id.items():
print(f"User {user_id}: {bytes_transferred / 1024 ** 3:.2f} GB")
```
## Error Handling
The client provides custom exceptions for different error scenarios:
```python
from pyoutlineapi import AsyncOutlineClient, OutlineError, APIError
async def handle_errors():
try:
async with AsyncOutlineClient(...) as client:
await client.get_server_info()
except APIError as e:
print(f"API error: {e}")
except OutlineError as e:
print(f"Client error: {e}")
```
## Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull
requests, report issues, and contribute to the project.
## Security
If you discover any security-related issues, please email `pytelemonbot@mail.ru` instead of using the issue tracker.
## License
PyOutlineAPI is open-sourced software licensed under the [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "pyoutlineapi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "outline, vpn, api, manager, wrapper, asyncio",
"author": "Denis Rozhnovskiy",
"author_email": "pytelemonbot@mail.ru",
"download_url": "https://files.pythonhosted.org/packages/ee/29/2c6e3208062e0266315ebc3144a32f6dad0830129be60cafcc152de9f47c/pyoutlineapi-0.2.0.tar.gz",
"platform": null,
"description": "# PyOutlineAPI\n\nA modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic\nmodels.\n\n[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)\n[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)\n[](https://sonarcloud.io/summary/new_code?id=orenlab_pyoutlineapi)\n[](https://github.com/orenlab/pyoutlineapi/actions/workflows/python_tests.yml)\n[](https://codecov.io/gh/orenlab/pyoutlineapi)\n\n\n## Features\n\n- **Async-First Design**: Built with modern async/await patterns for optimal performance\n- **Type Safety**: Full typing support with runtime validation via Pydantic\n- **Comprehensive API Coverage**: Support for all Outline VPN Server\n API [endpoints](https://github.com/Jigsaw-Code/outline-server/blob/master/src/shadowbox/server/api.yml)\n- **Error Handling**: Robust error handling with custom exception types\n- **SSL/TLS Security**: Certificate fingerprint verification for enhanced security\n- **Flexible Response Format**: Choose between Pydantic models or JSON responses\n- **Data Transfer Metrics**: Built-in support for monitoring server and key usage\n- **Context Manager Support**: Clean resource management with async context managers\n\n## Installation\n\nInstall via pip:\n\n```bash\npip install pyoutlineapi\n```\n\nOr using Poetry:\n\n```bash\npoetry add pyoutlineapi\n```\n\n## Quick Start\n\nHere's a simple example to get you started:\n\n```python\nimport asyncio\nfrom pyoutlineapi import AsyncOutlineClient\n\n\nasync def main():\n async with AsyncOutlineClient(\n api_url=\"https://your-outline-server:port/api\",\n cert_sha256=\"your-certificate-fingerprint\"\n ) as client:\n # Get server info\n server = await client.get_server_info()\n print(f\"Connected to {server.name} running version {server.version}\")\n\n # Create a new access key\n key = await client.create_access_key(name=\"TestUser\")\n print(f\"Created key: {key.access_url}\")\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Detailed Usage\n\n### Client Configuration\n\nThe client can be configured with several options:\n\n```python\nfrom pyoutlineapi import AsyncOutlineClient\n\nclient = AsyncOutlineClient(\n api_url=\"https://your-outline-server:port/api\",\n cert_sha256=\"your-certificate-fingerprint\",\n json_format=True, # Return JSON instead of Pydantic models\n timeout=30.0 # Request timeout in seconds\n)\n```\n\n### Managing Access Keys\n\nCreate and manage access keys:\n\n```python\n\nfrom pyoutlineapi import AsyncOutlineClient, DataLimit\n\n\nasync def manage_keys():\n async with AsyncOutlineClient(...) as client:\n # Create a key with data limit\n key = await client.create_access_key(\n name=\"Limited User\",\n port=8388,\n limit=DataLimit(bytes=5 * 1024 ** 3) # 5 GB limit\n )\n\n # List all keys\n keys = await client.get_access_keys()\n for key in keys.access_keys:\n print(f\"Key {key.id}: {key.name or 'unnamed'}\")\n\n # Modify a key\n await client.rename_access_key(1, \"New Name\")\n await client.set_access_key_data_limit(1, 10 * 1024 ** 3) # 10 GB\n\n # Delete a key\n await client.delete_access_key(1)\n```\n\n### Server Management\n\nConfigure server settings:\n\n```python\n\nfrom pyoutlineapi import AsyncOutlineClient\n\n\nasync def configure_server():\n async with AsyncOutlineClient(...) as client:\n # Update server name\n await client.rename_server(\"My VPN Server\")\n\n # Set hostname for access keys\n await client.set_hostname(\"vpn.example.com\")\n\n # Configure default port for new keys\n await client.set_default_port(8388)\n```\n\n### Metrics Collection\n\nMonitor server usage:\n\n```python\nfrom pyoutlineapi import AsyncOutlineClient, MetricsPeriod\n\n\nasync def get_metrics():\n async with AsyncOutlineClient(...) as client:\n # Enable metrics collection\n await client.set_metrics_status(True)\n\n # Get transfer metrics\n metrics = await client.get_transfer_metrics(MetricsPeriod.MONTHLY)\n for user_id, bytes_transferred in metrics.bytes_transferred_by_user_id.items():\n print(f\"User {user_id}: {bytes_transferred / 1024 ** 3:.2f} GB\")\n```\n\n## Error Handling\n\nThe client provides custom exceptions for different error scenarios:\n\n```python\nfrom pyoutlineapi import AsyncOutlineClient, OutlineError, APIError\n\n\nasync def handle_errors():\n try:\n async with AsyncOutlineClient(...) as client:\n await client.get_server_info()\n except APIError as e:\n print(f\"API error: {e}\")\n except OutlineError as e:\n print(f\"Client error: {e}\")\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull\nrequests, report issues, and contribute to the project.\n\n## Security\n\nIf you discover any security-related issues, please email `pytelemonbot@mail.ru` instead of using the issue tracker.\n\n## License\n\nPyOutlineAPI is open-sourced software licensed under the [MIT license](LICENSE).",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic models.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://orenlab.github.io/pyoutlineapi/",
"changelog": "https://github.com/orenlab/pyoutlineapi/blob/main/CHANGELOG.md",
"documentation": "https://github.com/orenlab/pyoutlineapi/blob/main/README.md",
"homepage": "https://github.com/orenlab/pyoutlineapi"
},
"split_keywords": [
"outline",
" vpn",
" api",
" manager",
" wrapper",
" asyncio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1f3ff64d46d378aae5df58b32cc06ebee9ddb0ebf857869ced23a5d5d08cccfc",
"md5": "25fc5fd266c935fd9cada0460543a1ba",
"sha256": "6f756746769dd2b888ef8f4b0a233f6ec46f0b0316c030007bdca79bf1bc3bb0"
},
"downloads": -1,
"filename": "pyoutlineapi-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25fc5fd266c935fd9cada0460543a1ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 10668,
"upload_time": "2025-01-10T17:21:30",
"upload_time_iso_8601": "2025-01-10T17:21:30.120046Z",
"url": "https://files.pythonhosted.org/packages/1f/3f/f64d46d378aae5df58b32cc06ebee9ddb0ebf857869ced23a5d5d08cccfc/pyoutlineapi-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ee292c6e3208062e0266315ebc3144a32f6dad0830129be60cafcc152de9f47c",
"md5": "02f58bf87f35e404ea40baaa84d5e14e",
"sha256": "2fe896000e0fbabb67f0f18b8e9a67cdabc8dee3e20b1b87bb8d4c19ebcd6db3"
},
"downloads": -1,
"filename": "pyoutlineapi-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "02f58bf87f35e404ea40baaa84d5e14e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 10269,
"upload_time": "2025-01-10T17:21:32",
"upload_time_iso_8601": "2025-01-10T17:21:32.679227Z",
"url": "https://files.pythonhosted.org/packages/ee/29/2c6e3208062e0266315ebc3144a32f6dad0830129be60cafcc152de9f47c/pyoutlineapi-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-10 17:21:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "orenlab",
"github_project": "pyoutlineapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyoutlineapi"
}
