fromscratch-pycoldb 0.4.0__tar.gz

fromscratch_pycoldb-0.4.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_pycoldb-0.4.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: false

fromscratch_pycoldb-0.4.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-pycoldb/
+    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_pycoldb-0.4.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.ruff_cache/
+_version.py
+.hypothesis/

fromscratch_pycoldb-0.4.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_pycoldb-0.4.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# Claude Code Instructions
+
+<!-- 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
+
+- Pyright in strict mode -- run `uv run pyright src tests` before committing
+- All violations must be fixed, not ignored (except D203/D213 incompatible pair)
+- Minimum 90% coverage enforced by pytest-cov
+- Use conventional commits (enforced by commitizen): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
+- All changes go via PR from a feature branch (main is protected)
+- Add production deps to `[project.dependencies]`

fromscratch_pycoldb-0.4.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.

fromscratch_pycoldb-0.4.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: fromscratch-pycoldb
+Version: 0.4.0
+Summary: An educational column-family store library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pycoldb
+Project-URL: Repository, https://github.com/robcox2910/pycoldb
+Project-URL: Issues, https://github.com/robcox2910/pycoldb/issues
+Project-URL: Documentation, https://robcox2910.github.io/pycoldb/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: column-family,database,education,wide-column
+Classifier: Development Status :: 3 - Alpha
+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 :: Software Development :: Libraries
+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-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyColDB
+
+An educational column-family store (wide-column database) built from scratch in Python. Part of the **PyLearn** platform for kids aged 12+.
+
+## What is a Column-Family Store?
+
+A column-family store is like a spreadsheet where every row can have different columns. Instead of forcing every record to have the same fields, each row picks and chooses what data it stores. Real-world examples include Apache Cassandra and HBase.
+
+## Features
+
+- **Columns** -- Name-value pairs with timestamps
+- **Rows** -- Flexible records where each row has its own set of columns
+- **Column Families** -- Named groups of rows (like gradebooks)
+- **Keyspaces** -- Top-level containers for column families (like a school)
+- **CRUD** -- Insert, read, update, and delete columns within rows
+- **Range Queries** -- Get rows by key range (e.g., keys from "A" to "M")
+- **Column Filtering** -- Get only specific columns from a row
+- **TTL** -- Columns can expire after a time-to-live
+- **Tombstones** -- Soft deletion with markers (like Cassandra)
+- **Persistence** -- Save and load to JSON files
+- **Compaction** -- Remove expired and deleted entries to reclaim space
+
+## Quick Start
+
+```python
+from pycoldb import Keyspace, Column
+
+# Create a keyspace (like a school)
+school = Keyspace(name="school")
+
+# Create a column family (like a gradebook)
+school.create_column_family("grades")
+
+# Add grades -- each student can have different columns!
+school.put("grades", "alice", Column(name="math", value="A+"))
+school.put("grades", "alice", Column(name="science", value="A"))
+school.put("grades", "bob", Column(name="math", value="B"))
+school.put("grades", "bob", Column(name="music", value="A"))
+
+# Read a grade
+grade = school.get_column("grades", "alice", "math")
+print(f"Alice's math grade: {grade.value}")  # A+
+
+# Range query -- get students from "alice" to "bob"
+from pycoldb import range_query
+cf = school.get_column_family("grades")
+rows = range_query(cf, start_key="alice", end_key="bob")
+for row in rows:
+    print(f"{row.key}: {row.column_names()}")
+
+# Save to disk
+from pycoldb import save_keyspace, load_keyspace
+save_keyspace(school, "school.json")
+restored = load_keyspace("school.json")
+```
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/robcox2910/pycoldb.git
+cd pycoldb
+uv sync --all-extras
+```
+
+## Development
+
+```bash
+uv run ruff check src/ tests/      # Lint
+uv run ruff format src/ tests/      # Format
+uv run pyright src tests            # Type check
+uv run pytest                       # Test (90%+ coverage)
+```
+
+## 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 -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pycoldb/
+<!-- docs:end -->
+
+## License
+
+MIT

fromscratch_pycoldb-0.4.0/README.md

@@ -0,0 +1,123 @@
+# PyColDB
+
+An educational column-family store (wide-column database) built from scratch in Python. Part of the **PyLearn** platform for kids aged 12+.
+
+## What is a Column-Family Store?
+
+A column-family store is like a spreadsheet where every row can have different columns. Instead of forcing every record to have the same fields, each row picks and chooses what data it stores. Real-world examples include Apache Cassandra and HBase.
+
+## Features
+
+- **Columns** -- Name-value pairs with timestamps
+- **Rows** -- Flexible records where each row has its own set of columns
+- **Column Families** -- Named groups of rows (like gradebooks)
+- **Keyspaces** -- Top-level containers for column families (like a school)
+- **CRUD** -- Insert, read, update, and delete columns within rows
+- **Range Queries** -- Get rows by key range (e.g., keys from "A" to "M")
+- **Column Filtering** -- Get only specific columns from a row
+- **TTL** -- Columns can expire after a time-to-live
+- **Tombstones** -- Soft deletion with markers (like Cassandra)
+- **Persistence** -- Save and load to JSON files
+- **Compaction** -- Remove expired and deleted entries to reclaim space
+
+## Quick Start
+
+```python
+from pycoldb import Keyspace, Column
+
+# Create a keyspace (like a school)
+school = Keyspace(name="school")
+
+# Create a column family (like a gradebook)
+school.create_column_family("grades")
+
+# Add grades -- each student can have different columns!
+school.put("grades", "alice", Column(name="math", value="A+"))
+school.put("grades", "alice", Column(name="science", value="A"))
+school.put("grades", "bob", Column(name="math", value="B"))
+school.put("grades", "bob", Column(name="music", value="A"))
+
+# Read a grade
+grade = school.get_column("grades", "alice", "math")
+print(f"Alice's math grade: {grade.value}")  # A+
+
+# Range query -- get students from "alice" to "bob"
+from pycoldb import range_query
+cf = school.get_column_family("grades")
+rows = range_query(cf, start_key="alice", end_key="bob")
+for row in rows:
+    print(f"{row.key}: {row.column_names()}")
+
+# Save to disk
+from pycoldb import save_keyspace, load_keyspace
+save_keyspace(school, "school.json")
+restored = load_keyspace("school.json")
+```
+
+## Installation
+
+```bash
+# From source
+git clone https://github.com/robcox2910/pycoldb.git
+cd pycoldb
+uv sync --all-extras
+```
+
+## Development
+
+```bash
+uv run ruff check src/ tests/      # Lint
+uv run ruff format src/ tests/      # Format
+uv run pyright src tests            # Type check
+uv run pytest                       # Test (90%+ coverage)
+```
+
+## 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 -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pycoldb/
+<!-- docs:end -->
+
+## License
+
+MIT

fromscratch_pycoldb-0.4.0/conftest.py

@@ -0,0 +1,21 @@
+"""Shared Hypothesis profiles for the series.
+
+Two profiles are registered, and ``ci`` is loaded by default:
+
+- ``ci`` runs 100 examples with no deadline, a fixed seed and no example
+  database, so the same code gives the same result on every machine and a
+  green build can be trusted.
+- ``thorough`` runs 2000 examples with a random seed, to hunt for the rare
+  counterexample before a release.
+
+Run the long one with ``uv run pytest --hypothesis-profile=thorough``.
+
+This file is owned by ``series sync``. Edit it in the series home repo
+(robcox2910.github.io), not here, or the next sync will put it back.
+"""
+
+from hypothesis import settings
+
+settings.register_profile("ci", max_examples=100, deadline=None, derandomize=True, database=None)
+settings.register_profile("thorough", max_examples=2000, deadline=None, derandomize=False)
+settings.load_profile("ci")

fromscratch_pycoldb-0.4.0/docs/concepts/column_families.md

@@ -0,0 +1,32 @@
+# Column Families -- Gradebooks
+
+## What is a Column Family?
+
+A column family is like a **teacher's gradebook**. It's a named collection of rows (student records), where each row can have different columns.
+
+Think of your school having different gradebooks:
+- The **"grades"** gradebook has math scores, science scores, etc.
+- The **"attendance"** gradebook has Monday, Tuesday, Wednesday entries
+- The **"contacts"** gradebook has phone numbers and emails
+
+Each gradebook (column family) groups related data together.
+
+```python
+from pycoldb import ColumnFamily, Column
+
+# Create a gradebook for grades
+grades = ColumnFamily(name="grades")
+
+# Add student grades
+grades.put("alice", Column(name="math", value="A+"))
+grades.put("alice", Column(name="science", value="A"))
+grades.put("bob", Column(name="math", value="B"))
+
+# How many students have grades?
+print(grades.row_count)  # 2
+print(grades.row_keys()) # ['alice', 'bob']
+```
+
+## Why Not Just One Big Table?
+
+Separating data into column families makes things faster. When you look up someone's grades, you don't have to read through their attendance records too. It's like having separate filing cabinets for different types of documents.

fromscratch_pycoldb-0.4.0/docs/concepts/columns.md

@@ -0,0 +1,35 @@
+# Columns -- The Building Blocks
+
+## What is a Column?
+
+A column is like a **single cell** in a spreadsheet, but smarter. Each column has three parts:
+
+1. **Name** -- The column header (like "Math Grade")
+2. **Value** -- The actual data (like "A+" or 95)
+3. **Timestamp** -- When this data was written (like a date stamp)
+
+## Why Timestamps?
+
+Imagine you and your friend both try to update Alice's math grade at the same time. You write "A+" and your friend writes "A-". Which one wins?
+
+The **timestamp** solves this! Whichever write happened most recently wins. It's like a "last edited" date on a Google Doc.
+
+```python
+from pycoldb import Column
+
+# A grade recorded at time 1000
+grade_v1 = Column(name="math", value="B", timestamp=1000)
+
+# Updated later at time 2000
+grade_v2 = Column(name="math", value="A+", timestamp=2000)
+
+# The column with timestamp 2000 is the most recent
+```
+
+## What Can Go in a Column?
+
+Columns can hold different types of values:
+- **Strings**: `"A+"`, `"present"`, `"blue"`
+- **Numbers**: `95`, `3.14`
+- **Booleans**: `True`, `False`
+- **None**: For "no value" / "unknown"

fromscratch_pycoldb-0.4.0/docs/concepts/compaction.md

@@ -0,0 +1,47 @@
+# Compaction -- Cleaning Up
+
+## What is Compaction?
+
+After a while, your data can get messy. You've got:
+- **Tombstones** (crossed-out data waiting to be cleaned up)
+- **Expired columns** (sticky notes whose time has run out)
+
+**Compaction** is like going through your messy notebook and rewriting everything on a fresh page, leaving out all the crossed-out stuff and expired sticky notes.
+
+## Why Compact?
+
+1. **Save space** -- Tombstones and expired data take up room
+2. **Speed up reads** -- Less clutter means faster lookups
+3. **Keep things tidy** -- A clean database is a happy database
+
+```python
+from pycoldb import ColumnFamily, Column
+from pycoldb.compaction import compact_column_family
+
+grades = ColumnFamily(name="grades")
+
+# Add some data
+grades.put("alice", Column(name="math", value="A+"))
+grades.put("alice", Column(name="science", value="A"))
+grades.put("bob", Column(name="math", value="B"))
+
+# Delete some data (creates tombstones)
+grades.delete_column("alice", "science")
+grades.delete_column("bob", "math")
+
+# Compact! Returns how many entries were cleaned up
+cleaned = compact_column_family(grades)
+print(f"Cleaned up {cleaned} entries")  # Cleaned up 2 entries
+```
+
+## Compaction Never Changes an Answer
+
+Compaction is tidying, not editing. Whatever a read returned just before
+compaction, it returns just after. That's why a row whose grades have all
+been deleted or have expired already counts as missing *before* compaction:
+`get_row` raises `RowNotFoundError`, exactly as it will once compaction has
+thrown the empty record card away.
+
+## When Does Compaction Happen?
+
+In real databases like Cassandra, compaction runs automatically in the background. In our educational version, you call it manually whenever you want to clean up. This lets you see exactly what's happening and learn how it works!