[claude-tmgbedu]

Summary

• Application(env=...) now emits a DeprecationWarning (stacklevel=2, so it points at the caller). The warning says the argument will be removed in 1.0 and to use APP_ENV or --env instead. Resolution order and behaviour are unchanged.
• The environment now comes only from outside the code: the APP_ENV variable, the CLI --env <name> / --env=<name> option, or pytest auto-detection (testing).
• Nothing in src/, the application/ starter, the installer stubs or the example bootstraps passed env=, so the framework itself never triggers the warning.
• Framework tests no longer pass the redundant env="testing". Pytest's filterwarnings turns this deprecation into an error, so the suite can't bring it back.
• example/config-app tests now select environments through APP_ENV.
• set_environment() is unchanged. It switches the environment at runtime and does not hard-code one in the bootstrap file.
• ADR 040 is added and indexed.

Tests

• New tests/core/test_application_env_deprecation.py checks that:
  • env= warns, and the warning points at the caller's file;
  • env= still selects the environment;
  • there is no warning by default;
  • APP_ENV, --env x and --env=x work without a warning and remove the --env tokens from argv.
• I wrote the warning tests first and saw them fail.
• uv run pytest --ignore=tests/masoniteorm/postgres --cov: 3300 passed, 10 skipped, coverage 91.50%.
• example/config-app: 12 passed.
• ruff check/format is clean. basedpyright reports 0 errors; the remaining warnings are older ones.

Docs follow-up: a separate docs-repo PR will update docs/configuration.md. It depends on this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QgHs6PRFJehnb1BbCNtLww

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[claude-tmgbedu]

Review + QA: PR #318 (deprecate Application(env=...))

Verdict: approve. No blocking issues, two non-blocking findings.

QA (own worktree at 6da18db)

• cd fastapi_startkit && uv run pytest --ignore=tests/masoniteorm/postgres --cov: 3300 passed, 10 skipped, 187 subtests, coverage 91.50% (threshold 80).
• example/config-app tests: 12 passed, also with -W error::DeprecationWarning. They need the gitignored .env; copy .env.example to .env first. Without it, 11 fail with "Unable to determine environment", which is not caused by this PR.
• Scratch app with -W default::DeprecationWarning:
  • Application(base_path=..., env="production") in the script warns at the script line.
  • The same call in a factory module (create_app) warns at the factory's line.
  • class MyApp(Application): pass called with env= warns at the caller.
• artisan --env=staging list and --env staging list: env is staging, --env tokens are removed from sys.argv, no warning. APP_ENV=production alone: no warning.
• Pytest: no warning without env=. The new tests cover APP_ENV, --env x and --env=x.

Review

• Warning fires once per construction, only when env is not None. Nothing in src/, the installer stubs or example/* passes env=. set_environment() is untouched.
• Environment.resolve_environment is untouched, so precedence is unchanged: pytest, then env=, then APP_ENV (which --env sets), then .env. Note that env= also outranks --env, not only APP_ENV. ADR 040 mentions only APP_ENV.
• Leaving set_environment() alone is right. It has no callers in src/, mutates a live app instead of putting a deployment environment in the bootstrap file, and ADR 040 says why.
• The filterwarnings entry is in the framework's own pyproject.toml only. It is scoped to this one message, so it neither affects downstream suites nor hides other warnings. Downstream suites that pass env="testing" get a normal warning.
• ADR 040 exists, the number is unused on main, and it is indexed in docs/adr/AGENTS.md. Other open PRs use 035-039, so there is no collision. No comments or docstrings were added to source or tests.

Findings (non-blocking)

1. The warning is invisible with Python's default filters for the usual layout. fastapi_startkit/src/fastapi_startkit/application.py:46-52. DeprecationWarning is shown by default only when attributed to __main__. Repro: bootstrap/factory.py with Application(..., env="production"), imported from a script, run with python main.py. It prints nothing; only -W default::DeprecationWarning or pytest shows it. Apps built on bootstrap/application.py, including under uvicorn --factory, will not see it. Consider FutureWarning or a documented filter, if the PM wants the warning seen. DeprecationWarning itself is acceptable and conventional.
2. Subclasses that override __init__ get the wrong location. application.py:51. With class MyApp2(Application): def __init__(self, *a, **kw): super().__init__(*a, **kw), the warning points at the super().__init__ line, not the user's MyApp2(env=...) call. This is a limit of fixed stacklevel. Subclasses without an __init__ override are fine.

Nits:

• example/config-app/tests/test_config_app.py rewords the existing comments instead of dropping them. This is harmless but conflicts with the no-comments rule.
• pyproject.toml stays at 0.67.0. A release bump is presumably handled separately.