Skip to content

Tutorials

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

All examples follow ArchiPy's coding standards:

  • ✅ Python 3.14 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
  • ScyllaDB - NoSQL database adapter for ScyllaDB and Apache Cassandra
  • 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.14 types
  • Interceptors - gRPC and FastAPI interceptors for cross-cutting concerns
  • Metaclasses - Singleton and registry metaclass patterns
  • Utils - Datetime, JWT, password, file, and validation utilities with proper error handling

Configuration

Type-safe configuration management:

Testing

Behavior-Driven Development with Behave:

  • BDD Testing — Gherkin features, mock adapters, testcontainers, and the Ports & Adapters testing pattern

Models

Data Transfer Objects and type-safe models:

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

Error Handling

Comprehensive error handling patterns:

  • Error Handling - 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.14 best practices. Each adapter example includes links to its corresponding BDD test scenarios and API reference documentation.

See Also