Merge branch 'feature/mkdocforge-setup-dev-environment' into develop

Author: Mdevpro78

.gitattributes

@@ -55,4 +55,4 @@ Makefile   text eol=lf
 
 # Exclude Git-specific files from exports
 .gitattributes export-ignore
-.gitignore     export-ignore
+.gitignore     export-ignore

hatch.toml

@@ -0,0 +1,3 @@
+[envs.default]
+installer = "uv"
+python = "3.11"

mypy.ini

@@ -0,0 +1,280 @@
+[mypy]
+# ==============================================================================
+# Global mypy Configuration
+# ==============================================================================
+# Python version: Specifies the target Python version for type checking.
+# This ensures compatibility with the specified Python version's type system.
+python_version = 3.11
+
+# Strict mode: Enables all strict type checking options for maximum type safety.
+# This is recommended for production code to catch potential type-related bugs early.
+strict = True
+
+# Exclusion patterns: Directories to exclude from type checking.
+# - tests: Test files often have different type checking requirements
+# - migrations: Database migration scripts typically don't benefit from type checking
+# - docs: Documentation code examples don't need strict type checking
+# - .venv: Virtual environment files should never be type checked
+exclude = (?x)(
+		^tests/
+		| ^migrations/
+		| ^docs/
+		| .venv/
+	)
+
+# Source directory: Sets the base directory for import resolution.
+# This helps mypy correctly resolve imports within your project structure.
+mypy_path = src
+
+# Namespace packages: Enables support for PEP 420 namespace packages.
+# Useful for projects with a distributed package structure across multiple directories.
+namespace_packages = True
+
+# Explicit package bases: Ensures clear package structure with defined base directories.
+# Helps prevent import confusion in complex project structures.
+explicit_package_bases = True
+
+# ==============================================================================
+# Plugin Configuration
+# ==============================================================================
+# Mypy plugins: Extends mypy's type checking capabilities for specific libraries.
+# - pydantic.mypy: Adds support for Pydantic model type checking
+# - sqlalchemy.ext.mypy.plugin: Enhances SQLAlchemy ORM type checking
+plugins =
+    pydantic.mypy,
+    sqlalchemy.ext.mypy.plugin
+
+# ==============================================================================
+# Strict Type Checking Settings
+# ==============================================================================
+# Function definitions: Requires explicit type annotations for all function definitions.
+# This ensures that function signatures are clear and well-documented.
+disallow_untyped_defs = True
+
+# Incomplete definitions: Prohibits functions with partial type annotations.
+# Ensures consistency by requiring complete type information for all parameters and returns.
+disallow_incomplete_defs = True
+
+# Untyped function checking: Enables type checking for functions without annotations.
+# Helps catch type errors even in functions that haven't been properly annotated yet.
+check_untyped_defs = True
+
+# Decorator annotations: Requires type annotations for decorators.
+# Important for ensuring type safety when using custom decorators.
+disallow_untyped_decorators = True
+
+# Implicit Optional handling: Disables automatic Optional typing for parameters with None defaults.
+# Forces explicit declaration of Optional types for better code clarity.
+no_implicit_optional = True
+
+# Redundant cast warnings: Flags unnecessary type casts to improve code cleanliness.
+# Helps maintain clean code by removing unnecessary type casting operations.
+warn_redundant_casts = True
+
+# Unused ignore warnings: Flags unnecessary # type: ignore comments.
+# Prevents accumulation of outdated type-ignore directives in the codebase.
+warn_unused_ignores = True
+
+# Missing return warnings: Warns about functions that don't return a value but should.
+# Catches potential bugs where a function is expected to return a value.
+warn_no_return = True
+
+# Unreachable code: Warns about code that can never be executed.
+# Identifies dead code that should be removed for maintenance clarity.
+warn_unreachable = True
+
+# Optional type checking: Enables strict checking of Optional types.
+# Ensures proper handling of potentially None values throughout the codebase.
+strict_optional = True
+
+# Equality checking: Ensures proper equality checks between different types.
+# Prevents subtle bugs from comparing incompatible types.
+strict_equality = True
+
+# Sequence concatenation: Enforces proper type checking when concatenating sequences.
+# Prevents type errors when combining lists, tuples, or other sequence types.
+strict_concatenate = True
+
+# ==============================================================================
+# Additional Production Safety Checks
+# ==============================================================================
+# Enhanced error detection: Enables specific error codes for production code safety.
+# These additional checks help catch subtle bugs that might otherwise go unnoticed.
+enable_error_code = [
+    "truthy-bool",          # Prevents using non-boolean expressions in boolean contexts (if x: vs if x is True:)
+    "redundant-expr",       # Identifies expressions that have no effect and can be removed
+    "unused-awaitable",     # Catches forgotten await statements that could lead to unexpected behavior
+    "ignore-without-code",  # Requires specific error codes with # type: ignore for better documentation
+    "possibly-undefined",   # Identifies variables that might be undefined in some execution paths
+    "redundant-self",       # Flags unnecessary self or cls parameters in methods
+]
+
+# ==============================================================================
+# Error Reporting Configuration
+# ==============================================================================
+# Output formatting: Configures how mypy presents error messages for better usability.
+# These settings make error messages more readable and actionable.
+pretty = True               # Uses a more readable format for error messages
+show_error_context = True   # Displays the code context where errors occur
+show_column_numbers = True  # Shows precise column positions for errors
+show_error_codes = True     # Includes error codes for easier reference and suppression
+color_output = True         # Uses colors in terminal output for better readability
+error_summary = True        # Provides a summary of all errors at the end of the report
+
+# ==============================================================================
+# Import Discovery Configuration
+# ==============================================================================
+# Import handling: Controls how mypy processes and validates imports.
+# These settings determine how strictly mypy enforces type checking for imported modules.
+ignore_missing_imports = False      # By default, requires type stubs for all imports
+follow_imports = normal             # Normal import following behavior for type checking
+follow_imports_for_stubs = True     # Prioritizes type stubs over implementation modules
+
+# ==============================================================================
+# Third-party Library Configurations
+# ==============================================================================
+# Library-specific settings: Configures type checking behavior for external dependencies.
+# Libraries without complete type annotations need special handling to prevent false positives.
+[mypy-orjson.*]
+ignore_missing_imports = True   # Skips import verification for this library
+ignore_errors = true            # Ignores type errors within this library's code
+
+[mypy-dotenv.*]
+ignore_missing_imports = True   # Skips import verification for this library
+ignore_errors = true            # Ignores type errors within this library's code
+
+# ==============================================================================
+# Database-related Configurations
+# ==============================================================================
+# ORM and database connectors: Special handling for database interaction libraries.
+# These libraries often use dynamic attribute access that's difficult to type check.
+[mypy-sqlalchemy.*]
+ignore_missing_imports = True   # SQLAlchemy uses complex metaprogramming that's hard to type check
+
+[mypy-alembic.*]
+ignore_missing_imports = True   # Alembic migration tool lacks complete type annotations
+
+[mypy-asyncpg.*]
+ignore_missing_imports = True   # AsyncPG PostgreSQL client lacks complete type annotations
+
+[mypy-databases.*]
+ignore_missing_imports = True   # Databases library lacks complete type annotations
+
+# ==============================================================================
+# Web Framework Configurations
+# ==============================================================================
+# FastAPI and ASGI: Configuration for web framework components.
+# Web frameworks often use complex dependency injection and routing that needs special handling.
+[mypy-fastapi.*]
+ignore_missing_imports = True   # FastAPI uses Pydantic models and complex routing
+
+[mypy-starlette.*]
+ignore_missing_imports = True   # Starlette (FastAPI foundation) lacks complete type annotations
+
+[mypy-uvicorn.*]
+ignore_missing_imports = True   # ASGI server lacks complete type annotations
+
+[mypy-gunicorn.*]
+ignore_missing_imports = True   # WSGI HTTP server lacks complete type annotations
+
+# ==============================================================================
+# HTTP Clients and Related Libraries
+# ==============================================================================
+# HTTP client libraries: Configuration for making network requests.
+# These libraries often have complex async patterns or dynamic response handling.
+[mypy-httpx.*]
+ignore_missing_imports = True   # Modern async HTTP client
+
+[mypy-requests.*]
+ignore_missing_imports = True   # Popular synchronous HTTP client
+
+[mypy-aiohttp.*]
+ignore_missing_imports = True   # Async HTTP client and server framework
+
+# ==============================================================================
+# Serialization/Validation Configurations
+# ==============================================================================
+# Data validation libraries: Settings for data parsing and validation tools.
+# These libraries often use complex validation logic and dynamic field access.
+[mypy-pydantic.*]
+ignore_missing_imports = True   # Data validation using Python type annotations
+
+[mypy-pydantic_settings.*]
+ignore_missing_imports = True   # Settings management with Pydantic
+
+[mypy-email_validator.*]
+ignore_missing_imports = True   # Email validation library used by Pydantic
+
+# ==============================================================================
+# Testing Frameworks
+# ==============================================================================
+# Test libraries: Configuration for testing tools and frameworks.
+# Testing libraries use fixtures and assertions that can be complex to type check.
+[mypy-pytest.*]
+ignore_missing_imports = True   # Popular Python testing framework
+
+[mypy-hypothesis.*]
+ignore_missing_imports = True   # Property-based testing framework
+
+# ==============================================================================
+# Utility Libraries
+# ==============================================================================
+# Common utilities: Settings for general-purpose utility libraries.
+# These provide infrastructure components that may use dynamic patterns.
+[mypy-celery.*]
+ignore_missing_imports = True   # Distributed task queue
+
+[mypy-redis.*]
+ignore_missing_imports = True   # Redis client library
+
+# ==============================================================================
+# Type Checking Adjustments for ORM Patterns
+# ==============================================================================
+# ORM compatibility: Relaxes certain type checks that conflict with ORM patterns.
+# These adjustments allow for common ORM usage patterns while maintaining type safety.
+allow_any_generics = True       # Allows Any in generic types (needed for some ORM patterns)
+allow_redefinition = True       # Permits redefinition of names in certain contexts
+
+# Disables specific error codes that often conflict with ORM and framework patterns
+disable_error_code = [
+    "override",    # Allows method overrides with signature differences (common in framework extensions)
+    "empty-body",  # Permits empty function bodies (useful for abstract methods and protocol definitions)
+    "misc",        # Disables miscellaneous checks that may be too strict for framework integration
+    "arg-type",    # Relaxes argument type checking for legacy code and framework callbacks
+]
+
+# ==============================================================================
+# Framework-specific Error Ignores
+# ==============================================================================
+# Special cases: Ignores errors in specific framework modules with complex metaprogramming.
+# These modules use advanced Python features that are difficult for static type checkers.
+[mypy-fastapi.dependencies.utils]
+ignore_errors = True    # FastAPI dependency resolution uses complex metaprogramming
+
+[mypy-fastapi.routing]
+ignore_errors = True    # FastAPI routing system uses decorators and complex type patterns
+
+[mypy-sqlalchemy.orm.decl_api]
+ignore_errors = True    # SQLAlchemy declarative API uses metaclasses and dynamic attributes
+
+# ==============================================================================
+# Cache Backends
+# ==============================================================================
+# Caching libraries: Configuration for memory and distributed cache systems.
+# These libraries often use dynamic key/value access patterns.
+[mypy-cachetools.*]
+ignore_missing_imports = True   # In-memory caching utilities
+
+[mypy-aiocache.*]
+ignore_missing_imports = True   # Async caching framework
+
+# ==============================================================================
+# Background Tasks and Scheduling
+# ==============================================================================
+# Task processing: Settings for background job processing libraries.
+# These systems often use decorators and dynamic task registration.
+[mypy-apscheduler.*]
+ignore_missing_imports = True   # Advanced Python scheduler
+
+[mypy-dramatiq.*]
+ignore_missing_imports = True   # Background task processing system