Development

README.md

@@ -9,6 +9,31 @@ For setup, usage, architecture, persistence, and contribution guidance, see the
 
 ## Quick Start
 
+### Use as Python library
+
+Install using
+
+- pip:
+```bash
+pip install git+https://github.com/danieldeer/seriousdb.git
+```
+Or
+- uv:
+```bash
+uv add git+https://github.com/danieldeer/seriousdb.git
+```
+
+Then use it directly form your python project:
+
+```python
+import seriousdb
+
+seriousdb.set("name", "Alice")
+print(seriousdb.get("name"))
+```
+
+### Run as HTTP server
+
 Clone the repository, install the project, and start the development server:
 
 ```bash

docs/api.md

@@ -1,6 +1,46 @@
 # API reference
 
-The server exposes a small HTTP API through FastAPI.
+seriousdb can be used as a storage layer directly from Python, or through
+the small HTTP API exposed by the FastAPI server.
+
+## Python API
+
+Other Python projects can import seriousdb and call its functions directly.
+
+```python
+import seriousdb
+
+seriousdb.set("name", "Alice")
+seriousdb.get("name")
+```
+
+All functions operate on a single shared cache and are thread-safe.
+The database file (default: `.sdb`) is loaded automatically on the first call.
+Use `seriousdb.load(path)` to load a different file explicitly.
+
+`set` and `delete` flush the database file before they return, so a successful call is persisted.
+
+| Function | Description |
+| :--- | :--- |
+| `get(key)` | Return the value stored under `key`. Raises `ResourceNotFoundError` if the key does not exist. |
+| | |
+| `set(key, value)` | Store `value` under `key`, overwriting any existing value. Returns the stored value. |
+| | |
+| `delete(key)` | Remove `key` and return its previous value. Raises `ResourceNotFoundError` if the key does not exist. |
+| | |
+| `exists(key)` | Return whether `key` exists. |
+| | |
+| `get_all()` | Return a snapshot of every key-value pair. |
+| | |
+| `get_bulk(keys)` | Return the values for multiple keys; missing keys are omitted. |
+| | |
+| `count()` | Return the number of stored key-value pairs. |
+
+The Python API raises the same application exceptions as the HTTP layer,
+e.g. `seriousdb.exceptions.ResourceNotFoundError`.
+
+
+## HTTP API
 
 Interactive OpenAPI documentation is available at `http://127.0.0.1:8000/docs` while the server is running.
 

docs/development.md

@@ -25,13 +25,19 @@ uv run run.py
 
 ## Nix
 
+>The project provides a Nix development environment with the tools required for local development.
+
 ### Enter Nix develop
 
+From the project root, run:
+
 ```bash
 nix develop
 ```
 
-## Starting in Nix develop
+This starts a shell with the project's development dependencies available.
+
+## Nix (in the Nix Shell) 
 
 ```bash
 python run.py
@@ -50,50 +56,73 @@ The readiness endpoint is available at `/health`.
 
 ## Formatting
 
-Format Python files with `ruff`:
+### Format Python files with `ruff`:
+
+#### uv
 
 ```bash
 uv run ruff format .
 ```
 
-To check formatting without changing files:
+### Nix (in Nix Shell)
+
+```bash
+ruff format .
+```
+
+### To check formatting without changing files:
+
+#### uv
 
 ```bash
 uv run ruff format --check .
 ```
 
-### Nix in Nix develop
+### Nix (in Nix Shell)
 
 ```bash
-ruff format .
+ruff format --check .
 ```
 
 ## Linting
 
-Lint python files with `ruff`:
+### Lint python files with `ruff`:
+
+#### uv
 
 ```bash
 uv run ruff check .
 ```
 
-Type checking with `ty`:
+#### Nix (in Nix Shell)
+
+```bash
+ruff check .
+```
+
+### Type checking with `ty`
+
+#### uv
+
 ```bash
 uv run ty check .
 ```
 
-### Nix in Nix develop
+#### Nix (in Nix Shell)
 
 ```bash
-ruff check .
+ty check .
 ```
 
-To fix linter errors and warning if possible run following command:
+### To fix linter errors and warning if possible run following command:
+
+#### uv
 
 ```bash
 uv run ruff check --fix .
 ```
 
-### Nix in Nix develop
+### Nix (in Nix Shell)
 
 ```bash
 ruff check --fix .

flake.nix

@@ -19,17 +19,25 @@
         system:
         let
           pkgs = import nixpkgs { inherit system; };
+
           python = pkgs.python314.withPackages (
             pythonPackages: with pythonPackages; [
-              ruff
               fastapi
               fastapi-cli
+              python-dotenv
+              uvicorn
+
+              pytest
+              pytest-benchmark
+              ruff
+              ty
             ]
           );
         in
         {
           default = pkgs.mkShell {
             packages = [ python ];
+
             shellHook = ''
               export PYTHONPATH="${toString ./.}/src''${PYTHONPATH:+:$PYTHONPATH}"
             '';

pyproject.toml

@@ -64,3 +64,6 @@ convention = "numpy"
 
 [tool.ruff.format]
 docstring-code-format = true
+
+[tool.ty.environment]
+root = ["."]

src/seriousdb/__init__.py

@@ -1 +1,29 @@
-"""SeriousDB, a small key-value store served over HTTP with FastAPI."""
+"""SeriousDB, a small persistent key-value database.
+
+seriousdb can be used as a storage layer from other Python projects.
+>>> import seriousdb as sdb
+>>> sdb.set("name", "Alice")
+'Alice'
+>>> sdb.get("name")
+'Alice'
+"""
+
+from seriousdb.api import (
+    count,
+    delete,
+    exists,
+    get,
+    get_all,
+    get_bulk,
+    set,
+)
+
+__all__ = [
+    "count",
+    "delete",
+    "exists",
+    "get",
+    "get_all",
+    "get_bulk",
+    "set",
+]