# SDXPy: a design course that rebuilds the tools programmers use

> Software Design by Example is a book and a set of runnable Python lessons that build small versions of familiar tools, from a duplicate file finder to an interpreter, a database and a debugger, so that the design decisions an experienced engineer makes are visible rather than assumed. The repository is the course itself, with a Makefile, a syllabus appendix and a custom licence.

**gvwilson/sdxpy** — Software Design by Example: a tool-based introduction with Python

- Repository: https://github.com/gvwilson/sdxpy
- Website: https://third-bit.com/sdxpy/
- Stars: 565 · Forks: 91
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/gvwilson-sdxpy

## Twenty-eight chapters, each one a small tool

The premise is stated in the README's opening: the best way to learn design in any field is to study examples, and the most approachable examples are ones that readers are already familiar with. So the lessons build small versions of tools that programmers use every day.

The chapter list is the syllabus. It runs from Introduction and Objects and Classes through Finding Duplicate Files, Matching Patterns, Parsing Text, Running Tests, An Interpreter, Functions and Closures and Protocols, then into longer builds: A File Archiver, An HTML Validator, A Template Expander, A Code Linter, Page Layout, Performance Profiling, Object Persistence, Binary Data, A Database, A Build Manager, A Package Manager, Transferring Files, Serving Web Pages, A File Viewer, Undo and Redo, A Virtual Machine and A Debugger, closing with a Conclusion.

Each chapter also has a slide deck, listed separately with a slides.html link per entry, so the same material is available in a form you can project in a classroom or read on its own.

The audience is stated precisely too. The lessons assume readers can write small programs and want to write larger ones, or are looking for material to use in software design classes that they teach. That is a narrow but honest scope, and it is worth noticing that the topics chosen are ones a working web developer would not otherwise meet: an interpreter, a virtual machine, a debugger, a database, a binary format.

Underneath the book there are 24 further appendices, and these are where the book is unusually ambitious. They cover Concurrency, MapReduce, a Publish-Subscribe Message Queue, a Work-Stealing Scheduler, Distributed Tracing, Conflict-Free Replicated Data Types, OAuth, Distributed Locks, BitTorrent, an Eventually Consistent Key-Value Store, the Saga Pattern, and then the wire-level chapters on TCP, DNS and NTP. A reader who works through the main chapters and skips the appendices will still have covered the material most courses call advanced.

## Each chapter teaches one mechanism, not a tool

The per-chapter descriptions in the README are short, and they are the clearest statement of the method. Reading them is the best way to decide whether this course fits you.

Objects and Classes is presented as solving two problems: what is a natural way to represent real-world things in code, and how can code be organized so that it is easier to understand, test and extend, with the chapter implementing a very simple object system using simpler data structures.

Finding Duplicate Files attacks the naive approach of comparing each file to all the others as unworkably slow for large sets, and replaces it with a short label that depends only on the file's contents, so only files with the same label need comparing. The README notes that this idea is the basis of many real-world applications, including the cryptographic systems used for secure online communication, which is an unusually direct link between a file utility and hash functions.

Matching Patterns implements the filename matching used in the Unix shell, in order to show how more complicated tools like regular expressions work. Parsing Text then builds a parser for that same pattern language, on the argument that a complete parser for a language like Python can be very complex, but the key ideas can be shown on a small one.

Running Tests builds the machinery every language has for collecting tests, running them and reporting results, and the README calls out the single most important idea in the book: that programs are just another kind of data. An Interpreter then takes that further, showing how a program in memory is a data structure whose elements trigger operations, and arguing that the quality of a program's design can be judged by asking how extensible it is.

That is a consistent method. Every chapter takes a mechanism that professionals take for granted and rebuilds it in a page or two of readable Python, then says what the mechanism buys you.

## The repository is the book, and the Makefile is the build

There is no separate website project and no publishing pipeline outside this tree. The top level is a directory per chapter, plus the appendices, and the tooling is a small Makefile and a pyproject.toml.

The Python side is minimal. The project metadata names the distribution sdxpy at version 0.1.0, requires Python 3.12 or later, and declares two dependencies, mccole at 2.13.1 or later and ruff at 0.15.15 or later. The tool configuration sets a brand of sdxpy, a title of Software Design by Example, a repository URL, and a skip list of file patterns and directories that the documentation builder should leave alone, among them *.py, *.html, *.js, *.json, the docs directory, solutions and uv.lock.

The Makefile is the interface to the whole thing, and it is worth reading because it shows what the maintainer expects a reader to run:

```make
## check: check HTML
.PHONY: check
check:
	@mccole check --src . --dst docs --files '*.jpg' '*.png' '*.svg'
```

That target runs the documentation checker over the sources and only complains about image files, which is a sensible trade for a book whose prose is full of inline code. The build target is the site target:

```make
## site: build documentation
site:
	@mccole build --math --src . --dst docs
	@touch docs/.nojekyll
```

Building the documentation writes into a docs directory and then touches .nojekyll, which tells GitHub Pages not to run Jekyll over the output, so the raw HTML and assets are served as they are. The serve target is a plain static server over that same directory:

```make
## serve: serve documentation
serve:
	python -m http.server -d docs
```

So reading the book locally is a two step thing: build the site, then serve it. The clean target removes the dist directory, the __pycache__ and .ruff_cache directories and any editor backup files, while the lint target chains the HTML check and the type checks together, and the fix and format targets hand the lesson code to ruff.

## The lesson code is checked and formatted by ruff

The Makefile treats the example programs as first class code, and that is the detail that tells you how the project is maintained. The fix target runs ruff check with fixes across the lesson files, and the format target runs ruff format on the same set. The lint target runs the HTML check and the type checks in sequence.

So the snippets in the book are not fragments typed into prose. They live in the tree, they are linted, they are formatted, and they are the same code the reader is expected to run.

There is a pattern rule for regenerating the expected output of the examples, which is a good sign about how the examples are kept honest:

```make
## examples: regenerate example output
examples: ${EXAMPLES_OUT}

%.txt: %.py
	python $< ${SEED} > $@
```

Each example script is run with a seed, and its output is captured into a text file next to it. The seed argument is what makes the runs reproducible, so a chapter that shows a program finding duplicate files or generating random data shows the same output every time, and the expected output is diffable in review. A typo in an example therefore shows up as a failing comparison rather than as a silently wrong illustration in a chapter.

The top-level tree also includes a solutions directory and an unused directory, alongside a build directory, an examples.mk file, a typos.toml for spell checking, and an .gitignore. The solutions directory is the interesting one for a course: it suggests the exercises have published answers, which is a choice about how the material can be used in a classroom where students should not simply read the answer.

## What this is not: a reference, a framework course, or a project

The limits are worth naming before anyone adopts it.

First, it is a course, not a library. There is nothing to import from sdxpy in your own work. The distribution version is 0.1.0 and the two dependencies, mccole and ruff, exist to build the book and check the examples, not to power anything a consumer would call. If you are looking for a component, this is the wrong repository.

Second, it is a specific course, not a curriculum you can dip into. The chapters build on each other. The parser chapter builds on the pattern matching chapter, the interpreter chapter builds on the test runner chapter, and the chapters after that assume the ones before. Reading chapter 20 without chapters 3 to 8 is possible but wasteful, since the exercise is usually in the mechanism rather than in the code.

Third, it is Python only, and deliberately so. The project description says a tool-based introduction with Python, and the topics are lesson, python and software-design. That makes it cheap to run and easy to teach, but it also means the systems ideas are shown in one language's idiom, and a reader who plans to work in a statically typed language will have to do the translation themselves.

Fourth, and most practically, the material is graded for the audience the author had in mind. The README says the lessons assume readers can write small programs and want to write larger ones. A reader who has never written anything beyond a script will find the interpreter, virtual machine and debugger chapters steep, and the appendices steeper still.

There is also the ordinary limit of a book. The repository has no issue tracker entries describing a live community of people working through the exercises, and it publishes no GitHub releases, so there is no version history to consult when a chapter changes.

## A comparison: an interactive course platform versus a book you read in sequence

The obvious alternative to a repository of prose and code is an interactive learning platform, where the exercises run in a browser and check your answer as you type. The difference in approach is not cosmetic.

An interactive platform can give immediate feedback, because it holds a reference implementation and compares. A book cannot, so this project uses a different mechanism: the seed. The example rule in the Makefile runs each example with a fixed seed and diffs the output, which moves the correctness check from the reader's head into the repository. The author's answer is a text file, and the exercise is to make your program produce it.

The second difference is scope. A platform teaches a language, one construct at a time, with a bounded vocabulary of exercises. This book attempts the opposite: it takes whole systems, a duplicate file finder, a shell glob matcher, a test runner, an interpreter, a database, a virtual machine, a debugger, and shows how each one is put together, and then goes further into distributed systems with CRDTs, a saga pattern, BitTorrent and eventually consistent storage. That is a breadth no interactive platform attempts, because it is a book-length commitment rather than a course-length one.

A third difference is the absence of a teacher. The appendices include a Syllabus and the repository includes a Code of Conduct, a Contributing guide, a Bibliography and a Glossary, which is the material set a course needs when it is used in a classroom by someone other than its author. Whether a given lecturer adopts it or writes their own is the practical question, and the syllabus appendix is where you would look to find out how the author sequenced a term.

## Maintenance, licence and what the appendix set implies

On maintenance, the facts are narrow. The repository is not archived, the last push was on 2026-08-29, and it publishes no GitHub releases. There is no version to pin and no changelog of releases, so the unit of currency is the commit history, and a reader who wants to know whether a chapter changed recently has to look at the log rather than at a tag list.

The licence is the point that deserves the most attention from anyone who plans to reuse the material. The platform lists the licence as Other, a custom one it cannot categorise, and the file on disk is LICENSE.md, with a License chapter among the appendices. So the terms are set by that document rather than by a standard licence, and a lecturer, a company or a book publisher who wants to adapt the lessons, or translate them, needs to read LICENSE.md and the license chapter before assuming the permissions they have in mind. No legal advice is implied here; the point is that this is not MIT, not CC, and not something you can assume.

The rest of the appendix set tells you what the maintainer considers part of the discipline. A Glossary defines the vocabulary the book uses. A Bibliography points at the reading behind the lessons. An Observers appendix covers how to watch a running system. A Generating Documentation appendix explains the docgen tooling. A Bonus Material appendix collects extras. And the topics of the top level directories mirror the appendices, so distributed tracing, work stealing, message queues and lock files all have code in the tree, not just prose.

The two remaining top level entries are practical. The examples.mk file feeds the example rules, and the solutions directory holds worked answers, so a student can compare, and a teacher can remove.

## Conclusion

Adopt SDXPy if you teach software design, want a structured path through systems programming that most self-taught developers never get, or want worked examples you can read in an afternoon each, since the lessons are short, runnable and Python only. Do not adopt it as a reference manual, because it is a sequence with a pedagogical order rather than a catalogue you can query, and do not expect it to cover a specific framework or language ecosystem. Verify first that Python 3.12 or later is what you run, since pyproject.toml sets requires-python to >=3.12, that you are willing to read the LICENSE.md file yourself, because the licence is custom and the platform cannot classify it, and that the mccole and ruff dependencies are acceptable in your environment, because the build and check targets depend on both.

## FAQ

### What is SDXPy, Software Design by Example?

It is a tool-based introduction to software design built around 27 Python lessons that each build a small version of a tool programmers use every day, from a duplicate file finder through a pattern matcher, a test runner, an interpreter, a database and a debugger, with 24 further appendices covering concurrency, distributed systems and TCP, DNS and NTP.

### How do I build and read the Software Design by Example book?

The project metadata requires Python 3.12 or later and depends on mccole and ruff. The Makefile has a site target that runs mccole build --math --src . --dst docs and touches docs/.nojekyll, and a serve target that runs python -m http.server -d docs, so you build the site and then serve the docs directory locally.

### Do I need to install SDXPy to use the lessons?

There is nothing to import from it in your own project. The distribution is sdxpy at version 0.1.0 and its two dependencies, mccole and ruff, exist to build the documentation and lint the example code, so the practical setup is a checkout with the dependencies available and the Makefile targets for the site and the checks.

### How are the example programs in the lessons kept correct?

The Makefile has a rule that runs each example script with a seed and captures its output into a matching text file, python $< ${SEED} > $@, and the examples target regenerates those expected outputs. That makes the output of every example reproducible and diffable, so a mistake in a chapter's code shows up as a changed text file rather than as a silently wrong illustration.

### What licence does Software Design by Example use?

The platform lists the licence as Other, a custom one it cannot classify, with the text in LICENSE.md and a License chapter among the appendices. Anyone adapting or redistributing the lessons, including a lecturer or a translator, needs to read that file rather than assume a standard open source licence.

## Sources

- [gvwilson/sdxpy on GitHub](https://github.com/gvwilson/sdxpy)
- [Issues](https://github.com/gvwilson/sdxpy/issues)
- [Project website](https://third-bit.com/sdxpy/)
- [README](https://github.com/gvwilson/sdxpy/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gvwilson-sdxpy