Add Python client documentation and expand multi-language examples

[amavashev]

Summary

This PR significantly expands the documentation to provide comprehensive coverage of the Python runcycles client alongside existing Java/Spring documentation. It adds a new Python client configuration reference and updates multiple how-to guides and quickstart docs to include Python-specific examples and patterns.

Key Changes

• New Python Configuration Reference (configuration/python-client-configuration-reference.md): Complete reference for CyclesConfig including required fields, subject defaults, HTTP timeouts, retry configuration, environment variable mapping, and default client setup patterns.

• Multi-language Documentation Updates:

  • error-handling-patterns-in-cycles-client-code.md: Restructured to cover both Python (CyclesProtocolError) and Java (CyclesProtocolException) with parallel examples for DENY handling, degradation patterns, debt/overdraft errors, expired reservations, and web framework error handlers (FastAPI and Spring).
  • using-the-cycles-client-programmatically.md: Added Python examples for client initialization, reservation creation, commit/release operations, full lifecycle example, preflight checks, balance queries, reservation listing, and event recording. Included async support documentation for AsyncCyclesClient.
  • testing-with-cycles.md: Added comprehensive Python testing section covering unit testing with mocks, pytest-httpx integration tests, error handling tests, and async test patterns alongside existing Java/Spring tests.

• API Key Management: Added Python-specific configuration examples in api-key-management-in-cycles.md showing both programmatic and environment variable approaches.

• Navigation Updates: Updated .vitepress/config.ts to reference the new Python client configuration reference in the configuration section.

• Cross-references: Updated multiple concept and protocol documents with consistent "Next steps" sections linking to Python client documentation.

Notable Implementation Details

• Python examples use the runcycles package with consistent patterns: CyclesClient context managers, CyclesConfig for configuration, and exception hierarchy (BudgetExceededError, DebtOutstandingError, etc.).
• Documentation maintains parity between Python and Java implementations while respecting language idioms (e.g., context managers vs. try-finally, async/await patterns).
• Error handling examples show both decorator/annotation patterns and programmatic client usage for both languages.
• Testing examples demonstrate mocking strategies appropriate to each language ecosystem (unittest.mock for Python, Mockito for Java).

https://claude.ai/code/session_01JR3CtJAL5geHGWkMSMj2WM