archipy 3.14.4__tar.gz

archipy-3.14.4/.cursor/rules/checks.mdc

@@ -0,0 +1,296 @@
+---
+description: Architectural principles and practices for clean, modular, and business-aligned design in ArchiPy
+globs:
+alwaysApply: true
+---
+
+# ArchiPy Cursor IDE Rules for Code Generation
+
+## General Guidelines
+
+**Small, Behavior-Preserving Steps**: Generate code in small, incremental changes that preserve existing functionality, validated via end-to-end Behave tests.
+
+**Clear Naming**: Use descriptive, intention-revealing names for variables, functions, and classes, following Pydantic naming conventions (e.g., CAMEL_CASE for BaseConfig fields) and domain terms (e.g., ParsianShaparakConfig).
+
+**No Duplication**: Eliminate duplicated code by extracting shared logic into reusable functions, methods, or Pydantic models in archipy.helpers.utils.
+
+**Single Responsibility**: Ensure functions, classes, and Pydantic models have a single, clear purpose. Split large components into smaller units.
+
+**Minimize Mutable Data**: Prefer immutable data structures (e.g., frozen=True in BaseDTO) and encapsulate mutable data to limit scope.
+
+**Avoid Over-Engineering**: Do not add speculative generality or unnecessary abstractions unless required.
+
+**Consistent Formatting**: Follow PEP 8, Black (line length 120 characters), and project-specific style (e.g., Pydantic Field descriptions). Use double quotes for strings.
+
+**Modular Design**: Organize code into modules (e.g., archipy.configs, archipy.helpers.utils) to minimize coupling and avoid divergent changes.
+
+**Documentation**: Use Pydantic field description attributes and Google-style docstrings for public APIs. Avoid redundant comments.
+
+## Python 3.13 Type Hints
+
+Use modern Python 3.13 type hints to ensure type safety and IDE support.
+
+**Rules**:
+- Use `|` for union types instead of `Union` (e.g., `BaseEntity | None`)
+- Use lowercase built-in types (e.g., `str` not `String`)
+- Use `@override` decorator for interface implementations
+- Use `type` instead of `Type` for class types
+- Use `Any` only for truly dynamic types
+- Avoid `Optional`; use `| None` instead
+- Use `X | Y` in isinstance calls instead of `(X, Y)`
+- Keep type hints simple and readable
+
+**Example**:
+```python
+from typing import Any, override
+from uuid import UUID
+
+def get_by_uuid(self, entity_type: type, entity_uuid: UUID) -> BaseEntity | None:
+    ...
+
+@override
+async def create(self, entity: BaseEntity) -> BaseEntity | None:
+    ...
+```
+
+## Exception Handling
+
+**Exception Chaining**: Always use `raise ... from exception` to preserve original error context for proper debugging.
+
+**Try-Except-Else Pattern**: When the try block returns a value on success, use an else block to make the success path explicit.
+
+**Rules**:
+- Preserve original exception context with `from e`
+- Use specific exception types (e.g., `InvalidEntityTypeError`)
+- For type validation, include clear error messages with expected and actual types
+- Use else block to separate exception handling from success path when returning values
+
+**Example with else**:
+```python
+try:
+    result = session.get(entity_type, entity_uuid)
+except DatabaseQueryError as e:
+    raise DatabaseQueryError() from e
+else:
+    return result
+```
+
+**Example without else (acceptable)**:
+```python
+try:
+    validate_config(config)
+except ValidationError as e:
+    logger.error(f"Config validation failed: {e}")
+    raise ConfigurationError() from e
+```
+
+## Pydantic Integration
+
+**Model Consistency**: Generate Pydantic models inheriting from `BaseModel` or `BaseSettings`, aligning with `BaseDTO` (frozen=True) and `BaseConfig` (env_nested_delimiter="__").
+
+**Settings Source Priority**: pyproject.toml → configs.toml → .env → OS env vars → class defaults
+
+**Validation Logic**: Use `@model_validator` for complex validation
+
+**Secret Handling**: Use `SecretStr` for sensitive fields and avoid exposing in logs
+
+**Type Safety**: Use strict typing (Generic, Literal, TypeVar)
+
+**Example**:
+```python
+from pydantic import BaseModel, Field, SecretStr, model_validator
+
+class ElasticsearchConfig(BaseModel):
+    """Elasticsearch connection configuration."""
+
+    HOSTS: list[str] = Field(
+        default=["http://localhost:9200"],
+        description="List of Elasticsearch node URLs",
+    )
+
+    @model_validator(mode='after')
+    def validate_hosts(self) -> 'ElasticsearchConfig':
+        if not self.HOSTS:
+            raise ValueError("At least one host required")
+        return self
+```
+
+## Architectural Design Patterns
+
+### Core Patterns
+
+**1. Ports & Adapters**: Define ports in `ports.py`, implement in `adapters.py`, provide `mocks.py`
+
+**2. Repository Pattern**: Abstract data access (e.g., PostgresSQLAlchemyAdapter)
+
+**3. Unit of Work**: Use atomic decorators (@postgres_sqlalchemy_atomic_decorator)
+
+**4. Service Layer**: Orchestrate business logic, keep framework-agnostic
+
+**5. Configuration**: Inherit from BaseConfig, use Pydantic Settings
+
+**6. Bounded Contexts**: Separate modules by domain (configs/, adapters/, models/, helpers/)
+
+### Anti-Patterns to Avoid
+- ❌ Tight coupling between adapters and business logic
+- ❌ Framework-dependent domain models
+- ❌ Configuration scattered across files
+- ❌ Circular dependencies
+- ❌ Excessive mocks in tests (prefer real implementations)
+
+## BDD Testing with Behave
+
+**Gherkin Scenarios**: Generate .feature files in features/ mapping to steps/
+
+**Test Philosophy**:
+- End-to-end focus at architectural boundaries
+- Minimize mocks, prefer testcontainers
+- Test behavior, not implementation
+- Independent, isolated scenarios
+
+**Running Tests**:
+- All: `make behave`
+- Single: `uv run --extra behave behave features/file_name.feature`
+- Scenario: `uv run --extra behave behave features/file_name.feature:line_number`
+
+## MyPy Compliance
+
+**Strict Mode**: disallow_untyped_defs, disallow_untyped_calls, strict_optional, warn_return_any
+
+**Pragmatic Overrides**: Allow Any for untyped third-party libs (confluent_kafka, zeep, minio), dynamic adapters (Redis, Keycloak, gRPC, Temporal), decorators, protobuf
+
+**Type Annotations**: Explicit for all parameters, return types, variables
+
+**Pydantic Plugin**: Enabled for proper model type checking
+
+## Ruff Compliance
+
+**Target**: Python 3.13, line length 120
+
+**Enabled Rules**:
+- A: flake8-builtins
+- ANN: flake8-annotations
+- ASYNC: flake8-async
+- B: flake8-bugbear
+- D: pydocstyle (Google-style, except D100, D104, D107)
+- E/W: pycodestyle (except E501)
+- ERA: eradicate
+- F: pyflakes (except F811 in steps)
+- G: logging (allow G004 f-strings)
+- I: isort (future → stdlib → third-party → first-party → local)
+- RUF: Ruff rules (except RUF001/RUF003 for Persian)
+- S: Bandit (allow S101 assert, S301/S403 pickle)
+- TRY: tryceratops (except TRY003, TRY301)
+- UP: pyupgrade
+
+**Ignored**:
+- BLE001: Allow Exception in adapters
+- C901: McCabe max 10
+- F811: Redefinition in steps
+- G004: f-strings in logging
+
+## Development Tools
+
+**Package Management**: `uv sync --all-extras --all-groups` or `make install-dev`
+
+**Workflow**:
+- Format: `make format` (Black, 120 chars)
+- Lint: `make lint` (Ruff + MyPy)
+- Test: `make behave`
+- Security: `make security` (Bandit)
+- All checks: `make check`
+- Pre-commit: `make pre-commit`
+
+**Documentation**: `make docs-serve`, `make docs-build`, `make docs-deploy`
+
+## Version Control
+
+**Commit Format**: Conventional Commits (feat:, fix:, refactor:, docs:, test:, chore:)
+
+**Workflow**:
+1. Feature branch from master
+2. Incremental changes with tests
+3. Run `make check`
+4. Run `make pre-commit`
+5. Commit with conventional message
+6. Create PR
+
+**Version Bump**: `make bump-patch/minor/major message="description"`
+
+**ADRs**: Create for significant changes in docs/adr/
+
+## Documentation Standards
+
+- Google-style docstrings for public APIs
+- Pydantic Field descriptions
+- Type hints as inline documentation
+- Avoid redundant comments
+- Examples in docs/examples/ with real code
+- API reference auto-generated from docstrings
+
+## AI Code Generation
+
+### Context Awareness
+
+Read before generating:
+- archipy/configs/base_config.py
+- archipy/models/dtos/base_dtos.py
+- archipy/helpers/utils/base_utils.py
+- Existing adapter implementations
+- pyproject.toml for dependencies and config
+
+### Principles
+
+1. Start small, iterate
+2. Follow existing patterns exactly
+3. Type safety first
+4. Test-driven (update .feature files)
+5. No API invention - use what exists or ask
+6. Explain decisions with rule references
+
+### New Adapter Workflow
+
+1. Create ports.py with interface
+2. Implement adapters.py
+3. Provide mocks.py
+4. Add config class
+5. Create .feature file
+6. Implement steps
+7. Update docs/examples/adapters/
+
+### Error Recovery
+
+- Fix linter errors immediately
+- Analyze test failures, suggest fixes
+- Ask if uncertain
+
+### Proactive Behavior
+
+- Identify code smells
+- Suggest architectural improvements
+- Point out security issues
+- Reference rules when explaining choices
+
+### Large Refactorings
+
+- Break into small steps
+- Ensure BaseConfig/BaseDTO consistency
+- Test after each step
+- Commit incrementally
+
+## Summary Checklist
+
+Before completing tasks, verify:
+
+- ✅ Python 3.13 type hints with `|` unions
+- ✅ Line length ≤ 120 characters
+- ✅ Google-style docstrings for public APIs
+- ✅ Pydantic Field descriptions
+- ✅ Exception chaining with `raise ... from e`
+- ✅ Ruff and MyPy compliant
+- ✅ Behave tests created/updated
+- ✅ Documentation updated
+- ✅ Conventional Commits message ready
+- ✅ No linter errors
+- ✅ No security issues
+- ✅ Tests pass

archipy-3.14.4/.cursorignore

@@ -0,0 +1,7 @@
+.idea/
+.venv/
+.vscode/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.DS_Store

archipy-3.14.4/.dockerignore

@@ -0,0 +1,174 @@
+# CMake
+cmake-build-*/
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/