Python prototype

A simple sample of a Python package prototype. Part of the educational repositories, used as reference for TDD, packaging and code quality best practices.

Full documentation on readthedocs.

Two reading paths through the development history:

  • step by step: built from scratch with the legacy stack (unittest + setup.py), uses see-git-steps to walk through the commits.

  • refactoring: migration to the modern stack (pytest + pyproject.toml, plus uv, ruff, pyright, pre-commit).

A visual overview of the daily code quality cycle and the TDD sequence is on the code quality page.

Installation

The package is self-contained. You can download it from GitHub:

$ git clone https://github.com/bilardi/python-prototype

Or install it with pip:

$ pip3 install simple-sample

Usage

Read tests/test_my_class.py to see how to use the package, or read the docstrings from the REPL:

$ python3
>>> from simple_sample.my_class import MyClass
>>> help(MyClass)
>>> quit()

For more, see readthedocs / howtouse.

Development

See readthedocs / howtomake for environment setup, testing, pre-commit hooks, conventional commits, versioning and packaging.

See readthedocs / refactoring for how this project moved from unittest / setup.py to pytest / pyproject.toml.

Project structure

simple_sample/  # the package source
    __init__.py  # package metadata and version
    my_class.py  # example class: inherits from interface and abstract
    my_class_abstract.py  # abstract class
    my_class_interface.py  # interface class
tests/  # pytest test files
docs/source/  # sphinx documentation (published on readthedocs)
pyproject.toml  # deps, ruff, pyright, bumpversion, git-cliff
Makefile  # targets for test, build, release
.pre-commit-config.yaml  # ruff + pytest hooks
CHANGELOG.md  # generated by git-cliff

Change Log

See CHANGELOG.md for details. This file is updated by a Makefile target:

$ make changelog

See the Versioning management section in howtomake for how to bump the version and release: the same page also shows how to install the dependencies first.

Blog post

License

This package is released under the MIT license. See LICENSE for details.