For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/python/file-structure.md.
Quick start

File structure

Place behavior in the smallest module that owns its callers and contract.

Module boundaries

Why

Importing a domain module should not initialize a client or execute a command.

Rules

  • MUST separate pure domain transformations, resource adapters, and application entrypoints. [review]
  • MUST avoid import-time I/O and mutable application globals. [review]
  • MUST use explicit imports and avoid wildcard re-export chains. [review]
  • MUST keep __init__.py focused on a deliberate public surface. [review]
  • MUST keep executable entrypoints thin and coordinate effects there. [review]
  • MUST place tests beside their capability or in a corresponding test directory. [review]
  • MUST use the consumer's established package and environment layout. [review]

[review]

Import tests expose initialization effects. Lint and typechecks cover configured imports; review establishes module ownership.

Enforcement

Import tests expose initialization effects. Lint and typechecks cover configured imports; review establishes module ownership.