mongodb-typesafe-aggregation 0.1.0__tar.gz

mongodb_typesafe_aggregation-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+mongodb-pipeline-demo-py
+.DS_Store

mongodb_typesafe_aggregation-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "mongodb-pipeline-demo-py"]
+	path = mongodb-pipeline-demo-py
+	url = https://github.com/zuruoke/mongodb-pipeline-demo-py.git

mongodb_typesafe_aggregation-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mongodb_typesafe_aggregation-0.1.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-03
+
+First release of the Python version of
+[mongodb-typesafe-aggregation](https://github.com/zuruoke/mongodb-typesafe-aggregation).
+
+### Added
+
+#### Pipeline Builder
+
+- `PipelineBuilder[T]`: fluent, immutable builder for MongoDB aggregation pipelines. Every
+  method returns a new builder.
+- `.build()`: returns a deep copy of the pipeline as `list[dict]`
+- `.raw(stage)`: escape hatch for adding any stage without checks
+- `.cast(schema)`: declares the document shape after a stage that changes it
+
+#### Pipeline Stages
+
+| Method                | MongoDB Stage  | Description                           |
+| --------------------- | -------------- | ------------------------------------- |
+| `.match(query)`       | `$match`       | Filter documents                      |
+| `.lookup(from_, ...)` | `$lookup`      | Join from another collection          |
+| `.group(spec)`        | `$group`       | Group and accumulate                  |
+| `.add_fields(spec)`   | `$addFields`   | Add computed fields                   |
+| `.set(spec)`          | `$set`         | Alias for `$addFields` (MongoDB 4.2+) |
+| `.project(spec)`      | `$project`     | Include/exclude/reshape fields        |
+| `.unset(fields)`      | `$unset`       | Remove fields                         |
+| `.sort(spec)`         | `$sort`        | Sort documents                        |
+| `.skip(n)`            | `$skip`        | Skip N documents                      |
+| `.limit(n)`           | `$limit`       | Limit to N documents                  |
+| `.unwind(path)`       | `$unwind`      | Deconstruct an array field            |
+| `.replace_root(root)` | `$replaceRoot` | Replace root document                 |
+| `.count(field)`       | `$count`       | Count matching documents              |
+| `.facet(spec)`        | `$facet`       | Multi-faceted aggregation             |
+| `.union_with(coll)`   | `$unionWith`   | Union with another collection         |
+| `.graph_lookup(...)`  | `$graphLookup` | Recursive graph traversal             |
+| `.bucket(...)`        | `$bucket`      | Categorise into buckets               |
+| `.bucket_auto(...)`   | `$bucketAuto`  | Auto-distribute into buckets          |
+| `.redact(expression)` | `$redact`      | Conditionally include/exclude content |
+| `.merge(into, ...)`   | `$merge`       | Write results to another collection   |
+
+Each stage is also available as a standalone function (`match_stage()`, `lookup_stage()`, ...).
+
+#### FilterOperator
+
+`FilterOperator[T]`: typed builder for MongoDB query and expression operators, with the same
+methods as the TypeScript version: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in_`, `nin`, `all`,
+`size`, `exists`, `regex`, `field_eq`, `field_ne`, `cond`.
+
+Also exports a `filter(type)` factory from `mongodb_typesafe_aggregation.types.filter` as a
+concise alternative to `FilterOperator[T]()`. Stages build `FilterOperator` values
+automatically, so `.build()` is optional.
+
+#### Schema checks
+
+- Field names are checked against a `TypedDict`, dataclass, Pydantic (v1/v2, by alias) or
+  annotated class, including `"$field"` paths inside expressions.
+- The known fields are tracked through every stage, so checks stay correct after `group`,
+  `project`, `facet`, `lookup` and other shape-changing stages.
+- `UnknownFieldError` (a `ValueError`) names the stage, suggests the closest field, and lists
+  the known fields.
+- `strict=False`, or no schema, skips the runtime checks.
+
+#### Validation
+
+`ValueError` for invalid sort orders, negative `skip` or non-positive `limit`, `$project`
+mixing inclusion and exclusion, `$group` without `_id`, `$unwind` paths without `$`,
+`$lookup` without a join condition, unordered `$bucket` boundaries, and stages added after
+`$merge`.
+
+[0.1.0]: https://github.com/zuruoke/mongodb-typesafe-aggregation-py/releases/tag/v0.1.0

mongodb_typesafe_aggregation-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing
+
+Thank you for taking the time to contribute.
+
+## Local Setup
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone --recursive https://github.com/zuruoke/mongodb-typesafe-aggregation-py.git
+cd mongodb-typesafe-aggregation-py
+uv sync
+```
+
+## Development Workflow
+
+```bash
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov
+
+# Check types
+uv run mypy
+
+# Lint
+uv run ruff check
+
+# Format
+uv run ruff format
+
+# Build
+uv build
+```
+
+### Integration tests
+
+Integration tests run pipelines against a real MongoDB. They are skipped unless `MONGODB_URI`
+is set, and they create and drop a throwaway database, so they never touch your data.
+
+```bash
+# Start a MongoDB, e.g. the demo container (see SUBMODULE_README.md)
+cd mongodb-pipeline-demo-py && MONGO_PORT=27018 docker compose up -d && cd ..
+
+MONGODB_URI=mongodb://localhost:27018 uv run pytest -m integration
+```
+
+## Branch Convention
+
+| Branch prefix | When to use                           |
+| ------------- | ------------------------------------- |
+| `feat/`       | New stage or operator                 |
+| `fix/`        | Bug fix                               |
+| `docs/`       | Documentation only                    |
+| `refactor/`   | Code restructure, no behaviour change |
+| `test/`       | New or improved tests                 |
+| `chore/`      | Tooling, deps, CI                     |
+
+Branch off `main` and target `main` with your PR.
+
+## Adding a New Pipeline Stage
+
+1. Create `src/mongodb_typesafe_aggregation/stages/my_stage.py` following the existing
+   pattern: a `my_stage_stage()` function that validates its input, builds `FilterOperator`
+   values with `resolve_filters()`, and returns the stage dict.
+2. Export it from `stages/__init__.py` and from the package `__init__.py`.
+3. Add the method to `PipelineBuilder` in `builder.py`. Check every field the stage reads
+   against the current schema (`check_field`, `check_query` or `check_expression`), and pass
+   the new set of known fields to `_add()` if the stage changes the document shape.
+4. Write test cases in `tests/test_stages.py` and `tests/test_builder.py`, including the field
+   checks and the shape afterwards.
+5. Add an example to the demo (`mongodb-pipeline-demo-py`) and check it against MongoDB.
+6. Document it in `README.md`, and in `CHANGELOG.md` under an `[Unreleased]` section.
+
+## Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(stages): add $sortByCount stage
+fix(filter): handle None in exists operator
+docs: update API reference table
+```
+
+## Pull Request Checklist
+
+- [ ] Tests pass (`uv run pytest`)
+- [ ] Types check (`uv run mypy`)
+- [ ] No lint or format errors (`uv run ruff check && uv run ruff format --check`)
+- [ ] New behaviour is covered by a test
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+
+## Releasing (Maintainers)
+
+One-time setup: on PyPI, add a [trusted publisher](https://docs.pypi.org/trusted-publishers/)
+for the project `mongodb-typesafe-aggregation` with owner `zuruoke`, repository
+`mongodb-typesafe-aggregation-py`, workflow `release.yml` and environment `pypi`. Create the
+`pypi` environment in the GitHub repository settings.
+
+For each release:
+
+1. Update `CHANGELOG.md`: move `[Unreleased]` to the new version with today's date.
+2. Bump `__version__` in `src/mongodb_typesafe_aggregation/__init__.py`.
+3. Commit, then tag the commit with the same version: `git tag vX.Y.Z`
+4. Push the commit and the tag: `git push && git push --tags`
+5. The `release.yml` GitHub Action checks that the tag matches `__version__`, runs the checks,
+   and publishes to PyPI.

mongodb_typesafe_aggregation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chimzuruoke Okafor Augustine Best
+
+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.