In this lesson, you will learn how to structure your Python project using the src-layout to ensure your code is organized, testable, and ready for professional distribution.
As projects grow beyond a single script, keeping your production code separate from your configuration and testing files becomes essential. Mixing these files often leads to import errors and accidental inclusion of test code when you share your package. The industry-standard approach is the src (source) layout.
The src-Layout Structure
In a src-layout, all your functional code resides inside a directory named src. This prevents your development tools from accidentally importing code from your project root, ensuring that your tests run against the installed version of your package rather than just the files in your folder.
Here is what a professional project structure looks like:
my_project/
├── pyproject.toml # Configuration for distribution
├── src/ # The heart of your project
│ └── my_package/ # Your actual code
│ ├── __init__.py
│ └── logic.py
├── tests/ # Test suites
│ └── test_logic.py
└── README.md
Why this matters
By placing your package inside src/, Python will not be able to import your code unless it is explicitly installed or the src directory is added to your path. This forces you to follow professional practices, such as running your unit tests against an installed version of your library. It mirrors how your users will interact with your code once you distribute it via standard tools.
When you organize your project this way, you decouple your production logic from the auxiliary files (like build scripts, documentation, and tests). This isolation makes it much easier to package your code, as tools like pip or other build systems will look specifically at the src folder to identify what constitutes your actual library.
Key Takeaway: Adopting the src layout isolates your source code from configuration and test files, preventing import ambiguity and ensuring your project is structured for seamless professional distribution.