How would you structure a mid-sized Python project's directory layout for maintainability?
Project layout: src layout, tests, config separation, and clear package boundaries
A maintainable layout separates source code, tests, configuration, and documentation. The src layout (src/mypkg/) prevents accidental imports from the working directory and forces installation for testing. Tests live in a separate tests/ directory, ideally mirroring the package structure. Configuration is in pyproject.toml, with environment-specific config in environment variables or a config module. Documentation goes in docs/, and scripts in scripts/ or bin/. The goal is that a new developer can find things quickly and that imports behave the same in development and production.
- 1
src layout: src/mypkg/ keeps the package isolated and avoids path issues.
- 2
tests/ directory with unit, integration, and e2e subfolders as needed.
- 3
pyproject.toml for build system, dependencies, and tool config.
- 4
README, LICENSE, and docs/ for documentation.
- 5
Separate configuration from code: use environment variables or a config module, not hardcoded values.
- 6
Common mistake: putting tests inside the package, which ships tests to users.
- 7
Common mistake: flat layout with modules in the root, which causes import shadowing and path confusion.
- 8
Version note: src layout is recommended by PyPA and most modern tools. It is not version-specific.
Scenario Questions
0-2 years experience
- 1Where should tests live in a Python project?
- 2What is the src layout and why use it?
2-5 years experience
- 1You have a flat project with all modules in the root and imports are inconsistent. How do you restructure it?
- 2You need to separate development and production configuration. How do you organize it?
5-8 years experience
- 1You are starting a new project that will grow to dozens of modules. How do you lay it out for maintainability?
- 2You have a monorepo with multiple services. How do you structure shared code and per-service code?
8+ years experience
- 1Design a project layout for a library that also ships a CLI and a web service, with shared core code and separate entry points.
- 2Explain how to enforce import boundaries and prevent circular dependencies through directory structure and tooling.
Follow-up Questions
- Why is the src layout preferred over a flat layout?
- How do you handle environment-specific configuration in a Python project?