objbase 0.4.0__tar.gz → 0.5.1__tar.gz

{objbase-0.4.0 → objbase-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: objbase
-Version: 0.4.0
+Version: 0.5.1
 Summary: Damn simple object store for Python dicts and Pydantic models across multiple backends
 Project-URL: Homepage, https://github.com/fm-labs/objbase
 Project-URL: Issues, https://github.com/fm-labs/objbase/issues
@@ -41,10 +41,10 @@ __No thrills__ - **just a simple key-value store for serializable Python objects
 
 ## What you get
 
-- Basic CRUD operations: `save`, `get`, `filter`, `keys`, `patch`, `delete`
+- Basic CRUD operations: `save`, `get`, `items`, `keys`, `patch`, `delete`
 - Multiple storage adapters (in-memory, file-based, SQLite, Redis, MongoDB)
-- Optional Pydantic model validation with `PydanticInventory` / `AsyncPydanticInventory`
-- Async support via `AsyncInventory` with async storage adapters (in-memory, file-based, SQLite, Redis, MongoDB)
+- Optional Pydantic model validation with `PydanticCollection` / `AsyncPydanticCollection`
+- Async support via `AsyncCollection` with async storage adapters (in-memory, file-based, SQLite, Redis, MongoDB)
 - Easy FastAPI integration with dependency injection
 - Fully typed (ships `py.typed`), checked with `mypy --strict`
 
@@ -60,7 +60,7 @@ and SQLite storage work out of the box. Install extras for the other backends:
 pip install objbase              # core only
 pip install "objbase[redis]"     # + redis-py, for (Async)RedisStorage
 pip install "objbase[mongodb]"   # + pymongo, for (Async)MongoDBStorage
-pip install "objbase[pydantic]"  # + pydantic, for (Async)PydanticInventory
+pip install "objbase[pydantic]"  # + pydantic, for (Async)PydanticCollection
 pip install "objbase[all]"       # everything
 # or with uv
 uv add "objbase[redis]"
@@ -70,25 +70,25 @@ uv add "objbase[redis]"
 
 ## Quick Start
 
-Every item must have an `"id"` field. Use `Inventory` with any storage adapter:
+Every item must have an `"id"` field. Use `Collection` with any storage adapter:
 
 ```python
-from objbase import Inventory, InMemoryStorage
+from objbase import Collection, InMemoryStorage
 
 storage = InMemoryStorage()
-todos = Inventory(item_type="todo", storage=storage)
+todos = Collection(item_type="todo", storage=storage)
 
 todos.save({"id": "1", "title": "Buy milk", "done": False})
 todos.save({"id": "2", "title": "Walk dog", "done": False})
 
 todos.get("1")  # → {"id": "1", "title": "Buy milk", "done": False}
-todos.filter()  # → [{"id": "1", ...}, {"id": "2", ...}]
+todos.items()  # → [{"id": "1", ...}, {"id": "2", ...}]
 todos.keys()  # → ["1", "2"] (order unspecified)
 todos.patch("1", {"done": True})  # → {"id": "1", ..., "done": True}
 todos.delete("1")  # → True
 ```
 
-Swapping the backend requires only changing the `storage` argument — the `Inventory`
+Swapping the backend requires only changing the `storage` argument — the `Collection`
 API stays identical.
 
 All public classes can be imported from the top-level `objbase` package, as above,
@@ -97,21 +97,21 @@ or from their submodules as in the examples below:
 | Module | Contents |
 |---|---|
 | `objbase.interface` | `Storage`, `AsyncStorage` protocols and the `Item` type |
-| `objbase.inventory` | `Inventory` |
-| `objbase.errors` | `InventoryError`, `ItemNotFoundError` |
-| `objbase.pydantic` | `PydanticInventory`, `AsyncPydanticInventory` (needs `objbase[pydantic]`) |
-| `objbase.storage.{inmemory,file,sqlite,redis,mongodb}_storage` | Sync storage adapters |
-| `objbase.asyncio.inventory` | `AsyncInventory` |
-| `objbase.asyncio.storage.{file,sqlite,redis,mongodb}_storage` | Async storage adapters |
+| `objbase.collection` | `Collection` |
+| `objbase.errors` | `CollectionError`, `ItemNotFoundError` |
+| `objbase.pydantic` | `PydanticCollection`, `AsyncPydanticCollection` (needs `objbase[pydantic]`) |
+| `objbase.storage.{inmemory,local,sqlite,redis,mongodb}` | Sync storage adapters |
+| `objbase.asyncio.collection` | `AsyncCollection` |
+| `objbase.asyncio.storage.{local,sqlite,redis,mongodb}` | Async storage adapters |
 
-`import objbase` works without Pydantic installed; `PydanticInventory` and
-`AsyncPydanticInventory` are loaded on first access.
+`import objbase` works without Pydantic installed; `PydanticCollection` and
+`AsyncPydanticCollection` are loaded on first access.
 
 ### Behaviour
 
 All adapters follow the same contract (verified by a shared test suite):
 
-- `get` returns `None` for a missing item; `filter` and `keys` return `[]` for an empty type.
+- `get` returns `None` for a missing item; `items` and `keys` return `[]` for an empty type.
 - `save` inserts a new item or **replaces** an existing one entirely (it does not merge fields).
 - `patch` merges the given fields into an existing item. It cannot change the item's `id`.
 - `delete` returns `True` if the item was removed, `False` if it did not exist.
@@ -123,10 +123,10 @@ Errors are raised, not returned:
 |---|---|
 | `save` an item without an `id` (or with an empty one) | `ValueError` |
 | `patch` with data that changes the item's `id` | `ValueError` |
-| `patch` a missing item | `objbase.ItemNotFoundError` (an `InventoryError` and a `LookupError`) |
-| The storage backend reports a failed write | `objbase.InventoryError` |
+| `patch` a missing item | `objbase.ItemNotFoundError` (a `CollectionError` and a `LookupError`) |
+| The storage backend reports a failed write | `objbase.CollectionError` |
 
-`InventoryError` is the base class of all objbase errors.
+`CollectionError` is the base class of all objbase errors.
 
 ---
 
@@ -135,8 +135,8 @@ Errors are raised, not returned:
 | Adapter | Sync class | Async class | When to use |
 |---|---|---|---|
 | In-Memory | `InMemoryStorage` | same class | Testing / prototyping — volatile |
-| File (one file per type) | `FileBasedStorage` | `AsyncFileBasedStorage` | Simple persistence for small datasets |
-| File (one file per item) | `DirectoryBasedStorage` | `AsyncDirectoryBasedStorage` | Medium datasets; per-item file operations |
+| File (one file per type) | `LocalFileStorage` | `AsyncLocalFileStorage` | Simple persistence for small datasets |
+| File (one file per item) | `LocalDirectoryStorage` | `AsyncLocalDirectoryStorage` | Medium datasets; per-item file operations |
 | SQLite | `SQLiteStorage` | `AsyncSQLiteStorage` | ACID persistence with zero external deps |
 | Redis | `RedisStorage` | `AsyncRedisStorage` | High-performance / distributed access |
 | MongoDB | `MongoDBStorage` | `AsyncMongoDBStorage` | Document-oriented storage and complex queries |
@@ -149,7 +149,7 @@ MongoDB ones use the drivers' native async clients.
 ### In-Memory
 
 ```python
-from objbase.storage.inmemory_storage import InMemoryStorage
+from objbase.storage.inmemory import InMemoryStorage
 
 storage = InMemoryStorage()
 ```
@@ -161,9 +161,9 @@ sync counterparts.
 ### File-Based (single file per type)
 
 ```python
-from objbase.storage.file_storage import FileBasedStorage
+from objbase.storage.local import LocalFileStorage
 
-storage = FileBasedStorage(base_dir="/var/data/myapp")
+storage = LocalFileStorage(base_dir="/var/data/myapp")
 ```
 
 All items of one type are stored in `{base_dir}/{item_type}.json`.
@@ -179,16 +179,16 @@ mid-write cannot corrupt data. Lock files are left in place after use.
 Every write rewrites the whole type file, so this adapter suits small datasets.
 Locks are advisory and may not work on network file systems (NFS, SMB).
 
-`AsyncFileBasedStorage(base_dir=...)` is the async counterpart. It uses the
+`AsyncLocalFileStorage(base_dir=...)` is the async counterpart. It uses the
 same files and locks, running each call in a worker thread (`asyncio.to_thread`),
 so it can share a directory with the sync adapter.
 
 ### File-Based (one file per item)
 
 ```python
-from objbase.storage.file_storage import DirectoryBasedStorage
+from objbase.storage.local import LocalDirectoryStorage
 
-storage = DirectoryBasedStorage(base_dir="/var/data/myapp")
+storage = LocalDirectoryStorage(base_dir="/var/data/myapp")
 ```
 
 Items are stored at `{base_dir}/{item_type}/{id}.json`.
@@ -211,14 +211,14 @@ correct with concurrent writers across threads and processes; concurrent writes
 to the same item are last-writer-wins. Locks are advisory and may not work on
 network file systems (NFS, SMB).
 
-`AsyncDirectoryBasedStorage(base_dir=...)` is the async counterpart. It uses
+`AsyncLocalDirectoryStorage(base_dir=...)` is the async counterpart. It uses
 the same files, index and locks, running each call in a worker thread
 (`asyncio.to_thread`); rebuild its index with `await storage.arebuild_index(item_type)`.
 
 ### Path safety
 
 Both file-based adapters build file paths from item types (and, for
-`DirectoryBasedStorage`, ids), so they guard against path traversal:
+`LocalDirectoryStorage`, ids), so they guard against path traversal:
 
 - Names must be a single path component: empty names, `.`, `..`, and names
   containing `/`, `\`, NUL or newlines are rejected. On Windows, `< > : " | ? *`
@@ -237,7 +237,7 @@ check and the operation. Don't give untrusted users write access to it.
 ### SQLite
 
 ```python
-from objbase.storage.sqlite_storage import SQLiteStorage
+from objbase.storage.sqlite import SQLiteStorage
 
 storage = SQLiteStorage(db_path="myapp.db")
 ```
@@ -252,15 +252,15 @@ also needs no extra dependencies.
 
 ```python
 import redis
-from objbase.storage.redis_storage import RedisStorage
+from objbase.storage.redis import RedisStorage
 
 client = redis.Redis(host="localhost", port=6379, decode_responses=True)
 storage = RedisStorage(redis_client=client)
 ```
 
-Each item type is one Redis hash, `inventory:{item_type}`, mapping item ids to
+Each item type is one Redis hash, `collection:{item_type}`, mapping item ids to
 JSON-encoded items, so value types (numbers, booleans, lists, nested dicts) are
-preserved. Pass `key_prefix="myapp:"` to use a different prefix than `inventory:`.
+preserved. Pass `key_prefix="myapp:"` to use a different prefix than `collection:`.
 
 Pass a pre-configured `redis.Redis` client (sync); `decode_responses` may be on or off.
 Requires `redis-py`. `AsyncRedisStorage` takes a `redis.asyncio.Redis` client
@@ -270,29 +270,30 @@ and uses the same layout, so sync and async adapters can share data.
 
 ```python
 import pymongo
-from objbase.storage.mongodb_storage import MongoDBStorage
+from objbase.storage.mongodb import MongoDBStorage
 
 client = pymongo.MongoClient("mongodb://localhost:27017")
 storage = MongoDBStorage(mongo_client=client)
 ```
 
-Items are stored in the `inventory` database, one collection per `item_type`.
+Items are stored in the `collection` database, one collection per `item_type`.
+Pass `db_name="myapp"` to use a different database.
 The MongoDB `_id` field is stripped from results automatically.
 Pass a pre-configured `pymongo.MongoClient`. Requires `pymongo`. `AsyncMongoDBStorage`
-takes a `pymongo.AsyncMongoClient` and uses the same layout, so sync and async adapters
+takes a `pymongo.AsyncMongoClient` (and the same `db_name` option) and uses the same layout, so sync and async adapters
 can share data. Both accept an optional MongoDB `query` in `items` / `aitems` to filter results.
 
 ---
 
 ## Pydantic Models
 
-Use `PydanticInventory` to validate items against a Pydantic `BaseModel`.
+Use `PydanticCollection` to validate items against a Pydantic `BaseModel`.
 `save` and `get` return typed model instances instead of plain dicts.
 
 ```python
 from pydantic import BaseModel
-from objbase.pydantic import PydanticInventory
-from objbase.storage.inmemory_storage import InMemoryStorage
+from objbase.pydantic import PydanticCollection
+from objbase.storage.inmemory import InMemoryStorage
 
 
 class Todo(BaseModel):
@@ -301,7 +302,7 @@ class Todo(BaseModel):
     done: bool = False
 
 
-todos = PydanticInventory(
+todos = PydanticCollection(
     item_type="todo",
     storage=InMemoryStorage(),
     model_class=Todo,
@@ -314,7 +315,7 @@ if item is not None:
 ```
 
 The model type is inferred from `model_class`, so type checkers know that
-`todos.get()` returns `Todo | None` and `todos.filter()` returns `list[Todo]`.
+`todos.get()` returns `Todo | None` and `todos.items()` returns `list[Todo]`.
 `todos.keys()` returns the item ids (`list[str]`) without loading or validating
 any items.
 
@@ -331,15 +332,15 @@ so values Pydantic coerces are stored normalized: patching `{"done": "true"}` st
 
 ### Async
 
-`AsyncPydanticInventory` has the same methods and behaviour, as coroutines, and
+`AsyncPydanticCollection` has the same methods and behaviour, as coroutines, and
 takes an async storage adapter:
 
 ```python
 import redis.asyncio
-from objbase.asyncio.storage.redis_storage import AsyncRedisStorage
-from objbase.pydantic import AsyncPydanticInventory
+from objbase.asyncio.storage.redis import AsyncRedisStorage
+from objbase.pydantic import AsyncPydanticCollection
 
-todos = AsyncPydanticInventory(
+todos = AsyncPydanticCollection(
     item_type="todo",
     storage=AsyncRedisStorage(redis.asyncio.Redis()),
     model_class=Todo,
@@ -353,31 +354,31 @@ item = await todos.get("1")  # Todo | None
 
 ## Async Usage
 
-`AsyncInventory` has the same methods and behaviour as `Inventory`, but every
+`AsyncCollection` has the same methods and behaviour as `Collection`, but every
 method is a coroutine. It works with any `AsyncStorage` adapter:
-`AsyncFileBasedStorage`, `AsyncDirectoryBasedStorage`, `AsyncSQLiteStorage`,
+`AsyncLocalFileStorage`, `AsyncLocalDirectoryStorage`, `AsyncSQLiteStorage`,
 `AsyncRedisStorage`, `AsyncMongoDBStorage`,
 or `InMemoryStorage` for tests.
 
 ```python
 import redis.asyncio
-from objbase.asyncio.inventory import AsyncInventory
-from objbase.asyncio.storage.redis_storage import AsyncRedisStorage
+from objbase.asyncio.collection import AsyncCollection
+from objbase.asyncio.storage.redis import AsyncRedisStorage
 
 client = redis.asyncio.Redis(host="localhost", port=6379)
-todos = AsyncInventory(item_type="todo", storage=AsyncRedisStorage(client))
+todos = AsyncCollection(item_type="todo", storage=AsyncRedisStorage(client))
 
 await todos.save({"id": "1", "title": "Buy milk", "done": False})
 await todos.get("1")  # → {"id": "1", "title": "Buy milk", "done": False}
-await todos.filter()  # → [{"id": "1", ...}]
+await todos.items()  # → [{"id": "1", ...}]
 await todos.keys()  # → ["1"]
 await todos.patch("1", {"done": True})  # → {"id": "1", ..., "done": True}
 await todos.delete("1")  # → True
 ```
 
-For Pydantic models, use `AsyncPydanticInventory` (see [Pydantic Models: Async](#async)).
+For Pydantic models, use `AsyncPydanticCollection` (see [Pydantic Models: Async](#async)).
 
-Passing a sync-only adapter (e.g. `SQLiteStorage`) to `AsyncInventory`
+Passing a sync-only adapter (e.g. `SQLiteStorage`) to `AsyncCollection`
 raises `TypeError`; use its async counterpart (e.g. `AsyncSQLiteStorage`) instead.
 The adapter methods (`akeys`, `aitems`, `aread`, `awrite`, `adelete`)
 can also be called directly on the storage.
@@ -390,12 +391,12 @@ Runnable scripts are in [`examples/`](examples/):
 
 | Script | Shows |
 |---|---|
-| `dict_example.py` | `Inventory` with plain dicts (in-memory) |
-| `pydantic_example.py` | `PydanticInventory` (in-memory) |
-| `async_example.py` | `AsyncInventory` (in-memory) |
-| `async_pydantic_example.py` | `AsyncPydanticInventory` (in-memory) |
-| `async_file_example.py` | `AsyncFileBasedStorage` |
-| `async_directory_example.py` | `AsyncDirectoryBasedStorage`, incl. concurrent saves and `arebuild_index` |
+| `dict_example.py` | `Collection` with plain dicts (in-memory) |
+| `pydantic_example.py` | `PydanticCollection` (in-memory) |
+| `async_example.py` | `AsyncCollection` (in-memory) |
+| `async_pydantic_example.py` | `AsyncPydanticCollection` (in-memory) |
+| `async_file_example.py` | `AsyncLocalFileStorage` |
+| `async_directory_example.py` | `AsyncLocalDirectoryStorage`, incl. concurrent saves and `arebuild_index` |
 | `async_sqlite_example.py` | `AsyncSQLiteStorage` |
 | `mongodb_example.py` | `MongoDBStorage`, incl. a MongoDB `query` filter |
 | `async_mongodb_example.py` | `AsyncMongoDBStorage`, incl. a MongoDB `query` filter |
@@ -405,7 +406,7 @@ uv run python examples/async_sqlite_example.py
 ```
 
 The file-based and SQLite examples write to `data/` in the current directory
-(ignored by git); set `INVENTORY_DIR` or `SQLITE_DB_PATH` to change that. The MongoDB
+(ignored by git); set `OBJBASE_DATA_DIR` or `SQLITE_DB_PATH` to change that. The MongoDB
 examples need a running server — `docker run --rm -p 27017:27017 mongo:7.0` — and
 connect to `MONGODB_URI` (default `mongodb://localhost:27017`).
 
@@ -422,7 +423,7 @@ once at startup and tear them down cleanly on shutdown.
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 import redis.asyncio
-from objbase.asyncio.storage.redis_storage import AsyncRedisStorage
+from objbase.asyncio.storage.redis import AsyncRedisStorage
 
 
 @asynccontextmanager
@@ -436,28 +437,28 @@ async def lifespan(app: FastAPI):
 app = FastAPI(lifespan=lifespan)
 ```
 
-### 2. Inject `AsyncInventory` with `Depends`
+### 2. Inject `AsyncCollection` with `Depends`
 
-Wrap the `AsyncInventory` construction in a dependency function so routes stay clean
+Wrap the `AsyncCollection` construction in a dependency function so routes stay clean
 and the storage adapter is easy to swap out (e.g. in tests).
 
 ```python
 from fastapi import Depends, HTTPException, Request
-from objbase.asyncio.inventory import AsyncInventory
+from objbase.asyncio.collection import AsyncCollection
 from objbase.errors import ItemNotFoundError
 
 
-def get_todos(request: Request) -> AsyncInventory:
-    return AsyncInventory(item_type="todo", storage=request.app.state.storage)
+def get_todos(request: Request) -> AsyncCollection:
+    return AsyncCollection(item_type="todo", storage=request.app.state.storage)
 
 
 @app.get("/todos")
-async def list_todos(todos: AsyncInventory = Depends(get_todos)):
-    return await todos.filter()
+async def list_todos(todos: AsyncCollection = Depends(get_todos)):
+    return await todos.items()
 
 
 @app.get("/todos/{todo_id}")
-async def get_todo(todo_id: str, todos: AsyncInventory = Depends(get_todos)):
+async def get_todo(todo_id: str, todos: AsyncCollection = Depends(get_todos)):
     item = await todos.get(todo_id)
     if item is None:
         raise HTTPException(status_code=404)
@@ -465,12 +466,12 @@ async def get_todo(todo_id: str, todos: AsyncInventory = Depends(get_todos)):
 
 
 @app.post("/todos")
-async def create_todo(item: dict, todos: AsyncInventory = Depends(get_todos)):
+async def create_todo(item: dict, todos: AsyncCollection = Depends(get_todos)):
     return await todos.save(item)
 
 
 @app.patch("/todos/{todo_id}")
-async def update_todo(todo_id: str, data: dict, todos: AsyncInventory = Depends(get_todos)):
+async def update_todo(todo_id: str, data: dict, todos: AsyncCollection = Depends(get_todos)):
     try:
         return await todos.patch(todo_id, data)
     except ItemNotFoundError:
@@ -486,8 +487,8 @@ automatically, keeping the event loop unblocked.
 ```python
 from contextlib import asynccontextmanager
 from fastapi import FastAPI, Depends, Request
-from objbase.inventory import Inventory
-from objbase.storage.sqlite_storage import SQLiteStorage
+from objbase.collection import Collection
+from objbase.storage.sqlite import SQLiteStorage
 
 
 @asynccontextmanager
@@ -499,13 +500,13 @@ async def lifespan(app: FastAPI):
 app = FastAPI(lifespan=lifespan)
 
 
-def get_todos(request: Request) -> Inventory:
-    return Inventory(item_type="todo", storage=request.app.state.storage)
+def get_todos(request: Request) -> Collection:
+    return Collection(item_type="todo", storage=request.app.state.storage)
 
 
 @app.get("/todos")  # sync — runs in threadpool
-def list_todos(todos: Inventory = Depends(get_todos)):
-    return todos.filter()
+def list_todos(todos: Collection = Depends(get_todos)):
+    return todos.items()
 ```
 
 ### 4. Override the dependency in tests
@@ -515,15 +516,15 @@ Swap the storage backend for the entire test run without touching any route code
 for Redis. Create it once so data persists across requests:
 
 ```python
-from objbase.asyncio.inventory import AsyncInventory
-from objbase.storage.inmemory_storage import InMemoryStorage
+from objbase.asyncio.collection import AsyncCollection
+from objbase.storage.inmemory import InMemoryStorage
 from fastapi.testclient import TestClient
 
 test_storage = InMemoryStorage()
 
 
 def override_todos():
-    return AsyncInventory(item_type="todo", storage=test_storage)
+    return AsyncCollection(item_type="todo", storage=test_storage)
 
 
 app.dependency_overrides[get_todos] = override_todos
@@ -536,8 +537,8 @@ client = TestClient(app)
 |---|---|
 | Single-process, low traffic | `SQLiteStorage` — zero deps, ACID, simple |
 | Multi-worker / multi-process | `RedisStorage` or `MongoDBStorage` |
-| Async routes | `AsyncInventory` + `AsyncRedisStorage` or `AsyncMongoDBStorage` — non-blocking, fits the event loop |
-| Async routes, single process, no infrastructure | `AsyncInventory` + `AsyncSQLiteStorage` — zero deps, runs in a worker thread |
+| Async routes | `AsyncCollection` + `AsyncRedisStorage` or `AsyncMongoDBStorage` — non-blocking, fits the event loop |
+| Async routes, single process, no infrastructure | `AsyncCollection` + `AsyncSQLiteStorage` — zero deps, runs in a worker thread |
 | Testing / local dev | `InMemoryStorage` — fast, no infrastructure needed |
 
 ---
@@ -617,7 +618,7 @@ class MyCustomStorage:
 
 
 # Works — no explicit inheritance required
-todos = Inventory(item_type="todo", storage=MyCustomStorage())
+todos = Collection(item_type="todo", storage=MyCustomStorage())
 ```
 
 ### Optional explicit inheritance
@@ -654,8 +655,8 @@ The package ships a `py.typed` marker, so mypy, Pyright and IDEs use its type
 hints. The library itself is checked with `mypy --strict`.
 
 - Items are typed as `objbase.Item`, an alias for `dict[str, Any]`.
-- `Inventory` and `AsyncInventory` accept and return `Item`; `get` returns `Item | None`.
-- `PydanticInventory` and `AsyncPydanticInventory` are generic over their model class, which is inferred from
+- `Collection` and `AsyncCollection` accept and return `Item`; `get` returns `Item | None`.
+- `PydanticCollection` and `AsyncPydanticCollection` are generic over their model class, which is inferred from
   `model_class` (see [Pydantic Models](#pydantic-models)).
 - Storage adapters accept any structurally compatible client. For example,
   `RedisStorage` and `AsyncRedisStorage` take anything with Redis's