Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 36 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ JSONLT is a data format for storing keyed records in append-only files using [JS
## Installation

```bash
pip install jsonlt
pip install jsonlt-python

# Or

uv add jsonlt
uv add jsonlt-python
```

## Quick start
Expand Down Expand Up @@ -132,23 +132,23 @@ table.clear()

The `Table` class is the primary interface for working with JSONLT files.

| Method | Description |
| ------ | ----------- |
| `Table(path, key)` | Open or create a table at the given path |
| `get(key)` | Get a record by key, returns `None` if not found |
| `has(key)` | Check if a key exists |
| `put(record)` | Insert or update a record |
| `delete(key)` | Delete a record, returns whether it existed |
| `all()` | Get all records in key order |
| `keys()` | Get all keys in key order |
| `items()` | Get all (key, record) pairs in key order |
| `count()` | Get the number of records |
| `find(predicate, limit=None)` | Find records matching a predicate |
| `find_one(predicate)` | Find the first matching record |
| `transaction()` | Start a new transaction |
| `compact()` | Compact the table file |
| `clear()` | Remove all records |
| `reload()` | Force reload from disk |
| Method | Description |
|-------------------------------|--------------------------------------------------|
| `Table(path, key)` | Open or create a table at the given path |
| `get(key)` | Get a record by key, returns `None` if not found |
| `has(key)` | Check if a key exists |
| `put(record)` | Insert or update a record |
| `delete(key)` | Delete a record, returns whether it existed |
| `all()` | Get all records in key order |
| `keys()` | Get all keys in key order |
| `items()` | Get all (key, record) pairs in key order |
| `count()` | Get the number of records |
| `find(predicate, limit=None)` | Find records matching a predicate |
| `find_one(predicate)` | Find the first matching record |
| `transaction()` | Start a new transaction |
| `compact()` | Compact the table file |
| `clear()` | Remove all records |
| `reload()` | Force reload from disk |

The `Table` class also supports idiomatic Python operations:

Expand All @@ -160,37 +160,28 @@ The `Table` class also supports idiomatic Python operations:

The `Transaction` class provides snapshot isolation and buffered writes.

| Method | Description |
| ------ | ----------- |
| `get(key)` | Get a record from the transaction snapshot |
| `has(key)` | Check if a key exists in the snapshot |
| `put(record)` | Buffer a record for commit |
| `delete(key)` | Buffer a deletion for commit |
| `commit()` | Write buffered changes to disk |
| `abort()` | Discard buffered changes |
| Method | Description |
|---------------|--------------------------------------------|
| `get(key)` | Get a record from the transaction snapshot |
| `has(key)` | Check if a key exists in the snapshot |
| `put(record)` | Buffer a record for commit |
| `delete(key)` | Buffer a deletion for commit |
| `commit()` | Write buffered changes to disk |
| `abort()` | Discard buffered changes |

### Exception hierarchy

All exceptions inherit from `JSONLTError`:

| Exception | Description |
| --------- | ----------- |
| `ParseError` | Invalid file format or content |
| `InvalidKeyError` | Invalid or missing key |
| `FileError` | File I/O error |
| `LockError` | Cannot obtain file lock |
| `LimitError` | Size limit exceeded |
| `TransactionError` | Transaction state error |
| `ConflictError` | Write-write conflict detected |

### Type exports

For type annotations, the package exports:

- `Key` - A key value (`str`, `int`, or tuple of these)
- `KeySpecifier` - Key field names (single or multiple)
- `JSONObject` - A JSON object (`dict[str, Any]`)
- `Header` - Table header data class
| Exception | Description |
|--------------------|--------------------------------|
| `ParseError` | Invalid file format or content |
| `InvalidKeyError` | Invalid or missing key |
| `FileError` | File I/O error |
| `LockError` | Cannot obtain file lock |
| `LimitError` | Size limit exceeded |
| `TransactionError` | Transaction state error |
| `ConflictError` | Write-write conflict detected |

## Documentation

Expand Down
5 changes: 4 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ requires = ["uv_build>=0.9.11,<0.10.0"]
build-backend = "uv_build"

[project]
name = "jsonlt"
name = "jsonlt-python"
version = "0.0.0"
description = "A library for using a JSON Lines (JSONL) file as a lightweight database."
readme = "README.md"
Expand Down Expand Up @@ -172,3 +172,6 @@ ignore-variadic-names = true
"S101", # assert statements in tests
"PLR2004", # magic values in assertions in tests
]

[tool.uv.build-backend]
module-name = "jsonlt"
2 changes: 1 addition & 1 deletion src/jsonlt/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
from ._table import Table
from ._transaction import Transaction

__version__ = version("jsonlt")
__version__ = version("jsonlt-python")

__all__ = [
"ConflictError",
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.