python-project-structure

To structure a Python project, you should enforce explicit interfaces and cohesive modules by placing one concept per file, favoring flat directory hierarchies with a top-level src/ layout, and defining public APIs using __all__.

To define a public API in a Python package, use the __all__ variable within your modules to expose a clean public surface, which explicitly declares accessible classes and functions while keeping internal implementation details private.

To set up a Python project layout, create a top-level src/ directory containing a package named after your project, a tests/ directory, and a pyproject.toml file, separating services, models, and APIs into focused modules under the src/ folder.

When organizing Python test files, you should choose either colocated tests or a parallel tests/ directory and apply the chosen convention consistently across the codebase to ensure the structure remains predictable and maintainable.

You should use a flat directory structure for Python modules to simplify imports and navigation, which reduces onboarding time and maintenance overhead by keeping hierarchies shallow and promoting focused, single-concept files.