Python Sdk

Python Sdk is an AI skill that guides the design, implementation, testing, and publishing of Python software development kits for APIs and services. It covers SDK architecture patterns, type annotation strategies, authentication handling, async support, documentation generation, and PyPI publishing workflows that produce developer friendly client libraries.

What Is This?

Overview

Python Sdk provides structured approaches to building client libraries that Python developers use to interact with APIs. It handles designing SDK interfaces that follow Python idioms and PEP conventions, adding comprehensive type annotations for IDE support and static analysis, implementing authentication flows including API keys, OAuth tokens, and custom headers, providing both synchronous and asynchronous client implementations, generating documentation from docstrings using Sphinx or MkDocs, and publishing packages to PyPI with proper versioning and metadata.

Who Should Use This

This skill serves platform teams building SDKs for public or internal APIs, developer advocates improving API adoption through client libraries, open source maintainers publishing Python packages, and backend developers providing typed client libraries for their services.

Why Use It?

Problems It Solves

Without an SDK, API consumers write repetitive boilerplate for authentication, serialization, and error handling. Untyped API clients provide no IDE autocomplete or static analysis benefits. Inconsistent error handling across raw HTTP calls makes debugging difficult. Supporting both sync and async usage patterns requires duplicating implementation logic.

Core Highlights

Pythonic API design produces intuitive interfaces that follow community conventions. Type annotations provide autocomplete and enable mypy validation. Built in retry logic and structured exceptions reduce consumer code complexity. Dual sync and async support serves both simple scripts and high performance applications.

How to Use It?

Basic Usage

import httpx
from dataclasses import dataclass
from typing import Optional

@dataclass
class ClientConfig:
    api_key: str
    base_url: str = "https://api.example.com/v1"
    timeout: int = 30

class ApiClient:
    def __init__(self, config: ClientConfig):
        self.config = config
        self.session = httpx.Client(
            base_url=config.base_url,
            timeout=config.timeout,
            headers={
                "Authorization": f"Bearer {config.api_key}",
                "Content-Type": "application/json"
            }
        )

    def _request(self, method, path, **kwargs):
        response = self.session.request(method, path, **kwargs)
        if response.status_code >= 400:
            raise ApiError(response.status_code,
                           response.text)
        return response.json()

    def list_users(self, page: int = 1) -> list:
        return self._request("GET", "/users",
                             params={"page": page})

    def get_user(self, user_id: str) -> dict:
        return self._request("GET", f"/users/{user_id}")

    def create_user(self, name: str,
                    email: str) -> dict:
        return self._request("POST", "/users",
                             json={"name": name,
                                   "email": email})

Real-World Examples

class ApiError(Exception):
    def __init__(self, status_code, body):
        self.status_code = status_code
        self.body = body
        self.retryable = status_code in (429, 500, 502, 503)
        super().__init__(f"API Error {status_code}: {body}")

class RetryHandler:
    def __init__(self, max_retries=3, base_delay=1.0):
        self.max_retries = max_retries
        self.base_delay = base_delay

    def execute(self, fn, *args, **kwargs):
        import time
        last_error = None
        for attempt in range(self.max_retries + 1):
            try:
                return fn(*args, **kwargs)
            except ApiError as e:
                last_error = e
                if not e.retryable:
                    raise
                if attempt < self.max_retries:
                    delay = self.base_delay * (2 ** attempt)
                    time.sleep(delay)
        raise last_error

class AsyncApiClient:
    def __init__(self, config: ClientConfig):
        self.config = config
        self.session = httpx.AsyncClient(
            base_url=config.base_url,
            timeout=config.timeout,
            headers={
                "Authorization": f"Bearer {config.api_key}"
            }
        )

    async def list_users(self, page: int = 1) -> list:
        response = await self.session.get(
            "/users", params={"page": page}
        )
        return response.json()

Advanced Tips

Use httpx instead of requests as the HTTP backend to provide both sync and async clients from the same codebase. Generate Pydantic models from your OpenAPI spec for response validation and serialization. Include a py.typed marker file in your package so mypy recognizes it as typed.

When to Use It?

Use Cases

Use Python Sdk when publishing a client library for your public or internal API, when wrapping third party APIs with typed interfaces for your team, when building SDKs that need both synchronous and asynchronous support, or when improving the developer experience for Python consumers of your service.

Related Topics

OpenAPI code generation for Python, PyPI package publishing, type annotation best practices, async programming with asyncio, and API documentation with Sphinx complement Python SDK development.

Important Notes

Requirements

A documented API with stable endpoints and response schemas. Python 3.8 or later for modern type annotation support. Build tooling such as setuptools or Poetry for packaging and publishing.

Usage Recommendations

Do: follow semantic versioning strictly so consumers can depend on your SDK reliably. Include comprehensive docstrings on all public methods for IDE integration. Ship the py.typed marker and inline type annotations rather than separate stub files.

Don't: expose internal implementation details in the public API surface that create coupling preventing refactoring. Bundle heavy dependencies that inflate install size for consumers who only need a subset. Release breaking changes in minor versions.

Limitations

Maintaining sync and async clients in parallel adds development and testing overhead. Generated SDKs from OpenAPI specs may produce less ergonomic interfaces than hand-crafted ones. Supporting multiple Python versions requires testing across version matrices that increase CI complexity.