@@ -97,18 +97,136 @@ instance on port ``27017`` of ``localhost``:
9797 uri = "mongodb://localhost:27017/"
9898 client = MongoClient(uri)
9999
100- .. tip:: Reusing Your Client
100+ The following table describes the positional parameters that the ``MongoClient()``
101+ constructor accepts. All parameters are optional.
101102
102- Because each ``MongoClient`` object represents a pool of connections to the
103- database, most applications require only a single instance of
104- ``MongoClient``, even across multiple requests. However, if you fork
105- a process, the child process *does* need its own ``MongoClient`` object.
106- To learn more, see the :ref:`FAQ <pymongo-faq>` page.
103+ .. list-table::
104+ :widths: 20 80
105+ :header-rows: 1
106+
107+ * - Parameter
108+ - Description
109+
110+ * - ``host``
111+ - The hostname, IP address, or Unix domain socket path of the MongoDB deployment.
112+ If your application connects to a replica set or sharded cluster, you can specify
113+ multiple hostnames or IP addresses in a Python list.
114+
115+ If you pass a literal IPv6 address, you must enclose the address in square brackets
116+ (``[ ]``). For example, pass the value ``[::1]`` to connect to localhost.
117+
118+ {+driver-short+} doesn't support :wikipedia:`multihomed <Multihoming>` and
119+ :wikipedia:`round-robin DNS <Round-robin_DNS>` addresses.
120+
121+ **Data type:** ``Union[str, Sequence[str]]``
122+ **Default value:** ``"localhost"``
123+
124+ * - ``port``
125+ - The port number {+mdb-server+} is running on.
126+
127+ You can include the port number in the ``host`` argument
128+ instead of using this parameter.
129+
130+ **Data type:** ``int``
131+ **Default value:** ``27017``
132+
133+ * - ``document_class``
134+ - The default class that the client uses to decode BSON documents returned by queries.
135+ This parameter supports the ``bson.raw_bson.RawBSONDocument`` type, as well as
136+ subclasses of the ``collections.abc.Mapping`` type, such as ``bson.son.SON``.
137+
138+ If you specify ``bson.son.SON`` as the document class, you must also specify types
139+ for the key and value.
140+
141+ **Data type:** ``Type[_DocumentType]``
142+
143+ * - ``tz_aware``
144+ - If this parameter is ``True``, the client treats ``datetime`` values as aware.
145+ Otherwise, it treats them as naive.
146+
147+ For more information about aware and naive ``datetime`` values, see
148+ `datetime <https://docs.python.org/3/library/datetime.html>`__ in the Python
149+ documentation.
150+
151+ **Data type:** ``bool``
152+
153+ * - ``connect``
154+ - If this parameter is ``True``, the client begins connecting to MongoDB
155+ in the background immediately after you create it. If this parameter is ``False``,
156+ the client connects to MongoDB when it performs the first database operation.
157+
158+ If your application is running in a
159+ :wikipedia:`function-as-a-service (FaaS) <Function_as_a_service>`
160+ environment, the default value is ``False``. Otherwise, the default value is ``True``.
161+
162+ **Data type:** ``bool``
163+
164+ * - ``type_registry``
165+ - An instance of the ``TypeRegistry`` class to enable encoding and decoding of
166+ custom types. For more information about encoding and decoding custom types,
167+ see :ref:`pymongo-custom-types`.
168+
169+ **Data type:** `TypeRegistry <{+api-root+}bson/codec_options.html#bson.codec_options.TypeRegistry>`__
170+
171+ Concurrent Execution
172+ --------------------
173+
174+ The following sections describe {+driver-short+}'s support for concurrent execution
175+ mechanisms.
176+
177+ Multithreading
178+ ~~~~~~~~~~~~~~
179+
180+ {+driver-short+} is thread-safe and provides built-in connection pooling
181+ for threaded applications.
182+ Because each ``MongoClient`` object represents a pool of connections to the
183+ database, most applications require only a single instance of
184+ ``MongoClient``, even across multiple requests.
185+
186+ .. _pymongo-forks:
187+
188+ Multiple Forks
189+ ~~~~~~~~~~~~~~~
190+
191+ {+driver-short+} supports calling the ``fork()`` method to create a new process.
192+ However, if you fork a process, you must create a new ``MongoClient`` instance in the
193+ child process.
194+
195+ .. important:: Don't Pass a MongoClient to a Child Process
196+
197+ If you use the ``fork()`` method to create a new process, don't pass an instance
198+ of the ``MongoClient`` class from the parent process to the child process. This creates
199+ a high probability of deadlock among ``MongoClient`` instances in the child process.
200+ {+driver-short+} tries to issue a warning if this deadlock might occur.
201+
202+ Multiprocessing
203+ ~~~~~~~~~~~~~~~
204+
205+ {+driver-short+} supports the Python ``multiprocessing`` module.
206+ However, on Unix systems, the multiprocessing module spawns processes by using
207+ the ``fork()`` method. This carries the same risks described in :ref:`<pymongo-forks>`
208+
209+ To use multiprocessing with {+driver-short+}, write code similar to the following example:
210+
211+ .. code-block:: python
212+
213+ # Each process creates its own instance of MongoClient.
214+ def func():
215+ db = pymongo.MongoClient().mydb
216+ # Do something with db.
217+
218+ proc = multiprocessing.Process(target=func)
219+ proc.start()
220+
221+ .. important::
222+
223+ Do not copy an instance of the ``MongoClient`` class from the parent process to a child
224+ process.
107225
108226API Documentation
109227-----------------
110228
111229To learn more about creating a ``MongoClient`` object in {+driver-short+},
112230see the following API documentation:
113231
114- - `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
232+ - `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
0 commit comments