VersioningClient

The VersioningClient provides version management, deprecation tracking, and compatibility checking for SDK and algorithm versions.

Overview

Manage and monitor:

• SDK Versions: Track supported SDK versions and platforms
• Algorithm Versions: Manage algo versions across environments
• Deprecations: Track deprecated features and migration paths
• Compatibility: Check version compatibility before deployment

Quick Start

from zenotc import ZenOTCClient

client = ZenOTCClient(
    api_key="your_api_key",
    api_secret="your_api_secret"
)

# Check current SDK version status
version_info = await client.versioning.get_current_version()

print(f"SDK Version: {version_info.sdk_version}")
print(f"Status: {version_info.status}")
print(f"Deprecations: {len(version_info.deprecations)}")

SDK Version Management

Get Current Version Info

info = await client.versioning.get_current_version()

print(f"SDK Version: {info.sdk_version}")
print(f"Platform: {info.platform}")
print(f"Status: {info.status}")  # "supported", "deprecated", "unsupported"
print(f"API Version: {info.api_version}")

if info.status == "deprecated":
    print(f"Sunset Date: {info.sunset_date}")
    print(f"Upgrade To: {info.recommended_version}")

List SDK Versions

versions = await client.versioning.list_sdk_versions(
    platform="python",    # "python", "nodejs", "go"
    status="supported",   # "supported", "deprecated", "all"
)

for version in versions:
    print(f"{version.version}: {version.status}")
    print(f"  Released: {version.release_date}")
    print(f"  Min API: {version.min_api_version}")
    if version.sunset_date:
        print(f"  Sunset: {version.sunset_date}")

Get SDK Version Details

version = await client.versioning.get_sdk_version("1.2.0")

print(f"Version: {version.version}")
print(f"Status: {version.status}")
print(f"Release Date: {version.release_date}")
print(f"Release Notes: {version.release_notes}")

# Features added in this version
for feature in version.features:
    print(f"  + {feature.name}: {feature.description}")

# Breaking changes
for change in version.breaking_changes:
    print(f"  ! {change.description}")
    print(f"    Migration: {change.migration_guide}")

Algorithm Versions

List Algo Versions

versions = await client.versioning.list_algo_versions(
    algo_type="twap",        # "twap", "vwap", "iceberg", "conditional"
    environment="production", # "production", "staging", "testing"
    status="active",         # "active", "deprecated", "retired"
)

for version in versions:
    print(f"{version.algo_type} v{version.version}: {version.status}")
    print(f"  Environment: {version.environment}")
    print(f"  Created: {version.created_at}")

Get Algo Version Details

version = await client.versioning.get_algo_version(
    algo_type="twap",
    version="2.1.0",
)

print(f"Algorithm: {version.algo_type}")
print(f"Version: {version.version}")
print(f"Status: {version.status}")
print(f"Description: {version.description}")

# Configuration schema
print(f"Config Schema: {version.config_schema}")

# Performance characteristics
print(f"Avg Slippage: {version.performance.avg_slippage_bps} bps")
print(f"Avg Fill Rate: {version.performance.avg_fill_rate}%")

Specify Algo Version in Orders

# Use a specific algorithm version
order = await client.algo.create_twap(
    asset="BTC",
    side="buy",
    total_quantity=10.0,
    duration_seconds=3600,
    algo_version="2.1.0",  # Specify version
)

Deprecations

List Active Deprecations

deprecations = await client.versioning.list_deprecations(
    status="active",         # "active", "upcoming", "completed"
    severity="warning",      # "info", "warning", "critical"
)

for dep in deprecations:
    print(f"{dep.feature}: {dep.message}")
    print(f"  Type: {dep.deprecation_type}")  # "endpoint", "parameter", "feature"
    print(f"  Severity: {dep.severity}")
    print(f"  Deprecated: {dep.deprecated_date}")
    print(f"  Sunset: {dep.sunset_date}")
    print(f"  Migration: {dep.migration_guide}")

Get Deprecation Details

deprecation = await client.versioning.get_deprecation(deprecation_id)

print(f"Feature: {deprecation.feature}")
print(f"Status: {deprecation.status}")
print(f"Message: {deprecation.message}")

# Affected versions
print(f"Affects SDK versions: {deprecation.affected_sdk_versions}")
print(f"Affects API versions: {deprecation.affected_api_versions}")

# Migration guide
print(f"Migration Guide:")
print(deprecation.migration_guide)

# Code examples
if deprecation.before_code and deprecation.after_code:
    print(f"Before:")
    print(deprecation.before_code)
    print(f"After:")
    print(deprecation.after_code)

Check for Deprecation Warnings

The SDK automatically checks for deprecations:

# Deprecation warnings are included in responses
response = await client.execution.create_order(...)

if response.deprecation_warnings:
    for warning in response.deprecation_warnings:
        print(f"Warning: {warning.message}")
        print(f"  Feature: {warning.feature}")
        print(f"  Sunset: {warning.sunset_date}")

Subscribe to Deprecation Alerts

async def on_deprecation_alert(alert):
    print(f"New Deprecation: {alert.feature}")
    print(f"  Message: {alert.message}")
    print(f"  Sunset: {alert.sunset_date}")
    print(f"  Action Required: {alert.action_required}")

await client.versioning.subscribe_alerts(on_deprecation_alert)

Compatibility Checking

Check SDK Compatibility

compat = await client.versioning.check_compatibility(
    sdk_version="1.0.0",
    target_api_version="2024-01",
)

print(f"Compatible: {compat.is_compatible}")
print(f"Status: {compat.status}")  # "full", "partial", "incompatible"

if not compat.is_compatible:
    print(f"Reason: {compat.reason}")
    print(f"Required SDK: {compat.required_sdk_version}")

# Feature compatibility
for feature, status in compat.features.items():
    icon = "✓" if status.supported else "✗"
    print(f"  {icon} {feature}: {status.message}")

Check Algo Version Compatibility

compat = await client.versioning.check_algo_compatibility(
    algo_type="twap",
    algo_version="1.0.0",
    environment="production",
)

print(f"Compatible: {compat.is_compatible}")

if compat.config_changes:
    print("Configuration changes required:")
    for change in compat.config_changes:
        print(f"  - {change.field}: {change.description}")

Pre-deployment Check

Run a comprehensive compatibility check before deployment:

check = await client.versioning.pre_deployment_check(
    sdk_version="1.2.0",
    algo_versions={
        "twap": "2.0.0",
        "vwap": "1.5.0",
    },
    environment="production",
)

print(f"Overall: {'Pass' if check.passed else 'Fail'}")

# SDK compatibility
print(f"SDK: {check.sdk_status}")

# Algo compatibility
for algo, status in check.algo_status.items():
    print(f"{algo}: {status}")

# Deprecation warnings
if check.deprecation_warnings:
    print("Deprecation Warnings:")
    for warning in check.deprecation_warnings:
        print(f"  - {warning}")

# Recommended actions
if check.recommendations:
    print("Recommendations:")
    for rec in check.recommendations:
        print(f"  - {rec}")

Environment Configuration

Get Environment Info

env = await client.versioning.get_environment_info()

print(f"Environment: {env.name}")
print(f"API Version: {env.api_version}")
print(f"Features Enabled: {env.features}")
print(f"Rate Limits: {env.rate_limits}")

# Maintenance windows
if env.scheduled_maintenance:
    for maintenance in env.scheduled_maintenance:
        print(f"Scheduled Maintenance: {maintenance.start} - {maintenance.end}")
        print(f"  Impact: {maintenance.impact}")

Get Feature Flags

features = await client.versioning.get_feature_flags()

for feature, enabled in features.items():
    status = "enabled" if enabled else "disabled"
    print(f"{feature}: {status}")

Version Resolution

Resolve Version

Get the actual version that will be used:

resolution = await client.versioning.resolve_version(
    requested_version="latest",  # "latest", "stable", or specific version
    algo_type="twap",
    environment="production",
)

print(f"Requested: {resolution.requested}")
print(f"Resolved: {resolution.resolved_version}")
print(f"Reason: {resolution.reason}")

if resolution.resolved_version != resolution.requested:
    print(f"Note: Version was resolved from '{resolution.requested}' to '{resolution.resolved_version}'")

Upgrade Guide

Get Upgrade Path

path = await client.versioning.get_upgrade_path(
    from_version="1.0.0",
    to_version="2.0.0",
)

print(f"From: {path.from_version}")
print(f"To: {path.to_version}")
print(f"Steps: {len(path.steps)}")

for i, step in enumerate(path.steps, 1):
    print(f"\nStep {i}: Upgrade to {step.version}")
    print(f"  Breaking Changes: {len(step.breaking_changes)}")

    for change in step.breaking_changes:
        print(f"    - {change.description}")
        print(f"      Migration: {change.migration}")

    print(f"  New Features: {len(step.new_features)}")
    for feature in step.new_features:
        print(f"    + {feature}")

Response Headers

Version information is included in response headers:

# Access version headers from any response
response = await client.execution.create_order(...)

# Headers include:
# X-API-Version: 2024-01
# X-SDK-Version: 1.2.0
# X-Deprecation-Warning: feature_name
# X-Sunset-Date: 2024-06-01

Error Handling

from zenotc.exceptions import (
    VersioningError,
    UnsupportedVersionError,
    DeprecatedVersionError,
    IncompatibleVersionError,
)

try:
    order = await client.algo.create_twap(
        algo_version="0.9.0",  # Old version
        ...
    )
except UnsupportedVersionError as e:
    print(f"Version {e.version} is no longer supported")
    print(f"Minimum supported: {e.min_supported_version}")
    print(f"Recommended: {e.recommended_version}")

except DeprecatedVersionError as e:
    print(f"Version {e.version} is deprecated")
    print(f"Sunset date: {e.sunset_date}")
    print(f"Upgrade to: {e.recommended_version}")
    # Can still proceed with deprecated version

except IncompatibleVersionError as e:
    print(f"Version incompatibility: {e.message}")
    print(f"Required: {e.required_version}")

except VersioningError as e:
    print(f"Versioning error: {e}")

Best Practices

1. Monitor deprecations: Regularly check for deprecation warnings
2. Plan upgrades: Use upgrade paths to plan version migrations
3. Test in staging: Always test new versions in staging first
4. Pin versions: Pin specific algo versions in production for consistency
5. Subscribe to alerts: Set up alerts for critical deprecations
6. Review changelogs: Check release notes before upgrading