| name | python |
| description | Python conventions for this user — underscore-prefix everything that is not public API, plus uv inline script metadata and typer for CLIs. Load before writing or editing any .py file. |
Python conventions
General
- Always use explicit typing. Use
import typing as t for succinct code.
Private names take a leading underscore
Anything not part of a module's public API is _-prefixed: functions, classes,
module-level helpers, constants that callers have no business reading. PEP 8's
rule, applied strictly — "nothing outside imports this" is not enough, the name
has to say so.
For a script, the public API is usually just main. Everything it calls is
private:
def _read_keys(path: pathlib.Path) -> list[str]: ...
def _render(source: pathlib.Path, dest: pathlib.Path) -> None: ...
def _fail(message: str) -> None: ...
def main() -> None:
...
Not:
def read_keys(path): ...
def render(source, dest): ...
For a library module, the public API is what the package intends callers to
use; helpers behind it are still _-prefixed.
Applies to classes (class _Tunnel:) too.
And constants:
_MYSQL_PORT = 3306
Do not rename existing public names in code you did not write as a
drive-by. Follow the rule for what you add; if the surrounding file predates it
and would benefit, say so and let the user decide.
Scripts: uv with inline dependencies
Standalone scripts declare their dependencies inline (PEP 723) and run under
uv — no requirements.txt, no venv to activate:
Invoke as uv run scripts/thing.py.
CLIs use typer
Not argparse, for anything new. Arguments and options are typed with
Annotated, and errors exit through typer rather than sys.exit:
def main(
env: Annotated[str, typer.Argument(help='environment name, e.g. "live"')],
source: Annotated[str, typer.Option("--from", help="template env")] = "dev",
force: Annotated[bool, typer.Option("--force")] = False,
) -> None:
...
if __name__ == "__main__":
typer.run(main)
def _fail(message: str) -> None:
typer.secho(message, fg=typer.colors.RED, err=True)
raise typer.Exit(1)