fromscratch-pydocdb 0.3.0__py3-none-any.whl

fromscratch_pydocdb-0.3.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: fromscratch-pydocdb
+Version: 0.3.0
+Summary: An educational document store library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pydoc-db
+Project-URL: Repository, https://github.com/robcox2910/pydoc-db
+Project-URL: Issues, https://github.com/robcox2910/pydoc-db/issues
+Project-URL: Documentation, https://robcox2910.github.io/pydoc-db/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: database,document,education,nosql,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
+
+# PyDocDB
+
+An educational document store (like MongoDB) built from scratch in Python. Part of the **PyLearn** platform for kids aged 12+.
+
+PyDocDB stores JSON-like documents without requiring a fixed schema -- each document can have different fields, just like how every index card in a filing cabinet can have different information on it.
+
+## Features
+
+- **Documents** -- Dict-like objects with auto-generated unique IDs
+- **Collections** -- Named groups of documents with full CRUD operations
+- **Query Language** -- Filter with operators: `$eq`, `$gt`, `$lt`, `$gte`, `$lte`, `$ne`, `$in`, `$exists`, `$and`, `$or`, `$not`
+- **Nested Field Access** -- Query nested fields with dot notation (e.g., `"address.city"`)
+- **Projection** -- Return only specific fields from documents
+- **Indexing** -- Create indexes on fields for faster lookups
+- **Persistence** -- Save/load collections to JSON files on disk
+- **Aggregation** -- Pipeline with `$match`, `$group`, `$sort`, `$limit`, `$count`
+
+## Quick Start
+
+```python
+from pydocdb import Collection, save_collection, load_collection, aggregate
+
+# Create a collection (like labeling a new folder in a filing cabinet)
+students = Collection("students")
+
+# Insert documents (like filing index cards)
+students.insert_one({"name": "Alice", "age": 14, "grade": "9th"})
+students.insert_one({"name": "Bob", "age": 13, "hobby": "chess"})
+students.insert_one({"name": "Charlie", "age": 15, "grade": "10th"})
+
+# Find documents with queries
+teenagers = students.find({"age": {"$gte": 13}})
+alice = students.find_one({"name": "Alice"})
+
+# Update and delete
+students.update_one({"name": "Alice"}, {"age": 15})
+students.delete_one({"name": "Bob"})
+
+# Use projection to get only specific fields
+names = students.find({}, projection={"name": 1, "_id": 0})
+
+# Aggregate data
+result = aggregate(students.to_list(), [
+    {"$group": {"_id": "$grade", "count": {"$sum": 1}}},
+    {"$sort": {"count": -1}},
+])
+
+# Save to disk and load later
+save_collection(students, "students.json")
+loaded = load_collection("students.json")
+```
+
+## Installation
+
+```bash
+uv add pydocdb
+```
+
+## Development
+
+```bash
+git clone https://github.com/robcox2910/pydoc-db.git
+cd pydoc-db
+uv sync --all-extras
+uv run pytest
+uv run ruff check src/ tests/
+uv run pyright src tests
+```
+
+## 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/pydoc-db/
+<!-- docs:end -->

fromscratch_pydocdb-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pydocdb/__init__.py,sha256=FS8xCxvqT1uu3lHGcKd9Rh82ajGfHIHFsiRKHa_OUgM,1369
+pydocdb/_version.py,sha256=RCY04NY0kBCyn6ttH6lnVL6Gz2gceOrt45f0yDOOU8A,520
+pydocdb/aggregation.py,sha256=ucovumNWSRoLUhAx8NscXRt2hg0oCnB9yuSfjXtmQ5g,10896
+pydocdb/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pydocdb/collection.py,sha256=7cem5CLJghwGk5pJE8o_dKkp2mmvIjJsut_YKIhOMnU,15724
+pydocdb/document.py,sha256=ofsx43JfueKFvpZ1pBCk4xh6JBaojkxQzJ6dI9G-tDw,4920
+pydocdb/errors.py,sha256=vi9aKiq28H7sWH8xk1e_X8IR2F08ecDGOWcJCHkJmp8,1792
+pydocdb/indexing.py,sha256=0yvemUgqXgD7AMV8983aiEWiftQ7-BHa_yde_r_dolc,3849
+pydocdb/operators.py,sha256=IA-3gEHiyNvkUn5-iGtdw7Ot_rtPn0LLAYr4e-74o-w,5173
+pydocdb/persistence.py,sha256=LqCEmWYgN8iFrCg_TYrzRkdyvB_0C1VlxAcsFB7XE80,4672
+pydocdb/projection.py,sha256=s2et1ErZjTiMsY1PqvRwD_YL70B3061KN6c9TKljiOs,2908
+pydocdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydocdb/query.py,sha256=tdK5DfvTP8pMeiyWrIqUG-liOxEqoHp7-W4lkZweXEk,6195
+fromscratch_pydocdb-0.3.0.dist-info/METADATA,sha256=5AB3ytxcNtQNGq4Jp4VqGE9y_gTqys4rPLuFotWMVYw,7027
+fromscratch_pydocdb-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pydocdb-0.3.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pydocdb-0.3.0.dist-info/RECORD,,

fromscratch_pydocdb-0.3.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_pydocdb-0.3.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.

pydocdb/__init__.py

@@ -0,0 +1,48 @@
+"""PyDocDB -- an educational document store for kids aged 12+.
+
+PyDocDB is a document database (like MongoDB) built from scratch in Python.
+It stores JSON-like documents without requiring a fixed schema -- each
+document can have different fields, just like how every index card in a
+filing cabinet can have different information on it.
+
+Quick start::
+
+    from pydocdb import Collection
+
+    students = Collection("students")
+    students.insert_one({"name": "Alice", "age": 14, "grade": "9th"})
+    students.insert_one({"name": "Bob", "age": 13, "hobby": "chess"})
+
+    # Find students older than 13
+    results = students.find({"age": {"$gt": 13}})
+"""
+
+from pydocdb.aggregation import aggregate
+from pydocdb.collection import Collection
+from pydocdb.document import Document, DocumentData
+from pydocdb.errors import (
+    DocumentNotFoundError,
+    DuplicateKeyError,
+    InvalidPipelineError,
+    InvalidQueryError,
+    PersistenceError,
+    PyDocDBError,
+)
+from pydocdb.indexing import Index
+from pydocdb.persistence import load_collection, save_collection
+
+__all__: list[str] = [
+    "Collection",
+    "Document",
+    "DocumentData",
+    "DocumentNotFoundError",
+    "DuplicateKeyError",
+    "Index",
+    "InvalidPipelineError",
+    "InvalidQueryError",
+    "PersistenceError",
+    "PyDocDBError",
+    "aggregate",
+    "load_collection",
+    "save_collection",
+]

pydocdb/_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.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

pydocdb/aggregation.py

@@ -0,0 +1,377 @@
+"""Aggregation pipeline for PyDocDB.
+
+Imagine you have a huge collection of trading cards. You might want to:
+1. First, pick out only the rare cards ($match)
+2. Then, group them by type -- Fire, Water, Grass ($group)
+3. Sort the groups by how many cards each has ($sort)
+4. Only look at the top 3 groups ($limit)
+5. Just count how many groups there are ($count)
+
+That's an aggregation pipeline! It's a series of steps (called "stages")
+that process your documents one step at a time. Each stage takes the
+output of the previous stage and transforms it.
+"""
+
+from typing import Any
+
+from pydocdb.document import Document, DocumentData, extract_field
+from pydocdb.errors import InvalidPipelineError
+from pydocdb.indexing import make_hashable
+from pydocdb.query import matches
+
+
+def aggregate(
+    documents: list[DocumentData],
+    pipeline: list[dict[str, Any]],
+) -> list[DocumentData]:
+    """Run an aggregation pipeline on a list of documents.
+
+    Process documents through a series of stages, where each stage
+    transforms the data in some way.
+
+    Args:
+        documents: The input documents to process.
+        pipeline: A list of stage dictionaries (e.g., [{"$match": {...}}, {"$sort": {...}}]).
+
+    Returns:
+        The resulting documents after all stages have been applied.
+
+    Raises:
+        InvalidPipelineError: If a stage is unknown or malformed.
+
+    """
+    current: list[DocumentData] = list(documents)
+
+    for stage in pipeline:
+        if len(stage) != 1:
+            msg = "Each pipeline stage must have exactly one operator"
+            raise InvalidPipelineError(msg)
+
+        stage_name = next(iter(stage))
+        stage_value = stage[stage_name]
+
+        if stage_name == "$match":
+            current = _stage_match(current, stage_value)
+        elif stage_name == "$group":
+            current = _stage_group(current, stage_value)
+        elif stage_name == "$sort":
+            current = _stage_sort(current, stage_value)
+        elif stage_name == "$limit":
+            current = _stage_limit(current, stage_value)
+        elif stage_name == "$count":
+            current = _stage_count(current, stage_value)
+        else:
+            msg = f"Unknown pipeline stage: {stage_name}"
+            raise InvalidPipelineError(msg)
+
+    return current
+
+
+def _stage_match(
+    documents: list[DocumentData],
+    query: dict[str, Any],
+) -> list[DocumentData]:
+    """Filter documents that match a query -- like picking cards from a pile.
+
+    Args:
+        documents: Input documents.
+        query: A query dictionary (same format as Collection.find).
+
+    Returns:
+        Only the documents that match the query.
+
+    """
+    return [doc for doc in documents if matches(Document(doc), query)]
+
+
+def _stage_group(
+    documents: list[DocumentData],
+    group_spec: dict[str, Any],
+) -> list[DocumentData]:
+    """Group documents by a field and compute aggregations.
+
+    Like sorting your cards into piles by type, then counting each pile.
+
+    The ``_id`` field in the spec tells us what to group by.
+    Other fields define accumulators:
+    - ``$sum``: Add up values (use 1 to count)
+    - ``$avg``: Calculate the average
+    - ``$min``: Find the smallest value
+    - ``$max``: Find the largest value
+
+    Note:
+        Group keys must be hashable to sort documents into piles, so a list
+        key comes back as a tuple and a dict key as a tuple of pairs in each
+        result's ``_id``. Grouping by simple values (strings, numbers) is the
+        common case and is unaffected.
+
+    Args:
+        documents: Input documents.
+        group_spec: A dict with ``_id`` (group key) and accumulator fields.
+
+    Returns:
+        One document per group with the computed values.
+
+    Raises:
+        InvalidPipelineError: If ``_id`` is missing from the spec.
+
+    """
+    if "_id" not in group_spec:
+        msg = "$group stage requires an '_id' field"
+        raise InvalidPipelineError(msg)
+
+    group_key = group_spec["_id"]
+
+    # Build groups
+    groups: dict[Any, list[DocumentData]] = {}
+    for doc in documents:
+        if group_key is None:
+            key: Any = None
+        elif isinstance(group_key, str) and group_key.startswith("$"):
+            key = extract_field(doc, group_key[1:])
+        else:
+            key = group_key
+
+        # Make the key hashable
+        hashable_key = make_hashable(key)
+        if hashable_key not in groups:
+            groups[hashable_key] = []
+        groups[hashable_key].append(doc)
+
+    # Apply accumulators to each group
+    results: list[DocumentData] = []
+    for key_value, group_docs in groups.items():
+        result: DocumentData = {"_id": key_value}
+
+        for field, accumulator in group_spec.items():
+            if field == "_id":
+                continue
+            if isinstance(accumulator, dict):
+                acc_dict: dict[str, Any] = dict(accumulator)  # pyright: ignore[reportUnknownArgumentType]
+                result[field] = _apply_accumulator(acc_dict, group_docs)
+
+        results.append(result)
+
+    return results
+
+
+def _apply_accumulator(
+    accumulator: dict[str, Any],
+    group_docs: list[DocumentData],
+) -> Any:
+    """Apply a single accumulator to a group of documents.
+
+    Args:
+        accumulator: A dict like ``{"$sum": "$price"}`` or ``{"$sum": 1}``.
+        group_docs: The documents in this group.
+
+    Returns:
+        The computed value.
+
+    Raises:
+        InvalidPipelineError: If the accumulator operator is unknown.
+
+    """
+    op = next(iter(accumulator))
+    value_spec = accumulator[op]
+
+    if op == "$sum":
+        return _acc_sum(value_spec, group_docs)
+    if op == "$avg":
+        return _acc_avg(value_spec, group_docs)
+    if op == "$min":
+        return _acc_min(value_spec, group_docs)
+    if op == "$max":
+        return _acc_max(value_spec, group_docs)
+
+    msg = f"Unknown accumulator: {op}"
+    raise InvalidPipelineError(msg)
+
+
+def _acc_sum(value_spec: Any, docs: list[DocumentData]) -> int | float:
+    """Compute sum for a group.
+
+    Args:
+        value_spec: Either a number (like 1 for counting) or a field reference like "$price".
+        docs: The documents in the group.
+
+    Returns:
+        The sum.
+
+    """
+    if isinstance(value_spec, (int, float)):
+        return value_spec * len(docs)
+
+    if isinstance(value_spec, str) and value_spec.startswith("$"):
+        field = value_spec[1:]
+        total: int | float = 0
+        for doc in docs:
+            val = extract_field(doc, field)
+            if isinstance(val, (int, float)):
+                total += val
+        return total
+
+    return 0
+
+
+def _acc_avg(value_spec: Any, docs: list[DocumentData]) -> float:
+    """Compute average for a group.
+
+    Args:
+        value_spec: A field reference like "$price".
+        docs: The documents in the group.
+
+    Returns:
+        The average, or 0.0 if no valid values.
+
+    """
+    if isinstance(value_spec, str) and value_spec.startswith("$"):
+        field = value_spec[1:]
+        values: list[float] = []
+        for doc in docs:
+            val = extract_field(doc, field)
+            if isinstance(val, (int, float)):
+                values.append(float(val))
+        if values:
+            return sum(values) / len(values)
+    return 0.0
+
+
+def _acc_min(value_spec: Any, docs: list[DocumentData]) -> Any:
+    """Compute minimum for a group.
+
+    Args:
+        value_spec: A field reference like "$price".
+        docs: The documents in the group.
+
+    Returns:
+        The minimum value, or None if no valid values.
+
+    """
+    if isinstance(value_spec, str) and value_spec.startswith("$"):
+        field = value_spec[1:]
+        values: list[Any] = []
+        for doc in docs:
+            val = extract_field(doc, field)
+            if val is not None:
+                values.append(val)
+        if values:
+            return min(values)
+    return None
+
+
+def _acc_max(value_spec: Any, docs: list[DocumentData]) -> Any:
+    """Compute maximum for a group.
+
+    Args:
+        value_spec: A field reference like "$price".
+        docs: The documents in the group.
+
+    Returns:
+        The maximum value, or None if no valid values.
+
+    """
+    if isinstance(value_spec, str) and value_spec.startswith("$"):
+        field = value_spec[1:]
+        values: list[Any] = []
+        for doc in docs:
+            val = extract_field(doc, field)
+            if val is not None:
+                values.append(val)
+        if values:
+            return max(values)
+    return None
+
+
+def _stage_sort(
+    documents: list[DocumentData],
+    sort_spec: dict[str, int],
+) -> list[DocumentData]:
+    """Sort documents by one or more fields.
+
+    Like arranging your cards in order -- alphabetically by name,
+    or by number from highest to lowest.
+
+    Args:
+        documents: Input documents.
+        sort_spec: A dict mapping field names to 1 (ascending) or -1 (descending).
+
+    Returns:
+        The sorted list of documents.
+
+    """
+    result = list(documents)
+    # Apply sorts in reverse order so first key is primary
+    for field in reversed(sort_spec):
+        direction = sort_spec[field]
+        is_reverse = direction == -1
+        result.sort(
+            key=lambda doc, f=field: _sort_key(doc, f),  # type: ignore[misc]
+            reverse=is_reverse,
+        )
+    return result
+
+
+def _sort_key(doc: DocumentData, field: str) -> Any:
+    """Get a sort-safe key for a document field.
+
+    Args:
+        doc: The document data.
+        field: The field to sort by.
+
+    Returns:
+        The value to sort by, with None values sorted last.
+
+    """
+    val = extract_field(doc, field)
+    if val is None:
+        return (1, "")
+    return (0, val)
+
+
+def _stage_limit(
+    documents: list[DocumentData],
+    limit: Any,
+) -> list[DocumentData]:
+    """Limit the number of documents -- like looking at only the top N cards.
+
+    Args:
+        documents: Input documents.
+        limit: Maximum number of documents to return.
+
+    Returns:
+        At most ``limit`` documents.
+
+    Raises:
+        InvalidPipelineError: If limit is not a positive integer.
+
+    """
+    if not isinstance(limit, int) or limit < 1:
+        msg = "$limit requires a positive integer"
+        raise InvalidPipelineError(msg)
+    return documents[:limit]
+
+
+def _stage_count(
+    documents: list[DocumentData],
+    field_name: Any,
+) -> list[DocumentData]:
+    """Count the number of documents and store the result in a named field.
+
+    Like counting how many cards are in a pile and writing the number down.
+
+    Args:
+        documents: Input documents.
+        field_name: The name of the field to store the count in.
+
+    Returns:
+        A single-element list with the count.
+
+    Raises:
+        InvalidPipelineError: If field_name is not a string.
+
+    """
+    if not isinstance(field_name, str):
+        msg = "$count requires a string field name"
+        raise InvalidPipelineError(msg)
+    return [{field_name: len(documents)}]