Add opt-in django-aqueduct settings module

[blarghmatey]

What are the relevant tickets?

N/A

Description (What does it do?)

Adds an opt-in, non-disruptive django-aqueduct-based
settings model alongside the classic one, built on django-aqueduct 0.9.0
(codegen v2). Nothing about the existing deployment changes unless
DJANGO_SETTINGS_MODULE is explicitly repointed — the classic
mitxpro/settings.py remains the default everywhere.

• mitxpro/aqueduct_settings.py — a typed pydantic AqueductSettings(BaseSettings)
  model mirroring mitxpro/settings.py. Codegen v2 discovers settings by
  static AST analysis (the settings module is never imported and no secrets
  are resolved), emitting field declarations into machine-owned
  # >>> aqueduct:generated:* regions. Hand-written refinements (validators,
  derived settings, secret/required overrides) live in the
  # >>> aqueduct:preserved:* region and survive regeneration.
• mitxpro/settings_aqueduct.py — production shim: init Sentry, then
  configure_django_settings(AqueductSettings).
• mitxpro/settings_aqueduct_dev.py — new local-dev shim constructing
  DevAqueductSettings (Vault KV v1, see below).
• docs/aqueduct.md — rewritten for the v2 regeneration workflow, the alias
  collapse, derivations, the now-shipped dev Vault story, and the intentional
  parity divergences.

The alias collapse. mitxpro systematically configures a Django setting from
a differently-named env var (SITE_BASE_URL from MITXPRO_BASE_URL,
EMAIL_HOST from MITXPRO_EMAIL_HOST, ENVIRONMENT from MITXPRO_ENVIRONMENT,
~30 total). The v1 model carried a dual set of fields — a raw MITXPRO_*
field plus a Django-facing placeholder — stitched by two hand-written copy
validators (_apply_env_name_aliases, _build_derived_aliases). v2 recovers
those relationships from the env-reader call sites and emits them as
validation_alias=AliasChoices('MITXPRO_BASE_URL') on a single field. The
placeholder fields and both copy validators are gone; the model file shrinks
from 1549 to 1078 lines.

Derivations. Redis fallback, DATABASES, CACHES, ADMINS, and the
FEATURE_* scan now use django_aqueduct.derivations instead of re-implemented
boilerplate. This fixes two previously-shipped divergences: database_config
omits sslmode for SQLite (which its driver rejects), and feature collection
(via mitol get_features) raises on non-true/false values where the old
hand-written scan silently dropped them — while also seeing Vault-sourced
FEATURE_* flags.

New dev / Vault subclass (KV v1). mitxpro's Vault mount secret-xpro runs
the KV v1 engine, which is why a Vault dev class was deferred originally.
django-aqueduct's VaultSettingsSource now supports kv_version=1, so
DevAqueductSettings ships here: it builds a Vault source from VAULT_* env
vars via django_aqueduct.sources.dev.vault_source_from_env, defaulting
VAULT_MOUNT to secret-xpro and VAULT_KV_VERSION to 1. With VAULT_ADDR
unset it runs on plain env/.env, so the dev shim is safe without a running
Vault.

Generation config. [tool.aqueduct] pins the source modules, output,
parity model/legacy, and parity_ignore. The EnvParser inspector is disabled
(include_envparser = false) so fields key off Django-facing names rather than
reintroducing the raw env-name dual set. aqueduct_settings.py is excluded from
ruff (see the ruff note below).

List/dict decoding (generated). The generator emits
Annotated[..., NoDecode] plus an _aqueduct_decode_list_fields
before-validator (in the aqueduct:generated:container_decoders region) for
every list/dict field, so a comma / JSON / Python-literal env value decodes
automatically — no hand-written _split_delimited needed for the generated
fields (CSRF_TRUSTED_ORIGINS, SHEETS_ADMIN_EMAILS,
EXTERNAL_COURSE_SYNC_EMAIL_RECIPIENTS; verified they still parse comma
strings). Two fields keep a small refinement, for reasons unrelated to
decoding: OAUTH2_PROVIDER_ALLOWED_REDIRECT_URI_SCHEMES is read only inside the
OAUTH2_PROVIDER dict in legacy (never a module-level setting), so static
discovery emits no field for it — an inline-read limitation, not the
get_list_of_str gap 0.9.0 fixed — and it keeps a dedicated one-field
before-validator; DIGITAL_CREDENTIALS_SUPPORTED_RUNS is name-redacted to
default=None, so its override only restores the legacy [] default.

AnyUrl promotion — left off. 0.9.0 makes the str→AnyUrl promotion
opt-in ([tool.aqueduct] enrich_url_types), denylists relative-URL Django
settings, only promotes when the field's own default validates as an absolute
URL, and pairs each promotion with a field_serializer so model_dump() still
emits str. It is left off here: mitxpro reads these values in-instance as
strings (urlparse(self.SITE_BASE_URL), first_url(...).strip(), redis
LOCATION nested in the CACHES/OAUTH2_PROVIDER dicts), and the top-level
serializer covers neither in-validator access nor nested-dict values — enabling
it was tested and raised 'AnyUrl' object has no attribute 'decode' at
instantiation. With the flag off the generated *_URL fields render as plain
str, so the ~22-field neutralization block earlier revisions carried is gone.
--enrich-usage found no closed-value-set/range comparison sites (no
Literal/Field(gt=…) promotions); --enrich-runtime is not used (it is the
one flag that imports the settings module).

Ruff exclude retained. 0.8.1 made the generator's output ruff format-
stable and dropped the blanket # ruff: noqa. Removing the
[tool.ruff] extend-exclude was tried, but ruff format still reflows two
generated constructs — the captured HUBSPOT_CONFIG dict-literal default
(embedded at its original source indentation) and an over-long
AliasChoices(...) line — which would reintroduce
generate_aqueduct_settings --check drift, so the exclude on
mitxpro/aqueduct_settings.py stays (the 0.8.1 documented fallback).

Dependency note: django-aqueduct[mitol,vault,derivations] is now pinned to
>=0.9.0 (published to PyPI), resolving from the release rather than a local
worktree override.

Screenshots (if appropriate):

N/A — no UI changes.

How can this be tested?

• uv lock resolves django-aqueduct to 0.9.0.
• manage.py generate_aqueduct_settings --check reports no drift.
• manage.py check_aqueduct_settings reports parity (15 annotated
  parity_ignore keys: raw env inputs the legacy module reads inline, and
  the S3-conditional AWS_S3_CUSTOM_DOMAIN. DATABASES/
  DEFAULT_DATABASE_CONFIG are no longer listed — 0.9.0 subset-compares
  dict settings, so Django's runtime-injected keys no longer diverge).
• manage.py check passes under both mitxpro.settings_aqueduct and
  mitxpro.settings_aqueduct_dev (dev shim with VAULT_ADDR unset), with
  the required env vars mitxpro already needs (MITXPRO_BASE_URL,
  SECRET_KEY, MAILGUN_SENDER_DOMAIN, MAILGUN_KEY,
  OPENEDX_API_CLIENT_ID, OPENEDX_API_CLIENT_SECRET,
  EXTERNAL_COURSE_SYNC_API_KEY) — confirmed locally.
• Confirm mitxpro/settings.py changes only add django_aqueduct to
  INSTALLED_APPS (for the management commands); no runtime behavior
  changes.
• Confirm the default DJANGO_SETTINGS_MODULE (web/worker/tests/Procfile/
  Kubernetes) is unaffected — nothing switches to an aqueduct shim
  automatically.
• Existing mitxpro/settings_test.py passes (7 passed, 1 skipped).

Additional Context

Both the validate-only production shim and the KV v1 dev Vault subclass now
ship together (the dev subclass was the deferred item in the original pass).
The rollout remains fully opt-in.

[blarghmatey]

django-aqueduct 0.6.0 is now published on PyPI, including the KV v1 fix mitxpro's Vault mount needs. Removed the [tool.uv.sources] local-path override in pyproject.toml and re-locked so django-aqueduct now resolves from PyPI instead of the local worktree — no longer blocked on that TODO. manage.py check --settings=mitxpro.settings_aqueduct still passes against the published package. The dev-settings Vault subclass remains deliberately out of scope for this PR.

[Copilot]

Pull request overview

Adds an opt-in django-aqueduct (codegen v2) settings model alongside the existing mitxpro.settings module, plus production/dev shims and documentation, without changing the default DJANGO_SETTINGS_MODULE.

Changes:

• Introduces AqueductSettings / DevAqueductSettings (generated + preserved regions) and two opt-in shims (settings_aqueduct*) to configure Django settings via django-aqueduct.
• Adds [tool.aqueduct] generation/parity configuration and excludes the generated settings file from Ruff formatting to prevent regen drift.
• Updates docs/README and pins django-aqueduct[mitol,vault,derivations]>=0.9.0 (plus lockfile updates).

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
uv.lock	Locks django-aqueduct and its transitive deps (e.g., hvac, pydantic-settings).
README.md	Adds a documentation link to the new aqueduct guide.
pyproject.toml	Adds the dependency pin plus [tool.ruff] exclude and [tool.aqueduct] config.
mitxpro/settings.py	Adds django_aqueduct to INSTALLED_APPS for management commands only.
mitxpro/settings_aqueduct.py	New opt-in production shim: init Sentry then configure_django_settings(AqueductSettings).
mitxpro/settings_aqueduct_dev.py	New opt-in dev shim using DevAqueductSettings (optional Vault layering).
mitxpro/aqueduct_settings.py	New generated+preserved pydantic settings model with derived/validator logic and Vault dev subclass.
docs/aqueduct.md	New documentation for regeneration workflow, parity, and Vault dev usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.