fromscratch-pyos 0.3.0__tar.gz

fromscratch_pyos-0.3.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git init:*)",
+      "Bash(uv venv:*)",
+      "Bash(uv pip install:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(.venv/bin/pre-commit install:*)",
+      "Bash(.venv/bin/pytest)",
+      "Bash(.venv/bin/ruff check:*)",
+      "Bash(.venv/bin/ruff format:*)",
+      "Bash(gh repo create:*)",
+      "Bash(gh api:*)",
+      "Bash(gh repo edit:*)",
+      "Bash(git checkout:*)",
+      "Bash(.venv/bin/pre-commit clean:*)",
+      "Bash(git push:*)",
+      "Bash(gh pr:*)",
+      "Bash(git pull:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(.venv/bin/pyright:*)",
+      "Bash(git rm:*)"
+    ]
+  }
+}

fromscratch_pyos-0.3.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "ci"

fromscratch_pyos-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/python-ci.yml@v1

fromscratch_pyos-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,16 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  docs:
+    uses: robcox2910/robcox2910.github.io/.github/workflows/docs.yml@v1
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      coverage-report: true

fromscratch_pyos-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fromscratch-pyos/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fromscratch_pyos-0.3.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+*.cover
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/
+
+# Environment variables
+.env
+.env.local
+
+# Auto-generated version file (hatch-vcs)
+src/py_os/_version.py
+
+# Logs
+*.log
+
+# MkDocs build output
+site/
+
+# Type checking cache
+.mypy_cache/
+.ruff_cache/
+.claude/settings.local.json
+
+# Hypothesis example database (local thorough runs)
+.hypothesis/

fromscratch_pyos-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Pages paste real pytest output, trailing spaces included.
+      - id: trailing-whitespace
+        exclude: ^docs/property-testing\.md$
+      - id: end-of-file-fixer
+        exclude: ^docs/property-testing\.md$
+      - id: check-yaml
+        args: ['--unsafe']
+      - id: check-added-large-files
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
+    hooks:
+      - id: pyright
+
+  - repo: local
+    hooks:
+      - id: pip-audit
+        name: pip-audit
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+        entry: >-
+          bash -c 'f=$(mktemp) &&
+          uv export --frozen --no-emit-project --all-extras --no-hashes -o "$f" >/dev/null &&
+          uvx pip-audit==2.10.0 -r "$f" --disable-pip --no-deps;
+          status=$?; rm -f "$f"; exit $status'
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.13.8
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+        additional_dependencies: [typing_extensions]

fromscratch_pyos-0.3.0/.python-version

@@ -0,0 +1 @@
+3.14

fromscratch_pyos-0.3.0/CLAUDE.md

@@ -0,0 +1,73 @@
+# PyOS
+
+<!-- standard:start -->
+## Code Style
+
+- All public functions, methods, classes, and modules **must** have a docstring
+- Use imperative mood: "Return the result." not "Returns the result."
+- One-line docstrings for simple functions; multi-line with summary + details for complex ones
+- Follow the Google docstring convention (D211, D212 selected via ruff)
+
+## Linting
+
+- Ruff enforces a comprehensive rule set -- run `uv run ruff check .` before committing
+- Pyright runs in strict mode -- run `uv run pyright src tests` before committing
+- All violations must be fixed, not ignored. Exceptions are the repo-owned `ignore` and `per-file-ignores` lists in `pyproject.toml`, which belong to this repo; the series sync never edits them
+
+## Testing
+
+- TDD workflow: Red-Green-Refactor
+- Coverage is enforced by pytest-cov; the floor in `pyproject.toml` is repo-owned
+- Test classes and methods also require docstrings
+- Use named constants instead of magic values (PLR2004)
+- Run `uv run pytest` before committing
+- Property-based tests (Hypothesis) live in `tests/test_properties.py` and `tests/test_model.py`; the shared profiles are in the root `conftest.py` (owned by `series sync`). Run `uv run pytest --hypothesis-profile=thorough` before a release.
+
+## Commits
+
+- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
+- All changes go via PR from a feature branch (main is protected); merge when CI is green
+
+## Dependencies
+
+- Package manager: uv
+- Run `uv sync --all-extras` after modifying dependencies
+- `uv.lock` is committed; CI and pre-commit audit it with pip-audit through `uvx`, so pip-audit is not a project dependency
+- Sibling projects, where used, are pinned release tags in `[tool.uv.sources]` (git + tag); never use `path` sources
+
+## Releasing
+
+- A release is a `vX.Y.Z` tag on main after the PR is merged
+- Docs-only and tooling-only changes do not get a release tag
+- Docs are built with `mkdocs build --strict` and deployed to GitHub Pages by the docs workflow
+<!-- standard:end -->
+
+## Project notes
+
+PyOS (`py_os`, repo `py-os`, distribution `pyos-learn`) is a teaching operating system simulated in Python: kernel, scheduler, memory, filesystem, IPC, sockets and a shell, written to be read. Source is in `src/py_os`, tests mirror it under `tests/`.
+
+### Package layout
+
+- `kernel.py` -- the `Kernel` that owns and boots every subsystem; `syscalls.py` -- the `SyscallNumber` table and dispatch; user-facing code only ever sees `SyscallError`.
+- `process/`, `memory/`, `fs/`, `io/`, `sync/` -- subsystem packages (scheduling and PCBs, paging and slab allocator, inodes/journal/procfs, devices/DNS/HTTP/sockets, locks and semaphores).
+- `shell/` -- the command interpreter, `repl.py` -- the interactive loop, `web/` and `tui/` -- optional front-ends (flask / textual extras).
+- `users.py` (accounts, ACLs, `OsPermissionError`), `containers.py`, `env.py`, `jobs.py`, `logging.py`, `tutorials.py`.
+
+### The shell package
+
+- `shell/base.py` holds `ShellBase` (parsing, pipes, redirection, history, aliases, dispatch). `shell/__init__.py` composes `Shell` from `ShellBase` plus the command-group mixins.
+- Command groups live in `shell/commands/*.py` (files, processes, memory, network, ...). Each group defines handler methods and a `COMMANDS` tuple of `(name, handler)` pairs; `ShellBase.__init__` builds its dispatch dict from every group's `COMMANDS`. To add a command: write the method, add one entry to that group's `COMMANDS`.
+- Shell handlers talk to the kernel only through `kernel.syscall(...)`, never by reaching into subsystems.
+
+### The `_missing_subsystem` pattern
+
+Kernel subsystems are `None` until boot. Rather than `assert` (banned at runtime, see `tests/test_no_runtime_asserts.py`), code does `if self._scheduler is None: _raise_missing_subsystem("scheduler")`. The helper is typed `NoReturn`, so pyright narrows the attribute afterwards. `kernel.py` raises `RuntimeError`; `syscalls.py` has its own helper raising `SyscallError`. Calling a raising helper (instead of `raise X("literal")`) also keeps ruff's EM101 satisfied.
+
+### Complexity
+
+Ruff `C90` runs with `max-complexity = 15` (and pylint `max-args = 9`). Split big functions into helpers or table-driven dispatch rather than raising the limit.
+
+### Running it
+
+- Shell: `uv run pyos` (or `uv run python -m py_os`); web: `uv run pyos-web` (needs `--extra web`); TUI: `uv run pyos-tui` (needs `--extra tui`).
+- Checks: `uv run ruff check .`, `uv run ruff format --check .`, `uv run pyright`, `uv run pytest` (coverage floor 80%).

fromscratch_pyos-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,216 @@
+# Contributing to PyOS
+
+Thanks for your interest in contributing! This guide covers everything you need
+to get started.
+
+## Prerequisites
+
+| Tool | Version | Install |
+|------|---------|---------|
+| Python | 3.14+ | [python.org](https://www.python.org/downloads/) |
+| uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| git | 2.x+ | [git-scm.com](https://git-scm.com/) |
+
+## Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/robcox2910/py-os.git
+cd py-os
+
+# Install all dependencies (including dev tools)
+uv sync --all-extras
+
+# Install pre-commit hooks (linting + commit message validation)
+uv run pre-commit install
+uv run pre-commit install --hook-type commit-msg
+```
+
+Verify everything works:
+
+```bash
+uv run pytest --cov          # tests pass, >= 80% coverage
+uv run ruff check src/ tests/  # no lint errors
+uv run pyright src tests       # no type errors
+```
+
+## TDD Workflow
+
+We follow **Red-Green-Refactor** for every code change:
+
+1. **Red** — Write a failing test that describes the behaviour you want.
+2. **Green** — Write the simplest code that makes the test pass.
+3. **Refactor** — Clean up while keeping all tests green.
+
+Never skip the red step. If you can't write a failing test first, take a moment
+to think about what the code should actually do.
+
+## Branch Naming
+
+Create a branch from `main` using one of these prefixes:
+
+| Prefix | When to use |
+|--------|-------------|
+| `feat/` | New feature or command |
+| `fix/` | Bug fix |
+| `refactor/` | Restructuring without behaviour change |
+| `test/` | Test-only changes |
+| `docs/` | Documentation updates |
+| `ci/` | CI/CD workflow changes |
+| `chore/` | Dependency bumps, config tweaks |
+
+Example: `feat/benchmark-suite`, `fix/scheduler-priority-bug`
+
+## Conventional Commits
+
+Every commit message must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>: <short description in imperative mood>
+
+Optional longer explanation.
+```
+
+Types match the branch prefixes: `feat:`, `fix:`, `refactor:`, `test:`,
+`docs:`, `ci:`, `chore:`.
+
+Good examples:
+
+```
+feat: add benchmark command for scheduler comparison
+fix: prevent deadlock when forking with held mutex
+docs: clarify memory paging analogy
+```
+
+Bad examples:
+
+```
+updated stuff          # no type, vague description
+feat: adds benchmarks  # not imperative mood ("adds" → "add")
+```
+
+## Code Style
+
+### Modern Python
+
+Use Python 3.14 idioms everywhere:
+
+- `X | Y` for union types (not `Union[X, Y]` or `Optional[X]`)
+- `StrEnum` for string enumerations
+- `match/case` instead of if/elif chains where appropriate
+- Direct imports: `from enum import StrEnum` not `import enum`
+
+### Docstrings
+
+Every public function, method, class, and module needs a docstring:
+
+- Use **imperative mood**: "Return the process." not "Returns the process."
+- One-liner for simple functions, multi-line (Google style) for complex ones.
+
+```python
+def terminate(self, pid: int) -> bool:
+    """Terminate a process by PID."""
+
+def allocate(self, num_pages: int, pid: int) -> list[int]:
+    """Allocate contiguous pages for a process.
+
+    Args:
+        num_pages: Number of pages to allocate.
+        pid: Process requesting the allocation.
+
+    Returns:
+        List of allocated frame numbers.
+
+    Raises:
+        MemoryError: If not enough free frames are available.
+    """
+```
+
+### Named Constants
+
+Use named constants instead of magic numbers in tests and source code. Ruff
+rule PLR2004 enforces this.
+
+```python
+# Good
+EXPECTED_FRAME_COUNT = 64
+assert manager.free_frames == EXPECTED_FRAME_COUNT
+
+# Bad
+assert manager.free_frames == 64
+```
+
+## Linting and Type Checking
+
+Run these before every commit (pre-commit hooks enforce them automatically):
+
+```bash
+uv run ruff check src/ tests/   # lint
+uv run ruff format src/ tests/   # format (or --check to verify)
+uv run pyright src tests          # type check (strict mode)
+```
+
+Fix all violations. Inline `# noqa:` is acceptable only when tools genuinely
+conflict (e.g., ARG002 vs pyright protocol parameter names).
+
+## Testing
+
+```bash
+uv run pytest                # run all tests
+uv run pytest --cov          # with coverage report
+uv run pytest tests/test_x.py  # run a specific file
+uv run pytest -k "test_name"   # run tests matching a pattern
+```
+
+- Minimum **80% coverage** is enforced.
+- Test classes and methods need docstrings too.
+- Use `pytest.raises` as a context manager for exception testing.
+
+## Adding a Shell Command
+
+1. **Add the syscall** (if needed) in `src/py_os/syscalls.py`:
+   - Add the enum value to `SysCall`
+   - Add a handler method `_handle_<name>`
+   - Register it in the dispatch table
+
+2. **Add the shell command** in `src/py_os/shell.py`:
+   - Add `"command_name": self._cmd_name` to the dispatch dict in `__init__`
+   - Implement `_cmd_name(self, args: list[str]) -> str`
+
+3. **Add tab completion** in `src/py_os/completer.py`:
+   - Add `"command_name": ["sub1", "sub2"]` to `_SUBCOMMANDS` (if it has
+     subcommands)
+
+4. **Write tests** in `tests/test_command_name.py` following TDD.
+
+5. **Update docs** — add a row to the shell commands table in `README.md`.
+
+## Documentation Style
+
+Our docs target a **12-year-old with an interest in computing**. Keep language
+simple, use analogies, and avoid jargon without explanation.
+
+Good:
+
+> Memory is like a warehouse with numbered shelves. Each shelf (called a
+> "frame") can hold one page of data. When a program needs space, the OS finds
+> empty shelves and assigns them.
+
+Bad:
+
+> The memory manager implements a demand-paged virtual memory system with
+> frame-based physical allocation.
+
+## Pull Request Process
+
+1. Create a feature branch from `main`.
+2. Make your changes following TDD.
+3. Ensure all checks pass: `uv run ruff check .`, `uv run pyright src tests`,
+   `uv run pytest --cov`.
+4. Push your branch and open a PR against `main`.
+5. PRs are squash-merged to keep history clean.
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/robcox2910/py-os/issues) — we're
+happy to help!

fromscratch_pyos-0.3.0/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.