fromscratch-pykv 0.4.0__py3-none-any.whl

fromscratch_pykv-0.4.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: fromscratch-pykv
+Version: 0.4.0
+Summary: An educational key-value store library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pykv
+Project-URL: Repository, https://github.com/robcox2910/pykv
+Project-URL: Issues, https://github.com/robcox2910/pykv/issues
+Project-URL: Documentation, https://robcox2910.github.io/pykv/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: cache,education,key-value,store
+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
+
+# PyKV
+
+An educational key-value store built from scratch in Python.
+
+Part of the [PyLearn](https://github.com/robcox2910) series — learning computer science by building real tools.
+
+## What Is a Key-Value Store?
+
+Think of a **phonebook**: you look up a name (the *key*) and get back a phone number (the *value*). A key-value store works the same way — it's the simplest kind of database.
+
+## Features
+
+- **Get / Set / Delete** — basic phonebook operations
+- **TTL (Time-To-Live)** — keys that expire, like milk with a use-by date
+- **Multiple Data Types** — store strings, numbers, lists, and dicts
+- **Persistence** — save to disk so data survives a restart
+- **Namespaces** — group keys like folders in a filing cabinet
+- **Batch Operations** — handle many keys at once, like a grocery list
+- **Atomic Counters** — thread-safe increment/decrement, like a tally counter
+- **Pattern Matching** — find keys matching a glob pattern
+
+## Quick Start
+
+```python
+from pykv.store import BasicStore
+
+store = BasicStore()
+store.set("greeting", "hello")
+print(store.get("greeting"))  # "hello"
+```
+
+## 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/pykv/
+<!-- docs:end -->

fromscratch_pykv-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pykv/__init__.py,sha256=TpQ1KNWdTqPxMx0BJ6CcCMN-GLfEdSN7O3W_wRrSdPo,2025
+pykv/_version.py,sha256=HGBlVvZpQ8N2kh1n_LY5PM4s9ljcIgdbOCgXN-uFje4,520
+pykv/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pykv/batch.py,sha256=LKMVD5CZ1FTNsssbSX6sGNGT5rHIKB4mflVTa3q2hS8,3176
+pykv/counters.py,sha256=4nrcG04kGJu3kS24nyOQHXdsXUk1F1hnoKVCnqoP6j0,4087
+pykv/errors.py,sha256=6VJJ2eHHPcB_8dDJDVbbbiZmvzfjvzrZGHbXjfPG7TQ,2187
+pykv/namespace.py,sha256=27ljO5mL7RDdPFRhTgDmyQslPCtUJrkw_QjQfft15Ss,7807
+pykv/patterns.py,sha256=RnEepUDjdsYG72r2zwuAQX8jL73yTu7vvOMl2C7koUk,2463
+pykv/persistence.py,sha256=I5yzHMiWkbWnXVfkZmz7NUP7pSap8AgSFCXYnLsj_90,4984
+pykv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pykv/store.py,sha256=jW-1tLO-vMZ8-t5YlX9gDQezVPDMoRsmRGiDLcMlmAQ,5094
+pykv/ttl.py,sha256=-S2nIfBJwSen1H5NQVmlmVa2ATELkbLKrj3k_Pcih9w,8286
+pykv/types.py,sha256=DV_kXwZFpHsskAzyAP2BhqBUOgPBHcSLiaQy4vx3q0c,3311
+fromscratch_pykv-0.4.0.dist-info/METADATA,sha256=VGEh_EZJUoal3HywhiRkvbYy0uUu0j8StKPD3CR3SDE,5820
+fromscratch_pykv-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pykv-0.4.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pykv-0.4.0.dist-info/RECORD,,

fromscratch_pykv-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_pykv-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.

pykv/__init__.py

@@ -0,0 +1,73 @@
+"""PyKV -- an educational key-value store built from scratch in Python.
+
+A key-value store is like a giant phonebook for your data. You give each
+piece of information a unique name (the "key") and store some data (the
+"value") next to it. Later, you can look up the data just by knowing
+its name -- lightning fast!
+
+Real-world key-value stores like Redis and Memcached power some of the
+biggest websites in the world. PyKV teaches you how they work from the
+inside, one piece at a time.
+
+Quick start:
+    >>> from pykv import BasicStore
+    >>> store = BasicStore()
+    >>> store.set("greeting", "Hello, world!")
+    >>> store.get("greeting")
+    'Hello, world!'
+
+Features:
+    - BasicStore: Simple get/set/delete operations
+    - TTLStore: Keys that expire after a time limit
+    - Namespace: Group keys with prefixes
+    - AtomicCounter: Thread-safe counters
+    - Persistence: Save and load from disk
+    - Batch operations: Work with many keys at once
+    - Pattern matching: Find keys with wildcards
+"""
+
+from pykv.batch import batch_delete, batch_exists, batch_get, batch_set
+from pykv.counters import AtomicCounter
+from pykv.errors import (
+    KeyExpiredError,
+    KeyNotFoundError,
+    NamespaceError,
+    PersistenceError,
+    PyKVError,
+    SerializationError,
+)
+from pykv.namespace import Namespace
+from pykv.patterns import count_matches, match_items, match_keys
+from pykv.persistence import load_store, save_store
+from pykv.store import BasicStore
+from pykv.ttl import TTLStore
+from pykv.types import StorableValue
+
+__all__ = [
+    "AtomicCounter",
+    # Core
+    "BasicStore",
+    "KeyExpiredError",
+    "KeyNotFoundError",
+    # Features
+    "Namespace",
+    "NamespaceError",
+    "PersistenceError",
+    # Errors
+    "PyKVError",
+    "SerializationError",
+    "StorableValue",
+    "TTLStore",
+    "batch_delete",
+    "batch_exists",
+    "batch_get",
+    # Batch
+    "batch_set",
+    "count_matches",
+    "load_store",
+    "match_items",
+    # Patterns
+    "match_keys",
+    # Persistence
+    "save_store",
+]

pykv/_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

pykv/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)

pykv/batch.py

@@ -0,0 +1,110 @@
+"""Batch operations -- get and set multiple keys at once.
+
+Imagine going to the grocery store. You could make one trip for each item
+on your list -- milk, bread, eggs -- but that would be exhausting! Instead,
+you take your whole shopping list and grab everything in one trip. Batch
+operations work the same way: instead of calling get() or set() over and
+over, you do it all at once.
+
+This is more convenient -- one call instead of many -- especially when you
+have lots of keys to work with. Under the hood it is still a plain loop
+calling ``set`` or ``get`` one key at a time, so it is not actually faster
+than doing it yourself; it just keeps your code short and tidy.
+
+Example:
+    >>> store = BasicStore()
+    >>> batch_set(store, {"name": "Alice", "age": 13, "grade": 8})
+    >>> batch_get(store, ["name", "age"])
+    {'name': 'Alice', 'age': 13}
+
+"""
+
+from pykv.store import BasicStore
+from pykv.types import StorableValue
+
+
+def batch_set(store: BasicStore, items: dict[str, StorableValue]) -> None:
+    """Set multiple key-value pairs in one call.
+
+    Like dropping off your whole grocery bag at once instead of
+    putting items away one by one.
+
+    Args:
+        store: The store to write to.
+        items: A dictionary of key-value pairs to set.
+
+    """
+    for key, value in items.items():
+        store.set(key, value)
+
+
+def batch_get(
+    store: BasicStore,
+    keys: list[str],
+    *,
+    skip_missing: bool = False,
+) -> dict[str, StorableValue]:
+    """Retrieve multiple values in one call.
+
+    Like reading multiple entries from your phonebook at once.
+    If ``skip_missing`` is True, keys that do not exist are silently
+    skipped. Otherwise, a ``KeyNotFoundError`` is raised for any
+    missing key.
+
+    Args:
+        store: The store to read from.
+        keys: A list of keys to retrieve.
+        skip_missing: If True, skip keys that do not exist instead of raising.
+
+    Returns:
+        A dictionary of the found key-value pairs.
+
+    Raises:
+        KeyNotFoundError: If a key is missing and skip_missing is False.
+
+    """
+    result: dict[str, StorableValue] = {}
+    for key in keys:
+        if skip_missing:
+            if store.exists(key):
+                result[key] = store.get(key)
+        else:
+            result[key] = store.get(key)
+    return result
+
+
+def batch_delete(store: BasicStore, keys: list[str]) -> int:
+    """Delete multiple keys in one call.
+
+    Like erasing several entries from your phonebook at once.
+
+    Args:
+        store: The store to delete from.
+        keys: A list of keys to remove.
+
+    Returns:
+        The number of keys that were actually deleted.
+
+    """
+    count = 0
+    for key in keys:
+        if store.delete(key):
+            count += 1
+    return count
+
+
+def batch_exists(store: BasicStore, keys: list[str]) -> dict[str, bool]:
+    """Check whether multiple keys exist in one call.
+
+    Like scanning your phonebook for a list of names and marking
+    which ones you found.
+
+    Args:
+        store: The store to check.
+        keys: A list of keys to look for.
+
+    Returns:
+        A dictionary mapping each key to True/False.
+
+    """
+    return {key: store.exists(key) for key in keys}

pykv/counters.py

@@ -0,0 +1,137 @@
+"""Atomic counters -- thread-safe increment and decrement.
+
+Imagine a tally counter (the clicky thing a bouncer uses to count people
+entering a club). Every time someone walks in, you click +1. Every time
+someone leaves, you click -1. The key word is "atomic" -- each click is
+one single, unbreakable action. Even if two people try to click at the
+exact same time, the counter never gets confused.
+
+In programming, this matters when multiple threads (like multiple workers)
+try to update the same number at the same time. Without atomic operations,
+two threads reading "5" at the same time might both write "6" instead of
+one writing "6" and the other writing "7".
+
+Example:
+    >>> store = BasicStore()
+    >>> counter = AtomicCounter(store)
+    >>> counter.increment("visitors")
+    1
+    >>> counter.increment("visitors")
+    2
+    >>> counter.decrement("visitors")
+    1
+
+"""
+
+import threading
+
+from pykv.errors import KeyNotFoundError
+from pykv.store import BasicStore
+from pykv.types import StorableValue
+
+
+class AtomicCounter:
+    """Thread-safe counter operations on integer keys in a BasicStore.
+
+    Like a digital tally counter that multiple people can click at the
+    same time without it ever getting confused. Each click (increment
+    or decrement) is guaranteed to be accurate.
+    """
+
+    def __init__(self, store: BasicStore) -> None:
+        """Create an atomic counter backed by the given store.
+
+        Args:
+            store: The BasicStore to use for storing counter values.
+
+        """
+        self._store = store
+        self._lock = threading.Lock()
+
+    def increment(self, key: str, amount: int = 1) -> int:
+        """Increase a counter by the given amount, creating it if needed.
+
+        Like clicking the tally counter one or more times. If the counter
+        does not exist yet, it starts at 0 before incrementing.
+
+        Args:
+            key: The counter name.
+            amount: How much to add (default 1).
+
+        Returns:
+            The new counter value after incrementing.
+
+        """
+        with self._lock:
+            current = self._get_int(key)
+            new_value = current + amount
+            self._store.set(key, new_value)
+            return new_value
+
+    def decrement(self, key: str, amount: int = 1) -> int:
+        """Decrease a counter by the given amount, creating it if needed.
+
+        Like un-clicking the tally counter. The counter can go negative
+        (below zero) -- there is no floor.
+
+        Args:
+            key: The counter name.
+            amount: How much to subtract (default 1).
+
+        Returns:
+            The new counter value after decrementing.
+
+        """
+        with self._lock:
+            current = self._get_int(key)
+            new_value = current - amount
+            self._store.set(key, new_value)
+            return new_value
+
+    def get_value(self, key: str) -> int:
+        """Read the current counter value.
+
+        Like glancing at the number on the tally counter without clicking
+        it. If nobody has clicked it yet, it reads 0.
+
+        Args:
+            key: The counter name.
+
+        Returns:
+            The current integer value, or 0 if the counter does not exist.
+
+        """
+        with self._lock:
+            return self._get_int(key)
+
+    def reset(self, key: str) -> None:
+        """Reset a counter to zero.
+
+        Like clearing the tally counter back to 0.
+
+        Args:
+            key: The counter name to reset.
+
+        """
+        with self._lock:
+            self._store.set(key, 0)
+
+    def _get_int(self, key: str) -> int:
+        """Read the current integer value of a key, defaulting to 0.
+
+        Args:
+            key: The key to read.
+
+        Returns:
+            The integer value, or 0 if the key does not exist.
+
+        """
+        try:
+            value: StorableValue = self._store.get(key)
+        except KeyNotFoundError:
+            return 0
+
+        if not isinstance(value, int):
+            msg = f"Counter key {key!r} holds a {type(value).__name__}, not an int"
+            raise TypeError(msg)
+        return value

pykv/errors.py

@@ -0,0 +1,68 @@
+"""Custom exceptions for PyKV.
+
+Think of exceptions like warning signs on a road. They tell you when something
+goes wrong so you can handle it properly instead of crashing. Each exception
+type is like a different road sign -- "Key Not Found" is like "Road Closed",
+while "Type Error" is like "Wrong Way".
+"""
+
+
+class PyKVError(Exception):
+    """Base exception for all PyKV errors.
+
+    Every PyKV error inherits from this class, like how every animal
+    inherits from the "Animal" category. This lets you catch ALL PyKV
+    errors with a single ``except PyKVError`` block.
+    """
+
+
+class KeyNotFoundError(PyKVError):
+    """Raise when a requested key does not exist in the store.
+
+    Imagine looking up a word in a dictionary and it is not there.
+    That is what this error represents.
+    """
+
+    def __init__(self, key: str) -> None:
+        """Initialize with the missing key name."""
+        self.key = key
+        super().__init__(f"Key not found: {key!r}")
+
+
+class KeyExpiredError(PyKVError):
+    """Raise when a key has expired due to its TTL.
+
+    Like trying to drink milk after the expiration date -- the key
+    existed once, but its time-to-live has passed.
+    """
+
+    def __init__(self, key: str) -> None:
+        """Initialize with the expired key name."""
+        self.key = key
+        super().__init__(f"Key has expired: {key!r}")
+
+
+class SerializationError(PyKVError):
+    """Raise when a value cannot be serialized or deserialized.
+
+    Some things cannot be written down in a notebook. If you try to
+    store something that PyKV cannot convert to a saveable format,
+    you get this error.
+    """
+
+
+class PersistenceError(PyKVError):
+    """Raise when saving to or loading from disk fails.
+
+    Like trying to save your game but the memory card is full or
+    broken. Something went wrong with the file on disk.
+    """
+
+
+class NamespaceError(PyKVError):
+    """Raise when a namespace name or a key inside a namespace breaks the rules.
+
+    Folders in a filing cabinet must never share a paper. A namespace
+    name can't be empty, and a key inside a namespace can't contain
+    the ``:`` separator -- otherwise one folder could reach into another.
+    """