{"id":26179695,"url":"https://github.com/davecom/computersciencefromscratch","last_synced_at":"2025-10-05T15:24:03.055Z","repository":{"id":272099290,"uuid":"342140017","full_name":"davecom/ComputerScienceFromScratch","owner":"davecom","description":"Source for the book Computer Science from Scratch","archived":false,"fork":false,"pushed_at":"2025-03-15T06:02:28.000Z","size":7831,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T10:50:30.195Z","etag":null,"topics":["basic","book","brainfuck","chip-8","computer-art","computer-science","dithering","emulator","interpreter","knn","knn-classification","knn-regression","macpaint","nes","nostarch","nostarchpress","python","run-length-encoding"],"latest_commit_sha":null,"homepage":"https://nostarch.com/computer-science-from-scratch","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davecom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-25T06:02:13.000Z","updated_at":"2025-03-15T06:02:32.000Z","dependencies_parsed_at":"2025-01-12T05:35:51.018Z","dependency_job_id":null,"html_url":"https://github.com/davecom/ComputerScienceFromScratch","commit_stats":null,"previous_names":["davecom/funcomputerscienceprojectsinpython"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davecom%2FComputerScienceFromScratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davecom%2FComputerScienceFromScratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davecom%2FComputerScienceFromScratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davecom%2FComputerScienceFromScratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davecom","download_url":"https://codeload.github.com/davecom/ComputerScienceFromScratch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975305,"owners_count":21192197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["basic","book","brainfuck","chip-8","computer-art","computer-science","dithering","emulator","interpreter","knn","knn-classification","knn-regression","macpaint","nes","nostarch","nostarchpress","python","run-length-encoding"],"created_at":"2025-03-11T21:52:50.799Z","updated_at":"2025-10-05T15:24:03.036Z","avatar_url":"https://github.com/davecom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Computer Science from Scratch\n\nThis repository contains all of the source code for the book *[Computer Science from Scratch: Building Interpreters, Art, Emulators and ML in Python](https://nostarch.com/computer-science-from-scratch)* by [David Kopec](https://davekopec.com) and published by No Starch Press. The book, intended for intermediate to advanced Python programmers, features 7 projects of varying complexity from the realm of interpreters, emulators, computer art, and simple machine learning. In the table below is a description of the 7 projects and further down in this README there are directions for running (and testing) each of them. The projects are compatible with Python 3.12 and above.\n\n| Project       | Chapter | Section                       | Description                                                                                                                                                              |\n|---------------|---------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [Brainfuck](#brainfuck-chapter-1)     | 1       | Interpreters                  | An interpreter for the one of the simplest possible programming languages, Brainfuck.                                                                                    |\n| [NanoBASIC](#nanobasic-chapter-2)     | 2       | Interpreters                  | An interpreter for Nano BASIC, a dialect of Tiny BASIC—a programming language that was used during the personal computer revolution.                                     |\n| [RetroDither](#retrodither-chapter-3)   | 3       | Computer Art                  | A program that converts modern photos for display on a classic 1980s Mac by performing 1-bit (black \u0026 white) Atkinson dithering and converting them to MacPaint format.  |\n| [Impressionist](#impressionist-chapter-4) | 4       | Computer Art                  | Impressionist uses a simple stochastic hill climbing algorithm to create abstract art from photographs that (sometimes) looks like the work of an impressionist painter. |\n| [Chip8](#chip8-chapter-5)         | 5       | Emulators                     | An implementation of the CHIP-8 virtual machine that can play all of the 1970s games that were released for CHIP-8.                                                      |\n| [NESEmulator](#nesemulator-chapter-6)   | 6       | Emulators                     | The simplest possible NES emulator with support for playing real games but lacking sound, performance, compatibility with most mappers, and several other features.      |\n| [KNN](#knn-chapters-7--8)           | 7 \u0026 8   | Super Simple Machine Learning | You draw a digit and the program can interpret your drawing (KNN classification) and/or complete it (KNN regression).                                                    |\n\n## Get the Book\n\n- [Get the print or eBook from the publisher, No Starch Press](https://nostarch.com/computer-science-from-scratch)\n- [Get the print book from Amazon](https://amzn.to/4p7zrJ2)\n- [Get the Kindle edition from Amazon](https://amzn.to/4p59oSH)\n\n## Running and Testing Each Project\n\nThe following directions assume you are in the root directory of the repository in a terminal and that your Python command is `python` (on some systems it is `python3`). The code is tested against Python 3.12 and 3.13. It will not work with earlier versions. \n\n**Please note that each project is run as a module from the main repository using the `-m` option.**\n\n### Brainfuck (Chapter 1)\n\nA simple [Brainfuck](https://en.wikipedia.org/wiki/Brainfuck) interpreter.\n\n#### Requirements\n\nNo External Dependencies\n\n#### Running\n\n`python -m Brainfuck \u003cyour_file_name\u003e`\n\nFor example:\n\n`python -m Brainfuck Brainfuck/Examples/beer.bf`\n\n#### Testing\n\n`python -m tests.test_brainfuck`\n\n### NanoBASIC (Chapter 2)\n\nAn interpreter for a very simple dialect of BASIC based on [Tiny BASIC](https://en.wikipedia.org/wiki/Tiny_BASIC).\n\n#### Requirements\n\nNo External Dependencies\n\n#### Running\n\n`python -m NanoBASIC \u003cyour_file_name\u003e`\n\nFor example:\n\n`python -m NanoBASIC NanoBASIC/Examples/fib.bas`\n\n#### Testing\n\n`python -m tests.test_nanobasic`\n\n### RetroDither (Chapter 3)\n\n\u003cimg src=\"figures/figure3_2.png\" alt=\"RetroDither MacPaint Beach Scene\" height=\"200\"\u003e\n\nDithers images into 1 bit black \u0026 white and exports them to MacPaint format.\n\n#### Requirements\n\n- Pillow\n\n#### Running\n\n`python -m RetroDither \u003cinput_file_name\u003e \u003coutput_file_name\u003e`\n\nFor example:\n\n`python -m RetroDither swing.jpeg swing.mac`\n\nAdditional options:\n\n`-g` output a .gif format version as well\n\n### Impressionist (Chapter 4)\n\n\u003cimg src=\"figures/figure4_7.png\" alt=\"Impressionist NYC Skyline\" height=\"200\"\u003e\n\nComputationally draws abstract approximations of images using vector shapes.\n\n#### Requirements\n\n- Pillow\n\n#### Running\n\n`python -m Impressionist \u003cinput_file_name\u003e \u003coutput_file_name\u003e`\n\nFor example:\n\n`python -m Impressionist swing.jpeg swing.png`\n\nAdditional options:\n\n`-h, --help`            shows help\n\n`-t TRIALS, --trials TRIALS`\n                        The number of trials to run (default 10000).\n\n`-m {random,average,common}, --method {random,average,common}`\n                        The method for determining shape colors (default average).\n\n`-s {ellipse,triangle,quadrilateral,line}, --shape {ellipse,triangle,quadrilateral,line}`\n                        The shape type to use (default ellipse). \n\n`-l LENGTH, --length LENGTH`\n                        The length (height) of the final image in pixels (default 256). \n\n`-v, --vector`          Create vector output. A SVG file will also be output.\n\n`-a ANIMATE, --animate ANIMATE` If a number greater than 0 is provided, will create an animated GIF with the number of milliseconds per frame\n                        provided.\n\n### Chip8 (Chapter 5)\n\n\u003cimg src=\"figures/figure5_4.png\" alt=\"Chip8 PacMan\" height=\"200\"\u003e\n\nA Chip8 virtual machine.\n\n#### Requirements\n\n- Pygame\n- NumPy\n\n#### Running\n\n`python -m Chip8 \u003cyour_file_name\u003e`\n\nFor example:\n\n`python -m Chip8 Chip8/Games/tetris.chip`\n\n#### Testing\n\n`python -m tests.test_chip8`\n\n### NESEmulator (Chapter 6)\n\n\u003cimg src=\"figures/figure6_8.png\" alt=\"NES Emulator Brix\" height=\"200\"\u003e\n\nA simple [NES](https://en.wikipedia.org/wiki/Nintendo_Entertainment_System) emulator that can play some basic public domain games.\n\n#### Requirements\n\n- Pygame\n- NumPy\n\n#### Running\n\n`python -m NESEmulator \u003cyour_file_name\u003e`\n\nFor example:\n\n`python -m NESEmulator NESEmulator/Games/LanMaster.nes`\n\n\"a\" is Select, \"s\" is Start, \"arrow keys\" are the D-pad, \"z\" is B, and \"x\" is A.\n\n#### Testing\n\n`python -m tests.test_nesemulator`\n\n### KNN (Chapters 7 \u0026 8)\n\n\u003cimg src=\"figures/figure8_3.png\" alt=\"KNN Digit Recognizer\" height=\"200\"\u003e\n\nA handwritten digit recognizer using the K-nearest neighbors algorithm.\n\n#### Requirements\n\n- Pygame\n- NumPy\n\n#### Running\n\n`python -m KNN`\n\nThen use the key commands \"c\" to classify, \"p\" to predict, and \"e\" to erase.\n\n#### Testing\n\n`python -m tests.test_knn`\n\n## Type Hints\nThe code in this repository uses the latest type hinting features in Python 3.12 and above. If you are using an older version of Python, you may be able to run the code by removing some of the type hints, but no support is offered for that endeavor. All the type hints in the source code were checked using [Pyright](https://github.com/microsoft/pyright).\n\n## Authorship and License\n\nThe code in this repository is Copyright 2024 David Kopec and released under the terms of the Apache License 2.0. That means you can reuse the code, but you must give credit to David Kopec. Please read the license for details and other requirements. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavecom%2Fcomputersciencefromscratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavecom%2Fcomputersciencefromscratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavecom%2Fcomputersciencefromscratch/lists"}