rework tutorial (#39)

BeanieODM · May 18, 2021 · 702b560 · 702b560
1 parent 87cbc52
commit 702b560
Show file tree

Hide file tree

Showing 17 changed files with 238 additions and 173 deletions.
diff --git a/README.md b/README.md
@@ -65,7 +65,7 @@ class Product(Document):  # This is the model
 ```
 
 More details about Documents, collections, and indexes configuration could be
-found in the [tutorial](https://roman-right.github.io/beanie/tutorial/install/).
+found in the [documentation](https://roman-right.github.io/beanie/document/).
 
 ### Initialization
 
@@ -109,7 +109,7 @@ peanut_bar = Product(name="Peanut Bar", price=4.44, category=chocolate)
 await Product.insert_many([milka, peanut_bar])
 ```
 
-Other details and examples could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/insert/)
+Other details and examples could be found in the [documentation](https://roman-right.github.io/beanie/insert/)
 
 ### Find
 
@@ -238,7 +238,7 @@ all_products = await Product.all().to_list()
 ```
 
 Information about sorting, skips, limits, and projections could be found in
-the [tutorial](https://roman-right.github.io/beanie/tutorial/find/)
+the [documentation](https://roman-right.github.io/beanie/find/)
 
 ### Update
 
@@ -324,7 +324,7 @@ await Product.find(
 ```
 
 More details and examples about update queries could be found in
-the [tutorial](https://roman-right.github.io/beanie/tutorial/update/)
+the [documentation](https://roman-right.github.io/beanie/update/)
 
 ### Delete
 
@@ -359,7 +359,7 @@ await Product.find(
 await Product.delete_all()
 ```
 
-More information could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/delete/)
+More information could be found in the [documentation](https://roman-right.github.io/beanie/delete/)
 
 ### Aggregate
 
@@ -369,14 +369,16 @@ You can aggregate and over the whole collection, using `aggregate()` method of t
 
 `FindMany` and `Document` classes implements [AggregateMethods](https://roman-right.github.io/beanie/api/interfaces/#aggregatemethods) interface with preset methods
 
-**With search criteria**
+Example of average calculation:
+
+*With search criteria*
 ```python
 avg_price = await Product.find(
     Product.category.name == "Chocolate"
 ).avg(Product.price)
 ```
 
-**Over the whole collection**
+*Over the whole collection*
 ```python
 avg_price = await Product.avg(Product.price)
 ```
@@ -399,12 +401,9 @@ result = await Product.find(
 
 ```
 
-Information about aggregation preset aggregation methods and native syntax
-aggregations could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/aggregate/)
-
 ### Documentation
 
-- **[Tutorial](https://roman-right.github.io/beanie/tutorial/install/)** -
+- **[Doc](https://roman-right.github.io/beanie/)** -
   Usage examples with descriptions
 - **[API](https://roman-right.github.io/beanie/api/document/)** - Full list of
   the classes and methods

diff --git a/beanie/__init__.py b/beanie/__init__.py
@@ -4,7 +4,7 @@
 from beanie.odm.utils.general import init_beanie
 from beanie.odm.documents import Document
 
-__version__ = "1.0.3"
+__version__ = "1.0.4"
 __all__ = [
     # ODM
     "Document",

diff --git a/beanie/odm/documents.py b/beanie/odm/documents.py
@@ -379,20 +379,20 @@ async def delete_all(
     def aggregate(
         cls,
         aggregation_pipeline: list,
-        aggregation_model: Type[BaseModel] = None,
+        projection_model: Type[BaseModel] = None,
         session: Optional[ClientSession] = None,
     ) -> AggregationQuery:
         """
         Aggregate over collection.
         Returns [AggregationQuery](https://roman-right.github.io/beanie/api/queries/#aggregationquery) query object
         :param aggregation_pipeline: list - aggregation pipeline
-        :param aggregation_model: Type[BaseModel]
+        :param projection_model: Type[BaseModel]
         :param session: Optional[ClientSession]
         :return: [AggregationQuery](https://roman-right.github.io/beanie/api/queries/#aggregationquery)
         """
         return cls.find_all().aggregate(
             aggregation_pipeline=aggregation_pipeline,
-            projection_model=aggregation_model,
+            projection_model=projection_model,
             session=session,
         )
 

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,6 +1,10 @@
 # Changelog
 Beanie project changes
 
+## [1.0.4] - 2021-05-18
+### Fixed
+- `aggregation_model` -> `projection_model` parameter. [PR](https://github.com/roman-right/beanie/pull/39)
+
 ## [1.0.3] - 2021-05-16
 ### Added
 - Index kwargs in the Indexed field. [PR](https://github.com/roman-right/beanie/pull/32). 
@@ -95,4 +99,5 @@ Beanie project changes
 [1.0.0]: https://pypi.org/project/beanie/1.0.0
 [1.0.1]: https://pypi.org/project/beanie/1.0.1
 [1.0.2]: https://pypi.org/project/beanie/1.0.2
-[1.0.3]: https://pypi.org/project/beanie/1.0.3
+[1.0.3]: https://pypi.org/project/beanie/1.0.3
+[1.0.4]: https://pypi.org/project/beanie/1.0.4
diff --git a/docs/index.md b/docs/index.md
@@ -65,7 +65,7 @@ class Product(Document):  # This is the model
 ```
 
 More details about Documents, collections, and indexes configuration could be
-found in the [tutorial](https://roman-right.github.io/beanie/tutorial/install/).
+found in the [documentation](https://roman-right.github.io/beanie/document/).
 
 ### Initialization
 
@@ -109,7 +109,7 @@ peanut_bar = Product(name="Peanut Bar", price=4.44, category=chocolate)
 await Product.insert_many([milka, peanut_bar])
 ```
 
-Other details and examples could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/insert/)
+Other details and examples could be found in the [documentation](https://roman-right.github.io/beanie/insert/)
 
 ### Find
 
@@ -238,7 +238,7 @@ all_products = await Product.all().to_list()
 ```
 
 Information about sorting, skips, limits, and projections could be found in
-the [tutorial](https://roman-right.github.io/beanie/tutorial/find/)
+the [documentation](https://roman-right.github.io/beanie/find/)
 
 ### Update
 
@@ -324,7 +324,7 @@ await Product.find(
 ```
 
 More details and examples about update queries could be found in
-the [tutorial](https://roman-right.github.io/beanie/tutorial/update/)
+the [documentation](https://roman-right.github.io/beanie/update/)
 
 ### Delete
 
@@ -359,7 +359,7 @@ await Product.find(
 await Product.delete_all()
 ```
 
-More information could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/delete/)
+More information could be found in the [documentation](https://roman-right.github.io/beanie/delete/)
 
 ### Aggregate
 
@@ -369,14 +369,16 @@ You can aggregate and over the whole collection, using `aggregate()` method of t
 
 `FindMany` and `Document` classes implements [AggregateMethods](https://roman-right.github.io/beanie/api/interfaces/#aggregatemethods) interface with preset methods
 
-**With search criteria**
+Example of average calculation:
+
+*With search criteria*
 ```python
 avg_price = await Product.find(
     Product.category.name == "Chocolate"
 ).avg(Product.price)
 ```
 
-**Over the whole collection**
+*Over the whole collection*
 ```python
 avg_price = await Product.avg(Product.price)
 ```
@@ -399,12 +401,9 @@ result = await Product.find(
 
 ```
 
-Information about aggregation preset aggregation methods and native syntax
-aggregations could be found in the [tutorial](https://roman-right.github.io/beanie/tutorial/aggregate/)
-
 ### Documentation
 
-- **[Tutorial](https://roman-right.github.io/beanie/tutorial/install/)** -
+- **[Doc](https://roman-right.github.io/beanie/)** -
   Usage examples with descriptions
 - **[API](https://roman-right.github.io/beanie/api/document/)** - Full list of
   the classes and methods

diff --git a/docs/tutorial/aggregate.md b/docs/tutorial/aggregate.md
@@ -1,64 +1,39 @@
 # Aggregations
 
-[AggregationQuery](https://roman-right.github.io/beanie/api/queries/#aggregationquery) is used to aggregate data
-over the whole collection or the subset selected with
-the [FindMany](https://roman-right.github.io/beanie/api/queries/#findmany) query.
+You can aggregate and over the whole collection, using `aggregate()` method of the `Document` class, and over search criteria, using `FindMany` instance. 
 
-## Preset aggregations
+#### Aggregation Methods
 
-[AggregateMethods](https://roman-right.github.io/beanie/api/interfaces/#aggregatemethods) is a list of preset
-aggregations, which simplifies some use cases.
+`FindMany` and `Document` classes implements [AggregateMethods](https://roman-right.github.io/beanie/api/interfaces/#aggregatemethods) interface with preset methods
 
-```python
-class Sample(Document):
-    category: str
-    price: int
-    count: int
-
-
-sum_count = await Sample.find(Sample.price <= 100).sum(Sample.count)
+Example of average calculation:
 
-# Or for the whole collection:
-
-avg_price = await Sample.avg(Sample.count)
+*With search criteria*
+```python
+avg_price = await Product.find(
+    Product.category.name == "Chocolate"
+).avg(Product.price)
+```
 
+*Over the whole collection*
+```python
+avg_price = await Product.avg(Product.price)
 ```
 
-## Aggregate over collection
+#### Native syntax
 
-`AggregationQuery` implements async generator pattern - results
-are available via `async for` loop
+You can use the native PyMongo syntax of the aggregation pipelines to aggregate over the whole collection or over the subset too. `projection_model` parameter is responsible for the output format. It will return dictionaries, if this parameter is not provided.
 
 ```python
 class OutputItem(BaseModel):
     id: str = Field(None, alias="_id")
     total: int
 
 
-async for item in Sample.aggregate(
-    [{"$group": {"_id": "$category", "total": {"$sum": "$count"}}}],
-    aggregation_model=OutputItem,
-):
-    ...
-```
-
-or with `to_list` method:
-
-```python
-result = await Sample.aggregate(
-    [{"$group": {"_id": "$category", "total": {"$sum": "$count"}}}]
+result = await Product.find(
+    Product.category.name == "Chocolate").aggregate(
+    [{"$group": {"_id": "$category.name", "total": {"$avg": "$price"}}}],
+    projection_model=OutputItem
 ).to_list()
-```
-
-If the `aggregation_model` parameter is not set, it will return dicts.
-
-## Over subsets
-
-To aggregate over a specific subset, FindQuery could be used.
-
-```python
-result = await Sample.find(Sample.price < 10).aggregate(
-    [{"$group": {"_id": "$category", "total": {"$sum": "$count"}}}]
-).to_list()
-```
 
+```
diff --git a/docs/tutorial/delete.md b/docs/tutorial/delete.md
@@ -1,5 +1,7 @@
 # Delete documents
 
+Beanie supports, and single, and batch deletions:
+
 ## Single
 
 ```python