WIP : Added docstrings for newly interfaced operators

monggregate/operators/arithmetic/add.py

@@ -1,5 +1,23 @@
 """
-Module defining an interface to $and operator
+Module defining an interface to the $add operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/add/#mongodb-expression-exp.-add
+
+Definition
+-------------------
+$add
+Adds numbers together or adds numbers and a date. If one of the arguments is a date, 
+$add treats the other arguments as milliseconds to add to the date.
+
+The $add expression has the following syntax:
+
+    >>> { $add: [ <expression1>, <expression2>, ... ] }
+
+The arguments can be any valid expression 
+as long as they resolve to either all numbers or to numbers and a date. For more information on expressions, see Expressions.
 
 """
 
@@ -12,7 +30,9 @@ class Add(ArithmeticOperator):
 
     Attributes
     -------------------
-        - expressions : list[Any]
+        - expressions, list[Any] : list of valid expressions,
+                                   each expression must resolve to either 
+                                   all numbers or to numbers and a date
             
     
     """

monggregate/operators/arithmetic/divide.py

@@ -1,5 +1,24 @@
 """
-Module defining an interface to $divide operator
+Module defining an interface to the $divide operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/divide/#mongodb-expression-exp.-divide
+
+Definition
+-------------------
+$divide
+Divides one number by another and returns the result. Pass the arguments to 
+$divide in an array.
+
+The $divide expression has the following syntax:
+
+    >>> { $divide: [ <expression1>, <expression2>] }
+
+The first argument is the dividend, and the second argument is the divisor; i.e. the first argument is divided by the second argument.
+
+The arguments can be any valid expression as long as they resolve to numbers. For more information on expressions, see Expressions.
 
 """
 
@@ -8,23 +27,30 @@
 
 class Divide(ArithmeticOperator):
     """
-    xxx
+    Creates a $divide expression
+
+    Attributes
+    -------------------
+        - numerator, Any : the numerator of the division
+        - denominator, Any : the denominator of the division
             
     
     """
 
 
-    expressions : list[Any]
+    numerator : Any
+    denominator : Any
 
     @property
     def statement(self) -> dict:
         return self.resolve({
-            "$divide" : self.expressions
+            "$divide" : [self.numerator, self.denominator]
         })
 
-def divide(*args:Any)->Divide:
-    """Returns an $divide statement"""
+def divide(numerator:Any, denominator:Any)->Divide:
+    """Returns a $divide statement"""
 
     return Divide(
-        expressions=list(args)
-    )
+        numerator=numerator,
+        denominator=denominator
+    )

monggregate/operators/arithmetic/multiply.py

@@ -1,5 +1,23 @@
 """
-Module defining an interface to $multiply operator
+Module defining an interface to the $multiply operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/multiply/#mongodb-expression-exp.-multiply
+
+Definition
+-------------------
+$multiply
+Multiplies numbers together and returns the result. Pass the arguments to 
+$multiply in an array.
+
+The $multiply expression has the following syntax:
+
+    >>> { $multiply: [ <expression1>, <expression2>] }
+
+The arguments can be any valid expression as long as they resolve to numbers. 
+For more information on expressions, see Expressions.
 
 """
 
@@ -8,7 +26,11 @@
 
 class Multiply(ArithmeticOperator):
     """
-    xxx
+    Creates a $multiply expression
+
+    Attributes
+    -------------------
+        - expressions, list[Any] : list of valid expressions
             
     
     """

monggregate/operators/arithmetic/pow.py

@@ -1,5 +1,41 @@
 """
-Module defining an interface to $pow operator
+Module defining an interface to the $pow operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/pow/#mongodb-expression-exp.-pow
+
+Definition
+-------------------
+$pow
+Raises a number to the specified exponent and returns the result. 
+$pow has the following syntax:.
+
+The $pow expression has the following syntax:
+
+    >>> { $pow: [ <expression1>, <expression2>] }
+
+The <number> expression can be any valid expression as long as it resolves to a number.
+
+The <exponent> expression can be any valid expression as long as it resolves to a number.
+
+You cannot raise 0 to a negative exponent.
+
+Behavior
+-------------------
+
+The result will have the same type as the input except when it cannot be represented accurately in that type. In these cases:
+
+    * A 32-bit integer will be converted to a 64-bit integer if the result is representable as a 64-bit integer.
+
+    * A 32-bit integer will be converted to a double if the result is not representable as a 64-bit integer.
+
+    * A 64-bit integer will be converted to double if the result is not representable as a 64-bit integer.
+
+If either argument resolves to a value of null or refers to a field that is missing, $pow returns null. 
+If either argument resolves to NaN, $pow returns NaN.
+
 
 """
 
@@ -8,23 +44,30 @@
 
 class Pow(ArithmeticOperator):
     """
-    xxx
+    Creates a $pow expression
+
+    Attributes
+    -------------------
+        - number, Any : the numerator of the division
+        - exponent, Any : the denominator of the division
             
     
     """
 
 
-    expressions : list[Any]
+    number : Any
+    exponent : Any
 
     @property
     def statement(self) -> dict:
         return self.resolve({
-            "$pow" : self.expressions
+            "$pow" : [self.number, self.exponent]
         })
 
-def pow(*args:Any)->Pow:
+def pow(number:Any, exponent:Any)->Pow:
     """Returns an $pow statement"""
 
     return Pow(
-        expressions=list(args)
-    )
+        number=number,
+        exponent=exponent
+    )

monggregate/operators/arithmetic/substract.py

@@ -1,5 +1,38 @@
 """
-Module defining an interface to $substract operator
+Module defining an interface to the $substract operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/substract/#mongodb-expression-exp.-substract
+
+Definition
+-------------------
+$substract
+Subtracts two numbers to return the difference, or two dates to return the difference in milliseconds, 
+or a date and a number in milliseconds to return the resulting date.
+
+The $substract expression has the following syntax:
+
+    >>> { $substract: [ <expression1>, <expression2>] }
+
+The second argument is subtracted from the first argument.
+
+The arguments can be any valid expression as long as they resolve to numbers and/or dates. To subtract a number from a date, the date must be the first argument. 
+For more information on expressions, see Expressions.
+
+Behavior
+-------------------
+
+Starting in MongoDB 5.0, the result will have the same type as the input except when it cannot be represented accurately in that type. In these cases:
+
+    * A 32-bit integer will be converted to a 64-bit integer if the result is representable as a 64-bit integer.
+
+    * A 32-bit integer will be converted to a double if the result is not representable as a 64-bit integer.
+
+    * A 64-bit integer will be converted to double if the result is not representable as a 64-bit integer.
+
+
 
 """
 
@@ -8,23 +41,30 @@
 
 class Substract(ArithmeticOperator):
     """
-    xxx
+    Creates a $substract expression
+
+    Attributes
+    -------------------
+        - left, Any : the numerator of the division
+        - right, Any : the denominator of the division
             
     
     """
 
 
-    expressions : list[Any]
+    left: Any
+    right: Any
 
     @property
     def statement(self) -> dict:
         return self.resolve({
-            "$substract" : self.expressions
+            "$substract" : [self.left, self.right]
         })
 
-def substract(*args:Any)->Substract:
+def substract(left:Any, right:Any)->Substract:
     """Returns an $substract statement"""
 
     return Substract(
-        expressions=list(args)
+        left=left,
+        right=right
     )

monggregate/operators/boolean/and_.py

@@ -1,5 +1,5 @@
 """
-Module defining an interface to $and operator
+Module defining an interface to the $and operator
 
 Online MongoDB documentation:
 --------------------------------------------------------------------------------------------------------------------

monggregate/operators/conditional/cond.py

@@ -1,5 +1,33 @@
 """
-Module defining an interface to $cond operator
+Module defining an interface to the $cond operator
+
+Online MongoDB documentation:
+--------------------------------------------------------------------------------------------------------------------
+Last Updated (in this package) : 14/08/2023
+Source : https://docs.mongodb.com/manual/reference/operator/aggregation/cond/#mongodb-expression-exp.-cond
+
+Definition
+-------------------
+$cond
+Evaluates a boolean expression to return one of the two specified return expressions.
+
+The $cond expression has one of two syntaxes:
+
+    >>> { $cond: { if: <boolean-expression>, then: <true-case>, else: <false-case> } }
+
+    or
+
+    >>> { $cond: [ <boolean-expression>, <true-case>, <false-case> ] }
+
+
+$cond requires all three arguments (if-then-else) for either syntax.
+
+If the <boolean-expression> evaluates to true, then 
+$cond evaluates and returns the value of the <true-case> expression. 
+Otherwise, $cond evaluates and returns the value of the <false-case> expression.
+
+The arguments can be any valid expression. 
+For more information on expressions, see Expressions.
 
 """
 
@@ -9,7 +37,20 @@
 
 class Cond(ConditionalOperator):
     """
-    xxx
+    Creates a $cond expression
+
+    Attributes
+    -------------------
+        - if_, Any : the boolean expression to evaluate
+        - then_, Any : the expression to evaluate if if_ is true
+        - else_, Any : the expression to evaluate if if_ is false
+
+        - expression, Any : the boolean expression to evaluate (alias for if_)
+        - true_, Any : the expression to evaluate if expression is true (alias for then_)
+        - false_, Any : the expression to evaluate if expression is false (alias for else_)
+
+    if_, then_ and else_ have precedence over expression, true_ and false_
+    Thus only the first syntax will be used whatever combination of arguments is provided (as long as it is valid)
             
     
     """