pallets/flask
The library entrypoints are the `flask` package namespace (`src/flask/__init__.py` re-exports the public API), the `flask` console script wired to `flask.cli:main`, and `python -m flask` via `__main__.py`. Runtime is split across a sans-IO layer (`Scaffold` → `App` → `Blueprint` in `src/flask/sansio/`) that holds registries and setup logic with no IO, and the IO layer (`Flask`, `Blueprint`, `cli`, `helpers`, `templating`) that performs WSGI dispatch, file serving and server startup. There is no database or persistence layer; the only durable state Flask owns is the signed session cookie written by `SecureCookieSessionInterface`. External integrations are all Pallets-family libraries pinned in `pyproject.toml` dependencies, plus optional `asgiref` (async views) and `python-dotenv` (env files). Build is flit_core; test/lint/type/docs orchestration is tox driven by uv, executed in GitHub Actions.
- `src/flask/__init__.py` is the public API surface: 39 explicit `X as X` re-exports covering `Flask`, `Blueprint`, `Config`, the five context proxies, all 10 signals, and the `render_template`/`stream_template` family — nothing is exported implicitly.
- The console script is declared as `flask = "flask.cli:main"` under `[project.scripts]`, and `src/flask/__main__.py` is a three-line shim (`from .cli import main; main()`) so `python -m flask` and `flask` share one code path.
- The sans-IO boundary is documented in-tree: `src/flask/sansio/README.md` states the folder must do no IO, must not be on a likely IO path, and must not use the Flask globals — which is why `sansio/app.py` declares `default_config` and `response_class` as bare annotations and lets `Flask` in `app.py` supply them.
- Class hierarchy is `Scaffold` (shared route/handler registration, static folder, `find_package`) → `App` (config, url_map, blueprints dict, extensions dict, template filters/tests/globals) → `Flask` (WSGI, Click group, sessions, file serving); `Blueprint` follows the same sansio → IO split.
- All context state lives in one `AppContext` object holding `app`, `g`, `url_adapter`, `_request`, `_session`, `_flashes` and `_after_request_functions`, stored in the single `ContextVar` `_cv_app` declared in `globals.py`; there is no second request-level ContextVar.
- The five public proxies (`app_ctx`, `current_app`, `g`, `request`, `session`) are all `werkzeug.local.LocalProxy` instances over the same `_cv_app`, differing only by attribute name and unbound-error message (`_no_app_msg` vs `_no_req_msg`).
- The only persistence layer is the signed cookie: `SecureCookieSessionInterface` builds a `URLSafeTimedSerializer` with salt `"cookie-session"`, hmac key derivation, lazily-resolved SHA-1 digest, and the `TaggedJSONSerializer` payload serializer.
- Runtime dependencies are exactly six Pallets-ecosystem packages (blinker≥1.9.0, click≥8.1.3, itsdangerous≥2.2.0, jinja2≥3.1.2, markupsafe≥2.1.1, werkzeug≥3.1.0) with `async` (asgiref) and `dotenv` (python-dotenv) as optional extras.
- Build backend is `flit_core>=3.11,<4` with `[tool.flit.module] name = "flask"`, and the sdist explicitly bundles `docs/`, `examples/`, `tests/`, `CHANGES.rst` and `uv.lock` while excluding `docs/_build/`.
- Developer commands are tox environments: `tox run` (pytest per Python version), `-e style` (pre-commit all files), `-e typing` (mypy then pyright), `-e docs` (`sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml`), plus `tests-min` and `tests-dev` which pip-install pinned-minimum and git-main dependency sets respectively.
- CI is four GitHub Actions workflows: `tests.yaml` (12-way matrix incl. 3.15, free-threaded 3.14t, Windows, Mac, PyPy, min and dev deps, plus a separate mypy/pyright `typing` job), `pre-commit.yaml`, `publish.yaml` (tag-triggered `uv build` → draft GH release → PyPI trusted publishing), and `zizmor.yaml` for Actions security analysis.
- Docs are Sphinx `dirhtml` built by Read the Docs using an asdf-installed uv and the `docs` dependency group; 34 top-level doc pages exist including `lifecycle.rst`, `appcontext.rst`, `reqcontext.rst` and `web-security.rst`.
- Deployment shape for the library itself is a wheel/sdist on PyPI; the framework's own "deployment" surface for users is `run_simple` from Werkzeug, explicitly documented as development-only in `run_command`'s help text.