AquilaConfig & Env — Aquilia Documentation
Comprehensive guide and documentation for AquilaConfig & Env in the Aquilia framework. View API reference, examples, and implementation patterns.
import from 'lucide-react' AquilaConfig aquilia.pyconfig — Python-native, zero-YAML environment configuration AquilaConfig is the base class for environment-specific configuration. Subclass it once per environment, override only what changes, and use Env to bind fields to OS environment variables or Secret to protect sensitive values. All of this lives directly in workspace.py. Why Python-native config , , , ].map(( ) => ( ))} AquilaConfig — layered inheritance Subclass AquilaConfig once per deployment environment. The env attribute is the identifier — AQ_ENV=prod selects the class whose env = "prod". Only override the nested sections that change between environments; everything else is inherited from the base class automatically. Built-in section types Each section type provides typed defaults, IDE hover docs, and a clean interface for overriding only what changes. Extend any of them inside your AquilaConfig subclass. Section Key fields Purpose ))} AquilaConfig.Server — full reference Every attribute maps directly to a uvicorn.Config parameter and is forwarded automatically. No glue code required — adding a new field here is all you need. AquilaConfig.Accelerator — Native C++ engines Controls the native C++ engine components. The framework uses a fail-soft approach: if the native extension is absent or disabled, it falls back to pure Python automatically. Values are propagated to os.environ so hot-reload worker subprocesses inherit the setting. Pre-existing environment variables (e.g. from CI) are never overwritten by workspace.py. Field Env Var Description engine AQUILIA_ENGINE The request engine — C++ router and RequestContext. Active on every HTTP request. Default: True. dataengine AQUILIA_DATAENGINE The data engine — C++ FieldPlan/TypeCode used by ORM query compiler and Contract hydration. Default: True. Configuration Priority (highest wins) CLI flag (aq run --no-engine) Process environment (AQUILIA_ENGINE=0 set before launch) workspace.py AquilaConfig.Accelerator settings Framework default (enabled) These settings control runtime loading only. The build-time CMake option AQUILIA_ENGINE_OPTIONAL is separate: ON permits a compiler-free source install, while release CI passes OFF so a wheel cannot silently omit an extension. No Accelerator fields or CLI flags changed in v1.4.0b5. See Native Extensions for build requirements, diagnostics, and Windows compatibility. AquilaConfig.VectorDB — vector stores New in 1.4.0b3. Declares the elips-backed vector stores a workspace opens at boot. Each alias maps to one on-disk directory and is what a vector model's Meta.store names. Disabled by default. elips is an optional extra, so a workspace that does not declare this block never loads the extension — ConfigLoader.get_vectordb_config() returns enabled = False and the subsystem returns early. Field Default Description mapping. Overrides the single-store shorthand above when given.'], ].map(([f, d, desc], i) => ( ))} Two constraints worth knowing before you deploy dimension and metric are database-global in elips: every model bound to a store must agree with them, and changing either against an existing directory invalidates the built index. elips is single-writer per directory. Running more than one worker against one store path makes every worker after the first fail to take the lock — a startup fault, not a degradation. Give each worker its own path, or set read_only = True for search-only workers. Env — live environment variable binding Env is a descriptor that reads from os.environ at attribute access time. Values already in the process environment (from Docker, Kubernetes, or CI/CD) always win over source-code defaults. The dotenv loader is triggered automatically on first access — you never call load_dotenv() manually. Auto-cast rules (no cast= specified) Raw string value Resolved Python value Type \'', ' ', 'dict (JSON)'], ['"hello"', '"hello"', 'str (fallback)'], ].map(([raw, out, t], i) => ( ))} Secret — redacted sensitive values Secret wraps any sensitive value — API keys, database passwords, signing keys. The underlying value never appears in repr(), str(), log output, or serialised config until you call .reveal() deliberately. The resolution order is: env var → literal value → default. — safe to log # >>> repr(BaseEnv.auth.secret_key) # "Secret(env='AQ_SECRET_KEY', *required*)" # Only .reveal() returns the actual value key = BaseEnv.auth.secret_key.reveal() # → "actual-key-value-from-env" # Properties is_required = BaseEnv.auth.secret_key.is_required # → True env_var_name = BaseEnv.auth.secret_key.env_name # → "AQ_SECRET_KEY"`} /> Never commit literal Secret values. Secret(value="...") is for local dev only. In staging and production always point to an env var: Secret(env="MY_KEY", required=True). Secret — Value vs. Env-Var Disambiguation v1.3.4 In v1.3.4, the Secret API was clarified to distinguish between literal values and environment variable names. Previously, a single positional argument was silently treated as an env-var name, leading to confusion. Now, ALL_CAPS identifiers without explicit kwargs emit a DeprecationWarning. You should explicitly use env=... or value=.... Old code Problem New code Secret("MY_DB_PASS") Silently looked up env-var MY_DB_PASS Secret(env="MY_DB_PASS") Secret("literal-value") Broke if no env-var named 'literal-value' exists Secret("literal-value") AquilaConfig.PasswordHasher Controls the password hashing algorithm used by the auth subsystem. Class-method shortcuts provide sensible defaults for each algorithm. Algorithm Factory method Notes ))} AquilaConfig.Signing — cryptographic signing Controls the aquilia.signing module that backs session cookies, CSRF tokens, one-time activation links, cache integrity checks, and signed cookies. Each subsystem uses an isolated namespace salt so cross-subsystem token reuse is cryptographically impossible. @section — custom config grouping The @section decorator marks any arbitrary nested class as a named config section included in the serialised to_dict() output. Use it for app-specific subsystems that don't map to a built-in section type. AquilaConfig.Dotenv — file loading policy Control exactly which .env files are loaded and in what order. Define a nested Dotenv class inside your AquilaConfig subclass. AquilaConfig.Apps — per-module namespaces Place module-specific settings inside a nested class named after the module. Access them via config.apps.. inside that module's services or controllers. Runtime API — to_dict, to_loader, get, for_env Testing patterns ))} )
Go to Homepage