### PeerTube Pre-commit Setup and Execution

Source: https://github.com/tonkintaylor/peertube/blob/master/AGENTS.md

Instructions for setting up and running pre-commit hooks in the PeerTube project using uv for dependency management. This includes syncing dependencies, installing git hooks, auto-formatting, running all hooks, and handling modifications.

```shell
uv sync
pre-commit install
uv run ruff format .
uv run pre-commit run --all-files
git add -A
git commit -m "..."
```

--------------------------------

### Context7 Tool Usage Examples

Source: https://github.com/tonkintaylor/peertube/blob/master/AGENTS.md

Examples demonstrating how to use the 'context7' tool for fetching documentation and information, tailored for package documentation, Python version-specific features, and examples.

```shell
context7: docs package=requests topics=install,quickstart,api,examples
context7: python version=3.12 topic=typing changes summary for "<task>"
context7: python version=3.12 topic="pattern matching" examples minimal
```

--------------------------------

### Install PeerTube Python API Client

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Installs the peertube package using pip. This is the primary method for adding the library to your Python project.

```bash
pip install peertube
```

--------------------------------

### Client Initialization and Usage

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Demonstrates how to initialize and use both unauthenticated and authenticated PeerTube API clients, including synchronous and asynchronous examples.

```APIDOC
## Client Initialization and Usage

This section covers the initialization and usage patterns for the PeerTube Python API client.

### Unauthenticated Client

**Description:** Initialize a client for accessing public PeerTube API endpoints without authentication.

```python
from peertube import Client

client = Client(base_url="https://your-peertube-instance.com")
```

### Authenticated Client

**Description:** Initialize a client for accessing protected PeerTube API endpoints using an API token.

```python
from peertube import AuthenticatedClient

auth_client = AuthenticatedClient(
    base_url="https://your-peertube-instance.com",
    token="your-api-token"
)
```

### Asynchronous Usage

**Description:** Example of using the client asynchronously for concurrent API requests.

```python
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:
        categories, languages = await asyncio.gather(
            get_categories.asyncio(client=async_client),
            get_languages.asyncio(client=async_client)
        )
        return categories, languages

asyncio.run(get_video_metadata())
```
```

--------------------------------

### Regenerate PeerTube Python Client

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Provides instructions on how to regenerate the PeerTube Python API client, typically done when the PeerTube API specification changes. Involves installing `openapi-python-client` and updating the OpenAPI spec file.

```bash
# Install development dependencies
pip install openapi-python-client

# Update the OpenAPI spec in assets/openapi.json

```

--------------------------------

### Type Safety and Requirements

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Highlights the type-safe nature of the client library and lists the necessary requirements for installation and use.

```APIDOC
## Type Safety and Requirements

This section focuses on the type-safe design of the client and its system requirements.

### Type Safety

**Description:** The client provides full type annotations for enhanced code quality and IDE support.

```python
from peertube.models import Video
from peertube.types import Response

response: Response[Video] = get_video.sync_detailed(client=client, id="uuid")
video: Video = response.parsed  # Fully typed video object
```

### Requirements

**Description:** Software requirements for using the PeerTube Python API client.

- Python 3.10+
- httpx >= 0.23.0
- attrs >= 22.2.0
```

--------------------------------

### Running PeerTube Tests with uv and pytest

Source: https://github.com/tonkintaylor/peertube/blob/master/AGENTS.md

Details on executing the project's test suite using uv and pytest. It covers the command to run tests and the necessary steps if tests fail, including fixing issues and re-running tests until all pass.

```shell
uv run python -m pytest tests/ -v
```

--------------------------------

### Running Unit Tests with Pytest

Source: https://github.com/tonkintaylor/peertube/blob/master/tests/AGENTS.md

Commands to activate the virtual environment and run specific or all unit tests using pytest. These commands are essential for verifying code changes.

```shell
.\venv\Scripts\activate; python -m pytest tests/path/to/test_file.py -v
```

```shell
python -m pytest tests/ -v
```

--------------------------------

### Define public API with __all__ in __init__.py

Source: https://github.com/tonkintaylor/peertube/blob/master/src/peertube/AGENTS.md

Each package within the Peertube project should clearly define its public API in its `__init__.py` file. Use the `__all__` list to explicitly export classes, functions, or constants intended for external consumption.

```python
# mypkg/__init__.py

from .module_a import public_function_a
from .module_b import PublicClassB

__all__ = [
    "public_function_a",
    "PublicClassB",
]

# Internal utilities should be prefixed with '_' and not re-exported
# from .utils import _internal_helper
```

--------------------------------

### SonarQube Issue Fetching for Branches

Source: https://github.com/tonkintaylor/peertube/blob/master/AGENTS.md

Guidance on using the 'sonarqube-search_sonar_issues_in_projects' tool to query SonarQube issues specific to the current branch via the pullRequestId parameter.

```shell
sonarqube-search_sonar_issues_in_projects --pullRequestId "<your_pull_request_id>"
```

--------------------------------

### Authenticated PeerTube Client Usage (Sync)

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Shows how to create an authenticated PeerTube client using an API token for accessing protected endpoints, such as retrieving current user information. Requires the `peertube` library.

```python
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}")
```

--------------------------------

### Additional API Modules

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Covers supplementary PeerTube API functionalities like instance configuration, registration, subscriptions, notifications, comments, live streaming, and statistics.

```APIDOC
## Additional API Modules

This section details the additional modules available in the PeerTube Python API client.

### Module: config

**Description:** Retrieves instance configuration details.

### Module: register

**Description:** Handles user registration requests.

### Module: my_subscriptions

**Description:** Manages user subscription operations.

### Module: my_notifications

**Description:** Handles user notification retrieval and management.

### Module: video_comments

**Description:** Provides operations for managing video comments.

### Module: live_videos

**Description:** Manages live streaming functionalities.

### Module: stats

**Description:** Retrieves instance statistics.
```

--------------------------------

### Basic PeerTube Client Usage (Sync)

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Demonstrates creating an unauthenticated PeerTube client and fetching video categories and a specific video using synchronous calls. It utilizes the `peertube` library and `httpx` for HTTP operations.

```python
from 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}")
```

--------------------------------

### Advanced PeerTube Client Configuration

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Demonstrates advanced configuration options for the PeerTube client, including custom timeouts, SSL verification settings, redirect handling, custom headers, and HTTP proxy configuration via `httpx_args`. Uses the `peertube` library.

```python
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"}
    }
)
```

--------------------------------

### Searching for 'TODO' Comments

Source: https://github.com/tonkintaylor/peertube/blob/master/AGENTS.md

A command to search for 'TODO' comments or their variants within the project repository using git grep. This is part of the comment policy enforcement.

```shell
git grep -n -E '\bT[O0]\s?DO\b|@todo' || true
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Executes all tests within the project using the pytest framework. This includes running tests for client generation and API function implementations.

```bash
pytest
```

--------------------------------

### Use httpx constants for HTTP status codes

Source: https://github.com/tonkintaylor/peertube/blob/master/src/peertube/AGENTS.md

When making API requests using the httpx package, utilize the predefined status code constants from `httpx.codes` instead of hardcoding numerical values. This enhances readability and maintainability.

```python
from httpx import codes

# Instead of using a hardcoded value like 200
response = httpx.get("...")
if response.status_code == codes.OK:
    print("Request successful")
```

--------------------------------

### PeerTube Client Type Safety with Models

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Illustrates the type safety provided by the PeerTube client library, showing how to use `Response` and specific model types (e.g., `Video`) for type-hinting and improved code completion. Requires `peertube.models` and `peertube.types`.

```python
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
```

--------------------------------

### Core API Modules

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Provides access to core PeerTube API functionalities including video management, user operations, authentication, search, and more.

```APIDOC
## Core API Modules

This section outlines the main modules available in the PeerTube Python API client.

### Module: video

**Description:** Manages video-related operations such as retrieving videos, categories, languages, and licenses.

**Endpoints:**
- `get_categories.sync(client)`: Retrieves a list of video categories.
- `get_video.sync(client, id='video-uuid')`: Retrieves details for a specific video.

### Module: videos

**Description:** Handles video listing and import operations.

### Module: accounts

**Description:** Provides access to account and user information.

### Module: users

**Description:** Manages user-related operations, including administration.

### Module: session

**Description:** Handles authentication and session management.

### Module: search

**Description:** Enables searching for videos, channels, and playlists.

### Module: my_user

**Description:** Accesses the current user's profile and settings.

### Module: video_channels

**Description:** Manages video channel operations.

### Module: video_playlists

**Description:** Handles video playlist operations.
```

--------------------------------

### Asynchronous PeerTube Client Usage

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Illustrates using the PeerTube client asynchronously, including running multiple API requests concurrently using `asyncio.gather`. This requires `asyncio` and the `peertube` library.

```python
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())
```

--------------------------------

### Run Specific Pytest Files

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Runs specific test files using pytest with verbose output. This allows for targeted testing of client generation or API function logic.

```bash
pytest tests/test_client_generation.py -v
```

```bash
pytest tests/test_api_functions.py -v
```

--------------------------------

### Generate Peertube OpenAPI Client

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Generates the Peertube client library from an OpenAPI specification file. It outputs the client to a specified directory and disables metadata generation. The `--overwrite` flag ensures existing files are replaced.

```bash
openapi-python-client generate --path assets/openapi.json --output-path src/peertube --meta none --overwrite
```

--------------------------------

### PeerTube API Response Handling (Detailed)

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Shows how to handle both simple data responses and detailed responses from the PeerTube API, including checking status codes and accessing headers. Uses `get_video.sync_detailed` for detailed responses.

```python
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}")
```

--------------------------------

### PeerTube API Error Handling

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Demonstrates how to handle specific API errors, such as `UnexpectedStatus`, which is raised when the API returns an unexpected HTTP status code. Catches the error and prints the status code and content. Requires `peertube.errors`.

```python
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}")
```

--------------------------------

### Correct internal module import paths

Source: https://github.com/tonkintaylor/peertube/blob/master/src/peertube/AGENTS.md

When importing modules from within the Peertube package, exclude the 'src' directory from the import path. The package structure is defined in `pyproject.toml`, making 'src' implicit.

```python
# Correct import
from peertube.auth import login

# Incorrect import (do not include 'src')
# from src.peertube.auth import login
```

--------------------------------

### Response Handling and Error Management

Source: https://github.com/tonkintaylor/peertube/blob/master/README.md

Details how to handle API responses, access detailed response information (status code, headers), and manage potential API errors.

```APIDOC
## Response Handling and Error Management

This section explains how to interpret API responses and handle errors gracefully.

### Simple Response

**Description:** Retrieving just the parsed data from a successful API call.

```python
from peertube.api.video import get_video

video = get_video.sync(client=client, id="video-uuid")
# 'video' object contains the parsed response data
```

### Detailed Response

**Description:** Accessing comprehensive response details including status code and headers.

```python
from peertube.api.video import get_video

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}")
```

### Error Handling

**Description:** Catching and handling specific API errors, such as unexpected status codes.

```python
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}")
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.