### Quick Start - Ethereum Usage

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Example of how to use the Turbo SDK with an Ethereum signer to upload data.

```APIDOC
## Quick Start - Ethereum Usage

```python
from turbo_sdk import Turbo, EthereumSigner

# Create Ethereum signer
signer = EthereumSigner("0x1234567890abcdef...")  # Your private key

# Create Turbo client
turbo = Turbo(signer, network="mainnet")

# Upload data
result = turbo.upload(b"Hello, Turbo!", tags=[
    {"name": "Content-Type", "value": "text/plain"},
    {"name": "App-Name", "value": "MyApp"}
])

print(f"✅ Uploaded! TX ID: {result.id}")
print(f"🌐 View at: https://arweave.net/{result.id}")
```
```

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

### Installation

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Install the Turbo Python SDK using pip.

```APIDOC
## Installation

```bash
pip install turbo-sdk
```
```

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

### Quick Start - Arweave Usage

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Example of how to use the Turbo SDK with an Arweave signer to upload data.

```APIDOC
## Quick Start - Arweave Usage

```python
import json
from turbo_sdk import Turbo, ArweaveSigner

# Load Arweave wallet (JWK format)
with open("test-wallet.json") as f:
    jwk = json.load(f)

# Create Arweave signer
signer = ArweaveSigner(jwk)

# Create Turbo client
turbo = Turbo(signer, network="mainnet")

# Upload data
result = turbo.upload(b"Hello from Arweave!", tags=[
    {"name": "Content-Type", "value": "text/plain"}
])

print(f"✅ Uploaded! URI: ar://{result.id}")
```
```

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

### Install Turbo Python SDK

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Install the SDK using pip. This command is used for setting up the library in your Python environment.

```bash
pip install turbo-sdk
```

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

### Install Dependencies

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Install project dependencies, including development packages, using pip.

```bash
pip install -e ".[dev]"
```

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

### Initialize Turbo Client with Default and Custom URLs

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Examples of creating a Turbo client instance. You can use default network URLs or specify custom upload and payment service URLs.

```python
# Using default URLs (mainnet)
turbo = Turbo(signer)

# Using testnet
turbo = Turbo(signer, network="testnet")

# Using custom URLs
turbo = Turbo(signer, upload_url="https://my-upload-service.example.com")
```

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

### Complete File Upload Workflow Example

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

A comprehensive Python script demonstrating the full file upload process using the Turbo SDK. It includes loading a wallet, checking balance against estimated cost, configuring chunking for large files, and handling upload progress and errors.

```python
from turbo_sdk import Turbo, ArweaveSigner, ChunkingParams, UnderfundedError
import json
import os
import sys

def upload_file(file_path: str, wallet_path: str, network: str = "mainnet"):
    """Upload a file to Arweave via Turbo with full error handling"""

    # Load wallet
    with open(wallet_path) as f:
        jwk = json.load(f)

    signer = ArweaveSigner(jwk)
    turbo = Turbo(signer, network=network)

    print(f"Wallet: {signer.get_wallet_address()}")
    print(f"Network: {network}")

    # Check balance and cost
    file_size = os.path.getsize(file_path)
    balance = turbo.get_balance()
    cost = turbo.get_upload_price(file_size)

    print(f"File size: {file_size:,} bytes")
    print(f"Upload cost: {cost:,} winc")
    print(f"Balance: {balance.winc} winc")

    if int(balance.winc) < cost:
        print("ERROR: Insufficient balance")
        sys.exit(1)

    # Configure chunking for large files
    chunking = ChunkingParams(
        chunk_size=10 * 1024 * 1024,  # 10 MiB
        max_chunk_concurrency=2
    )

    def progress(processed: int, total: int):
        pct = (processed / total) * 100
        bar = "=" * int(pct // 2) + ">" + " " * (50 - int(pct // 2))
        print(f"\r[{bar}] {pct:.1f}%", end="", flush=True)

    # Determine content type from extension
    ext = os.path.splitext(file_path)[1].lower()
    content_types = {".mp4": "video/mp4", ".jpg": "image/jpeg", ".png": "image/png",
                     ".pdf": "application/pdf", ".json": "application/json"}
    content_type = content_types.get(ext, "application/octet-stream")

    try:
        result = turbo.upload(
            stream_factory=lambda: open(file_path, "rb"),
            data_size=file_size,
            tags=[
                {"name": "Content-Type", "value": content_type},
                {"name": "App-Name", "value": "Turbo-SDK-Python"},
                {"name": "File-Name", "value": os.path.basename(file_path)}
            ],
            chunking=chunking,
            on_progress=progress
        )

        print(f"\n\nUpload successful!")
        print(f"Transaction ID: {result.id}")
        print(f"URI: ar://{result.id}")
        print(f"Gateway: https://arweave.net/{result.id}")
        print(f"Cost: {result.winc} winc")
        return result

    except UnderfundedError:
        print("\nERROR: Account underfunded during upload")
        sys.exit(1)

# Usage
if __name__ == "__main__":
    result = upload_file("document.pdf", "wallet.json", network="mainnet")
```

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

### Quick Start: Upload with Ethereum Signer

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Demonstrates uploading data using an Ethereum signer. Ensure your private key is securely handled. The result includes the transaction ID for viewing on Arweave.

```python
from turbo_sdk import Turbo, EthereumSigner

# Create Ethereum signer
signer = EthereumSigner("0x1234567890abcdef...")  # Your private key

# Create Turbo client
turbo = Turbo(signer, network="mainnet")

# Upload data
result = turbo.upload(b"Hello, Turbo!", tags=[
    {"name": "Content-Type", "value": "text/plain"},
    {"name": "App-Name", "value": "MyApp"}
])

print(f"✅ Uploaded! TX ID: {result.id}")
print(f"🌐 View at: https://arweave.net/{result.id}")
```

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

### Quick Start: Upload with Arweave Signer

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Shows how to upload data using an Arweave signer with a JWK wallet file. The output provides a URI to view the uploaded data.

```python
import json
from turbo_sdk import Turbo, ArweaveSigner

# Load Arweave wallet (JWK format)
with open("test-wallet.json") as f:
    jwk = json.load(f)

# Create Arweave signer
signer = ArweaveSigner(jwk)

# Create Turbo client
turbo = Turbo(signer, network="mainnet")

# Upload data
result = turbo.upload(b"Hello from Arweave!", tags=[
    {"name": "Content-Type", "value": "text/plain"}
])

print(f"✅ Uploaded! URI: ar://{result.id}")
```

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

### Get Upload Price

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Estimates the cost in winston credits to upload data of a specified size.

```APIDOC
## GET /upload_price

### Description
Get the cost to upload data of a specific size.

### Method
GET

### Endpoint
/upload_price

### Parameters
#### Query Parameters
- **byte_count** (int) - Required - The size of the data in bytes.

### Response
#### Success Response (200)
- **cost** (int) - The cost to upload the data in winc.

### Response Example
```json
{
  "cost": 10000
}
```
```

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

### Get Upload Price

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Determine the cost to upload data of a specific size in bytes. This function returns the price in winc.

```python
cost = turbo.get_upload_price(1024)  # Cost for 1KB
print(f"Upload cost: {cost} winc")
```

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

### Get Wallet Balance

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Retrieves the winston credit balance for a wallet. Uses signed authentication when checking your own balance, or queries any address without authentication.

```python
from turbo_sdk import Turbo, EthereumSigner

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

# Check your own balance (authenticated request)
balance = turbo.get_balance()
print(f"Available credits: {balance.winc} winc")
print(f"Controlled credits: {balance.controlled_winc} winc")
print(f"Effective balance: {balance.effective_balance} winc")

# Check another wallet's balance (no auth required)
other_balance = turbo.get_balance(address="0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A")
print(f"Other wallet balance: {other_balance.winc} winc")
```

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

### Get Upload Price

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Calculates the cost in winston credits to upload data of a specific byte size. Useful for estimating costs before uploading. This function can also be used to check if a balance is sufficient before proceeding with an upload.

```python
from turbo_sdk import Turbo, EthereumSigner

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

# Get cost for different file sizes
sizes = [1024, 1024 * 1024, 10 * 1024 * 1024]  # 1KB, 1MB, 10MB

for size in sizes:
    cost = turbo.get_upload_price(size)
    print(f"Cost for {size} bytes: {cost} winc")

# Check if balance is sufficient before uploading
data = b"My important data" * 1000
cost = turbo.get_upload_price(len(data))
balance = turbo.get_balance()

if int(balance.winc) >= cost:
    print("Sufficient balance, proceeding with upload")
    result = turbo.upload(data, tags=[{"name": "Content-Type", "value": "text/plain"}])
else:
    print(f"Insufficient balance. Need {cost} winc, have {balance.winc} winc")
```

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

### Get Wallet Address from Signer

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Retrieve the wallet address associated with the initialized signer object. This applies to both Ethereum and Arweave signers.

```python
address = signer.get_wallet_address()
print(f"Wallet address: {address}")
```

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

### Get Winston Credit Balance

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Retrieve the winston credit balance for your account or another specified address. Uses a signed request for authenticated balance checks when no address is provided.

```python
# Check your own balance (signed request)
balance = turbo.get_balance()
print(f"Balance: {balance.winc} winc")
```

```python
# Check another address (no signature needed)
other_balance = turbo.get_balance("0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A")
print(f"Other balance: {other_balance.winc} winc")
```

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

### Get Balance

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Retrieves the winston credit balance. It supports checking the authenticated user's balance via a signed request or checking the balance of any specified address.

```APIDOC
## GET /balance

### Description
Get winston credit balance. Uses signed request for authenticated balance check when no address specified.

### Method
GET

### Endpoint
/balance

### Parameters
#### Query Parameters
- **address** (str) - Optional - The address to check the balance for. If not provided, the balance of the authenticated user is returned.

### Response
#### Success Response (200)
- **winc** (str) - Available winston credits
- **controlled_winc** (str) - Controlled amount
- **effective_balance** (str) - Effective balance including shared credits

### Response Example
```json
{
  "winc": "1000000000000000000",
  "controlled_winc": "0",
  "effective_balance": "1000000000000000000"
}
```
```

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

### Turbo Client Initialization

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Demonstrates how to initialize the Turbo client with different signers and network configurations.

```APIDOC
## Turbo Client Initialization

The main `Turbo` class connects to ArDrive's upload and payment services. It requires a signer (Ethereum or Arweave) and supports mainnet/testnet networks or custom service URLs.

```python
from turbo_sdk import Turbo, EthereumSigner, ArweaveSigner
import json

# Initialize with Ethereum signer (mainnet)
eth_signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(eth_signer, network="mainnet")

# Initialize with Arweave signer (testnet)
with open("wallet.json") as f:
    jwk = json.load(f)
ar_signer = ArweaveSigner(jwk)
turbo_testnet = Turbo(ar_signer, network="testnet")

# Initialize with custom service URLs
turbo_custom = Turbo(
    eth_signer,
    upload_url="https://my-upload-service.example.com",
    payment_url="https://my-payment-service.example.com"
)

# Get wallet address
print(f"Wallet: {eth_signer.get_wallet_address()}")
# Output: Wallet: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A
```
```

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

### Initialize Ethereum Signer

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Create an Ethereum signer instance using a private key. The private key can be provided with or without the '0x' prefix.

```python
signer = EthereumSigner("0x1234567890abcdef...")
```

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

### Initialize Turbo Client

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Instantiate the Turbo client with an Ethereum or Arweave signer. Supports mainnet, testnet, or custom service URLs. Displays the wallet address after initialization.

```python
from turbo_sdk import Turbo, EthereumSigner, ArweaveSigner
import json

# Initialize with Ethereum signer (mainnet)
eth_signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(eth_signer, network="mainnet")

# Initialize with Arweave signer (testnet)
with open("wallet.json") as f:
    jwk = json.load(f)
ar_signer = ArweaveSigner(jwk)
turbo_testnet = Turbo(ar_signer, network="testnet")

# Initialize with custom service URLs
turbo_custom = Turbo(
    eth_signer,
    upload_url="https://my-upload-service.example.com",
    payment_url="https://my-payment-service.example.com"
)

# Get wallet address
print(f"Wallet: {eth_signer.get_wallet_address()}")
# Output: Wallet: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A
```

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

### Create Virtual Environment

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Set up a Python virtual environment using venv. This isolates project dependencies.

```bash
python -m venv venv
source venv/bin/activate
```

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

### EthereumSigner Initialization and Usage

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Create an Ethereum signer using a private key. Retrieve the wallet address and generate signed headers for authenticated API requests.

```python
from turbo_sdk import EthereumSigner

# Create signer from private key
signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")

# Get wallet address (checksum format)
address = signer.get_wallet_address()
print(f"Address: {address}")
# Output: Address: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A

# Create signed headers for authenticated API requests
headers = signer.create_signed_headers()
print(f"Headers: {headers.keys()}")
# Output: Headers: dict_keys(['x-signature', 'x-nonce', 'x-public-key'])
```

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

### Run Performance Benchmarks

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Execute performance tests for the Turbo service. Requires setting environment variables for the test wallet and optionally the upload URL.

```bash
export TURBO_TEST_WALLET=/path/to/wallet.json
export TURBO_UPLOAD_URL=https://upload.ardrive.dev  # optional, defaults to testnet
pytest -m performance -v -s
```

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

### Turbo Client Initialization

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Initialize the Turbo client with a signer and network configuration. Custom upload and payment URLs can also be provided.

```APIDOC
## Turbo Client Initialization

### `Turbo(signer, network="mainnet", upload_url=None, payment_url=None)`

Main client for interacting with Turbo services.

**Parameters:**

- `signer`: Either `EthereumSigner` or `ArweaveSigner` instance
- `network`: `"mainnet"` or `"testnet"` (default: `"mainnet"`)
- `upload_url`: Optional custom upload service URL (overrides network default)
- `payment_url`: Optional custom payment service URL (overrides network default)

```python
# Using default URLs (mainnet)
turbo = Turbo(signer)

# Using testnet
turbo = Turbo(signer, network="testnet")

# Using custom URLs
turbo = Turbo(signer, upload_url="https://my-upload-service.example.com")
```
```

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

### Build and Publish Package Locally

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Build the Python package and upload it to a package index using build and twine. This is an alternative to automated publishing via GitHub Actions.

```bash
pip install build twine
python -m build
twine check dist/*
twine upload dist/*
```

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

### upload() - Basic Data Upload

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Explains how to perform a basic data upload using the `upload()` method, including metadata tagging and handling of different file sizes.

```APIDOC
## upload() - Basic Data Upload

Uploads data to Arweave with optional metadata tags. Automatically signs data and handles the upload request. For files under 5 MiB, uses a single HTTP request.

```python
from turbo_sdk import Turbo, EthereumSigner

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

# Upload bytes with metadata tags
result = turbo.upload(
    data=b"Hello, Arweave!",
    tags=[
        {"name": "Content-Type", "value": "text/plain"},
        {"name": "App-Name", "value": "MyApp"},
        {"name": "App-Version", "value": "1.0.0"}
    ]
)

print(f"Transaction ID: {result.id}")
print(f"Owner: {result.owner}")
print(f"Cost: {result.winc} winc")
print(f"Data caches: {result.data_caches}")
print(f"Gateway URL: https://arweave.net/{result.id}")
# Output:
# Transaction ID: 8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0
# Owner: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A
# Cost: 123456789 winc
# Data caches: ['https://turbo.ardrive.io']
# Gateway URL: https://arweave.net/8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0
```
```

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

### Initialize Arweave Signer

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Instantiate an Arweave signer using a wallet in JWK format. This signer uses RSA-PSS signatures.

```python
signer = ArweaveSigner({
    "kty": "RSA",
    "n": "...",
    "e": "AQAB",
    "d": "...",
    # ... other JWK fields
})
```

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

### Handle Turbo SDK Exceptions

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Demonstrates how to catch specific Turbo SDK exceptions for granular error handling during uploads. Includes handling for insufficient balance, validation errors, finalization timeouts, and general chunked upload failures.

```python
from turbo_sdk import (
    Turbo, EthereumSigner,
    ChunkedUploadError, UnderfundedError,
    UploadValidationError, UploadFinalizationError
)

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

data = b"Important data to store permanently" * 100000

try:
    result = turbo.upload(
        data=data,
        tags=[{"name": "Content-Type", "value": "application/octet-stream"}]
    )
    print(f"Upload successful: {result.id}")

except UnderfundedError:
    # HTTP 402 - insufficient balance
    balance = turbo.get_balance()
    cost = turbo.get_upload_price(len(data))
    print(f"Insufficient balance: have {balance.winc} winc, need {cost} winc")
    print("Please top up your account at https://ardrive.io/turbo")

except UploadValidationError as e:
    # Upload was rejected during validation
    print(f"Upload validation failed: {e}")

except UploadFinalizationError as e:
    # Upload timed out during finalization
    print(f"Upload finalization timed out: {e}")
    print("The upload may still complete - check status later")

except ChunkedUploadError as e:
    # General chunked upload error
    print(f"Chunked upload failed: {e}")

except Exception as e:
    # Other errors (network issues, etc.)
    print(f"Upload failed: {e}")
```

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

### Upload Data with Metadata Tags

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Uploads data as bytes with specified metadata tags using the Turbo client. Handles signing and upload requests, optimizing for files under 5 MiB with a single HTTP request. Displays transaction details including ID, owner, cost, and data cache locations.

```python
from turbo_sdk import Turbo, EthereumSigner

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

# Upload bytes with metadata tags
result = turbo.upload(
    data=b"Hello, Arweave!",
    tags=[
        {"name": "Content-Type", "value": "text/plain"},
        {"name": "App-Name", "value": "MyApp"},
        {"name": "App-Version", "value": "1.0.0"}
    ]
)

print(f"Transaction ID: {result.id}")
print(f"Owner: {result.owner}")
print(f"Cost: {result.winc} winc")
print(f"Data caches: {result.data_caches}")
print(f"Gateway URL: https://arweave.net/{result.id}")
# Output:
# Transaction ID: 8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0
# Owner: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A
# Cost: 123456789 winc
# Data caches: ['https://turbo.ardrive.io']
# Gateway URL: https://arweave.net/8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0
```

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

### Upload Small Data with Metadata Tags

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

This snippet demonstrates uploading a small amount of data with associated metadata tags. It's suitable for direct uploads where the data fits within a single request.

```python
# Simple upload
result = turbo.upload(
    data=b"Your data here",
    tags=[
        {"name": "Content-Type", "value": "application/json"},
        {"name": "App-Name", "value": "MyApp"}
    ]
)
```

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

### EthereumSigner

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Details on how to create and use an EthereumSigner for signing transactions with an Ethereum private key.

```APIDOC
## EthereumSigner

Creates a signer using an Ethereum private key for ECDSA signatures. Accepts hex-encoded private keys with or without the `0x` prefix.

```python
from turbo_sdk import EthereumSigner

# Create signer from private key
signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")

# Get wallet address (checksum format)
address = signer.get_wallet_address()
print(f"Address: {address}")
# Output: Address: 0x742d35Cc6635C0532925a3b8C17af2e95C5Aca4A

# Create signed headers for authenticated API requests
headers = signer.create_signed_headers()
print(f"Headers: {headers.keys()}")
# Output: Headers: dict_keys(['x-signature', 'x-nonce', 'x-public-key'])
```
```

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

### ArweaveSigner Initialization and Verification

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Initialize an Arweave signer with a JWK wallet. Retrieve the wallet address and verify the public key length, which must be 512 bytes for Arweave.

```python
from turbo_sdk import ArweaveSigner
import json

# Load JWK from file
with open("arweave-wallet.json") as f:
    jwk = json.load(f)

# Create signer
signer = ArweaveSigner(jwk)

# Get wallet address (base64url-encoded SHA-256 hash of public key)
address = signer.get_wallet_address()
print(f"Arweave Address: {address}")
# Output: Arweave Address: 8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0

# Verify the public key is valid (must be 512 bytes for Arweave)
print(f"Public key length: {len(signer.public_key)} bytes")
# Output: Public key length: 512 bytes
```

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

### Large File Uploads with Progress

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Demonstrates uploading large files using `stream_factory` and an `on_progress` callback for real-time progress updates.

```APIDOC
## Large File Uploads with Progress

For files >= 5 MiB, the SDK automatically uses chunked multipart uploads. Use `stream_factory` to avoid loading the entire file into memory. A factory is needed because the stream is consumed twice — once for signing and once for uploading — so the SDK calls it each time to get a fresh stream.

```python
import os

def on_progress(processed: int, total: int):
    pct = (processed / total) * 100
    print(f"Upload progress: {pct:.1f}%")

file_path = "large-video.mp4"

result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=os.path.getsize(file_path),
    tags=[{"name": "Content-Type", "value": "video/mp4"}],
    on_progress=on_progress,
)
```
```

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

### ArweaveSigner

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Instructions for creating an ArweaveSigner using an Arweave JWK wallet for RSA-PSS signatures.

```APIDOC
## ArweaveSigner

Creates a signer using an Arweave JWK (JSON Web Key) wallet for RSA-PSS signatures. The JWK must contain the full RSA key components (n, e, d, p, q, dp, dq, qi).

```python
from turbo_sdk import ArweaveSigner
import json

# Load JWK from file
with open("arweave-wallet.json") as f:
    jwk = json.load(f)

# Create signer
signer = ArweaveSigner(jwk)

# Get wallet address (base64url-encoded SHA-256 hash of public key)
address = signer.get_wallet_address()
print(f"Arweave Address: {address}")
# Output: Arweave Address: 8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0

# Verify the public key is valid (must be 512 bytes for Arweave)
print(f"Public key length: {len(signer.public_key)} bytes")
# Output: Public key length: 512 bytes
```
```

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

### upload() - Chunked Upload with Custom Configuration

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Allows configuration of chunked uploads using ChunkingParams to control chunk size, concurrency, and upload mode for improved throughput.

```APIDOC
## POST /upload

### Description
Uploads a file using chunked transfer with custom configurations for chunk size, concurrency, and mode.

### Method
POST

### Endpoint
/upload

### Parameters
#### Request Body
- **stream_factory** (callable) - Required - A factory function that returns a readable byte stream.
- **data_size** (int) - Required - The total size of the data in bytes.
- **tags** (list of dict) - Optional - Metadata tags for the upload. Each dict should have 'name' and 'value' keys.
- **chunking** (ChunkingParams) - Optional - Configuration object for chunked uploads.
  - **chunk_size** (int) - Optional - The size of each chunk in bytes (allowed range: 5 MiB to 500 MiB).
  - **max_chunk_concurrency** (int) - Optional - The maximum number of chunks to upload in parallel.
  - **chunking_mode** (string) - Optional - The mode for chunking ('auto', 'force', or 'disabled').
- **on_progress** (callable) - Optional - A callback function to report upload progress. It receives processed and total bytes.

### Request Example
```python
from turbo_sdk import Turbo, EthereumSigner, ChunkingParams
import os

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

chunking = ChunkingParams(
    chunk_size=10 * 1024 * 1024,    # 10 MiB chunks
    max_chunk_concurrency=3,
    chunking_mode="auto"
)

file_path = "large-dataset.bin"
file_size = os.path.getsize(file_path)

result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=file_size,
    tags=[{"name": "Content-Type", "value": "application/octet-stream"}],
    chunking=chunking,
    on_progress=lambda p, t: print(f"Progress: {p}/{t} bytes")
)

print(f"Transaction ID: {result.id}")
print(f"Timestamp: {result.timestamp}")
print(f"Signature: {result.signature}")
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the uploaded data.
- **timestamp** (int) - The Unix timestamp of the transaction.
- **signature** (string) - The signature of the transaction.

#### Response Example
```json
{
  "id": "8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0",
  "timestamp": 1699123456789,
  "signature": "abc123..."
}
```
```

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

### Run Tests with Coverage

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Execute the project's tests using pytest and generate a code coverage report.

```bash
pytest --cov=turbo_sdk
```

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

### get_balance()

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Retrieves the winston credit balance for a wallet. It can be used to check your own balance (requires authentication) or the balance of any other address (no authentication needed).

```APIDOC
## GET /balance

### Description
Retrieves the winston credit balance for a specified wallet address.

### Method
GET

### Endpoint
/balance

### Parameters
#### Query Parameters
- **address** (string) - Optional - The wallet address to query. If not provided, the balance of the authenticated wallet is returned.

### Response
#### Success Response (200)
- **winc** (string) - The available balance in winston credits.
- **controlled_winc** (string) - The controlled balance in winston credits.
- **effective_balance** (string) - The effective balance (available + controlled) in winston credits.

#### Response Example
```json
{
  "winc": "1000000000000",
  "controlled_winc": "0",
  "effective_balance": "1000000000000"
}
```
```

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

### get_upload_price()

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Calculates the cost in winston credits to upload data of a specific byte size, useful for estimating costs before initiating an upload.

```APIDOC
## GET /price/upload

### Description
Calculates the estimated cost in winston credits to upload data of a given size.

### Method
GET

### Endpoint
/price/upload

### Parameters
#### Query Parameters
- **size** (int) - Required - The size of the data in bytes for which to estimate the upload cost.

### Response
#### Success Response (200)
- **cost** (string) - The estimated cost in winston credits.

#### Response Example
```json
{
  "cost": "12345678"
}
```
```

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

### Handle Turbo SDK Exceptions

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Implement error handling for common Turbo SDK exceptions such as insufficient balance or upload failures. Catch specific exceptions like UnderfundedError and ChunkedUploadError.

```python
from turbo_sdk import UnderfundedError, ChunkedUploadError

try:
    result = turbo.upload(large_data)
except UnderfundedError:
    print("Insufficient balance - please top up your account")
except ChunkedUploadError as e:
    print(f"Upload failed: {e}")
```

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

### Upload Large File with Stream Factory

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Use `stream_factory` for files >= 5 MiB to avoid loading the entire file into memory. The factory must return a fresh stream each time it's called for signing and uploading.

```python
from turbo_sdk import Turbo, EthereumSigner, ChunkingParams
import os

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

file_path = "large-video.mp4"
file_size = os.path.getsize(file_path)

def on_progress(processed: int, total: int):
    percent = (processed / total) * 100
    print(f"Upload progress: {percent:.1f}% ({processed}/{total} bytes)")

# Upload using stream factory for memory efficiency
result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=file_size,
    tags=[
        {"name": "Content-Type", "value": "video/mp4"},
        {"name": "App-Name", "value": "VideoUploader"}
    ],
    on_progress=on_progress
)

print(f"Upload complete: https://arweave.net/{result.id}")
```

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

### Exceptions

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Details on exceptions provided by the SDK for error handling.

```APIDOC
## Exceptions

The SDK provides specific exceptions for error handling:

- **ChunkedUploadError**: Base exception for chunked upload failures.
- **UnderfundedError**: Account has insufficient balance (HTTP 402).
- **UploadValidationError**: Upload validation failed (INVALID status).
- **UploadFinalizationError**: Finalization timed out or failed.
```

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

### Upload Large File with Chunking Parameters

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Configure chunked uploads with `ChunkingParams` to control chunk size, concurrency, and upload mode. Concurrent uploads can significantly improve throughput for large files.

```python
from turbo_sdk import Turbo, EthereumSigner, ChunkingParams
import os

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

# Configure chunked upload parameters
chunking = ChunkingParams(
    chunk_size=10 * 1024 * 1024,    # 10 MiB chunks (5-500 MiB allowed)
    max_chunk_concurrency=3,        # Upload 3 chunks in parallel
    chunking_mode="auto"            # "auto", "force", or "disabled"
)

file_path = "large-dataset.bin"
file_size = os.path.getsize(file_path)

result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=file_size,
    tags=[{"name": "Content-Type", "value": "application/octet-stream"}],
    chunking=chunking,
    on_progress=lambda p, t: print(f"Progress: {p}/{t} bytes")
)

print(f"Transaction ID: {result.id}")
print(f"Timestamp: {result.timestamp}")
print(f"Signature: {result.signature}")
```

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

### Upload Large Files with Progress Callback

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Handles uploading large files (>= 5 MiB) using chunked multipart uploads. The `stream_factory` is crucial for non-seekable streams or to avoid loading the entire file into memory. A progress callback is provided to monitor the upload status.

```python
import os

def on_progress(processed: int, total: int):
    pct = (processed / total) * 100
    print(f"Upload progress: {pct:.1f}%")

file_path = "large-video.mp4"

result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=os.path.getsize(file_path),
    tags=[{"name": "Content-Type", "value": "video/mp4"}],
    on_progress=on_progress,
)
```

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

### Lint and Format Code

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Apply code formatting and linting using Black and Flake8 to maintain code quality and consistency.

```bash
black turbo_sdk tests
flake8 turbo_sdk tests
```

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

### Configure Chunked Upload Parameters

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Customize chunked upload behavior using `ChunkingParams`. This allows control over chunk size, concurrency, and the chunking mode (auto, force, or disabled).

```python
from turbo_sdk import ChunkingParams

result = turbo.upload(
    data=large_data,
    chunking=ChunkingParams(
        chunk_size=10 * 1024 * 1024,  # 10 MiB chunks (default: 5 MiB)
        max_chunk_concurrency=3,             # Parallel chunk uploads (default: 1)
        chunking_mode="auto",                # "auto", "force", or "disabled"
    ),
    on_progress=lambda p, t: print(f"{p}/{t} bytes"),
)
```

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

### upload() - Large File Upload with stream_factory

Source: https://context7.com/ardriveapp/turbo-python-sdk/llms.txt

Handles large file uploads (>= 5 MiB) by using a stream_factory to avoid loading the entire file into memory. The factory is called multiple times, so it must return a fresh stream each time.

```APIDOC
## POST /upload

### Description
Uploads a file using a stream factory for memory efficiency, suitable for large files.

### Method
POST

### Endpoint
/upload

### Parameters
#### Request Body
- **stream_factory** (callable) - Required - A factory function that returns a readable byte stream.
- **data_size** (int) - Required - The total size of the data in bytes.
- **tags** (list of dict) - Optional - Metadata tags for the upload. Each dict should have 'name' and 'value' keys.
- **on_progress** (callable) - Optional - A callback function to report upload progress. It receives processed and total bytes.

### Request Example
```python
from turbo_sdk import Turbo, EthereumSigner
import os

signer = EthereumSigner("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
turbo = Turbo(signer, network="mainnet")

file_path = "large-video.mp4"
file_size = os.path.getsize(file_path)

def on_progress(processed: int, total: int):
    percent = (processed / total) * 100
    print(f"Upload progress: {percent:.1f}% ({processed}/{total} bytes)")

result = turbo.upload(
    stream_factory=lambda: open(file_path, "rb"),
    data_size=file_size,
    tags=[
        {"name": "Content-Type", "value": "video/mp4"},
        {"name": "App-Name", "value": "VideoUploader"}
    ],
    on_progress=on_progress
)

print(f"Upload complete: https://arweave.net/{result.id}")
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the uploaded data.

#### Response Example
```json
{
  "id": "8wgRDgvYOrtSaWEIV21g0lTuWDUnTu4_iYj4hmA3Pn0"
}
```
```

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

### Chunking Configuration

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Customize chunked upload behavior using `ChunkingParams` for chunk size, concurrency, and mode.

```APIDOC
## Chunking Configuration

Use `ChunkingParams` to customize chunked upload behavior:

```python
from turbo_sdk import ChunkingParams

result = turbo.upload(
    data=large_data,
    chunking=ChunkingParams(
        chunk_size=10 * 1024 * 1024,  # 10 MiB chunks (default: 5 MiB)
        max_chunk_concurrency=3,             # Parallel chunk uploads (default: 1)
        chunking_mode="auto",                # "auto", "force", or "disabled"
    ),
    on_progress=lambda p, t: print(f"{p}/{t} bytes"),
)
```

**ChunkingParams options:**

- `chunk_size`: Chunk size in bytes (5-500 MiB, default: 5 MiB)
- `max_chunk_concurrency`: Number of parallel chunk uploads (default: 1)
- `chunking_mode`:
  - `"auto"` (default): Use chunked upload for files >= 5 MiB
  - `"force"`: Always use chunked upload
  - `"disabled"`: Always use single request upload
```

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

### Signers

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Information about available signer implementations for creating authenticated requests.

```APIDOC
## Signer Implementations

### EthereumSigner

#### Description
Ethereum signer using ECDSA signatures.

#### Parameters
- **private_key** (str) - Required - Hex private key with or without `0x` prefix.

### ArweaveSigner

#### Description
Arweave signer using RSA-PSS signatures.

#### Parameters
- **jwk** (dict) - Required - Arweave wallet in JWK format.

### Signer Methods
Both signers provide the following methods:

#### `get_wallet_address() -> str`

##### Description
Get the wallet address for the signer.

##### Method
GET

##### Endpoint
(Internal SDK method, not a direct API endpoint)

#### `create_signed_headers() -> dict`

##### Description
Create signed headers for authenticated API requests.

##### Method
GET

##### Endpoint
(Internal SDK method, not a direct API endpoint)
```

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

### Create Signed Headers for API Requests

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Generate signed headers required for authenticated API requests using the signer object. This is crucial for operations that require authorization.

```python
headers = signer.create_signed_headers()
```

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

### Update Project Version

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Modify the 'version' field in the 'pyproject.toml' file to reflect the new release version before publishing.

```toml
[project]
version = "0.0.5"
```

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

### Upload Data

Source: https://github.com/ardriveapp/turbo-python-sdk/blob/alpha/README.md

Upload data using the Turbo client. Supports both small files and large files via chunked multipart uploads.

```APIDOC
## Upload Data

### `upload(data=None, tags=None, on_progress=None, chunking=None, data_size=None, stream_factory=None) -> TurboUploadResponse`

Upload data to the Turbo datachain. Supports both small files (single request) and large files (chunked multipart upload).

**Parameters:**

- `data`: Data to upload (`bytes` or file-like `BinaryIO` object)
- `tags`: Optional list of metadata tags
- `on_progress`: Optional callback `(processed_bytes, total_bytes) -> None`
- `chunking`: Optional `ChunkingParams` for upload configuration
- `data_size`: Required when `data` is a file-like object or when using `stream_factory`
- `stream_factory`: Optional callable that returns a fresh `BinaryIO` stream each time it's called. Use this for non-seekable streams or when you want to avoid loading the entire file into memory.

```python
# Simple upload
result = turbo.upload(
    data=b"Your data here",
    tags=[
        {"name": "Content-Type", "value": "application/json"},
        {"name": "App-Name", "value": "MyApp"}
    ]
)
```

**Returns:** `TurboUploadResponse`

```python
@dataclass
class TurboUploadResponse:
    id: str                        # Transaction ID
    owner: str                     # Owner address
    data_caches: List[str]         # Cache endpoints
    fast_finality_indexes: List[str] # Fast finality indexes
    winc: str                      # Winston credits cost
```
```

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