fromscratch-pycoldb 0.4.0__py3-none-any.whl

fromscratch_pycoldb-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+pycoldb/__init__.py,sha256=RAeXrOTOZuneYqnMZGyNXD3GMq6Opx7epLuMhb9fusw,1997
+pycoldb/_version.py,sha256=HGBlVvZpQ8N2kh1n_LY5PM4s9ljcIgdbOCgXN-uFje4,520
+pycoldb/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pycoldb/column.py,sha256=zpsjnqekaO7hN6nyG-e4AyagpkBUNOLsDUv7n1Ar8WA,2108
+pycoldb/column_family.py,sha256=ptZ8aWXUP4iVH5QJHrvqE4AvPR6zvgqlgNdgHFKHzHo,10306
+pycoldb/compaction.py,sha256=1gCKPCtPQTuzFFNhckpx6R_kkAXAY_asUzLHqKRW1Wg,2596
+pycoldb/errors.py,sha256=S6SZy5GZvvOV_R-1D68GoyB9RyOnIU0aifAL1QHw0Pk,2658
+pycoldb/keyspace.py,sha256=SYRTjZ8ILh1L8xp1qdh_drNxHPeiDCzCWoV0sb169_w,6279
+pycoldb/persistence.py,sha256=7ZNqERzSQLTdnpkHPG1uVBECNBVQDbX6-k8uQkhGS7o,7925
+pycoldb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycoldb/query.py,sha256=lyGa0gL0UVF8-FRrSfJ-ai75aZAI-3WE6DzcMYpPOZw,4626
+pycoldb/row.py,sha256=0w892qWqnlhIiK75OkLOf6QbUT78BwuYjbJEf65r5B4,9515
+pycoldb/tombstone.py,sha256=_Xt_4B2t66xLLr1W1zekvR0ZmvFj58zxZ0Za3e46Zc0,2292
+pycoldb/ttl.py,sha256=XtbI3E19ImboY2v9NslsUlh3IArI9z7HK-rw7Lzk41I,8993
+fromscratch_pycoldb-0.4.0.dist-info/METADATA,sha256=JuKzTc4tidccOR4LH3Ibr1-RxpqSamHE6DH_dMFxOLM,7304
+fromscratch_pycoldb-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pycoldb-0.4.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pycoldb-0.4.0.dist-info/RECORD,,

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

pycoldb/__init__.py

@@ -0,0 +1,65 @@
+"""PyColDB -- An educational column-family store built from scratch in Python.
+
+A column-family store (also called a wide-column store) is a type of NoSQL
+database where each row can have different columns. Think of it like a
+spreadsheet where every row is allowed to have different column headers!
+
+Real-world column-family stores include Apache Cassandra and HBase. This
+library teaches the core concepts in a simple, understandable way.
+
+Quick Start:
+    >>> from pycoldb import Keyspace, Column
+    >>> school = Keyspace(name="school")
+    >>> school.create_column_family("grades")
+    ColumnFamily(name='grades', ...)
+    >>> school.put("grades", "alice", Column(name="math", value="A+"))
+    >>> school.get_column("grades", "alice", "math").value
+    'A+'
+"""
+
+from pycoldb.column import Column
+from pycoldb.column_family import ColumnFamily
+from pycoldb.compaction import compact_all, compact_column_family
+from pycoldb.errors import (
+    ColumnFamilyAlreadyExistsError,
+    ColumnFamilyNotFoundError,
+    ColumnNotFoundError,
+    InvalidTTLError,
+    KeyspaceAlreadyExistsError,
+    KeyspaceNotFoundError,
+    PersistenceError,
+    PyColDBError,
+    RowNotFoundError,
+)
+from pycoldb.keyspace import Keyspace
+from pycoldb.persistence import load_keyspace, save_keyspace
+from pycoldb.query import column_filter, query_with_filter, range_query
+from pycoldb.row import Row
+from pycoldb.tombstone import Tombstone
+from pycoldb.ttl import TTLEntry, TTLManager
+
+__all__ = [
+    "Column",
+    "ColumnFamily",
+    "ColumnFamilyAlreadyExistsError",
+    "ColumnFamilyNotFoundError",
+    "ColumnNotFoundError",
+    "InvalidTTLError",
+    "Keyspace",
+    "KeyspaceAlreadyExistsError",
+    "KeyspaceNotFoundError",
+    "PersistenceError",
+    "PyColDBError",
+    "Row",
+    "RowNotFoundError",
+    "TTLEntry",
+    "TTLManager",
+    "Tombstone",
+    "column_filter",
+    "compact_all",
+    "compact_column_family",
+    "load_keyspace",
+    "query_with_filter",
+    "range_query",
+    "save_keyspace",
+]

pycoldb/_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.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
+
+__commit_id__ = commit_id = None

pycoldb/atomic.py

@@ -0,0 +1,66 @@
+"""Safe saving -- never leave a half-written file behind.
+
+The usual way to save a file is: open it, wipe it, write the new
+contents. If the computer crashes after the wipe but before the writing
+finishes, your data is gone -- the old version was wiped and the new one
+never arrived.
+
+So we save like a careful student copying out their homework:
+
+1. Write the new version on a **fresh sheet** (a temporary file sitting
+   right next to the real one).
+2. Make sure the **ink is dry** -- ``fsync`` forces the bytes out of the
+   computer's memory and onto the disk.
+3. **Swap** the fresh sheet in for the old one in a single instant step
+   (``Path.replace``). There is never a moment with no complete file: you
+   see either the old version or the new one, never half of each.
+
+Real databases (SQLite, PostgreSQL, Redis) all use this same trick.
+"""
+
+import contextlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+# Permissions for a brand-new file: owner can read/write, others can read.
+_NEW_FILE_MODE = 0o644
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Replace the file at *path* with *text*, so a crash can never leave it half-written.
+
+    Args:
+        path: The file to create or replace (its folder must already exist).
+        text: The new contents, saved as UTF-8.
+
+    """
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else _NEW_FILE_MODE
+    fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as temp_file:
+            temp_file.write(text)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+        temp_path.chmod(mode)
+        temp_path.replace(path)
+    except BaseException:
+        temp_path.unlink(missing_ok=True)  # don't leave the scrap sheet lying around
+        raise
+    _sync_folder(path.parent)
+
+
+def _sync_folder(folder: Path) -> None:
+    """Make the swap itself durable by syncing the folder's list of files.
+
+    Some systems (like Windows) can't sync a folder; there the swap is
+    still safe, just not guaranteed to survive a power cut.
+    """
+    with contextlib.suppress(OSError):
+        fd = os.open(folder, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)

pycoldb/column.py

@@ -0,0 +1,73 @@
+"""Column data structure for the column-family store.
+
+Think of a column like a single cell in a spreadsheet. Each cell has:
+- A **name** (the column header, like "Math Grade")
+- A **value** (the actual data, like "A+")
+- A **timestamp** (when the data was written, like a date stamp)
+
+Unlike a regular spreadsheet, every cell remembers exactly when it was
+last updated. This is super useful for knowing which data is newest!
+
+Example:
+    >>> from pycoldb.column import Column
+    >>> grade = Column(name="math", value="A+", timestamp=1000)
+    >>> grade.name
+    'math'
+    >>> grade.value
+    'A+'
+
+"""
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Column:
+    """A single named value with a timestamp.
+
+    A column is the smallest unit of data in a column-family store.
+    Think of it as one cell in a spreadsheet that also remembers
+    when it was last changed.
+
+    Attributes:
+        name: The column name (like a spreadsheet header).
+        value: The stored data (can be any JSON-serializable value).
+        timestamp: When this column was last written (epoch seconds).
+            If not provided, uses the current time.
+
+    """
+
+    name: str
+    value: str | int | float | bool | None
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict[str, str | int | float | bool | None]:
+        """Convert this column to a dictionary for serialization.
+
+        Returns:
+            A dictionary with name, value, and timestamp keys.
+
+        """
+        return {
+            "name": self.name,
+            "value": self.value,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str | int | float | bool | None]) -> Column:
+        """Create a Column from a dictionary.
+
+        Args:
+            data: Dictionary with name, value, and timestamp keys.
+
+        Returns:
+            A new Column instance.
+
+        """
+        return cls(
+            name=str(data["name"]),
+            value=data["value"],
+            timestamp=float(data.get("timestamp", 0.0) or 0.0),
+        )