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
  • MySQL - Database operations with SQLAlchemy and atomic transactions
  • SQLite - Lightweight database adapter for local storage
  • SQLAlchemy Search Totals - Search pagination with total counts for SQLAlchemy adapters
  • StarRocks - Analytics database adapter
  • ScyllaDB - NoSQL database adapter for ScyllaDB and Apache Cassandra
  • Redis - Cache operations, pub/sub, and testing with testcontainers
  • Elasticsearch - Search and indexing with the Elasticsearch adapter
  • Vault - Secrets management with HashiCorp Vault
  • 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 ( Parsian, Saman)

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

Dependency Injection

Observability

  • Observability - OpenTelemetry traces, metrics, and logs
  • Pydantic AI - Pydantic AI agent telemetry through BaseConfig.PYDANTIC_AI

Operations

  • Caching - In-process TTL caching with ttl_cache and the cache extra
  • Scheduler - Running APScheduler jobs with the scheduler extra
  • Health Checks and Shutdown - Readiness checks and graceful shutdown building blocks

Note: Each adapter tutorial links to its BDD scenarios and API reference.

See Also