PYTHON-2802 Link to create command docs in create_collection (#678)

ShaneHarvey · ShaneHarvey · commit be131dda0ab1 · 2021-07-26T15:31:41.000-07:00
PYTHON-2840 Document "let" support for aggregation. (cherry picked from commit 9833ce0)
diff --git a/pymongo/collection.py b/pymongo/collection.py
@@ -2423,24 +2423,6 @@ def aggregate(self, pipeline, session=None, **kwargs):
         """Perform an aggregation using the aggregation framework on this
         collection.
 
-        All optional `aggregate command`_ parameters should be passed as
-        keyword arguments to this method. Valid options include, but are not
-        limited to:
-
-          - `allowDiskUse` (bool): Enables writing to temporary files. When set
-            to True, aggregation stages can write data to the _tmp subdirectory
-            of the --dbpath directory. The default is False.
-          - `maxTimeMS` (int): The maximum amount of time to allow the operation
-            to run in milliseconds.
-          - `batchSize` (int): The maximum number of documents to return per
-            batch. Ignored if the connected mongod or mongos does not support
-            returning aggregate results using a cursor, or `useCursor` is
-            ``False``.
-          - `collation` (optional): An instance of
-            :class:`~pymongo.collation.Collation`. This option is only supported
-            on MongoDB 3.4 and above.
-          - `useCursor` (bool): Deprecated. Will be removed in PyMongo 4.0.
-
         The :meth:`aggregate` method obeys the :attr:`read_preference` of this
         :class:`Collection`, except when ``$out`` or ``$merge`` are used, in
         which case  :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`
@@ -2458,7 +2440,30 @@ def aggregate(self, pipeline, session=None, **kwargs):
           - `pipeline`: a list of aggregation pipeline stages
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
-          - `**kwargs` (optional): See list of options above.
+          - `**kwargs` (optional): extra `aggregate command`_ parameters.
+
+        All optional `aggregate command`_ parameters should be passed as
+        keyword arguments to this method. Valid options include, but are not
+        limited to:
+
+          - `allowDiskUse` (bool): Enables writing to temporary files. When set
+            to True, aggregation stages can write data to the _tmp subdirectory
+            of the --dbpath directory. The default is False.
+          - `maxTimeMS` (int): The maximum amount of time to allow the operation
+            to run in milliseconds.
+          - `batchSize` (int): The maximum number of documents to return per
+            batch. Ignored if the connected mongod or mongos does not support
+            returning aggregate results using a cursor, or `useCursor` is
+            ``False``.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`. This option is only supported
+            on MongoDB 3.4 and above.
+          - `let` (dict): A dict of parameter names and values. Values must be
+            constant or closed expressions that do not reference document
+            fields. Parameters can then be accessed as variables in an
+            aggregate expression context (e.g. ``"$$var"``). This option is
+            only supported on MongoDB >= 5.0.
+          - `useCursor` (bool): Deprecated. Will be removed in PyMongo 4.0.
 
         :Returns:
           A :class:`~pymongo.command_cursor.CommandCursor` over the result
diff --git a/pymongo/database.py b/pymongo/database.py
@@ -357,22 +357,6 @@ def create_collection(self, name, codec_options=None,
         creation. :class:`~pymongo.errors.CollectionInvalid` will be
         raised if the collection already exists.
 
-        Options should be passed as keyword arguments to this method. Supported
-        options vary with MongoDB release. Some examples include:
-
-          - ``size``: desired initial size for the collection (in
-            bytes). For capped collections this size is the max
-            size of the collection.
-          - ``capped``: if True, this is a capped collection
-          - ``max``: maximum number of objects if capped (optional)
-          - ``timeseries``: a document specifying configuration options for
-            timeseries collections
-          - ``expireAfterSeconds``: the number of seconds after which a
-            document in a timeseries collection expires
-
-        See the MongoDB documentation for a full list of supported options by
-        server version.
-
         :Parameters:
           - `name`: the name of the collection to create
           - `codec_options` (optional): An instance of
@@ -395,7 +379,21 @@ def create_collection(self, name, codec_options=None,
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
           - `**kwargs` (optional): additional keyword arguments will
-            be passed as options for the create collection command
+            be passed as options for the `create collection command`_
+
+        All optional `create collection command`_ parameters should be passed
+        as keyword arguments to this method. Valid options include, but are not
+        limited to:
+
+          - ``size``: desired initial size for the collection (in
+            bytes). For capped collections this size is the max
+            size of the collection.
+          - ``capped``: if True, this is a capped collection
+          - ``max``: maximum number of objects if capped (optional)
+          - ``timeseries``: a document specifying configuration options for
+            timeseries collections
+          - ``expireAfterSeconds``: the number of seconds after which a
+            document in a timeseries collection expires
 
         .. versionchanged:: 3.11
            This method is now supported inside multi-document transactions
@@ -412,6 +410,9 @@ def create_collection(self, name, codec_options=None,
 
         .. versionchanged:: 2.2
            Removed deprecated argument: options
+
+        .. _create collection command:
+            https://docs.mongodb.com/manual/reference/command/create
         """
         with self.__client._tmp_session(session) as s:
             # Skip this check in a transaction where listCollections is not
@@ -476,21 +477,6 @@ def aggregate(self, pipeline, session=None, **kwargs):
                for operation in cursor:
                    print(operation)
 
-        All optional `aggregate command`_ parameters should be passed as
-        keyword arguments to this method. Valid options include, but are not
-        limited to:
-
-          - `allowDiskUse` (bool): Enables writing to temporary files. When set
-            to True, aggregation stages can write data to the _tmp subdirectory
-            of the --dbpath directory. The default is False.
-          - `maxTimeMS` (int): The maximum amount of time to allow the operation
-            to run in milliseconds.
-          - `batchSize` (int): The maximum number of documents to return per
-            batch. Ignored if the connected mongod or mongos does not support
-            returning aggregate results using a cursor.
-          - `collation` (optional): An instance of
-            :class:`~pymongo.collation.Collation`.
-
         The :meth:`aggregate` method obeys the :attr:`read_preference` of this
         :class:`Database`, except when ``$out`` or ``$merge`` are used, in
         which case  :attr:`~pymongo.read_preferences.ReadPreference.PRIMARY`
@@ -506,7 +492,27 @@ def aggregate(self, pipeline, session=None, **kwargs):
           - `pipeline`: a list of aggregation pipeline stages
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
-          - `**kwargs` (optional): See list of options above.
+          - `**kwargs` (optional): extra `aggregate command`_ parameters.
+
+        All optional `aggregate command`_ parameters should be passed as
+        keyword arguments to this method. Valid options include, but are not
+        limited to:
+
+          - `allowDiskUse` (bool): Enables writing to temporary files. When set
+            to True, aggregation stages can write data to the _tmp subdirectory
+            of the --dbpath directory. The default is False.
+          - `maxTimeMS` (int): The maximum amount of time to allow the operation
+            to run in milliseconds.
+          - `batchSize` (int): The maximum number of documents to return per
+            batch. Ignored if the connected mongod or mongos does not support
+            returning aggregate results using a cursor.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `let` (dict): A dict of parameter names and values. Values must be
+            constant or closed expressions that do not reference document
+            fields. Parameters can then be accessed as variables in an
+            aggregate expression context (e.g. ``"$$var"``). This option is
+            only supported on MongoDB >= 5.0.
 
         :Returns:
           A :class:`~pymongo.command_cursor.CommandCursor` over the result
