A Python src-layout project with pyproject.toml, venv or uv and tests, as a zip.
Make a project skeleton
Choose what to build and a package tool (pip or uv); the folder tree, file notes and layer picture follow. Click a file to see its starter code, then download the zip and run it.
Build a
Package tool
Tests
Folder tree 8 files
src/hello_app/
tests/
src/hello_app/__main__.py
The entry point for python -m. It reads arguments with argparse, hands them to the rule function and prints the result. No rules live here.
Versions written in the files Python 3.10+ · pytest 8 · setuptools 68 or newer (pip) · hatchling (uv). Library files are not inside the zip. pip or uv downloads them on the first install.
The standard src layout
Path
What goes there
src/<package>/
The program code. The folder name is the name you import.
__init__.py
Lives in the package folder. Marks it as a package; re-export the public names here.
__main__.py
Also in the package folder. The file that runs first with python -m <package>.
tests/
Test code (pytest). It is not shipped with the package.
pyproject.toml
Project name, version, required Python, dependencies and build backend.
.venv/
A virtual environment for this project only. Create it locally and keep it out of git.
Keeping code under src/ means it can only be imported once installed, which cuts down on "works only on my machine" problems. Tests then run against the installed package.
Splitting into layers
Put the part that takes requests, the part that decides rules and the part that stores data in separate modules. In a web API, api.py calls service.py, which calls repository.py, never the other way round.
With that split you can move storage from memory to a database without touching the service, and pytest can check service rules without starting a server.
api.py reads the request and builds the response; it does no calculations.
service.py decides the rules and knows nothing about HTTP.
repository.py saves and loads. Describe its shape with typing.Protocol and you can swap memory and database versions.
Naming
The project name (name in pyproject) may contain -, as in hello-app, but the package folder must be importable, so it uses underscores: hello_app.
Modules, packages, functions and variables use lowercase with underscores (snake_case); classes use CapWords.
Never name a file after a standard library module, such as json.py, random.py or test.py. Your file gets imported first and strange errors follow.
Keep passwords and API keys out of the code; read them from environment variables (os.environ).
Four common design patterns and dependency injection
Python passes functions around like values, so many patterns need fewer classes than in Java. All of this code was run on Python 3.12.
Singleton · when there must be exactly one
__new__ remembers the first object it made and returns it every time after. a and b are the same object, so a change through b shows through a.
In Python a module is imported only once, so creating one object inside a module and importing it is the more common and simpler choice.
Look at the extension and return the matching parser. Keeping functions in a dict means a new format is one more line in the dict, and case is normalized in one spot.
Write each discount rule as a function and pass it to Checkout. Functions are values in Python, so no class per strategy is needed. A rule that needs settings, like coupon(3000), is a function that returns a function.
When an event such as a restock happens, every registered function is called in turn. A listener can be a lambda or an ordinary method such as list.append.
Dependency injection · receiving what you need through the constructor
Greeter does not build its user store; it receives one in the constructor. Real code passes MemoryUsers, a test passes FakeUsers, which only has find(). Duck typing makes it fit without inheritance.
Features such as Depends in FastAPI do the same job: they find the right object and pass it in.
Answer: 3. .venv/.venv/ holds packages installed on your own machine, and everyone recreates it. Put it in .gitignore.
Question 2
After installing the src-layout package hello_app, which command runs it properly?
Show the answer
Answer: 3. python -m hello_apppython -m package runs the installed package's __main__.py. Running a file by path breaks relative imports such as from . import. Run it inside your .venv.
Questions people ask
How do requirements.txt and pyproject.toml differ?
pyproject.toml is the standard file for the project name, version and dependencies. requirements.txt is a list for pip to install in one go, often with exact versions.
Do I really need a virtual environment?
It keeps each project's package versions from clashing. Create one with python -m venv .venv and keep .venv out of git.
Should I pick uv or pip?
pip ships with Python, so there is nothing extra to install. uv must be installed separately but handles environments, installs and a lock file in one fast tool.