fixed class docstrings in stages and pipeline.py

monggregate/pipeline.py

@@ -221,6 +221,7 @@ def add_fields(self, document:dict={}, **kwargs:Any)->"Pipeline":
     def bucket(self, *, by:Any, boundaries:list, default:Any=None, output:dict|None=None)->"Pipeline":
         """
         Adds a bucket stage to the current pipeline.
+        This stage aggregates documents into buckets specified by the boundaries argument.
 
         Arguments:
         ---------------------------------
@@ -270,7 +271,9 @@ def bucket(self, *, by:Any, boundaries:list, default:Any=None, output:dict|None=
 
     def bucket_auto(self, *, by:Any, buckets:int, output:dict=None, granularity:GranularityEnum|None=None)->"Pipeline":
         """
-        Adds a bucket_auto stage to the current pipeline
+        Adds a bucket_auto stage to the current pipeline.
+        This stage aggregates documents into buckets automatically computed to statisfy the number of buckets desired
+        and provided as an input.
 
         Arguments:
         ---------------------------------
@@ -309,7 +312,8 @@ def bucket_auto(self, *, by:Any, buckets:int, output:dict=None, granularity:Gran
 
     def count(self, name:str)->"Pipeline":
         """
-        Adds a count stage to the current pipeline
+        Adds a count stage to the current pipeline.
+        Passes a document to the next stage that contains a count of the number of documents input to the stage.
 
         Arguments
         -------------------------------
@@ -352,7 +356,9 @@ def explode(self, path:str, *,  include_array_index:str|None=None, always:bool=F
     def group(self, *,  by:Any|None=None, query:dict={})->"Pipeline":
         """
         Adds a group stage to the current pipeline.
-
+        The group stage separates documents into groups according to a "group key". The output is one document for each unique group key.
+        The output documents can also contain additional fields that are set using accumulator expressions.
+        
         Arguments:
         ------------------------
             - by,  str | list[str] | set[str] | dict | None : field or group of fields to group by
@@ -371,6 +377,7 @@ def group(self, *,  by:Any|None=None, query:dict={})->"Pipeline":
     def limit(self, value:int)->"Pipeline":
         """
         Adds a limit stage to the current pipeline.
+        Limits the number of documents passed to the next stage in the pipeline.
 
         Arguments:
         ---------------------------------
@@ -393,7 +400,10 @@ def lookup(self, *, \
         right_on:str=None)->"Pipeline":
         """
         Adds a lookup stage to the current pipeline.
-
+        Performs a left outer join to a collection in the same database to filter in documents from the "joined" collection for processing. The
+        lookup stage adds a new array field to each input document. The new array field contains the matching documents from the "joined" collection. The
+        lookup stage passes these reshaped documents to the next stage.
+        
         Arguments:
         ----------------------------
             - right / from (official MongoDB name), str : foreign collection
@@ -550,6 +560,7 @@ def __inner_join(self, right:str, on:str|None, left_on:str|None, right_on:str|No
     def match(self, query:dict={}, **kwargs:Any)->"Pipeline":
         """
         Adds a match stage to the current pipeline.
+        Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline stage.
 
         Arguments:
         -------------------
@@ -569,6 +580,7 @@ def match(self, query:dict={}, **kwargs:Any)->"Pipeline":
     def out(self, collection:str, *, db:str|None=None)->"Pipeline":
         """
         Adds an out stage to the current pipeline.
+        Takes the documents returned by the aggregation pipeline and writes them to a specified collection. Starting in MongoDB 4.4, you can specify the output database.
 
         Arguments:
         ---------------------------
@@ -593,6 +605,7 @@ def project(self, *,\
         **kwargs:Any)->"Pipeline":
         """
         Adds a project stage to the current pipeline.
+        Passes along the documents with the requested fields to the next stage in the pipeline. The specified fields can be existing fields from the input documents or newly computed fields.
 
         Arguments:
         ---------------------------
@@ -618,7 +631,10 @@ def project(self, *,\
     def replace_root(self, path:str|None=None, *, document:dict|None=None)->"Pipeline":
         """
         Adds a replace_root stage to the current pipeline.
-
+        Replaces the input document with the specified document.
+        The operation replaces all existing fields in the input document, including the _id field.
+        You can promote an existing embedded document to the top level, or create a new document for promotion
+        
         Arguments:
         -------------------------------------
 
@@ -655,6 +671,7 @@ def replace_with(self, path:str|None=None, *,document:dict|None=None)->"Pipeline
     def sample(self, value:int)->"Pipeline":
         """
         Adds a sample stage to the current pipeline.
+        Randomly selects the specified number of documents from the input documents.
 
         Arguments:
         -----------------------
@@ -683,7 +700,9 @@ def search(
             **kwargs:Any
     )->"Pipeline":
         """
-        Adds a search stage to the current pipeline
+        Adds a search stage to the current pipeline.
+        The search stage performs a full-text search on the specified field or fields which must be covered by an Atlas Search index.
+
         NOTE : if used, search has to be the first stage of the pipeline
 
         Arguments:
@@ -758,7 +777,9 @@ def search_meta(
             **kwargs:Any
     )->"Pipeline":
         """
-        Adds a searchMeta stage to the current pipeline
+        Adds a searchMeta stage to the current pipeline.
+        The searchMeta stage returns different types of metadata result documents.
+        
         NOTE : if used, search has to be the first stage of the pipeline
 
         Arguments:
@@ -812,6 +833,9 @@ def search_meta(
     def set(self, document:dict={}, **kwargs:Any)->"Pipeline":
         """
         Adds a set stage to the current pipeline.
+        Adds new fields to documents. $set outputs documents that conain all existing fields from the inputs documents
+        and newly added fields.
+        Both stages are equivalent to a $project stage that explicitly specifies all existing fields in the inputs documents and adds the new fields.
 
         Arguments:
         ---------------------------------
@@ -829,6 +853,7 @@ def set(self, document:dict={}, **kwargs:Any)->"Pipeline":
     def skip(self, value:int)->"Pipeline":
         """
         Adds a skip stage to the current pipeline.
+        Skips over the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline.
 
         Arguments:
         -----------------------
@@ -850,7 +875,8 @@ def sort(self, *,\
         **kwargs:Any)->"Pipeline":
         """
         Adds a sort stage to the current pipeline.
-
+        Sorts all input documents and returns them to the pipeline in sorted order.
+        
         Arguments:
         -----------------------
             - statement, dict : the statement generated after instantiation
@@ -890,7 +916,12 @@ def sort(self, *,\
     def sort_by_count(self, by:str)->"Pipeline":
         """
         Adds a sort_by_count stage to the current pipeline.
+        Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.
+
+        Each output document contains two fields: an _id field containing the distinct grouping value,
+        and a count field containing the number of documents belonging to that grouping or category.
 
+        The documents are sorted by count in descending order.
 
         Arguments:
         -------------------------
@@ -908,7 +939,9 @@ def sort_by_count(self, by:str)->"Pipeline":
     def union_with(self, collection:str, pipeline:list[dict]|None=None)->"Pipeline":
         """
         Adds a union_with stage to the current pipeline.
+        Performs a union of two collections. unionWith combines pipeline results from two collections into a single result set. The stage outputs the combined result set (including duplicates) to the next stage.
 
+    The order in which the combined result set documents are output is unspecified.
         Arguments:
         ---------------------------------
             - collection / coll, str : The collection or view whose pipeline results you wish to include in the result set
@@ -949,6 +982,7 @@ def unwind(self, path:str, include_array_index:str|None=None, always:bool=False)
     def unset(self, field:str=None, fields:list[str]|None=None)->"Pipeline":
         """
         Adds an unset stage to the current pipeline.
+        Removes/excludes fields from documents.
         
         Arguments:
         -------------------------------

monggregate/stages/count.py

@@ -37,26 +37,30 @@
 from monggregate.stages.stage import Stage
 from monggregate.fields import FieldName
 
-
 class Count(Stage):
     """
-    Creates a count statement for an aggregation pipeline count stage
+    Creates a count statement for an aggregation pipeline count stage.
+
+    Extended definition:
+    ---------------------
+    Passes a document to the next stage that contains a count of the number of documents input to the stage.
+
+    Online MongoDB documentation:
+    ----------------------------
+    Last Updated (in this package) : 18/09/2022
+    Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/count/#mongodb-pipeline-pipe.-count
 
     Attributes:
     -------------------------------
-
-        - name, str : name of the output field which the count as its value.
-                      Must be a non-empty string,
-                      NOTE : Must not start with $ and must not contain the
-                             . character and must not be empty
+    - name, str : name of the output field which the count as its value.
+                  Must be a non-empty string, must not start with $, and must not contain the . character.
 
     """
 
-    name : FieldName
+    name: FieldName
 
     @property
-    def statement(self)-> dict:
-
-        return  self.resolve({
-            "$count" : self.name
+    def statement(self) -> dict:
+        return self.resolve({
+            "$count": self.name
         })

monggregate/stages/group.py

@@ -72,20 +72,32 @@ class Group(Stage):
     """
     Creates a group statement for an aggregation pipeline group stage.
 
+    Extended definition
+    ------------------------
+    The group stage separates documents into groups according to a "group key". The output is one document for each unique group key.
+
+    A group key is often a field, or group of fields. The group key can also be the result of an expression. Use the _id field in the $group pipeline stage to set the group key. See below for
+    usage examples.
+
+    In the group stage output, the _id field is set to the group key for that document.
+
+    The output documents can also contain additional fields that are set using accumulator expressions.
+
+    NOTE : The group stage does not order its output documents.
+
+    Online MongoDB documentation:
+    --------------------------------------------------------------------------------------------
+    Last Updated (in this package) : 18/09/2022
+    Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#mongodb-pipeline-pipe.-group
+
     Attributes:
     ------------------------
         - by,  str | list[str] | set[str] | dict | None : field or group of fields to group by
         - query, dict | None : Computed aggregated values (per group)
-
-
     """
 
     by : Any  = pyd.Field(None, alias = "_id") # | or any constant value, in this case
                                                 # the stage returns a single document that aggregates values across all of the input documents
-    #sum
-    #avg
-    #count
-    #result : Any
     query : dict = {}
 
     # Validators

monggregate/stages/limit.py

@@ -5,7 +5,10 @@
 --------------------------------------------------------------------------------------------------------------------
 
 Last Updated (in this package) : 18/09/2022
-Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#mongodb-pipeline-pipe.-group
+Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit
+
+# Definition
+---------------------------------
 
 Limits the number of documents passed to the next stage in the pipeline.
 
@@ -55,14 +58,22 @@ class Limit(Stage):
     """
     Creates a $limit statement for an aggregation pipeline $limit stage.
 
+    Extended definition:
+    ---------------------
+    Limits the number of documents passed to the next stage in the pipeline.
+
+    Online MongoDB documentation:
+    ------------------------------
+    Last Updated (in this package) : 18/09/2022
+    Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#mongodb-pipeline-pipe.-group
+
     Attributes:
-    ---------------------------------
+    -----------
         - value, int : the actual limit to apply.
                        limits the number of documents returned by the stage to
                        the provided value.
-
     """
-
+    
     value : int = pyd.Field(gt=0)
 
     @property

monggregate/stages/lookup.py

@@ -260,8 +260,25 @@ class Lookup(Stage):
     """
     Creates a lookup statement for an aggregation pipeline lookup stage.
 
+    `Changed in version 5.1`
+
+    Extended definition:
+    --------------------
+
+    Performs a left outer join to a collection in the same database to filter in documents from the "joined" collection for processing. The lookup stage adds a new array field to each input document. The new array field contains the matching documents from the "joined" collection. The
+    lookup stage passes these reshaped documents to the next stage.
+
+    Starting in MongoDB 5.1, $lookup works across sharded collections.
+
+    To combine elements from two different collections, use the $unionWith pipeline stage.
+
+    Online MongoDB documentation:
+    -----------------------------
+    Last Updated (in this package) : 23/09/2022
+    Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#mongodb-pipeline-pipe.-lookup
+
     Attributes:
-    ----------------------------
+    -----------
         - right / from (official MongoDB name), str : foreign collection
         - left_on / local_field (official MongoDB name)), str | None : field of the current collection to join on
         - right_on / foreign_field (official MongoDB name), str | None : field of the foreign collection to join on

monggregate/stages/match.py

@@ -53,8 +53,18 @@ class Match(Stage):
     """
     Creates a match statement for an aggregation pipeline match stage.
 
+    Extended definition:
+    --------------------
+    Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline stage.
+
+    Online MongoDB documentation:
+    -----------------------------
+
+    Last Updated (in this package) : 16/09/2022
+    Source :  https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/#mongodb-pipeline-pipe.-match
+
     Attributes:
-    -------------------
+    -----------
 
         - statement, dict : the statement generated during instantiation after parsing the other arguments
         - query, dict : the query use to filter the documents

monggregate/stages/out.py

@@ -119,13 +119,28 @@ class Out(Stage):
     """
     Creates a out statement for an aggregation pipeline out stage.
 
+    Extended definition:
+    --------------------
+    Takes the documents returned by the aggregation pipeline and writes them to a specified collection.
+    The out stage must be the last stage in the pipeline. The out operator lets the aggregation framework return result sets of any size.
+
+    WARNING : out replaces the specified collection if it exists.
+    See [Replace Existing Collection](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/#std-label-replace-existing-collection) for details.
+
+    
+    Online MongoDB documentation:
+    -----------------------------
+    Last Updated (in this package) : 23/09/2022
+    Source : https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/#mongodb-pipeline-pipe.-out
+
     Attributes:
-    ---------------------------
-        - db, str|None : name of the db to output the collection. Defaults to current collection.
+    -----------
+        - db, str|None : name of the db to output the collection. Defaults to the current collection.
         - collection, str : name of the output collection
 
     """
 
+
     db : str|None
     collection : str = pyd.Field(...,alias="coll")