Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

aiopythonik

Asynchronous wrapper for the pythonik library, enabling its use in async Python applications without blocking the event loop.

PyPI Version Python Versions License

Overview

aiopythonik provides asynchronous versions of pythonik functionality by wrapping the synchronous operations in a thread pool executor. This approach is similar to how aioboto3 wraps boto3, allowing you to use asynchronous syntax while maintaining the original library's capabilities.

Features

  • Complete async API for the pythonik library
  • Automatic thread pool management for non-blocking operations
  • Built-in rate limit handling with proactive throttling and configurable retry strategies
  • Extended functionality through patched pythonik methods
  • Support for Python 3.11+

Installation

Requirements

  • Python 3.11 or higher
# Install from PyPI (recommended for most users)
pip install aiopythonik

The required dependency nsa-pythonik will be automatically installed.

Installing from Source

For development or to get the latest unreleased changes:

# Clone the repository
git clone https://bitbucket.org/chesa/aiopythonik.git
cd aiopythonik

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quickstart

import asyncio
from aiopythonik import AsyncPythonikClient

async def main():
    # Initialize the client
    client = AsyncPythonikClient(
        app_id="your_app_id",
        auth_token="your_auth_token",
        timeout=60,
        base_url="https://app.iconik.io",
    )

    try:
        # Use async methods
        asset = await client.assets().get("asset_id")
        print(f"Asset title: {asset.data.title}")

        # Get files for the asset
        files = await client.files().get_asset_files("asset_id")
        print(f"Number of files: {len(files.data.files)}")

        # Search for assets
        from pythonik.models.search.search_body import SearchBody
        search_results = await client.search().search(
            SearchBody(doc_types=["assets"], query="title:sample")
        )
        print(f"Found {len(search_results.data.objects)} assets")

    finally:
        # Always close the client when done
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

Using the Context Manager

For convenience, you can use the async context manager to ensure proper cleanup:

import asyncio
from aiopythonik import AsyncPythonikClientContext

async def main():
    async with AsyncPythonikClientContext(
        app_id="your_app_id",
        auth_token="your_auth_token",
        timeout=60,
        base_url="https://app.iconik.io",
    ) as client:
        # Use async methods
        asset = await client.assets().get("asset_id")
        print(f"Asset title: {asset.data.title}")

if __name__ == "__main__":
    asyncio.run(main())

API Coverage

aiopythonik provides async wrappers for all pythonik APIs and extends functionality with some additional methods. Each API from the original library is accessible through the corresponding async wrapper:

# Assets
asset = await client.assets().get("asset_id")
assets = await client.assets().fetch(params={"per_page": 50})  # Enhanced method
await client.assets().delete("asset_id")

# Collections
collection = await client.collections().get("collection_id")
info = await client.collections().get_info("collection_id")
contents = await client.collections().get_contents("collection_id")

# Files
files = await client.files().get_asset_files("asset_id")
# Enhanced method with automatic checksum calculation
files_by_checksum = await client.files().get_files_by_checksum("d41d8cd98f00b204e9800998ecf8427e")
# Or calculate checksum automatically from a file
files_by_file = await client.files().get_files_by_checksum("path/to/file.mp4")

# Metadata
views = await client.metadata().get_views()
view = await client.metadata().get_view("view_id")
metadata = await client.metadata().get_asset_metadata("asset_id", "view_id")

# Jobs
# Read methods added by aiopythonik; upstream can only create and update
job = await client.jobs().get("job_id")
jobs = await client.jobs().list(params={"per_page": 50, "status": "STARTED"})

Automatic Rate Limit Handling

The library includes built-in handling for API rate limits with both proactive throttling and reactive retry logic:

from aiopythonik import AsyncPythonikClient, RateLimitConfig

# Configure custom rate limiting behavior
rate_limit_config = RateLimitConfig(
    max_retries=5,                      # Maximum number of retries for rate-limited requests
    initial_backoff=1.0,                # Initial backoff in seconds
    max_backoff=30.0,                   # Maximum backoff in seconds
    backoff_factor=2.0,                 # Exponential backoff factor
    jitter=True,                        # Add randomness to backoff times
    enable_proactive_throttling=True,   # Enable proactive throttling (default: True)
    proactive_throttling_threshold=0.8, # Start throttling at 80% quota usage
    max_proactive_delay=5.0             # Maximum proactive delay in seconds
)

client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    rate_limit_config=rate_limit_config
)

# Rate-limited requests will automatically be handled with:
# 1. Proactive throttling - slows down requests before hitting limits
# 2. Retry logic - handles 429 errors with exponential backoff

Proactive Throttling

The library automatically monitors your API quota usage through RateLimit-Remaining headers and applies graduated delays before hitting rate limits:

  • 80%+ quota remaining: No delay (full speed)
  • 30-20% quota remaining: Light throttling (0.1-0.5s delays)
  • 20-10% quota remaining: Moderate throttling (0.5-2.0s delays)
  • <10% quota remaining: Aggressive throttling (2.0-5.0s delays)

This prevents 429 errors instead of just reacting to them, resulting in:

  • Faster overall operations (no waiting for 5+ second retry delays)
  • More predictable request timing
  • Better resource efficiency
  • Reduced server load
# Proactive throttling can be disabled if needed
rate_limit_config = RateLimitConfig(
    enable_proactive_throttling=False  # Disable proactive throttling
)

Advanced Usage

Concurrent Operations

Running multiple operations concurrently:

import asyncio
from aiopythonik import AsyncPythonikClientContext

async def main():
    async with AsyncPythonikClientContext(
        app_id="your_app_id",
        auth_token="your_auth_token",
    ) as client:
        # Run multiple operations concurrently
        asset_ids = ["id1", "id2", "id3", "id4", "id5"]

        tasks = [client.assets().get(asset_id) for asset_id in asset_ids]
        results = await asyncio.gather(*tasks)

        for i, result in enumerate(results):
            print(f"Asset {i+1}: {result.data.title}")

if __name__ == "__main__":
    asyncio.run(main())

Custom Base URL

If you need to use a different API endpoint:

client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    base_url="https://custom.iconik.io"
)

Customizing Thread Pool Size

Control the maximum number of worker threads:

client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    max_workers=10  # Set maximum number of worker threads
)

Connection Pool Configuration

For high-concurrency workloads, you can configure the urllib3 connection pool to avoid connection churn:

client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    pool_connections=20,  # Number of connection pools to cache (default: 10)
    pool_maxsize=50,      # Max connections per pool (default: 10)
)
  • pool_connections: Controls how many different hosts can have pooled connections. The default of 10 is sufficient for most use cases since requests typically go to a single iconik host.
  • pool_maxsize: Controls concurrent connections to a single host. Increase this for high-concurrency workloads where many requests run simultaneously to avoid "Connection pool is full" warnings.

Rate Limiting Details

The iconik APIs implement rate limiting to prevent individual users from negatively impacting system performance. By default, the aiopythonik library includes automatic handling of rate limits using a retry strategy with exponential backoff.

Rate limits are enforced per authenticated user and application token:

  • 50 requests per second sustained
  • 1000 requests over any 20 second period

The library uses a hybrid approach to handle these limits:

  1. Proactive Throttling: Monitors RateLimit-Remaining headers and gradually slows down requests as you approach the limit, preventing 429 errors from occurring
  2. Reactive Retry Logic: If 429 errors still occur, automatically retries with exponential backoff

This combination provides optimal performance - prevention when possible, recovery when necessary.

You can disable automatic rate limit handling if you prefer to manage it yourself:

# Disable all rate limit handling
client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    disable_rate_limit_handling=True
)

# Or disable only proactive throttling while keeping retry logic
rate_limit_config = RateLimitConfig(
    enable_proactive_throttling=False,  # Disable proactive throttling
    max_retries=3                       # Keep retry logic
)
client = AsyncPythonikClient(
    app_id="your_app_id",
    auth_token="your_auth_token",
    rate_limit_config=rate_limit_config
)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Metadata

Release files for aiopythonik 2026.9b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiopythonik 2026.9b1
File Size Uploaded Provenance Actions
aiopythonik-2026.9b1.tar.gz 38.6 kB Without provenance Details for aiopythonik-2026.9b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiopythonik 2026.9b1
File Interpreter ABI Platform Actions
aiopythonik-2026.9b1-py3-none-any.whl Python 3 none any Details for aiopythonik-2026.9b1-py3-none-any.whl

Total release size: 81.8 kB

Release files / aiopythonik-2026.9b1.tar.gz

Download URL aiopythonik-2026.9b1.tar.gz
Size 38.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4224c6daa09abb277ebe274170b5d15f8ea0049a898ac74434d55f316c6900ed
BLAKE2b-256 checksum
How to use checksums
542e11589135d729c3e88c9ba444c31e347e1893fa2cccbac101616c0622fcdd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.13 readme-renderer/46.0 requests/2.34.2 requests-toolbelt/1.0.0 urllib3/2.8.0 tqdm/4.70.1 importlib-metadata/9.0.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.11.16

Release files / aiopythonik-2026.9b1-py3-none-any.whl

Download URL aiopythonik-2026.9b1-py3-none-any.whl
Size 43.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bde521be8eb2cb515a9d048bacdb9aa5e7ce2bd7a28dd2ef250de34620a9128c
BLAKE2b-256 checksum
How to use checksums
0a4b6e59a05dfc9e1d54c7e7b8868318342b8e8c607183acea6362fd32a9cac5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.13 readme-renderer/46.0 requests/2.34.2 requests-toolbelt/1.0.0 urllib3/2.8.0 tqdm/4.70.1 importlib-metadata/9.0.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.11.16

Security for aiopythonik 2026.9b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page