python.instructions.md in streamlit/streamlit runs 736 words across 7 headings.
Streamlit — A faster way to build and share data apps.
PythonCovers
6 of the 20 section tags
In the order a file is read inHeadings
7 headings, in the order the file writes them
01Python Development Guide
02Key Principles
03Docstrings
04Package Structure
05Dependencies
06Typing
07Relevant `make` commands
Commands
6 commands this file writes down
Extracted from the file, verbatimuv.lock
make python-types
make
make python-lint
make python-tests
make python-format
The file
.github/instructions/python.instructions.md
82 lines1---
2applyTo: "**/*.py"
3---
4
5<!-- Generated from lib/AGENTS.md. Edit that file instead, then run: uv run python scripts/generate_agent_rules.py -->
6
7# Python Development Guide
8
9- Supported Python versions: 3.10 - 3.14
10- Docstrings: Numpy style
11- Linter: Ruff 0.x (config in root `pyproject.toml`)
12- Formatter: Ruff 0.x (config in root `pyproject.toml`)
13- Type Checker: mypy 2.x + ty 0.x (config in root `pyproject.toml`)
14- Testing: pytest 9.x (config in root `pyproject.toml`)
15
16## Key Principles
17
18- PEP 8 Compliance: Adhere to PEP 8 guidelines for code style, with Ruff as the primary linter and formatter.
19- Elegance and Readability: Strive for elegant and Pythonic code that is easy to understand and maintain.
20- Zen of Python: Keep the Zen of Python in mind when making design decisions.
21- Avoid inheritance (prefer composition).
22- Avoid methods (prefer non-class functions, or static).
23- Name functions and variables in such a way that you don't need comments to explain the code.
24- Python folder and filenames should all be snake_cased regardless of what they contain.
25- Prefer importing entire modules instead of single functions: `from streamlit import mymodule` over `from streamlit.mymodule import internal_function`
26- Prefer keyword arguments, use positional values only for required values that frame the API. Enhancing arguments should be keyword-only.
27- Capitalize comments, use proper grammar and punctuation, and no cursing.
28- Inside a module, anything that is declared at the root level MUST be prefixed with a _ if it's only used inside that module (anything private).
29- Prioritize new features in Python 3.10+.
30
31## Docstrings
32
33- Use Numpydoc style.
34- Docstrings are meant for users of a function, not developers who may edit the internals of that function in the future. If you want to talk to future developers, use comments.
35- All modules that we expect users to interact with must have top-level docstrings. If a user is not meant to interact with a module, docstrings are optional.
36
37## Package Structure
38
39- `streamlit/`: The main Streamlit library package.
40- `streamlit/elements`: Backend code of elements and widgets.
41- `streamlit/runtime`: App runtime and execution logic.
42- `streamlit/web`: Web server and CLI implementation
43- `streamlit/commands`: `st` commands that don't add UI elements.
44- `streamlit/components`: Backend-implementation of custom components.
45- `streamlit/connections`: `st.connection` backends (SQL, Snowflake, and callers-rights variants).
46- `streamlit/hello`: `streamlit hello` app implementation.
47- `streamlit/navigation`: Multi-page app implementation.
48- `streamlit/proto`: Generated protobuf definitions for client-server communication.
49- `streamlit/testing`: AppTest v1 implementation.
50- `streamlit/vendor`: Vendored dependencies.
51- `streamlit/watcher`: File-watcher implementations.
52- `streamlit/__init__.py`: Defines all commands in the `st` namespace.
53- `pyproject.toml`: Package configuration of the Streamlit library.
54- `tests`: Python unit tests (pytest).
55
56## Dependencies
57
58- Add a dependency only when it provides meaningful value that cannot easily be replicated with an in-house implementation. Each dependency increases the risk of supply-chain attacks, breakage from incompatible new versions, and conflicts with other dependencies in users' environments.
59- Runtime dependencies of the published Streamlit library in `lib/pyproject.toml` must include a lower bound and an upper bound pinned to the next unreleased major version, for example `package>=1.2.3,<2`. These ranges are the published package's contract with users and feed the min-version CI job, so they minimize potential breaks from new major versions. Exemptions are allowed, but must include a clear comment explaining why the dependency should not be capped.
60- This bounded-range rule does NOT apply to the dev/CI-only `[dependency-groups]` in the root `pyproject.toml`. Those use bare package names because `uv.lock` owns the exact versions; add a constraint only when functionally required (an exact `==` pin for a deliberately held-back tool, or an upper cap `<` for a known-broken version, mirrored by an `ignore` entry in `.github/dependabot.yml`; a single-release `!=` exclusion needs no `ignore` entry), and do not add lower-bound floors.
61
62## Typing
63
64- Add typing annotations to every new function, method or class member.
65- Use `typing_extensions` for back-porting newer typing features.
66- Use future annotations via `from __future__ import annotations`.
67- `make python-types` runs both `ty` and `mypy`. `ty` resolves first-party
68 `streamlit.*` imports (config in root `pyproject.toml`); prefer real
69 narrowing/annotation fixes over suppressions. When a checker-specific
70 suppression is needed, use a rule-specific comment such as
71 `# ty: ignore[redundant-cast]` (and keep `# type: ignore[...]` for mypy when
72 both apply).
73
74## Relevant `make` commands
75
76Run from the repo root:
77
78- `make python-lint`: Lint and check formatting of Python files (ruff).
79- `make python-tests`: Run all Python unit tests (pytest).
80- `make python-types`: Run the Python type checker (mypy & ty).
81- `make python-format`: Format Python files (ruff).
82
The rest of the repository
streamlit/streamlit ships 20 other instruction files
e2e_playwright/AGENTS.md.cursor/rules/protobuf.mdc.cursor/rules/python.mdc.claude/agents/AGENTS.md.claude/skills/AGENTS.md.cursor/rules/agents.mdc.cursor/rules/e2e_playwright.mdc.cursor/rules/embedded_skills.mdc.cursor/rules/overview.mdc.cursor/rules/python_lib.mdc.cursor/rules/python_tests.mdc.cursor/rules/scripts.mdc.cursor/rules/skills.mdc.cursor/rules/specs.mdc.cursor/rules/typescript.mdc.cursor/rules/workflows.mdc.github/copilot-instructions.md.github/instructions/agents.instructions.md.github/instructions/e2e_playwright.instructions.md.github/instructions/embedded_skills.instructions.md
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs streamlit/streamlit can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.