Python Use a src/ Layout for a Package

This guide explains use a src/ layout for a package through a focused Python example. You will learn the behavior to expect, why it matters in a real program, and how to recognize the common mistakes before applying it in your own project.

What You Will Learn

The src/ layout stores importable package code under a dedicated src directory instead of the repository root. It helps tests detect accidental imports from the working tree.

When and Why to Use It

The following example focuses on a practical use of Use a src/ Layout for a Package.

Step-by-Step Example

from pathlib import PurePosixPath

package_module = PurePosixPath("src/shop/pricing.py")
test_module = PurePosixPath("tests/test_pricing.py")
print(package_module)
print(test_module)

Understanding the Example

The two paths illustrate the separation of package code and tests. Correct packaging configuration is needed for imports and editable installs.

Expected Output

src/shop/pricing.py
tests/test_pricing.py

Important Behavior and Edge Cases

Creating a src folder alone does not make code importable from every context; configure the build tool and install the package in a venv.

Try It Yourself

Design a minimal src/shop package and a tests directory.

Run environment-management commands in your terminal, not in a Python source file. Use the executable associated with the selected project interpreter and verify the environment before installing dependencies.

Common Beginner Mistakes

• Creating a src folder alone does not make code importable from every context; configure the build tool and install the package in a venv.
• Running installation commands against a different Python interpreter than the one used for the project.
• Skipping the practice step and assuming the example covers every input. Test at least one normal case and one edge case relevant to this topic.

Key Takeaways

• The src/ layout stores importable package code under a dedicated src directory instead of the repository root.
• The two paths illustrate the separation of package code and tests.
• Apply the technique deliberately, checking its documented input requirements and failure behavior before integrating it into a larger project.