python-sdk

Sunra Clients - Python SDK Developer Role Document

Overview

This document defines the role and responsibilities of a Python SDK Developer for the Sunra Clients project. The Python SDK provides both synchronous and asynchronous client libraries for interacting with Sunra.ai services, following Python best practices and type safety standards.

Project Structure

The Python SDK is organized as follows:

• src/sunra_client/: Main package directory
  • init.py: Package initialization and public API
  • client.py: Main client implementation with sync/async support
  • auth.py: Authentication and credential management
  • py.typed: Type checking marker file

Development Guidelines

1. Code Style and Standards

Python Style Guide

• Follow PEP 8 coding standards
• Use 4 spaces for indentation (Python standard)
• Maximum line length: 120 characters
• Use snake_case for functions and variables: submit_request, get_status
• Use PascalCase for class names: SunraClient, QueueClient
• Use UPPER_SNAKE_CASE for constants: DEFAULT_TIMEOUT, MAX_RETRIES

Type Hints

• Use type hints for all function parameters and return values
• Use modern union syntax: str | None instead of Optional[str]
• Include from __future__ import annotations for forward references
• Maintain py.typed file for type checking support

Import Organization

# Standard library imports
import asyncio
import os
from typing import Any, Dict, Optional, Union

# Third-party imports
import httpx
from pydantic import BaseModel, Field

# Local imports
from .auth import CredentialsResolver
from .exceptions import SunraException, SunraValidationException

2. Architecture Patterns

Client Architecture

class SunraClient:
    """Main Sunra client with both sync and async support."""

    def __init__(
        self,
        credentials: str | None = None,
        api_endpoint: str | None = None,
        queue_domain: str | None = None,
        timeout: float = 300.0,
    ):
        self._credentials = credentials or os.getenv("SUNRA_KEY")
        self._api_endpoint = api_endpoint or os.getenv("SUNRA_API_ENDPOINT")
        self._queue_domain = queue_domain or os.getenv("SUNRA_QUEUE_DOMAIN")
        self._timeout = timeout

        # Initialize HTTP clients
        self._sync_client = httpx.Client(timeout=timeout)
        self._async_client = httpx.AsyncClient(timeout=timeout)

    def subscribe(self, endpoint_id: str, **kwargs) -> Dict[str, Any]:
        """Synchronous subscribe method."""
        pass

    async def subscribe_async(self, endpoint_id: str, **kwargs) -> Dict[str, Any]:
        """Asynchronous subscribe method."""
        pass