PyKV

An educational key-value store built from scratch in Python.

Part of the PyLearn 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

from pykv.store import BasicStore

store = BasicStore()
store.set("greeting", "hello")
print(store.get("greeting"))  # "hello"

Releasing

Other projects in the series (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.

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 for the full story.

Documentation

Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pykv/