mongo-pipebuilder 0.3.0__tar.gz → 0.4.0__tar.gz

mongo_pipebuilder-0.4.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include pyproject.toml

{mongo_pipebuilder-0.3.0/src/mongo_pipebuilder.egg-info → mongo_pipebuilder-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.3.0
+Version: 0.4.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/seligoroff/mongo-pipebuilder
 Project-URL: Documentation, https://github.com/seligoroff/mongo-pipebuilder#readme
 Project-URL: Repository, https://github.com/seligoroff/mongo-pipebuilder
@@ -11,7 +11,6 @@ Project-URL: Issues, https://github.com/seligoroff/mongo-pipebuilder/issues
 Keywords: mongodb,aggregation,pipeline,builder,query
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -98,6 +97,15 @@ Adds a `$match` stage to filter documents.
 .match({"status": "active", "age": {"$gte": 18}})
 ```
 
+##### `match_expr(expr: Dict[str, Any]) -> Self`
+
+Adds a `$match` stage with an `$expr` condition (expression-based filter; useful for comparing fields or using variables from `let` in subpipelines).
+
+```python
+.match_expr({"$eq": ["$id", "$$teamId"]})
+.match_expr({"$and": [{"$gte": ["$field", "$other"]}, {"$lte": ["$score", 100]}]})
+```
+
 ##### `lookup(from_collection: str, local_field: str, foreign_field: str, as_field: str, pipeline: Optional[List[Dict[str, Any]]] = None) -> Self`
 
 Adds a `$lookup` stage to join with another collection.
@@ -112,6 +120,43 @@ Adds a `$lookup` stage to join with another collection.
 )
 ```
 
+##### `lookup_let(from_collection: str, let: Dict[str, Any], pipeline: Union[List[Dict[str, Any]], PipelineBuilder], as_field: str) -> Self`
+
+Adds a `$lookup` stage with `let` and `pipeline` (join by expression; variables from the current document are available in the subpipeline as `$$var`). Use this when the join condition is an expression (e.g. `$expr`) rather than equality of two fields.
+
+```python
+# With list of stages
+.lookup_let(
+    from_collection="teams",
+    let={"teamId": "$idTeam"},
+    pipeline=[
+        {"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}},
+        {"$project": {"name": 1, "_id": 0}}
+    ],
+    as_field="team"
+)
+
+# With PipelineBuilder for the subpipeline (optionally using match_expr)
+sub = PipelineBuilder().match_expr({"$eq": ["$_id", "$$teamId"]}).project({"name": 1, "_id": 0})
+.lookup_let("teams", {"teamId": "$idTeam"}, sub, as_field="team")
+```
+
+##### `union_with(coll: str, pipeline: Optional[Union[List[Dict[str, Any]], PipelineBuilder]] = None) -> Self`
+
+Adds a `$unionWith` stage to combine documents from the current pipeline with documents from another collection. Optionally runs a subpipeline on the other collection before merging.
+
+```python
+# Union with another collection (no subpipeline)
+.union_with("other_coll")
+
+# With subpipeline as list of stages
+.union_with("logs", [{"$match": {"level": "error"}}, {"$limit": 100}])
+
+# With PipelineBuilder for the subpipeline
+sub = PipelineBuilder().match({"source": "individual"}).project({"name": 1})
+.union_with("sso_individual_statistics", sub)
+```
+
 ##### `add_fields(fields: Dict[str, Any]) -> Self`
 
 Adds a `$addFields` stage to add or modify fields.
@@ -252,7 +297,7 @@ builder.prepend({"$match": {"deleted": False}})
 Inserts a stage at a specific position (0-based index) in the pipeline.
 
 ```python
-builder.match({"status": "active"}).group({"_id": "$category"}, {"count": {"$sum": 1}})
+builder.match({"status": "active"}).group("$category", {"count": {"$sum": 1}})
 builder.insert_at(1, {"$sort": {"name": 1}})
 # Pipeline: [{"$match": {...}}, {"$sort": {...}}, {"$group": {...}}]
 ```
@@ -327,6 +372,15 @@ print(builder.pretty_print())
 # ]
 ```
 
+##### `pretty_print_stage(stage: Union[int, Dict[str, Any]], indent: int = 2, ensure_ascii: bool = False) -> str`
+
+Returns a formatted JSON string representation of a single stage (by index or by dict).
+
+```python
+builder = PipelineBuilder().match({"status": "active"}).limit(10)
+print(builder.pretty_print_stage(0))  # Prints the $match stage
+```
+
 ##### `to_json_file(filepath: Union[str, Path], indent: int = 2, ensure_ascii: bool = False, metadata: Optional[Dict[str, Any]] = None) -> None`
 
 Saves the pipeline to a JSON file. Useful for debugging, comparison, or versioning.
@@ -345,6 +399,17 @@ builder.to_json_file(
 )
 ```
 
+##### `compare_with(other: PipelineBuilder, context_lines: int = 3) -> str`
+
+Returns a unified diff between two pipelines (useful for comparing “new” builder pipelines vs legacy/template pipelines).
+
+```python
+legacy = PipelineBuilder().match({"status": "active"}).limit(10)
+new = PipelineBuilder().match({"status": "inactive"}).limit(10)
+
+print(new.compare_with(legacy))
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -391,6 +456,31 @@ pipeline = (
 )
 ```
 
+### Lookup by expression (lookup_let)
+
+When the join condition is an expression (e.g. `$expr`) rather than matching two fields, use `lookup_let`. The subpipeline can be built with `match_expr()`:
+
+```python
+sub = (
+    PipelineBuilder()
+    .match_expr({"$eq": ["$_id", "$$teamId"]})
+    .project({"name": 1, "slug": 1, "_id": 0})
+)
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "active"})
+    .lookup_let(
+        from_collection="teams",
+        let={"teamId": "$idTeam"},
+        pipeline=sub,
+        as_field="team"
+    )
+    .unwind("team", preserve_null_and_empty_arrays=True)
+    .project({"title": 1, "teamName": "$team.name"})
+    .build()
+)
+```
+
 ### Aggregation with Grouping
 
 ```python
@@ -500,11 +590,39 @@ base = get_base_pipeline(user_id)
 # Create multiple queries from cached base
 recent = base.copy().sort({"createdAt": -1}).limit(10).build()
 by_category = base.copy().match({"category": "tech"}).build()
-with_stats = base.copy().group({"_id": "$category"}, {"count": {"$sum": 1}}).build()
+with_stats = base.copy().group("$category", {"count": {"$sum": 1}}).build()
 
 # Base pipeline is safely cached and reused
 ```
 
+## Best Practices
+
+### Array `_id` after `$group`: prefer `$arrayElemAt` and materialize fields
+
+If you use `$group` with an array `_id` (e.g. `["_idSeason", "_idTournament"]`), avoid relying on `$_id` later in the pipeline.
+Instead, **extract elements with `$arrayElemAt` and store them into explicit fields**, then use those fields in subsequent stages.
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .group(
+        group_by=["$idSeason", "$idTournament"],
+        accumulators={"idTeams": {"$addToSet": "$idTeam"}},
+    )
+    .project({
+        "idSeason": {"$arrayElemAt": ["$_id", 0]},
+        "idTournament": {"$arrayElemAt": ["$_id", 1]},
+        "idTeams": 1,
+        # Optional: preserve array _id explicitly if you really need it later
+        # "_id": "$_id",
+    })
+    .build()
+)
+```
+
+This pattern reduces surprises and helps avoid errors like:
+`$first's argument must be an array, but is object`.
+
 #### Example: Pipeline Factories
 
 ```python

{mongo_pipebuilder-0.3.0 → mongo_pipebuilder-0.4.0}/README.md

@@ -70,6 +70,15 @@ Adds a `$match` stage to filter documents.
 .match({"status": "active", "age": {"$gte": 18}})
 ```
 
+##### `match_expr(expr: Dict[str, Any]) -> Self`
+
+Adds a `$match` stage with an `$expr` condition (expression-based filter; useful for comparing fields or using variables from `let` in subpipelines).
+
+```python
+.match_expr({"$eq": ["$id", "$$teamId"]})
+.match_expr({"$and": [{"$gte": ["$field", "$other"]}, {"$lte": ["$score", 100]}]})
+```
+
 ##### `lookup(from_collection: str, local_field: str, foreign_field: str, as_field: str, pipeline: Optional[List[Dict[str, Any]]] = None) -> Self`
 
 Adds a `$lookup` stage to join with another collection.
@@ -84,6 +93,43 @@ Adds a `$lookup` stage to join with another collection.
 )
 ```
 
+##### `lookup_let(from_collection: str, let: Dict[str, Any], pipeline: Union[List[Dict[str, Any]], PipelineBuilder], as_field: str) -> Self`
+
+Adds a `$lookup` stage with `let` and `pipeline` (join by expression; variables from the current document are available in the subpipeline as `$$var`). Use this when the join condition is an expression (e.g. `$expr`) rather than equality of two fields.
+
+```python
+# With list of stages
+.lookup_let(
+    from_collection="teams",
+    let={"teamId": "$idTeam"},
+    pipeline=[
+        {"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}},
+        {"$project": {"name": 1, "_id": 0}}
+    ],
+    as_field="team"
+)
+
+# With PipelineBuilder for the subpipeline (optionally using match_expr)
+sub = PipelineBuilder().match_expr({"$eq": ["$_id", "$$teamId"]}).project({"name": 1, "_id": 0})
+.lookup_let("teams", {"teamId": "$idTeam"}, sub, as_field="team")
+```
+
+##### `union_with(coll: str, pipeline: Optional[Union[List[Dict[str, Any]], PipelineBuilder]] = None) -> Self`
+
+Adds a `$unionWith` stage to combine documents from the current pipeline with documents from another collection. Optionally runs a subpipeline on the other collection before merging.
+
+```python
+# Union with another collection (no subpipeline)
+.union_with("other_coll")
+
+# With subpipeline as list of stages
+.union_with("logs", [{"$match": {"level": "error"}}, {"$limit": 100}])
+
+# With PipelineBuilder for the subpipeline
+sub = PipelineBuilder().match({"source": "individual"}).project({"name": 1})
+.union_with("sso_individual_statistics", sub)
+```
+
 ##### `add_fields(fields: Dict[str, Any]) -> Self`
 
 Adds a `$addFields` stage to add or modify fields.
@@ -224,7 +270,7 @@ builder.prepend({"$match": {"deleted": False}})
 Inserts a stage at a specific position (0-based index) in the pipeline.
 
 ```python
-builder.match({"status": "active"}).group({"_id": "$category"}, {"count": {"$sum": 1}})
+builder.match({"status": "active"}).group("$category", {"count": {"$sum": 1}})
 builder.insert_at(1, {"$sort": {"name": 1}})
 # Pipeline: [{"$match": {...}}, {"$sort": {...}}, {"$group": {...}}]
 ```
@@ -299,6 +345,15 @@ print(builder.pretty_print())
 # ]
 ```
 
+##### `pretty_print_stage(stage: Union[int, Dict[str, Any]], indent: int = 2, ensure_ascii: bool = False) -> str`
+
+Returns a formatted JSON string representation of a single stage (by index or by dict).
+
+```python
+builder = PipelineBuilder().match({"status": "active"}).limit(10)
+print(builder.pretty_print_stage(0))  # Prints the $match stage
+```
+
 ##### `to_json_file(filepath: Union[str, Path], indent: int = 2, ensure_ascii: bool = False, metadata: Optional[Dict[str, Any]] = None) -> None`
 
 Saves the pipeline to a JSON file. Useful for debugging, comparison, or versioning.
@@ -317,6 +372,17 @@ builder.to_json_file(
 )
 ```
 
+##### `compare_with(other: PipelineBuilder, context_lines: int = 3) -> str`
+
+Returns a unified diff between two pipelines (useful for comparing “new” builder pipelines vs legacy/template pipelines).
+
+```python
+legacy = PipelineBuilder().match({"status": "active"}).limit(10)
+new = PipelineBuilder().match({"status": "inactive"}).limit(10)
+
+print(new.compare_with(legacy))
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -363,6 +429,31 @@ pipeline = (
 )
 ```
 
+### Lookup by expression (lookup_let)
+
+When the join condition is an expression (e.g. `$expr`) rather than matching two fields, use `lookup_let`. The subpipeline can be built with `match_expr()`:
+
+```python
+sub = (
+    PipelineBuilder()
+    .match_expr({"$eq": ["$_id", "$$teamId"]})
+    .project({"name": 1, "slug": 1, "_id": 0})
+)
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "active"})
+    .lookup_let(
+        from_collection="teams",
+        let={"teamId": "$idTeam"},
+        pipeline=sub,
+        as_field="team"
+    )
+    .unwind("team", preserve_null_and_empty_arrays=True)
+    .project({"title": 1, "teamName": "$team.name"})
+    .build()
+)
+```
+
 ### Aggregation with Grouping
 
 ```python
@@ -472,11 +563,39 @@ base = get_base_pipeline(user_id)
 # Create multiple queries from cached base
 recent = base.copy().sort({"createdAt": -1}).limit(10).build()
 by_category = base.copy().match({"category": "tech"}).build()
-with_stats = base.copy().group({"_id": "$category"}, {"count": {"$sum": 1}}).build()
+with_stats = base.copy().group("$category", {"count": {"$sum": 1}}).build()
 
 # Base pipeline is safely cached and reused
 ```
 
+## Best Practices
+
+### Array `_id` after `$group`: prefer `$arrayElemAt` and materialize fields
+
+If you use `$group` with an array `_id` (e.g. `["_idSeason", "_idTournament"]`), avoid relying on `$_id` later in the pipeline.
+Instead, **extract elements with `$arrayElemAt` and store them into explicit fields**, then use those fields in subsequent stages.
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .group(
+        group_by=["$idSeason", "$idTournament"],
+        accumulators={"idTeams": {"$addToSet": "$idTeam"}},
+    )
+    .project({
+        "idSeason": {"$arrayElemAt": ["$_id", 0]},
+        "idTournament": {"$arrayElemAt": ["$_id", 1]},
+        "idTeams": 1,
+        # Optional: preserve array _id explicitly if you really need it later
+        # "_id": "$_id",
+    })
+    .build()
+)
+```
+
+This pattern reduces surprises and helps avoid errors like:
+`$first's argument must be an array, but is object`.
+
 #### Example: Pipeline Factories
 
 ```python

{mongo_pipebuilder-0.3.0 → mongo_pipebuilder-0.4.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mongo-pipebuilder"
-version = "0.3.0"
+version = "0.4.0"
 description = "Type-safe, fluent MongoDB aggregation pipeline builder"
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [
     "typing_extensions>=4.0.0; python_version<'3.11'",
 ]
-license = {text = "MIT"}
+license = "MIT"
 authors = [
     {name = "seligoroff", email = "seligoroff@gmail.com"}
 ]
@@ -19,7 +19,6 @@ keywords = ["mongodb", "aggregation", "pipeline", "builder", "query"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
@@ -51,12 +50,13 @@ addopts = [
     "--cov=src/mongo_pipebuilder",
     "--cov-report=term-missing",
     "--cov-report=html:tests/htmlcov",
-    "--cov-report=json:coverage.json",
-    "--cov-report=xml:coverage.xml",
+    "--cov-report=json:tests/coverage.json",
+    "--cov-report=xml:tests/coverage.xml",
     "--cov-branch",
 ]
 
 [tool.coverage.run]
+data_file = "tests/.coverage"
 source = ["src/mongo_pipebuilder"]
 omit = [
     "*/tests/*",
@@ -99,3 +99,44 @@ warn_no_return = true
 module = "tests.*"
 disallow_untyped_defs = false
 
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+# В Ruff лучше использовать .gitignore, но если нужно строго как было:
+#respect-gitignore = false
+#extend-exclude = ["venv", "deprecated"]
+
+[tool.ruff.lint]
+# E, F — база (Flake8), B — Bugbear (ошибки логики), I — Isort (импорты)
+select = ["E", "F", "W", "B", "C901", "I", "Q", "T20", "COM"]
+ignore = [
+    "B008",    # Аргументы-функции в дефолтных значениях (часто нужно для FastAPI Depends)
+    "E266",    # Слишком много # в комментариях
+    "E712",    # Сравнение с True через == (иногда нужно в SQLAlchemy)    
+    "COM812",  # Конфликт с форматтером (запятые)
+    "COM819",  # Trailing comma в type hints
+    "E203",    # Пробел перед двоеточием (совместимость с Black)
+    "Q003",    # Кавычки в f-строках
+    "PT006",   # Типы параметров pytest
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Игнорируем специфичные ошибки в тестах, скриптах, примерах и инициализации
+"tests/*" = ["T201"]
+"examples/*" = ["T201"]
+
+
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+
+[tool.ruff.lint.isort]
+# Автоматически определяет внутренние модули, чтобы не мешать их с pip-пакетами
+known-first-party = [
+    "api", "cli", "constants", "core", "helpers", 
+    "infrastructure", "schemas", "scripts", "services", 
+    "startup", "tasks", "tests"
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

{mongo_pipebuilder-0.3.0 → mongo_pipebuilder-0.4.0}/src/mongo_pipebuilder/__init__.py

@@ -9,6 +9,6 @@ Author: seligoroff
 
 from mongo_pipebuilder.builder import PipelineBuilder
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = ["PipelineBuilder"]