v.0.3.0

🚀 Release v0.3.0 - Major API Enhancements and Breaking Changes

📋 Overview

This pull request introduces significant improvements to the PyOutlineAPI client, including new API methods, enhanced error handling, improved type safety, and architectural refinements. This release contains breaking changes that require attention during migration.

🆕 New Features

📡 Extended API Coverage

• create_access_key_with_id() - Create access keys with custom IDs for better organization
• get_experimental_metrics() - Access detailed server analytics and performance metrics
• set_global_data_limit() / remove_global_data_limit() - Manage server-wide data transfer limits

🔄 Robust Retry Mechanism

• Configurable retry attempts via constructor parameter
• Automatic retry for transient failures (HTTP 408, 429, 500, 502, 503, 504)
• Exponential backoff with intelligent error tracking
• Enhanced error messages with attempt context

🏗️ Architectural Improvements

• Dedicated exception module (exceptions.py) for better error hierarchy
• New Pydantic request models for type-safe API interactions
• Constants module with MIN_PORT, MAX_PORT, retry configurations
• Enhanced type annotations throughout the codebase

⚠️ Breaking Changes

🔧 API Behavior Changes

Change	Before (v0.2.0)	After (v0.3.0)	Impact
Default Response Format	json_format=True (JSON dict)	json_format=False (Pydantic models)	🔴 High
Access Key IDs	int type	str type	🔴 High
Default Timeout	30 seconds	10 seconds	🟡 Medium
Metrics Period	get_transfer_metrics(period=...)	get_transfer_metrics()	🟡 Medium

📝 Migration Examples

Click to expand migration guide

# 1. Response Format Change
# OLD - Returns JSON dict by default
async with AsyncOutlineClient(url, cert) as client:
    server = await client.get_server_info()  # Returns dict
    print(server['name'])

# NEW - Returns Pydantic model by default  
async with AsyncOutlineClient(url, cert) as client:
    server = await client.get_server_info()  # Returns Server model
    print(server.name)

# To maintain old behavior:
async with AsyncOutlineClient(url, cert, json_format=True) as client:
    server = await client.get_server_info()  # Returns dict
    print(server['name'])

# 2. Access Key ID Type Change
# OLD
await client.get_access_key(1)
await client.rename_access_key(1, "New Name")

# NEW
await client.get_access_key("1")
await client.rename_access_key("1", "New Name")

# 3. Metrics API Simplification
# OLD
from .models import MetricsPeriod
metrics = await client.get_transfer_metrics(MetricsPeriod.MONTHLY)

# NEW
metrics = await client.get_transfer_metrics()  # Always returns current data

🔧 Improvements

🛡️ Enhanced Error Handling

• Separated exceptions into dedicated module for better organization
• More descriptive error messages with context
• Better handling of API validation errors
• Improved SSL certificate validation

📊 Better Type Safety

• All API requests now use proper Pydantic models
• Consistent serialization with by_alias=True
• Enhanced type hints for better IDE support
• Stricter validation of input parameters

⚡ Performance Optimizations

• Reduced default timeout for better responsiveness
• More efficient request handling with dedicated methods
• Improved session management and connection pooling
• Better resource cleanup

🧪 New API Methods Examples

async with AsyncOutlineClient(api_url, cert_sha256) as client:
    # Create access key with custom ID
    key = await client.create_access_key_with_id(
        "user-alice", 
        name="Alice's Key"
    )
    
    # Get detailed experimental metrics
    metrics = await client.get_experimental_metrics()
    print(f"Server tunnel time: {metrics.server.tunnel_time.seconds}s")
    
    # Set global data limit (100 GB for all users)
    await client.set_global_data_limit(100 * 1024**3)
    
    # Remove global limit
    await client.remove_global_data_limit()

🧹 Removed/Deprecated

• ❌ MetricsPeriod enum (API doesn't support period filtering)
• ❌ Direct dictionary usage in API requests
• ❌ Redundant parameter validation (handled by Pydantic)

🔍 Testing & Quality

• ✅ All existing functionality preserved (with type changes)
• ✅ New methods thoroughly tested
• ✅ Enhanced error handling validated
• ✅ Migration path verified
• ✅ Type safety improvements confirmed

📚 Documentation Updates

• 📖 Updated method signatures and examples
• 📖 Enhanced docstrings with proper type hints
• 📖 Migration guide included in changelog
• 📖 New API methods documented with examples

🚨 Action Required

For maintainers:

1. Review breaking changes impact
2. Update any internal tooling using the client
3. Validate migration examples
4. Consider version compatibility strategy

For users:

1. Review the migration guide above
2. Test changes in development environment
3. Update exception handling for new exception hierarchy
4. Adjust access key ID handling from int to str

📈 Metrics

• Lines changed: ~500+ (significant refactoring)
• New methods: 4
• New models: 7+
• Breaking changes: 4 major
• Bug fixes: Multiple reliability improvements

---

Version: 0.3.0
Backward compatibility: ❌ Contains breaking changes
Migration complexity: 🟡 Medium (clear migration path provided)
Recommended action: Staged rollout with thorough testing