- Courses
- 💻Programming Languages
- 🐍Python
- Intermediate Python & Best Practices
- Guided Exercise: Build a Python Package
On this page
Guided Exercise: Build a Python Package
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
Overview
This guided exercise walks you through creating a fully functional, installable Python package using modern packaging standards.
You will:
- Design a clean project structure
- Write package code using the
src/layout - Configure
pyproject.toml - Build wheel and source distributions
- Install the package locally
- Prepare it for PyPI publishing
This mirrors real‑world workflows used in professional Python development.
Step 1 — Create the Project Structure
Use the modern, recommended src/ layout:
awesomecalc/
pyproject.toml
README.md
LICENSE
src/
awesomecalc/
__init__.py
operations.py
tests/
test_operations.py
What each part means
pyproject.toml— package metadata and build configurationsrc/awesomecalc/— actual package codetests/— isolated test suiteREADME.md— documentation shown on PyPILICENSE— required for open‑source distribution
Step 2 — Write the Package Code
Inside src/awesomecalc/operations.py:
def add(a: float, b: float) -> float:
return a + b
def subtract(a: float, b: float) -> float:
return a - b
Inside src/awesomecalc/__init__.py:
from .operations import add, subtract
This exposes a clean public API:
from awesomecalc import add
Step 3 — Write the pyproject.toml File
Create a minimal but complete configuration:
[project]
name = "awesomecalc"
version = "0.1.0"
description = "A simple example calculator package"
authors = [{ name = "Enrico" }]
readme = "README.md"
requires-python = ">=3.10"
dependencies = []
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
Why this matters
pyproject.tomlis now the single source of truth- No
setup.pyis needed - Setuptools handles the build backend
Step 4 — Add a Test Suite
Inside tests/test_operations.py:
from awesomecalc import add, subtract
def test_add():
assert add(2, 3) == 5
def test_subtract():
assert subtract(5, 2) == 3
Run tests:
pytest
A package should always be tested before distribution.
Step 5 — Build the Package
Install the build tool:
python -m pip install build
Build distributions:
python -m build
This generates:
dist/awesomecalc‑0.1.0-py3-none-any.whldist/awesomecalc‑0.1.0.tar.gz
These are the files used for installation and distribution.
Step 6 — Install the Package Locally
Test the wheel:
pip install dist/awesomecalc-0.1.0-py3-none-any.whl
Verify:
>>> from awesomecalc import add
>>> add(10, 20)
30
This confirms the package installs and works correctly.
Step 7 — Editable Install for Development
During development, use:
pip install -e .
This allows live code changes without reinstalling.
Step 8 — Prepare for PyPI Publishing
Install Twine:
pip install twine
Upload:
twine upload dist/*
After publishing, anyone can install your package:
pip install awesomecalc
Step 9 — Add Documentation and Metadata
A professional package includes:
README.md— overview, usage examplesLICENSE— legal clarityCHANGELOG.md— version historypyproject.toml— metadata and configuration
These files improve discoverability and trust.
Step 10 — Optional Enhancements
You can extend the package with:
- Additional math operations
- Submodules (
geometry,algebra, etc.) - Type hints and static analysis
- Continuous integration for automated testing
- Automated versioning and release workflows
Each enhancement builds on the same packaging foundation.
Summary
In this guided exercise, you built a complete, modern Python package using:
- The
src/layout - A clean public API
- A fully configured
pyproject.toml - Wheel and source distribution builds
- Local installation and testing
- PyPI‑ready metadata
This workflow reflects the standards used in professional Python development and prepares you for distributing real‑world packages.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Packaging & Distribution
Next
Standard Library Deep Dive
-
Overview
-
Step 1 — Create the Project Structure
- What each part means
-
Step 2 — Write the Package Code
-
Step 3 — Write the
pyproject.tomlFile- Why this matters
-
Step 4 — Add a Test Suite
-
Step 5 — Build the Package
-
Step 6 — Install the Package Locally
-
Step 7 — Editable Install for Development
-
Step 8 — Prepare for PyPI Publishing
-
Step 9 — Add Documentation and Metadata
-
Step 10 — Optional Enhancements
-
Summary
