Book cover

Skip to content
  1. Introduction
  2. Objects and Classes
  3. Finding Duplicate Files
  4. Matching Patterns
  5. Parsing Text
  6. Running Tests
  7. An Interpreter
  8. Functions and Closures
  9. Protocols
  10. A File Archiver
  11. An HTML Validator
  12. A Template Expander
  13. A Code Linter
  14. Page Layout
  15. Performance Profiling
  16. Object Persistence
  17. Binary Data
  18. A Database
  19. A Build Manager
  20. A Package Manager
  21. Transferring Files
  22. Serving Web Pages
  23. A File Viewer
  24. Undo and Redo
  25. A Virtual Machine
  26. A Debugger
  27. Conclusion
  1. Bibliography
  2. Bonus Material
  3. Syllabus
  4. License
  5. Code of Conduct
  6. Contributing
  7. Glossary
  8. Colophon
  9. Index

download examples

GitHub repository

Appendix F: Contributing

Contributions are very welcome; please contact us by email or by filing an issue on this site. All contributors must abide by our Code of Conduct.

Section F.1: Editing Content

  1. Clone the GitHub repository at https://github.com/gvwilson/sdxpy.

  2. Create a new Python virtual environment.

  3. pip install -r lib/mccole/requirements.txt.

  4. pip install -r ./requirements.txt.

  5. make will show a list of available commands.

  6. make build to regenerate HTML from Markdown.

    • The generated HTML can be found in ./docs.
    • You must have draw.io installed and on your path to regenerate diagrams.

  7. make serve to regenerate HTML and preview it locally.

    • The preview appears at http://localhost:4000/.
    • Ark will regenerate the HTML as the Markdown files are edited and saved.

  8. To change a code example and its output:

    1. cd ./src/chapter.
    2. Edit the Python file(s) you wish to change.
    3. Run make in the chapter directory to rebuild the corresponding output files.

Please see CONTRIBUTING.md in the root directory of our GitHub repository for a complete description of our formatting rules.

Section F.2: Making Decisions

This project uses Martha’s Rules for consensus decision making:

  1. Before each meeting, anyone who wishes may sponsor a proposal by filing an issue in the GitHub repository tagged “comm-proposal”. People must file proposals at least 24 hours before a meeting in order for them to be considered at that meeting, and they must include:

    • a one-line summary (the subject line of the issue)
    • the full text of the proposal
    • any required background information
    • pros and cons
    • possible alternatives

  2. A quorum is established in a meeting if half or more of voting members are present.

  3. Once a person has sponsored a proposal, they are responsible for it. The group may not discuss or vote on the issue unless the sponsor or their delegate is present. The sponsor is also responsible for presenting the item to the group.

  4. After the sponsor presents the proposal, a “sense” vote is cast for the proposal before any discussion:

    • Who likes the proposal?
    • Who can live with the proposal?
    • Who is uncomfortable with the proposal?

  5. If everyone likes or can live with the proposal, it passes immediately.

  6. If most of the group is uncomfortable with the proposal, it is postponed for further rework by the sponsor.

  7. Otherwise, members who are uncomfortable can briefly state their objections. A timer is then set for a brief discussion moderated by the facilitator. After 10 minutes or when no one has anything further to add (whichever comes first), the facilitator calls for a yes-or-no vote on the question: “Should we implement this decision over the stated objections?” If a majority votes “yes”, the proposal is implemented. Otherwise, the proposal is returned to the sponsor for further work.

Section F.3: FAQ

Why is this book free to read online?

Because only a tiny minority of technical books make enough money to pay back the time required to create them, and because I would rather be able to fix errata than have people pirating out-of-date PDFs.

Why are the royalties going to charity?

The Red Door Family Shelter and places like it have always been short of money and resources, and the COVID-19 pandemic only made matters worse. They do more good on the average Tuesday than most of us do in a year (or a lifetime); I’m glad to be able to help however I can.

What sort of feedback would be useful?

Everything is welcome, but what would help most is:

  1. Fixes for mistakes in the code, the descriptions, or the formatting. All of the examples run and all of the tests pass, but that doesn’t guarantee they’re correct.
  2. Reports of continuity errors, e.g., places where a concept is used before it is explained.
  3. Suggestions for new diagrams, or for ways to improve existing ones.
  4. New or clearer summary points for each chapter’s syllabus.
  5. More or better exercises. “This is too hard” or “this is unclear” helps as well.

Why don’t the examples connect with each other?

It was tempting, but attempts to do this in the past have not gone well. First, it makes maintenance much more difficult because a change in an early chapter may have knock-on effects on several subsequent chapters. Second, it constrains what is taught and in what order: if the examples are independent of each other, instructors can pick and choose the pieces that are most relevant to their audience and goals.

How did you settle on these particular topics?

I started with a list of tools programmers use that can be implemented in the small (like version control systems and debuggers). I added a few things that programmers rely on (like page layout and object persistence), then went back and filled in gaps, which is why there are chapters on functions and closures, protocols, and binary data.

Will there be a sequel?

If enough people want to write chapters I would be happy to organize and edit a second volume. Some things I’d particularly like to see are:

  • An object-relational mapper to show people how tools like SQLAlchemy work.
  • A discrete event simulator to show people how tools like SimPy work.
  • An issue-tracking system, mostly to show how workflow management and authentication work.
  • Another build system that uses publish/subscribe instead of the top-down approach of Chapter 19.
  • A fuzz tester that uses some of the ideas from [Zeller2023].
  • A package installer to complement the package manager of Chapter 20.
  • A file compression tool like zip.
  • A database that uses B-trees instead of a log for storage.

Why did you build your own production pipeline?

I’ve written or edited books with GitBook, Quarto, Jupyter Book, and other tools like them, and found them more frustrating than helpful. For example, the code samples in this book often show one or two methods from a class rather than the whole class; there is no straightforward way to achieve that with tools built on computational notebooks. That said, I’m sure the authors of those systems would find this book’s tooling just as frustrating as I find theirs.