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 -->
