Modern Python client library for the PeerTube API using openapi-python-client. Provides type-safe, well-structured clients with both synchronous and asynchronous support.
This package provides a comprehensive Python client for the PeerTube API, automatically generated from the official OpenAPI specification. It uses httpx for HTTP operations and attrs for type-safe data classes.
pip install peertubefrom peertube import Client
from peertube.api.video import get_categories, get_video
# Create an unauthenticated client for public endpoints
client = Client(base_url="https://your-peertube-instance.com")
# Get video categories
categories = get_categories.sync(client=client)
print(f"Available categories: {list(categories.keys())}")
# Get specific video details
video = get_video.sync(client=client, id="video-uuid")
print(f"Video: {video.name}")from peertube import AuthenticatedClient
from peertube.api.my_user import get_user
# Create authenticated client for protected endpoints
auth_client = AuthenticatedClient(
base_url="https://your-peertube-instance.com",
token="your-api-token"
)
# Get current user information
user = get_user.sync(client=auth_client)
print(f"Logged in as: {user.username}")import asyncio
from peertube import Client
from peertube.api.video import get_categories, get_languages
async def get_video_metadata():
client = Client(base_url="https://your-peertube-instance.com")
async with client as async_client:
# Run multiple requests concurrently
categories, languages = await asyncio.gather(
get_categories.asyncio(client=async_client),
get_languages.asyncio(client=async_client)
)
return categories, languages
# Run async function
categories, languages = asyncio.run(get_video_metadata())from peertube import AuthenticatedClient
# Client with custom configuration
client = AuthenticatedClient(
base_url="https://your-peertube-instance.com",
token="your-api-token",
timeout=30.0,
verify_ssl=True, # Set to False only for testing
follow_redirects=True,
headers={"User-Agent": "MyPeerTubeApp/1.0"},
httpx_args={
"proxies": {"https://": "https://proxy.example.com"}
}
)from peertube.api.video import get_video
# Simple response (just the data)
video = get_video.sync(client=client, id="video-uuid")
# Detailed response (includes status code, headers, etc.)
response = get_video.sync_detailed(client=client, id="video-uuid")
if response.status_code == 200:
video = response.parsed
print(f"Status: {response.status_code}")
print(f"Headers: {response.headers}")
else:
print(f"Error: {response.status_code}")The client provides access to all PeerTube API endpoints organized by functionality:
- video: Video management (get, delete, categories, languages, licenses)
- videos: Video listing and import operations
- accounts: Account and user information
- users: User management and administration
- session: Authentication and session management
- search: Video, channel, and playlist search
- my_user: Current user profile and settings
- video_channels: Video channel management
- video_playlists: Playlist operations
- config: Instance configuration
- register: User registration
- my_subscriptions: Subscription management
- my_notifications: Notification handling
- video_comments: Comment operations
- live_videos: Live streaming
- stats: Instance statistics
from peertube.errors import UnexpectedStatus
from peertube.api.video import get_video
try:
video = get_video.sync(client=client, id="invalid-uuid")
except UnexpectedStatus as e:
print(f"API error: {e.status_code} - {e.content}")The client provides full type annotations and IDE auto-completion:
from peertube.models import Video
from peertube.types import Response
# Type-safe response handling
response: Response[Video] = get_video.sync_detailed(client=client, id="uuid")
video: Video = response.parsed # Fully typed video object- Python 3.10+
- httpx >= 0.23.0
- attrs >= 22.2.0
This package is automatically generated from the PeerTube OpenAPI specification using openapi-python-client.
To update the client when the PeerTube API changes:
# Install development dependencies
pip install openapi-python-client
# Update the OpenAPI spec in assets/openapi.json
# Then regenerate the client
openapi-python-client generate --path assets/openapi.json --output-path src/peertube --meta none --overwrite# Run all tests
pytest
# Run specific test files
pytest tests/test_client_generation.py -v
pytest tests/test_api_functions.py -vSee the examples/ directory for complete usage examples:
examples/client_usage.py- Basic client usage patterns- More examples coming soon...
- Type Safety: Full type annotations with proper typing support
- Dual Clients:
Client(unauthenticated) andAuthenticatedClient(with token) - Async Support: Both sync and async methods for all endpoints
- httpx Based: Uses modern httpx library for HTTP requests
- Context Manager: Proper resource management with
withstatements - Customizable: Supports custom timeout, SSL settings, headers, cookies
- ✅ Video Management: Get, list, upload, delete videos
- ✅ Video Metadata: Categories, languages, licenses
- ✅ Search: Videos, channels, playlists
- ✅ User Management: Registration, profiles, settings
- ✅ Authentication: Login, logout, token management
- ✅ Video Channels: Channel operations and management
- ✅ Playlists: Playlist creation and management
- ✅ Comments: Video comment operations
- ✅ Live Streaming: Live video operations
- ✅ Moderation: Content moderation tools
- ✅ Instance: Configuration and statistics
This project follows modern Python development practices:
- Type hints for all functions
- Pydantic models for data validation
- Comprehensive error handling
- 100-character line length limit
- pytest for testing
MIT License