Examples

This section contains practical examples of using ArchiPy components with Python 3.13 type hints, proper exception handling patterns, and comprehensive error chaining.

All examples follow ArchiPy's coding standards:

• ✅ Python 3.13 Type Hints: Using | for unions, lowercase built-in types (str, int, list, dict)
• ✅ Exception Chaining: All exceptions use raise ... from e to preserve error context
• ✅ Try-Except-Else Pattern: Explicit else blocks with return statements for clear control flow
• ✅ Proper Logging: Using logger instead of print() statements throughout
• ✅ Domain-Specific Errors: ArchiPy custom exceptions instead of generic ValueError or Exception

Adapters

Learn how to use ArchiPy's database, cache, messaging, and storage adapters with complete error handling:

• PostgreSQL - Database operations with SQLAlchemy and atomic transactions
• SQLite - Lightweight database adapter for local storage
• StarRocks - Analytics database adapter
• Redis - Cache operations, pub/sub, and async mock testing
• Email - Email sending with proper error handling
• Keycloak - Authentication and authorization with proper exception chaining
• MinIO - Object storage operations with presigned URLs
• Kafka - Message streaming with producer/consumer patterns
• Temporal - Workflow orchestration
• Payment Gateways - Iranian payment gateway integration

Helpers

Utility functions and decorators following best practices:

• Decorators - Retry, timeout, caching, and transaction decorators with Python 3.13 types
• Interceptors - gRPC and FastAPI interceptors for cross-cutting concerns
• Utils - Datetime, JWT, password, file, and validation utilities with proper error handling

Configuration

Type-safe configuration management:

• Configuration Management - Environment-based configuration with Pydantic and security best practices

Testing

Behavior-Driven Development with Behave:

• BDD Testing - Writing Gherkin scenarios and step definitions with exception chaining

Models

Data Transfer Objects and type-safe models:

• Protobuf DTOs - Converting between Pydantic DTOs and Protocol Buffers with Python 3.13 syntax

Error Handling

Comprehensive error handling patterns:

• Error Handling Examples - Domain-specific exceptions, error recovery, and proper exception chaining

---

Note: All code examples in this section have been updated to follow ArchiPy's architectural principles and Python 3.13 best practices. Each adapter example includes links to its corresponding BDD test scenarios and API reference documentation.