pyproject.toml

[project]
name = "archipy"
description = "Architecture + Python – Perfect for structured design."
authors = [
    { name = "Hossein Nejati", email = "hosseinnejati14@gmail.com" },
    { name = "Mehdi Einali", email = "einali@gmail.com" },
]
readme = "README.md"
version = "0.1.0" # This vesrion set on publish flow!
requires-python = ">=3.14,<4"
dependencies = [
    "pydantic>=2.13.4",
    "pydantic-settings>=2.15.0",
    "requests>=2.34.2",
    "jdatetime>=6.1.0",
]
license = { file = "LICENSE" }

[project.optional-dependencies]
# Core optional dependencies
aiosqlite = ["aiosqlite>=0.22.1"]
behave = ["behave>=1.3.3"]
cache = ["cachetools>=7.1.7", "async-lru>=2.3.0"]
dependency-injection = ["dependency-injector>=4.49.1"]
elastic-apm = ["elastic-apm>=6.26.2"]
elasticsearch = ["elasticsearch>=9.5.0"]
elasticsearch-async = ["elasticsearch[async]>=9.5.0"]
fakeredis = ["fakeredis>=2.37.0"]
fastapi = ["fastapi[all]>=0.141.1"]
grpc = ["grpcio>=1.83.0", "grpcio-health-checking>=1.83.0", "protobuf>=7.35.1"]
jwt = ["pyjwt>=2.13.0"]
kafka = ["confluent-kafka>=2.15.0"]
keycloak = ["python-keycloak>=7.1.1", "cachetools>=7.1.7", "async-lru>=2.3.0"]
minio = ["boto3>=1.43.72", "cachetools>=7.1.7", "async-lru>=2.3.0"]
parsian-ipg = ["zeep>=4.3.3", "requests[socks]>=2.34.2"]
parsian-ipg-async = ["zeep[async]>=4.3.3", "httpx2[socks]>=2.10.0"]
mysql = ["pymysql>=1.2.0"]
mysql-async = ["asyncmy2>=0.2.21"]
postgres = ["psycopg[binary,pool]>=3.3.4"]
prometheus = ["prometheus-client>=0.26.0"]
redis = ["redis[hiredis]>=8.1.0"]
saman-ipg = ["httpx2[socks]>=2.10.0"]
scheduler = ["apscheduler>=3.11.3"]
scylladb = ["scylla-driver>=3.29.11", "lz4>=4.4.5", "cachetools>=7.1.7", "async-lru>=2.3.0"]
sentry = ["sentry-sdk>=2.68.0"]
sqlalchemy = ["sqlalchemy>=2.0.52"]
sqlalchemy-async = ["sqlalchemy[asyncio]>=2.0.52"]
starrocks = ["starrocks>=1.3.4", "pymysql>=1.2.0"]
starrocks-async = ["starrocks>=1.3.4", "aiomysql>=0.3.2", "asyncmy2>=0.2.21"]
temporalio = ["temporalio>=1.31.0"]
testcontainers = ["testcontainers[elasticsearch, minio, mysql, vault]>=4.15.0"]
vault = ["hvac[parser]>=2.4.0", "cachetools>=7.1.7"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[dependency-groups]
dev = [
    "add-trailing-comma>=4.0.0",
    "bandit>=1.9.4",
    "boto3-stubs>=1.43.72",
    "codespell>=2.4.3",
    "pre-commit-hooks>=6.0.0",
    "pre-commit>=4.6.2",
    "ruff>=0.16.3",
    "ty>=0.0.72",
    "types-cachetools>=7.0.0.20260713",
    "types-grpcio>=1.83.0.20260730",
    "types-protobuf>=7.34.1.20260816",
    "types-pymysql>=1.2.0.20260807",
    "types-regex>=2026.7.19.20260720",
    "types-requests>=2.33.0.20260712",
    "validate-pyproject>=0.25",
]

docs = [
    "mkdocs-autorefs>=1.4.4",
    "mkdocs-material>=9.7.7",
    "mkdocs>=1.6.1",
    "mkdocstrings-python>=2.0.5",
    "mkdocstrings>=1.0.6",
    "pymdown-extensions>=11.0.1",
]


[project.urls]
Homepage = "https://syntaxarc.github.io/ArchiPy/"
Documentation = "https://archipy.readthedocs.io/"
"Bug Tracker" = "https://github.com/SyntaxArc/ArchiPy/issues"
"Source Code" = "https://github.com/SyntaxArc/ArchiPy"
"Contributing" = "https://github.com/SyntaxArc/ArchiPy/blob/master/CONTRIBUTING.md"
"Code of Conduct" = "https://github.com/SyntaxArc/ArchiPy/blob/master/CODE_OF_CONDUCT.md"


[tool.ruff]
# Enable automatic fixes for supported rules
fix = true

lint.select = [
    "A", # flake8-builtins
    "ANN", # flake8-annotations
    "ARG", # flake8-unused-arguments
    "ASYNC", # flake8-async
    "B", # flake8-bugbear
    "BLE", # flake8-blind-except
    "C4", # flake8-comprehensions
    "C901", # complex-structure
    "D", # pydocstyle
    "E", # pycodestyle errors
    "EM", # flake8-errmsg
    "ERA", # eradicate
    "F", # pyflakes
    "FAST", # FastAPI
    "FURB", # refurb
    "G", # flake8-logging-format
    "I", # isort
    "ICN", # flake8-import-conventions
    "LOG", # flake8-logging
    "PERF", # Perflint
    "PIE", # flake8-pie
    "PL", # Pylint (includes PLC, PLE, PLR, PLW)
    "PTH", # flake8-use-pathlib
    "PYI", # flake8-pyi
    "RUF", # Ruff-specific rules
    "S", # flake8-bandit
    "SIM", # flake8-simplify
    "SLOT", # flake8-slots
    "T10", # flake8-debugger
    "T20", # flake8-print
    "TC", # flake8-type-checking
    "TID", # flake8-tidy-imports
    "TRY", # tryceratops
    "UP", # pyupgrade
    "W", # pycodestyle warnings
]

# Explicitly ignore specific rules
lint.ignore = [
    "BLE001", # Do not catch blind exception: `Exception`
    "D100", # Missing docstring in public module
    "D104", # Missing docstring in public package
    "E501", # Line too long (handled by Ruff formatter)
    "PERF203", # try-except in loop (sometimes necessary for robust error handling)
    "PLR0913", # Too many arguments in function (e.g., FastAPI Swagger)
    "PLR0917", # Too many positional arguments (abstract methods match external APIs)
    "RUF003", # String contains ambiguous characters
    "SIM102", # Collapsible if (sometimes explicit is clearer)
    "TRY301", # Abstract raise into a function
]

# Define source directories
src = ["archipy"]

exclude = [
    "features/*",
    "scripts/*",
    ".agents/*",
]

# Set line length for Ruff formatter
line-length = 120

# Target Python version
target-version = "py314"

# Ruff format configuration
[tool.ruff.format]
# Use double quotes for strings
quote-style = "double"
# Use spaces for indentation
indent-style = "space"
# Line ending style
line-ending = "auto"
# Skip magic trailing comma
skip-magic-trailing-comma = false
# Docstring code format
docstring-code-format = true
# Docstring code line length
docstring-code-line-length = "dynamic"

# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"archipy/configs/config_template.py" = ["S104"]  # Allow binding to all interfaces for containerized deployments
"archipy/models/errors/keycloak_errors.py" = ["ANN401"]  # Allow Any type for additional_data
"archipy/helpers/interceptors/grpc/base/client_interceptor.py" = ["ANN401"]  # Allow Any type for gRPC message types
"archipy/helpers/utils/keycloak_utils.py" = ["FBT001", "FBT002", "PLC0415", "B008"]  # Allow lazy imports for optional dependencies
"archipy/helpers/utils/app_utils.py" = ["PLC0415", "ARG004"]  # Allow lazy imports and unused args in FastAPI handlers
"archipy/helpers/utils/jwt_utils.py" = ["S105", "PLC0415"]  # Allow lazy imports for optional dependencies
"archipy/helpers/utils/error_utils.py" = ["PLC0415"]  # Allow lazy imports for optional dependencies
"archipy/helpers/utils/file_utils.py" = ["S324"]  # nginx secure_link requires MD5 (compatibility)
"archipy/adapters/base/sqlalchemy/ports.py" = ["ANN401", "ARG002", "PLR0913"]  # Allow Any, unused args, many params in interfaces
"archipy/adapters/base/sqlalchemy/adapters.py" = ["ANN401", "ARG002"]  # Allow Any, unused args in interfaces
"archipy/adapters/elasticsearch/ports.py" = ["ANN401"]  # Allow Any type for **kwargs parameters
"archipy/adapters/keycloak/ports.py" = ["ANN401"]  # Allow Any type for **kwargs parameters
"archipy/adapters/keycloak/port_mixins/*" = ["ANN401"]  # Port mixins inherit ports.py ANN401 exemption
"archipy/adapters/redis/ports.py" = ["ANN401", "D102", "FBT001", "FBT002", "ARG002"]  # Interface methods may have unused params
"archipy/adapters/redis/port_mixins/*" = ["ANN401", "D102", "FBT001", "FBT002", "ARG002"]  # Port mixins inherit ports.py exemptions
"archipy/adapters/scylladb/ports.py" = ["ANN401"]  # Allow Any type for CQL parameters
"archipy/models/dtos/base_protobuf_dto.py" = ["ANN401"]
"archipy/models/entities/sqlalchemy/base_entities.py" = ["TC003"]  # datetime required at runtime for SQLAlchemy Mapped[]
"archipy/adapters/base/sqlalchemy/session_manager_registry.py" = ["PLC0415"]  # Circular import workaround
"archipy/adapters/temporal/base.py" = ["ARG002"]  # Interface methods may have unused params
"archipy/adapters/mysql/sqlalchemy/session_manager_registry.py" = ["PLC0415"]  # Circular import workaround
"archipy/adapters/postgres/sqlalchemy/session_manager_registry.py" = ["PLC0415"]  # Circular import workaround
"archipy/adapters/sqlite/sqlalchemy/session_manager_registry.py" = ["PLC0415"]  # Circular import workaround
"archipy/adapters/starrocks/sqlalchemy/session_manager_registry.py" = ["PLC0415"]  # Circular import workaround
"archipy/adapters/elasticsearch/adapters.py" = ["ANN401"]  # Allow Any type for **kwargs parameters
"archipy/adapters/redis/adapters.py" = ["ANN401", "FBT001", "FBT002", "PGH003", "PLC0415"]  # Lazy imports for optional dependencies
"archipy/adapters/redis/adapter_mixins/*" = ["ANN401", "FBT001", "FBT002", "PGH003", "PLC0415"]  # Adapter mixins inherit adapters.py exemptions
"archipy/adapters/redis/search.py" = ["ANN401"]  # redis-py search result objects use dynamic shapes
"archipy/adapters/redis/search_ports.py" = ["ANN401", "ARG002"]  # Port escape hatch kwargs
"archipy/adapters/redis/mocks.py" = ["ARG002", "ARG004", "ARG005", "ANN401", "ARG001", "PLR0913", "PLC0415"]  # Lazy imports and mock functions
"archipy/adapters/scylladb/adapters.py" = ["ANN401", "PLC0415"]  # Allow Any types and lazy imports
"archipy/adapters/keycloak/adapters.py" = ["PLC0415"]  # Lazy imports for optional dependencies
"archipy/adapters/keycloak/adapter_mixins/*" = ["PLC0415", "ANN401", "PLW0108"]  # Adapter mixins inherit adapters.py exemptions; lambdas wrap Keycloak calls
"archipy/adapters/temporal/*" = ["ANN401", "TRY300", "RUF006", "PLC0415"]  # Allow Any types for Temporal's dynamic system, else blocks, asyncio task handling, lazy imports
"archipy/adapters/scylladb/*" = ["S608"]  # False positives - using parameterized queries with %s placeholders
"archipy/helpers/decorators/*" = ["ANN401", "ARG001", "PLR0913", "PLC0415"]  # Allow Any, unused args, many params, lazy imports in decorators
"archipy/helpers/interceptors/grpc/trace/client_interceptor.py" = ["ANN401", "PLC0415"]  # Lazy imports
"archipy/helpers/interceptors/grpc/trace/server_interceptor.py" = ["PLC0415", "ANN401"]  # Lazy imports, context proxy
"archipy/helpers/utils/tracing_utils.py" = ["PLC0415", "ANN401"]  # Lazy optional deps; span/status union types
"archipy/helpers/interceptors/grpc/metric/server_interceptor.py" = ["PLC0415"]  # Lazy imports
"archipy/models/errors/base_error.py" = ["PLC0415"]  # Circular import workaround

# Configure McCabe complexity
[tool.ruff.lint.mccabe]
max-complexity = 10  # Maximum allowed McCabe complexity

# Configure Pylint rules
[tool.ruff.lint.pylint]
max-args = 5  # Maximum number of function arguments
max-branches = 25  # Maximum number of branches in a function (increased for complex auth/tracing logic)
max-returns = 16  # Maximum number of return statements in a function
max-statements = 75  # Maximum number of statements in a function (increased for decorators/interceptors)

# Configure isort (import sorting)
[tool.ruff.lint.isort]
combine-as-imports = true  # Combine `import` and `from ... import` statements
known-first-party = ["archipy"]  # Treat `archipy` as a first-party module
section-order = [
    "future", # `__future__` imports
    "standard-library", # Standard library imports
    "third-party", # Third-party imports
    "first-party", # First-party imports (e.g., `archipy`)
    "local-folder", # Local folder imports
]

[tool.ruff.lint.flake8-quotes]
inline-quotes = "double"  # Use double quotes for inline strings
multiline-quotes = "double"  # Use double quotes for multiline strings

[tool.ruff.lint.pydocstyle]
convention = "google"  # Use Google-style docstrings

# Configure flake8-comprehensions
[tool.ruff.lint.flake8-comprehensions]
allow-dict-calls-with-keyword-arguments = true  # Allow dict(a=1, b=2) style

# Configure flake8-errmsg
[tool.ruff.lint.flake8-errmsg]
max-string-length = 80  # Allow reasonable error messages

# Configure flake8-type-checking
[tool.ruff.lint.flake8-type-checking]
runtime-evaluated-base-classes = [
    "pydantic.BaseModel",
    "pydantic_settings.BaseSettings",
    "sqlalchemy.orm.DeclarativeBase",
]
runtime-evaluated-decorators = [
    "pydantic.validator",
    "pydantic.field_validator",
]
exempt-modules = ["typing", "typing_extensions"]

# Configure flake8-unused-arguments
[tool.ruff.lint.flake8-unused-arguments]
ignore-variadic-names = true  # Allow unused *args, **kwargs

[tool.ty.environment]
# Target Python version
python-version = "3.14"

[tool.ty.src]
# Include source directories
include = ["archipy"]
# Exclude directories from type checking
exclude = ["features", "scripts", ".agents"]

[tool.ty.rules]
# Enable strict type checking rules (similar to mypy strict mode)
# Error-level rules (default)
abstract-method-in-final-class = "error"
assert-type-unspellable-subtype = "error"
call-abstract-method = "error"
call-non-callable = "error"
call-top-callable = "error"
conflicting-declarations = "error"
conflicting-metaclass = "error"
cyclic-class-definition = "error"
cyclic-type-alias-definition = "error"
dataclass-field-order = "error"
duplicate-base = "error"
duplicate-kw-only = "error"
empty-body = "error"
escape-character-in-forward-annotation = "error"
final-on-non-method = "error"
final-without-value = "error"
implicit-concatenated-string-type-annotation = "error"
inconsistent-mro = "error"
index-out-of-bounds = "error"
instance-layout-conflict = "error"
invalid-argument-type = "error"
invalid-assignment = "error"
invalid-attribute-access = "error"
invalid-attribute-override = "error"
invalid-await = "error"
invalid-base = "error"
invalid-context-manager = "error"
invalid-dataclass = "error"
invalid-dataclass-override = "error"
invalid-declaration = "error"
invalid-enum-member-annotation = "error"
invalid-exception-caught = "error"
invalid-explicit-override = "error"
invalid-frozen-dataclass-subclass = "error"
invalid-generic-class = "error"
invalid-generic-enum = "error"
invalid-key = "error"
invalid-legacy-positional-parameter = "error"
invalid-legacy-type-variable = "error"
invalid-match-pattern = "error"
invalid-metaclass = "error"
invalid-method-override = "error"
invalid-named-tuple = "error"
invalid-named-tuple-override = "error"
invalid-newtype = "error"
invalid-overload = "error"
invalid-parameter-default = "error"
invalid-paramspec = "error"
invalid-protocol = "error"
invalid-raise = "error"
invalid-return-type = "error"
invalid-super-argument = "error"
invalid-syntax-in-forward-annotation = "error"
invalid-total-ordering = "error"
invalid-type-alias-type = "error"
invalid-type-arguments = "error"
invalid-type-checking-constant = "error"
invalid-type-form = "error"
invalid-type-guard-definition = "error"
invalid-type-variable-bound = "error"
invalid-type-variable-constraints = "error"
invalid-type-variable-default = "error"
invalid-typed-dict-field = "error"
invalid-typed-dict-header = "error"
invalid-typed-dict-statement = "error"
invalid-yield = "error"
isinstance-against-protocol = "error"
isinstance-against-typed-dict = "error"
mismatched-type-name = "error"
missing-argument = "error"
missing-typed-dict-key = "error"
no-matching-overload = "error"
non-callable-init-subclass = "error"
not-iterable = "error"
not-subscriptable = "error"
override-of-final-method = "error"
override-of-final-variable = "error"
parameter-already-assigned = "error"
positional-only-parameter-as-kwarg = "error"
raw-string-type-annotation = "error"
static-assert-error = "error"
subclass-of-final-class = "error"
subclass-of-dataclass-with-order = "error"
super-call-in-named-tuple-method = "error"
too-many-positional-arguments = "error"
type-assertion-failure = "error"
unavailable-implicit-super-arguments = "error"
unbound-type-variable = "error"
unknown-argument = "error"
unresolved-attribute = "error"
unresolved-import = "error"
unresolved-reference = "error"
unsupported-bool-conversion = "error"
unsupported-operator = "error"
zero-stepsize-in-slice = "error"
# Warning-level rules (default) - set to error for strict checking
ambiguous-protocol-member = "error"
deprecated = "error"
ignore-comment-unknown-rule = "error"
ineffective-final = "error"
invalid-ignore-comment = "error"
possibly-missing-attribute = "error"
possibly-missing-implicit-call = "error"
possibly-missing-import = "error"
possibly-missing-submodule = "error"
pydantic-discarded-extra-argument = "error"
redundant-cast = "error"
redundant-final-classvar = "error"
shadowed-type-variable = "error"
undefined-reveal = "error"
unresolved-global = "error"
unsupported-base = "error"
unsupported-dynamic-base = "error"
unused-awaitable = "error"
useless-overload-body = "error"
# Ignore-level rules (default) - set to error for strict checking
blanket-ignore-comment = "error"
division-by-zero = "error"
experimental-syntax = "error"
possibly-unresolved-reference = "error"
unused-ignore-comment = "error"
unused-type-ignore-comment = "error"

[tool.config]
pyproject_root_var = "pyproject"

[tool.codespell]
ignore-words-list = "exat,convertor"
skip = ".git,__pycache__,build,dist"

[tool.bandit]
# Bandit configuration for security scanning
# https://bandit.readthedocs.io/en/latest/config.html

# Target directories to scan
targets = ["archipy"]

# Exclude directories from scanning
exclude_dirs = ["features", "docs", "scripts"]

# Skip specific test IDs
# B101: assert_used - Allow assert statements in tests
# B301: pickle - Allow pickle usage (needed for some serialization)
# B403: import_pickle - Allow pickle imports
skips = ["B101", "B301", "B403"]

[tool.behave]

# Output formatting
show_snippets = false
show_source = false
show_timings = true

# Logging and capture
capture = true
capture_stdout = true
capture_stderr = true
capture_log = true

# Test execution
stop = false
dry_run = false
verbose = false