Ship a small Python project

I can lay out a small Python project so that someone else can clone it, install it, run it and run its tests from the README alone.

Domain: Python Programming
Level: advanced
Status: draft · v0.1.0
Also called: Project layout, pyproject.toml, Packaging Python, Python project structure
License: CC BY-SA 4.0

Learn first

Test Python code with pytest intermediate
Read and write files and structured data intermediate

Learn it

Scope

The difference between code that works on your machine and a project someone else can pick up. This is what a take-home submission is actually judged on once the solution is correct.

In scope: directory layout, pyproject.toml, declaring dependencies, an entry point, and a README that answers the reviewer’s questions before they ask. Out of scope: publishing to PyPI, building wheels for distribution, and continuous integration.

The layout, and why

project/
  README.md
  pyproject.toml
  src/thing/__init__.py
  src/thing/core.py
  tests/test_core.py

Code in one place, tests beside it but separate, metadata at the root. Putting the package under src/ means the tests import it the way a user would — from the installed package, not from whatever happens to be in the current directory — so “works when I run it here” and “works when installed” stop being different states.

`pyproject.toml` is the project’s identity card

One file states the name, the version, the Python it needs and what it depends on. A reviewer runs pip install -e . and has your environment. Pin what you must and leave the rest open: a dependency list that is too tight fails on their machine, one that is too loose fails next month.

If the project is a script rather than a package, a requirements file and a clear command are enough. Match the ceremony to the size.

The README is part of the deliverable

Four things, in this order: what it does, how to run it, how to test it, and what you chose not to do. That last section is the one reviewers remember — it shows you knew the trade-offs rather than missed them, and it pre-empts the obvious question about the thing you left out.

Assume the reader has your repository, a terminal and no context. Every step they have to guess is a mark against work that may well be correct.

Common misconceptions

“The code is the deliverable.” The deliverable is something another person can run. A perfect solution nobody can start scores badly.
“A requirements file records my environment.” Only if you wrote it deliberately. pip freeze dumps everything, including what you installed and abandoned.
“Tests go in the same file.” They go in tests/, so the package can be installed without them and the suite can be run as a suite.
“A README is documentation you write at the end.” It is the interface. Writing it first tends to improve the design.

Notes for teachers

The exercise that teaches this is a swap: two learners exchange repositories and each must run the other’s project and its tests using only the README, without speaking. Every question they need to ask is a defect, and the list of questions is the feedback.

Resources

Resource	Kind	Cost	Provider
Packaging Python projects	reading	free	Python Packaging Authority
Writing your pyproject.toml	reference	free	Python Packaging Authority
The Python Tutorial: virtual environments and packages	reading	free	Python Software Foundation

Courses that include it

draft

Python for a Coding Assessment

A refresher path through the Python graph for someone who has written Python before and has an assessment coming: run and read, rebuild the core, then work the way an assessment expects.

Prove it

Evidence of mastery

Hands a reviewer a repository they can set up and run without asking a question.
Separates the code, the tests and the entry point, and explains why the layout is what it is.
Declares dependencies so that a fresh environment reproduces the one it was developed in.
Writes a README that states what the project does, how to run it, how to test it, and what was deliberately left out.

Assessments that measure it

No assessment yet.

Credentials that include it

No credential yet.

What learners show

Nothing to show yet. The publisher last published on 2026-09-20, and no aggregate for this outcome has reached the 50 learners a number needs. Open Degree does not track learners. About learner evidence.

What comes next

No outcome builds on this yet. Ask for the next concept.