FoxNose Python SDK

Overview

The FoxNose Python SDK provides a convenient way to interact with FoxNose APIs from your Python applications. It includes two main clients:

• ManagementClient - For administrative operations: managing collections, components, resources, roles, and API keys
• FluxClient - For content delivery: fetching published resources, searching content, and accessing localized data

Features

• Type-safe - Full type hints and Pydantic models for all API responses
• Sync and async - Both synchronous and asynchronous clients available
• Automatic retries - Configurable retry logic with exponential backoff
• JWT authentication - Built-in support for JWT tokens with automatic refresh
• Python 3.9+ - Supports Python 3.9 and higher

Installation

pip install foxnose-sdk

Getting Started

See the Getting Started Guide for installation, configuration, and usage examples.

Components on Collections

Collections can embed Components as nested fields with explicit pin semantics (component, component_version, auto_update). The NestedFieldMeta helper builds the meta block for you, and sync_collection_component advances pinned fields to a target Component version on demand.

from foxnose_sdk import ManagementClient, FoxnoseConfig, NestedFieldMeta
from foxnose_sdk.auth import JWTAuth

client = ManagementClient(
    FoxnoseConfig(base_url="https://api.foxnose.net"),
    environment_key="prod",
    auth=JWTAuth.from_static_token("YOUR_ACCESS_TOKEN"),
)

# Embed a Component as a pinned nested field on a Collection draft.
client.create_collection_field(
    "articles",
    "v2-draft",
    {
        "key": "seo",
        "name": "SEO",
        "type": "nested",
        "required": True,
        "meta": NestedFieldMeta(
            component="cmp-seo-metadata",
            component_version="ver-abc12345",
            auto_update=False,  # default — pin until explicit sync
        ).to_meta(),
    },
)

# Later, advance pinned nested fields to a newer Component version.
# An empty body syncs every pinned field to its Component's current version.
result = client.sync_collection_component("articles")
print(result.synced_paths, result.schema_version)

# Advance specific paths to a chosen Component version.
result = client.sync_collection_component(
    "articles",
    field_paths=["seo"],
    to_versions={"seo": "ver-def67890"},
)

sync_collection_component returns a SyncComponentResponse with synced_paths, skipped (per-path reasons), and schema_version (the UID of the newly published Collection schema version, or None if no field needed advancing). On a compatibility conflict the server returns 409 component_sync_conflict; quota exhaustion returns 422 too_many_versions. Both surface as FoxnoseAPIError.

Handling billing errors

Billing and quota responses raise typed subclasses of FoxnoseAPIError, so existing except FoxnoseAPIError handlers keep working while new code can read the typed attributes:

from foxnose_sdk import (
    SpendCapExceeded,
    PlanExhausted,
    PlanLimitExceeded,
    RateLimitExceeded,
)

try:
    client.create_collection({"name": "Blog"})
except SpendCapExceeded as e:  # HTTP 402
    print(f"Spend cap {e.cap_usd}; resets at {e.cycle_resets_at}: {e.raise_cap_url}")
except PlanExhausted as e:  # HTTP 402
    print(f"Allowance for {e.axis} exhausted; resets at {e.window_resets_at}")
except PlanLimitExceeded as e:  # HTTP 403
    print(f"{e.entity}: {e.current}/{e.limit}. Upgrade: {e.upgrade_url}")
except RateLimitExceeded as e:  # HTTP 429
    print(f"Rate limited; retry after {e.retry_after}s")

All four subclass FoxnoseAPIError, so a single except FoxnoseAPIError still catches them when you don't need the typed fields.

Resources

• Full Documentation - Complete SDK reference
• GitHub Repository - Source code and issues
• PyPI Package - Package downloads
• Management API Reference - API documentation
• Flux API Reference - Content delivery API docs