https://github.com/orenlab/pyoutlineapi
A modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic models.
https://github.com/orenlab/pyoutlineapi
aiohttp api asincio manager outline python shadowsocks vpn wrapper
Last synced: 4 months ago
JSON representation
A modern, async-first Python client for the Outline VPN Server API with comprehensive data validation through Pydantic models.
- Host: GitHub
- URL: https://github.com/orenlab/pyoutlineapi
- Owner: orenlab
- License: mit
- Created: 2024-08-28T09:36:34.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-13T11:04:26.000Z (4 months ago)
- Last Synced: 2026-02-13T19:27:11.861Z (4 months ago)
- Topics: aiohttp, api, asincio, manager, outline, python, shadowsocks, vpn, wrapper
- Language: Python
- Homepage: https://orenlab.github.io/pyoutlineapi/
- Size: 2.37 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# PyOutlineAPI
**Enterprise-grade async Python client for Outline VPN Server Management API**
[](https://github.com/orenlab/pyoutlineapi/actions/workflows/python_tests.yml)
[](https://codecov.io/gh/orenlab/pyoutlineapi)
[](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)
---
## Overview
PyOutlineAPI is a modern, **production-ready** Python library for managing [Outline VPN](https://getoutline.org/)
servers.
It is async-first, type-safe, and designed for reliable operation in production.
Highlights:
- Async-first client built on aiohttp
- Certificate pinning + sensitive data protection
- Circuit breaker, health monitoring, retries with backoff
- Typed models (Pydantic v2) + rich validation
- Batch operations and rate limiting
---
## Installation
**Requirements:** Python 3.10+
Using `pip`:
```bash
pip install pyoutlineapi
```
Using `uv` (recommended):
```bash
uv add pyoutlineapi
```
**Optional dependencies:**
```bash
# Development tools
pip install pyoutlineapi[dev]
```
---
## Quick Start
### 1) Setup configuration
```bash
# Generate .env template
python -c "from pyoutlineapi import quick_setup; quick_setup()"
# Edit .env.example → .env
OUTLINE_API_URL=https://your-server.com:12345/your-secret-path
OUTLINE_CERT_SHA256=your-64-character-sha256-fingerprint
```
### 2) Minimal usage
```python
from pyoutlineapi import AsyncOutlineClient
import asyncio
async def main():
async with AsyncOutlineClient.from_env() as client:
server = await client.get_server_info()
print(f"Server: {server.name} (v{server.version})")
key = await client.create_access_key(name="Alice")
print(f"Access URL: {key.access_url}")
keys = await client.get_access_keys()
print(f"Total keys: {keys.count}")
asyncio.run(main())
```
---
## Documentation
Detailed examples and guides are in `docs/guides/`. Start with the index:
- [Guides index](docs/guides/README.md) (full list)
- [Access keys](docs/guides/access-keys.md)
- [Server management](docs/guides/server-management.md)
- [Metrics](docs/guides/metrics.md)
- [Enterprise features](docs/guides/enterprise-features.md)
- [Configuration](docs/guides/configuration.md)
- [Error handling](docs/guides/error-handling.md)
- [Best practices](docs/guides/best-practices.md)
---
## License
MIT. See `LICENSE`.