python-project-structure

Use a src layout with your package containing subdirectories like services, models, and api, plus a top-level tests directory and pyproject.toml. Keep the structure flat and add nesting only for genuine sub-domains.

Define __all__ in each module's __init__.py listing exactly which names are public. Import the public classes and functions there so consumers can import directly from the package root.

Both approaches work; colocated tests make coverage gaps visible, while a parallel tests directory cleanly separates production and test code. Pick one convention and apply it consistently across the project.

Use absolute imports like 'from myproject.services import UserService' for clarity and reliability. Relative imports can break when modules are moved or reorganized during refactoring.

Split when a file handles multiple unrelated responsibilities, grows beyond roughly 300-500 lines, or contains classes that change for different reasons. Each file should focus on a single concept.

Deep nesting is rarely appropriate; prefer flat structures since deep hierarchies make imports verbose and navigation difficult. Add sub-packages only when a genuine sub-domain requires isolation.