diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 0f09af5a..b303329c 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -97,6 +97,77 @@ instance on port ``27017`` of ``localhost``: uri = "mongodb://localhost:27017/" client = MongoClient(uri) +The following table describes the positional parameters that the ``MongoClient()`` +constructor accepts. All parameters are optional. + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Parameter + - Description + + * - ``host`` + - The hostname, IP address, or Unix domain socket path of the MongoDB deployment. + If your application connects to a replica set or sharded cluster, you can specify + multiple hostnames or IP addresses in a Python list. + + If you pass a literal IPv6 address, you must enclose the address in square brackets + (``[ ]``). For example, pass the value ``[::1]`` to connect to localhost. + + {+driver-short+} doesn't support :wikipedia:`multihomed ` and + :wikipedia:`round-robin DNS ` addresses. + + **Data type:** ``Union[str, Sequence[str]]`` + **Default value:** ``"localhost"`` + + * - ``port`` + - The port number {+mdb-server+} is running on. + + You can include the port number in the ``host`` argument + instead of using this parameter. + + **Data type:** ``int`` + **Default value:** ``27017`` + + * - ``document_class`` + - The default class that the client uses to decode BSON documents returned by queries. + This parameter supports the ``bson.raw_bson.RawBSONDocument`` type, as well as + subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``. + + If you specify ``bson.son.SON`` as the document class, you must also specify types + for the key and value. + + **Data type:** ``Type[_DocumentType]`` + + * - ``tz_aware`` + - If this parameter is ``True``, the client treats ``datetime`` values as aware. + Otherwise, it treats them as naive. + + For more information about aware and naive ``datetime`` values, see + `datetime `__ in the Python + documentation. + + **Data type:** ``bool`` + + * - ``connect`` + - If this parameter is ``True``, the client begins connecting to MongoDB + in the background immediately after you create it. If this parameter is ``False``, + the client connects to MongoDB when it performs the first database operation. + + If your application is running in a + :wikipedia:`function-as-a-service (FaaS) ` + environment, the default value is ``False``. Otherwise, the default value is ``True``. + + **Data type:** ``bool`` + + * - ``type_registry`` + - An instance of the ``TypeRegistry`` class to enable encoding and decoding of + custom types. For more information about encoding and decoding custom types, + see :ref:`pymongo-custom-types`. + + **Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__ + .. tip:: Reusing Your Client Because each ``MongoClient`` object represents a pool of connections to the @@ -105,6 +176,28 @@ instance on port ``27017`` of ``localhost``: a process, the child process *does* need its own ``MongoClient`` object. To learn more, see the :ref:`FAQ ` page. +Type Hints +---------- + +If you're using Python v3.5 or later, you can add type hints to your Python code. + +The following code example shows how to declare a type hint for a ``MongoClient`` +object: + +.. code-block:: python + + client: MongoClient = MongoClient() + +In the previous example, the code doesn't specify a type for the documents that the +``MongoClient`` object will work with. To specify a document type, +include the ``Dict[str, Any]`` type when you +create the ``MongoClient`` object, as shown in the following example: + +.. code-block:: python + + from typing import Any, Dict + client: MongoClient[Dict[str, Any]] = MongoClient() + API Documentation -----------------