fromscratch-pyos 0.3.0__py3-none-any.whl

fromscratch_pyos-0.3.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: fromscratch-pyos
+Version: 0.3.0
+Summary: A simulated operating system built in Python for learning OS concepts
+Project-URL: Homepage, https://github.com/robcox2910/py-os
+Project-URL: Repository, https://github.com/robcox2910/py-os
+Project-URL: Issues, https://github.com/robcox2910/py-os/issues
+Project-URL: Documentation, https://robcox2910.github.io/py-os/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: education,learning,operating-system,os-concepts,simulator
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Operating System
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Provides-Extra: tui
+Requires-Dist: textual>=0.90; extra == 'tui'
+Provides-Extra: web
+Requires-Dist: flask>=3.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# PyOS
+
+**Build your own operating system in Python -- then play with it.**
+
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
+[![CI](https://github.com/robcox2910/py-os/actions/workflows/ci.yml/badge.svg)](https://github.com/robcox2910/py-os/actions/workflows/ci.yml)
+[![Docs](https://github.com/robcox2910/py-os/actions/workflows/docs.yml/badge.svg)](https://robcox2910.github.io/py-os/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Ever wondered what happens when you open a program, save a file, or connect to the internet? PyOS is a complete operating system simulator that lets you see every piece -- processes, memory, filesystems, networking -- and poke at them from a real shell. Built with test-driven development and written for learners.
+
+## What Does It Look Like?
+
+```
+  ======================================
+            PyOS v0.1.0
+     A simulated operating system
+  ======================================
+
+  [POST] CPU ... OK
+  [POST] Memory ... OK
+  [POST] Storage ... OK
+  [BOOT] Loading kernel image v0.1.0 ... OK
+  [OK] Logger
+  [OK] Memory manager (256 frames)
+  [OK] Slab allocator
+  [OK] File system (journaled)
+  [OK] Scheduler (FCFS)
+  [OK] Init process (PID 1)
+
+Kernel running. Type 'help' for commands, 'exit' to quit.
+
+root@pyos $ ps
+PID  State    Name
+1    READY    init
+
+root@pyos $ fork 1
+Forked process 1 → child PID 2 (init)
+
+root@pyos $ pstree
+init (PID 1)
+  └── init (PID 2)
+
+root@pyos $ learn
+Available tutorials:
+  processes  — What is a process and how do they work?
+  memory     — How does the OS manage memory?
+  filesystem — How are files stored and organised?
+  shell      — What is a shell and why do we need one?
+  scheduling — How does the CPU decide what to run next?
+Type 'learn <topic>' to start a tutorial.
+```
+
+## Features
+
+- **Six CPU schedulers** -- FCFS, Round Robin, Priority, Aging, MLFQ, and CFS with multi-core support
+- **Virtual memory** -- page tables, address translation, swap (FIFO/LRU/Clock), slab allocator, and mmap
+- **Journaled filesystem** -- inodes, directories, hard/soft links, file descriptors, /proc, and crash recovery
+- **Full network stack** -- sockets, DNS, HTTP, and TCP with three-way handshake, flow control, and congestion control
+- **Shell scripting** -- pipes, variables, conditionals, job control, tab completion, and 80+ built-in commands
+- **Interactive tutorials** -- guided lessons that teach OS concepts hands-on using real system calls
+
+## Install
+
+```bash
+pip install pyos-learn
+pyos
+```
+
+Want the browser-based terminal too?
+
+```bash
+pip install pyos-learn[web]
+pyos-web
+```
+
+## Learn the Concepts
+
+Each guide explains one part of the OS with real-world analogies and simple language.
+
+| Guide | What You'll Learn |
+|-------|-------------------|
+| [What Is an OS?](docs/concepts/what-is-an-os.md) | The big picture -- what an OS does and why you need one |
+| [Processes](docs/concepts/processes.md) | Programs that are running, how they take turns, forking, and threads |
+| [Memory](docs/concepts/memory.md) | How the OS manages limited memory with pages, virtual addresses, and swap |
+| [Filesystem](docs/concepts/filesystem.md) | How files and folders are organised, and how they're saved to disk |
+| [The Kernel](docs/concepts/kernel-and-syscalls.md) | The brain of the OS -- boot sequence and system calls |
+| [The Shell](docs/concepts/shell.md) | Typing commands, pipes, scripting, and environment variables |
+| [Devices and Networking](docs/concepts/devices-and-networking.md) | Hardware, inter-process communication, disk scheduling, and sockets |
+| [Interrupts and Timers](docs/concepts/interrupts.md) | Interrupt controller, vectors, masking, timer, preemption |
+| [TCP: Reliable Delivery](docs/concepts/tcp.md) | Three-way handshake, flow control, congestion control, retransmission |
+| [Users and Safety](docs/concepts/users-and-safety.md) | Permissions, signals, logging, and deadlocks |
+| [Synchronization](docs/concepts/synchronization.md) | Mutexes, semaphores, condition variables, and race conditions |
+| [The Boot Chain](docs/concepts/bootloader.md) | What happens between pressing power and seeing a prompt |
+| [Framebuffer](docs/concepts/framebuffer.md) | Pixel-level graphics, drawing shapes, and displaying images |
+| [TUI Dashboard](docs/concepts/tui.md) | A live terminal dashboard that shows OS internals in real time |
+| [Permissions](docs/concepts/permissions.md) | File ownership, read/write/execute bits, groups, and ACLs |
+| [Binary Loader](docs/concepts/binary-loader.md) | Loading and running programs -- how `exec` works |
+| [Containers](docs/concepts/containers.md) | Lightweight isolation with PID, mount, and network namespaces |
+| [Inter-Machine Networking](docs/concepts/inter-machine-networking.md) | Connecting multiple kernels with bridges and clusters |
+| [Interactive Tutorials](docs/concepts/tutorials.md) | Guided lessons that teach OS concepts hands-on |
+| [Web UI](docs/concepts/web-ui.md) | Browser-based terminal interface |
+
+## Development
+
+```bash
+git clone https://github.com/robcox2910/py-os.git
+cd py-os
+uv sync --all-extras
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards and PR workflow.
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| **PyOS** | **Operating systems** | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+## Links
+
+- [Documentation](https://robcox2910.github.io/py-os/)
+- [Shell Reference](docs/shell-reference.md) -- all 80+ commands by category
+- [Architecture](docs/architecture.md) -- technical overview of every module
+- [Visual Guide](docs/diagrams.md) -- architecture diagrams
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/py-os/
+<!-- docs:end -->

fromscratch_pyos-0.3.0.dist-info/RECORD

@@ -0,0 +1,77 @@
+py_os/__init__.py,sha256=ISMnoFS4-vc0wuBPW1-JCQ106FlvOZZtqpPlLYjn0LY,84
+py_os/__main__.py,sha256=eKdbA2szDY2jIcUbyGgZ08eYreUA2To5o0V04FBO7cU,88
+py_os/_version.py,sha256=RCY04NY0kBCyn6ttH6lnVL6Gz2gceOrt45f0yDOOU8A,520
+py_os/bootloader.py,sha256=HnpXGPh_kEUuI1kaLekayLDBYMStpGYLCm6dUhET1pg,6800
+py_os/completer.py,sha256=vstLRECoP19gz_7IXd-WCitK_rquqn8Cy6HAiwcKmQ4,8370
+py_os/containers.py,sha256=3gZSSHD8Y9IItkv_JKBFd7EBX0uJi-A2tnFwGhvqTUE,10786
+py_os/env.py,sha256=JfW8-zSz40lqu6Xuypox8XK7atPkLDC5rgjEMld0poM,2243
+py_os/jobs.py,sha256=1fbeea9Y-lcbavwKWjUVAllnE1oYTolvrdWfwF1sLfk,3236
+py_os/kernel.py,sha256=YODPmFEQ8tLzi6GGFPHtwKmEAn-8sZm-4M9-lOg9o-w,128581
+py_os/logging.py,sha256=HRwRBflcQ8d4eoP_FtsXvTGBKvhjEh-sqG9_Deou0Ds,3568
+py_os/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_os/repl.py,sha256=ksn8ZoBX-2fomqE4ZaX58kvt8Vmnk9wKvms8qvtnqow,3584
+py_os/syscalls.py,sha256=DU-CZkc8ex6b2sSV6Of2BEIneAQOAgGxBGRggVeGqnU,83567
+py_os/tutorials.py,sha256=8hbZN2zWsl00x74zG34O-J5ZdZN4wXcI-kMjUFI8lOI,31075
+py_os/users.py,sha256=VDJLlm6JMbNwLJ7BVJb6ivlc0cYnG9tSNebXmkqBk9E,15094
+py_os/fs/__init__.py,sha256=xHFSdwnU-1z9PPKxO3e58UvXC_cd6X0jpUeONePwEVY,1051
+py_os/fs/fd.py,sha256=zaUiFq0_vgyV9TSf5QTvu8Xpsxf30VruF613jYrxL5s,4458
+py_os/fs/filesystem.py,sha256=oL-fPIJQ-6YruLogP-dknbJFrSKbW1VcUeLzAjmpKjs,20138
+py_os/fs/journal.py,sha256=Nic3z508RkFXuaH7qMb5C2hXwxzhOb-mvdgQNQYnVyA,17407
+py_os/fs/persistence.py,sha256=8qJXj0fn-kiSffzBs21eO9ezzDF-gEMosUntmnJRG_0,2727
+py_os/fs/procfs.py,sha256=OpKhV3gLU1NC1AkKJoRT6gGoLBGlykUiJflm8vV3BH0,11878
+py_os/io/__init__.py,sha256=7NF7oOlMiFS7rbKTVNCm1Kn7afv4qa209m0R_iR_Zzo,2087
+py_os/io/bridge.py,sha256=meQKEbz77RONwsX5zwN7rwqji9hExLDNikE4Y8jx0gQ,10609
+py_os/io/devices.py,sha256=eDoAGXxDy9MY4xVcL0j1A-AJ9lxzT0Zhf27azYARujc,5564
+py_os/io/disk.py,sha256=Gl3wiEA5ZCd5jouVV2yCqS7VkRENu1dMuAsTVcQKE6Q,7823
+py_os/io/dns.py,sha256=iInGYV-17AP1WtX1VgfRMl5pJ8kt6CS8laZeeMFKJ0I,3134
+py_os/io/framebuffer.py,sha256=T6TbFfr5POSuJlw5n75pEzAlZTESPgHgOZ3r_TknoyQ,5663
+py_os/io/http.py,sha256=cz3ugp6BiCVlB_I6xxrqoGTKdwJlQmNKobuy96u0-n8,7857
+py_os/io/interrupts.py,sha256=fkp6fygpZYx_YChFsLOxzDn0xoO9MRzKRzIBzdK2DgA,9262
+py_os/io/ipc.py,sha256=EgqIR831tXpehIALTMAdaoFVvCyzvTwDxzcUMRjAZwo,4100
+py_os/io/networking.py,sha256=4gwm6OyC3D7h0wXGkH3SJdC2fuA6aq2C57oW7nUV61o,10391
+py_os/io/shm.py,sha256=uCo2XQZLlIaWAWfEgERNbmrw378c7-_LIx8jJBCroas,1805
+py_os/io/tcp.py,sha256=HN76BhDgP4C7yR1LfUwhBvy7z1L0gnntk38PHdjO7ps,26842
+py_os/io/timer.py,sha256=VpGP_QqabKoryzJGZS40FCmYEU9d4jV2u7f-agkxrAE,4516
+py_os/memory/__init__.py,sha256=lzh8L_MhfevqFWsK_rDelz0PDJiQLL8HUjRpBT6zPmM,892
+py_os/memory/manager.py,sha256=6lP1q1IM6CjQLSwuFNaMNWn-ZFIhkfziAOMHYEeLSVY,7293
+py_os/memory/mmap.py,sha256=HwQy4PO5q8SZrDnq9NyLkHJXNuiRmQlzGrOlU6qyj1s,1638
+py_os/memory/slab.py,sha256=_ruRF9NoWkQm1H7sqm8nev5W5HMdQgfEPoU-wkDF6Qs,14908
+py_os/memory/swap.py,sha256=rwL4Z4UYqvvbSgutfV00zUt4YinHRcjud-SUS5rRgpA,14484
+py_os/memory/virtual.py,sha256=2O5YTx1mDhxkNR2hIBuY6va8ydk_HAPsjUqEIIzNgSA,8504
+py_os/process/__init__.py,sha256=3Q4wA9qFMu7jxbKwibWsfHxufHjBYFIzOtD6yPJI0pc,942
+py_os/process/binary.py,sha256=PljUki3MgmpphNYyaSb_sar_55AIota_05e3hPLF4og,12797
+py_os/process/pcb.py,sha256=64YINo81CBRbG41xAOp_wCDjrsTyBc2GlKye8t4Wdqc,13644
+py_os/process/scheduler.py,sha256=uJ1oieIuH46G9inVUX1MAnCI4I8m7urXwNAIdDCuJq8,28506
+py_os/process/signals.py,sha256=hs6hjKMLkvQu60dxdnwhzwKNq_Anma-86bTevt5UB9M,3291
+py_os/process/threads.py,sha256=xHRDFsokgMqhi7G8wFrIteNAc33hghX4xDt9ikAnY_k,4985
+py_os/shell/__init__.py,sha256=sGqubpCnXqrdxDYIP2k0On30ZSNcl-zX8gsW54w6AEw,2153
+py_os/shell/base.py,sha256=RssovgXKDuJ6l3TyUAz6R6ppdusoQmeJAutTZGyF5aY,21083
+py_os/shell/commands/__init__.py,sha256=LHjz8PQ0HCvvJ0ujEEm_YJfVh5Cg0ZVoW31pK0EsjE8,859
+py_os/shell/commands/basics.py,sha256=yX2a4lLjAKTDyU03CW0N1lxgQ2NNDJgxfWY5G6GNCeQ,3970
+py_os/shell/commands/devices.py,sha256=fehv02H_zPNPwxWeK_verxFU-zkuA3R5Yk7eJcfTIIE,14733
+py_os/shell/commands/files.py,sha256=k2VnKYK0k3dCvmCMv6RVm2jBNH8fzFmIKc3rvDjkY_Y,19192
+py_os/shell/commands/isolation.py,sha256=HmRNArhuYXnayrrkppeQYfMoqC53MSqnQT1rEli5AAI,10590
+py_os/shell/commands/learn.py,sha256=Ur_jM0oa7i2N_r8hFejFyJMzMa1jZX0uUkhzNnPK8Ww,1046
+py_os/shell/commands/memory.py,sha256=Xe7xT8Sn2NQqeZQbC1-yXtZrLrsRRZJ47n13jd-DkKI,18159
+py_os/shell/commands/network.py,sha256=9NV1n8rf5ttyQ2bC7ETFEP0rTdMX9FebNKZbx7h6FP8,30031
+py_os/shell/commands/processes.py,sha256=r_zCF4AXFFCm2On_aF2gNjnA97VgVjojNenhxoF0_b8,42354
+py_os/shell/commands/sync.py,sha256=aePAAG4XC5hXKTCccN8qbpQxZAw0hVRcblwBAy5435M,19561
+py_os/shell/commands/users.py,sha256=YoPSGfeNVP1zelIX8CEE3hn3p_Budw2FLmjIve6jUX4,5282
+py_os/sync/__init__.py,sha256=1lVOCpWesVG7RvLRvqv4RZbN055thFXjzMODltuaswA,780
+py_os/sync/deadlock.py,sha256=7icCHt1CDLodJWVBGY0FMCTgBgD66VRMJDy3BjQH_ko,9487
+py_os/sync/inheritance.py,sha256=FKJmBvYZCFIWvwuL_3-nuD3E2DxUFCcjfUtKBTZfQdo,6867
+py_os/sync/ordering.py,sha256=RXGmLIWLpcqW-cBcO1W4wWeELSZst0oKbxCxjlnCWw4,7388
+py_os/sync/primitives.py,sha256=cWoDThw1ytOVQFmYgSQH7SmoIZMJHMguq9eChTGTKzs,23024
+py_os/tui/__init__.py,sha256=ivIrIDQom5BiWlpqLquwRi2j-UrdnSrutYt2_A7PMzA,206
+py_os/tui/app.py,sha256=hYx6p-XJ60_ldotaR2HN5Yfzr52SRzFZjAq6sEgm0nw,4042
+py_os/tui/widgets.py,sha256=coswN1G27qp766UJ51O3QkH05XMA-rfteNxX9MYtWCY,4628
+py_os/web/__init__.py,sha256=CRf53S1sO59mTgd2X2d-QahHi4wchRE1t3Ry91W0ikk,485
+py_os/web/app.py,sha256=vMpm26gOYuwGoN2kDdLM2hxDDU_ONctOzWIqOsTWS_c,2771
+py_os/web/static/style.css,sha256=QTuER3LAe1jmSfcYqQT3LCrNrBNQpbvvjIKE4Vkwduk,1243
+py_os/web/static/terminal.js,sha256=QuzO54uBYgxGUZF-Ki07EG68cEYBgsquQsL7XZa8k-0,1804
+py_os/web/templates/index.html,sha256=0rhqKLLV70_2PNzD7Ctp8qRH9IMHhYuBTD7grXAXWtY,728
+fromscratch_pyos-0.3.0.dist-info/METADATA,sha256=c0w65vCzLYyGa-7BZysdSbnYdmv1JiPiJ4U1UjAwskQ,10541
+fromscratch_pyos-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pyos-0.3.0.dist-info/entry_points.txt,sha256=4zHzRCJ_SMpscOw_jkX1gKNC-F2x9qaUJRO4KcgsyJc,100
+fromscratch_pyos-0.3.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pyos-0.3.0.dist-info/RECORD,,

fromscratch_pyos-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromscratch_pyos-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+pyos = py_os.repl:run
+pyos-tui = py_os.tui.app:main
+pyos-web = py_os.web.app:main

fromscratch_pyos-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_os/__init__.py

@@ -0,0 +1 @@
+"""PyOS - A simulated operating system built in Python for learning OS concepts."""

py_os/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the OS with ``python -m py_os``."""
+
+from py_os.repl import run
+
+run()

py_os/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

py_os/bootloader.py

@@ -0,0 +1,219 @@
+"""Bootloader — simulated firmware POST and boot chain.
+
+Every real computer follows a boot chain before you see a shell prompt:
+
+    Firmware POST → Bootloader → Kernel → Userspace
+
+Think of it like opening a school building each morning:
+
+1. **Firmware POST** — Security guard checks lights, water, doors.
+2. **Bootloader** — Janitor fetches "Today's School Plan" from the
+   supply closet (disk) and hands it to the principal.
+3. **Kernel boot** — Principal sets up each department from the plan.
+4. **Userspace** — Vice principal opens the front desk (shell) so
+   students can check in.
+
+This module simulates that chain so you can see what happens between
+pressing the power button and getting a shell prompt.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from py_os.kernel import Kernel
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class BootStage(StrEnum):
+    """Represent the current phase of the boot chain.
+
+    The boot process moves through these stages in order:
+    FIRMWARE → BOOTLOADER → KERNEL → USERSPACE.
+    """
+
+    FIRMWARE = "firmware"
+    BOOTLOADER = "bootloader"
+    KERNEL = "kernel"
+    USERSPACE = "userspace"
+
+
+@dataclass(frozen=True)
+class PostResult:
+    """Capture the outcome of the firmware Power-On Self-Test (POST).
+
+    POST checks that essential hardware works before the OS loads.
+    If any check fails, the machine cannot boot safely.
+    """
+
+    memory_ok: bool
+    disk_ok: bool
+    devices_ok: bool
+    messages: tuple[str, ...] = ()
+
+    @property
+    def passed(self) -> bool:
+        """Return True only if every hardware check passed."""
+        return self.memory_ok and self.disk_ok and self.devices_ok
+
+
+@dataclass(frozen=True)
+class KernelImage:
+    """Represent the kernel binary stored on disk.
+
+    In a real system the bootloader reads the kernel image from a
+    partition (e.g. ``/boot/vmlinuz``).  Our image carries the
+    configuration the kernel needs to initialise itself.
+    """
+
+    version: str
+    total_frames: int
+    default_policy: str
+    boot_args: dict[str, str] = field(default_factory=lambda: {})  # noqa: PIE807
+    num_cpus: int = 1
+
+
+class BootError(RuntimeError):
+    """Raise when the boot chain cannot continue.
+
+    Examples: POST failure, missing kernel image, corrupt image file.
+    """
+
+
+class Bootloader:
+    """Simulate the firmware + bootloader that starts the kernel.
+
+    Usage::
+
+        bootloader = Bootloader()
+        kernel = bootloader.boot()  # full chain, returns running kernel
+
+    """
+
+    def __init__(
+        self,
+        *,
+        kernel_image_path: Path | None = None,
+        total_frames: int = 64,
+        num_cpus: int = 1,
+    ) -> None:
+        """Create a bootloader with optional kernel image path.
+
+        Args:
+            kernel_image_path: Path to a JSON kernel image file.
+                If None, a default image is constructed in memory.
+            total_frames: Default memory frame count (used when no
+                image file is provided).
+            num_cpus: Number of CPUs to simulate (default 1).
+
+        """
+        self._kernel_image_path = kernel_image_path
+        self._total_frames = total_frames
+        self._num_cpus = num_cpus
+        self._stage: BootStage = BootStage.FIRMWARE
+        self._boot_log: list[str] = []
+        self._kernel: Kernel | None = None
+
+    @property
+    def stage(self) -> BootStage:
+        """Return the current boot stage."""
+        return self._stage
+
+    @property
+    def boot_log(self) -> list[str]:
+        """Return the accumulated boot log messages."""
+        return list(self._boot_log)
+
+    @property
+    def kernel(self) -> Kernel | None:
+        """Return the booted kernel, or None if boot has not completed."""
+        return self._kernel
+
+    def boot(self) -> Kernel:
+        """Run the full boot chain and return a running kernel.
+
+        Raises:
+            BootError: If POST fails or the kernel image is missing.
+
+        """
+        # Stage 1: Firmware POST
+        self._stage = BootStage.FIRMWARE
+        post_result = self._run_post()
+        if not post_result.passed:
+            msg = "POST failed: " + ", ".join(post_result.messages)
+            raise BootError(msg)
+        self._boot_log.extend(f"[POST] {m}" for m in post_result.messages)
+
+        # Stage 2: Load kernel image
+        self._stage = BootStage.BOOTLOADER
+        image = self._load_kernel_image()
+        self._boot_log.append(f"[BOOT] Loading kernel image v{image.version} ... OK")
+
+        # Stage 3: Boot kernel
+        self._stage = BootStage.KERNEL
+        kernel = Kernel(total_frames=image.total_frames, num_cpus=image.num_cpus)
+        kernel.boot()
+        self._kernel = kernel
+
+        # Stage 4: Userspace ready
+        self._stage = BootStage.USERSPACE
+        return kernel
+
+    def _run_post(self) -> PostResult:
+        """Simulate the Power-On Self-Test.
+
+        Check memory frames, disk accessibility, and device availability.
+        """
+        messages: list[str] = []
+        memory_ok = self._total_frames > 0
+        messages.append(
+            f"Memory: {self._total_frames} frames ... " + ("OK" if memory_ok else "FAIL")
+        )
+
+        # Disk is always accessible in our simulation
+        disk_ok = True
+        messages.append("Disk: accessible ... OK")
+
+        # Devices are always available in our simulation
+        devices_ok = True
+        messages.append("Devices: ready ... OK")
+
+        return PostResult(
+            memory_ok=memory_ok,
+            disk_ok=disk_ok,
+            devices_ok=devices_ok,
+            messages=tuple(messages),
+        )
+
+    def _load_kernel_image(self) -> KernelImage:
+        """Load the kernel image from a JSON file or construct defaults.
+
+        Raises:
+            BootError: If the image file is specified but cannot be read.
+
+        """
+        if self._kernel_image_path is not None:
+            try:
+                data = json.loads(self._kernel_image_path.read_text())
+                return KernelImage(
+                    version=data.get("version", "0.1.0"),
+                    total_frames=data.get("total_frames", self._total_frames),
+                    default_policy=data.get("default_policy", "fcfs"),
+                    boot_args=data.get("boot_args", {}),
+                    num_cpus=data.get("num_cpus", self._num_cpus),
+                )
+            except (OSError, json.JSONDecodeError) as e:
+                msg = f"Cannot load kernel image: {e}"
+                raise BootError(msg) from e
+
+        return KernelImage(
+            version="0.1.0",
+            total_frames=self._total_frames,
+            default_policy="fcfs",
+            num_cpus=self._num_cpus,
+        )