How do you organize a Python project for maintainability?

Good structure makes Python projects navigable and maintainable as they grow.

src layout places your package under /src/yourpackage/. This prevents accidentally importing from the working directory instead of the installed package. Tests stay outside src/.

Standard structure: /src/yourpackage/ (main code), /tests/ (test files), /docs/ (documentation), pyproject.toml (configuration, dependencies, build settings), README.md.

Module organization groups related code. For a web app: /src/app/routes/, /src/app/services/, /src/app/models/. Each module has an __init__.py exposing its public API. Import from the module, not from internal files.

pyproject.toml is the modern standard for project configuration. It contains project metadata, dependencies, and tool configurations (pytest, ruff, black) in one place. Replaces the old setup.py approach.

__init__.py files define what a package exports. They can be empty (just marking a directory as a package) or define __all__ and import key objects for convenient access.

Type hints (function signatures, variable annotations) document expected types and enable IDE support and mypy checking. They're especially valuable in larger codebases.

Configuration in environment variables, loaded at startup. Separate config modules for different environments (development, testing, production).

Keep the root clean. Business logic lives in src/. The root has only configuration, documentation, and entry points.