Skip to content

Commit 2318c84

Browse files
author
Chris Cho
authored
DOCSP-16255 python updates (#740)
* DOCSP-16255: python updates
1 parent f164125 commit 2318c84

File tree

4 files changed

+146
-53
lines changed

4 files changed

+146
-53
lines changed

‎source/includes/university-m220p.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Take the Free Online Course Taught by MongoDB
2+
---------------------------------------------
3+
4+
.. list-table::
5+
6+
* - .. cssclass:: bordered-figure
7+
.. figure:: /figures/M220P_hero.jpg
8+
:alt: Banner for the M220P MongoDB University Course
9+
10+
- `M220P: MongoDB for Python Developers <https://university.mongodb.com/courses/M220P/about>`__
11+
12+
Learn the essentials of Python application development with MongoDB.
13+

‎source/motor.txt‎

Lines changed: 82 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,49 +17,117 @@ Motor (Async Driver)
1717
Introduction
1818
------------
1919

20-
**Motor (Python async)** is the recommended asynchronous Python driver for MongoDB.
21-
It is compatible with `Tornado <http://www.tornadoweb.org/>`_ and
22-
`asyncio <https://docs.python.org/3/library/asyncio.html>`_.
20+
**Motor** is the recommended asynchronous Python driver for MongoDB.
21+
It is compatible with `Tornado <http://www.tornadoweb.org/>`__ and
22+
`asyncio <https://docs.python.org/3/library/asyncio.html>`__. We recommend
23+
that you use this driver if you need to run asynchronous operations. If
24+
you do not need to access MongoDB in a non-blocking manner or from
25+
co-routines, we recommend that you use the :doc:`PyMongo </pymongo>`
26+
driver instead.
2327

24-
- `Tutorial <http://motor.readthedocs.org/en/stable/tutorial.html>`_
28+
Follow the links below to learn more about how to use the Motor driver:
2529

26-
- `Documentation <http://motor.readthedocs.org/>`_
30+
- `Tutorial on using Motor with Tornado <http://motor.readthedocs.org/en/stable/tutorial-tornado.html>`__
31+
32+
- `Tutorial on using Motor with asyncio <https://motor.readthedocs.io/en/stable/tutorial-asyncio.html>`__
33+
34+
- `Motor Documentation <http://motor.readthedocs.org/>`__
2735

2836
- `Changelog <http://motor.readthedocs.org/en/stable/changelog.html>`__
2937

3038
- `Source Code <https://github.com/mongodb/motor/>`__
3139

32-
- `Porting From PyMongo To Motor <http://emptysqua.re/blog/porting-from-pymongo-to-motor/>`_
40+
Follow the links below to read blog posts that describe specific use cases
41+
for the Motor driver:
3342

34-
- `Refactoring Tornado Coroutines <http://emptysqua.re/blog/refactoring-tornado-coroutines/>`_
43+
- `Porting From PyMongo To Motor <http://emptysqua.re/blog/porting-from-pymongo-to-motor/>`__
3544

36-
- `All Motor articles on A. Jesse Jiryu Davis's blog <http://emptysqua.re/blog/category/motor/>`_
45+
- `Refactoring Tornado Coroutines <http://emptysqua.re/blog/refactoring-tornado-coroutines/>`__
3746

47+
- `All Motor articles on A. Jesse Jiryu Davis's blog <http://emptysqua.re/blog/category/motor/>`__
3848

3949
Installation
4050
------------
4151

42-
We recommend using `pip <http://pypi.python.org/pypi/pip>`__ to install
43-
Motor on all platforms:
52+
You must install the Motor driver module to make it available to your Python
53+
application. We recommend using `pip <http://pypi.python.org/pypi/pip>`__
54+
to install Motor.
55+
56+
The following command demonstrates how you can install the latest version of
57+
the module using the command line:
4458

4559
.. code-block:: sh
4660

47-
$ pip install motor
61+
$ python -m pip install motor
4862

63+
For more information on requirements and other methods of installation,
64+
see the `Motor Installation <https://motor.readthedocs.io/en/stable/installation.html>`__
65+
documentation.
4966

5067
Connect to MongoDB Atlas
5168
------------------------
5269

5370
.. include:: /includes/atlas-connect-blurb.rst
5471

72+
If you are using the ``asyncio`` asynchronous framework, you can use the
73+
following code to connect:
74+
5575
.. code-block:: python
5676

77+
import asyncio
78+
import motor.motor_asyncio
79+
80+
async def get_server_info():
81+
82+
# replace this with your MongoDB connection string
83+
conn_str = "<your MongoDB Atlas connection string>"
84+
85+
# set a 5-second connection timeout
86+
client = motor.motor_asyncio.AsyncIOMotorClient(conn_str, serverSelectionTimeoutMS=5000)
87+
88+
try:
89+
print(await client.server_info())
90+
except Exception:
91+
print("Unable to connect to the server.")
92+
93+
loop = asyncio.get_event_loop()
94+
loop.run_until_complete(get_server_info())
95+
96+
If you are using the ``tornado`` asynchronous library, you can use the
97+
following code to connect:
98+
99+
.. code-block:: python
100+
101+
import tornado
57102
import motor
58103

59-
client = motor.motor_tornado.MotorClient(
60-
"mongodb+srv://<username>:<password>@<cluster-url>/test?retryWrites=true&w=majority")
61-
db = client.test
104+
async def get_server_info():
105+
106+
# replace this with your MongoDB connection string
107+
conn_str = "<your MongoDB Atlas connection string>"
108+
109+
# set a 5-second connection timeout
110+
client = motor.motor_tornado.MotorClient(conn_str, serverSelectionTimeoutMS=5000)
111+
112+
try:
113+
print(await client.server_info())
114+
except Exception:
115+
print("Unable to connect to the server.")
116+
117+
tornado.ioloop.IOLoop.current().run_sync(get_server_info)
118+
119+
If the connection succeeds before a five-second timeout, you will see a
120+
dictionary containing information about the server you connected to.
121+
122+
If the connection fails, you should see the following message:
123+
124+
.. code-block:: console
125+
:copyable: false
126+
127+
Unable to connect to the server.
62128

129+
For more information on the connection string, see the MongoDB Server
130+
Manual entry on :manual:`Connection String URI Format </reference/connection-string/>`.
63131

64132
Compatibility
65133
-------------

‎source/pymongo.txt‎

Lines changed: 43 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -15,56 +15,55 @@ PyMongo
1515
Introduction
1616
------------
1717

18-
**PyMongo** is the recommended way to work with MongoDB from Python.
18+
**PyMongo** is the official MongoDB Python driver for MongoDB. We
19+
recommend you use this driver to work with MongoDB from Python. If you
20+
need to access MongoDB in a non-blocking manner or from co-routines, we
21+
recommend that you use the :doc:`Motor </motor>` driver instead.
1922

20-
- `Tutorial <https://pymongo.readthedocs.io/en/stable/tutorial.html>`__
23+
Follow the links below to learn more about how to use the PyMongo driver:
24+
25+
- `Tutorial <https://pymongo.readthedocs.io/en/stable/tutorial.html>`__ on
26+
how to connect to MongoDB and run common operations.
2127

2228
- `API Reference <https://pymongo.readthedocs.io/en/stable/api/index.html>`__
2329

2430
- `Changelog <https://pymongo.readthedocs.io/en/stable/changelog.html>`__
2531

2632
- `Source Code <https://github.com/mongodb/mongo-python-driver>`__
2733

28-
29-
Take the free online course taught by MongoDB
30-
---------------------------------------------
31-
32-
.. list-table::
33-
34-
* - .. cssclass:: bordered-figure
35-
.. figure:: /figures/M220P_hero.jpg
36-
:alt: Banner for the M220P MongoDB University Course
37-
38-
- `M220P: MongoDB for Python Developers <https://university.mongodb.com/courses/M220P/about>`__
39-
40-
Learn the essentials of Python application development with MongoDB.
41-
34+
.. include:: /includes/university-m220p.rst
4235

4336
Installation
4437
------------
4538

46-
We recommend using `pip <http://pypi.python.org/pypi/pip>`__ to install
47-
pymongo on all platforms:
39+
You must install the PyMongo driver module to make it available to your Python
40+
application. We recommend using `pip <http://pypi.python.org/pypi/pip>`__
41+
to install PyMongo.
42+
43+
The following command demonstrates how you can install the latest version of
44+
the module using the command line:
4845

4946
.. code-block:: sh
5047

5148
$ python -m pip install 'pymongo[srv]'
5249

53-
To get a specific version of pymongo:
50+
If you need to install a specific version of ``pymongo``, specify the
51+
version in your command. The following command shows how you can use
52+
``pip`` to install PyMongo version ``3.11``:
5453

5554
.. code-block:: sh
5655

5756
$ python -m pip install 'pymongo[srv]'==3.11
5857

59-
To upgrade using pip:
58+
If you already have PyMongo installed and need to upgrade to the latest
59+
version, use the following ``pip`` command:
6060

6161
.. code-block:: sh
6262

6363
$ python -m pip install --upgrade 'pymongo[srv]'
6464

65-
6665
See `Installation <https://pymongo.readthedocs.io/en/stable/installation.html>`__
67-
for more ways to install.
66+
for more ways to install PyMongo.
6867

6968

7069
Connect to MongoDB Atlas
@@ -76,10 +75,29 @@ Connect to MongoDB Atlas
7675

7776
import pymongo
7877

79-
client = pymongo.MongoClient(
80-
"mongodb+srv://<username>:<password>@<cluster-url>/test?retryWrites=true&w=majority")
81-
db = client.test
78+
# replace this with your MongoDB connection string
79+
conn_str = "<your MongoDB Atlas connection string>"
80+
81+
# set a 5-second connection timeout
82+
client = pymongo.MongoClient(conn_str, serverSelectionTimeoutMS=5000)
83+
84+
try:
85+
print(client.server_info())
86+
except Exception:
87+
print("Unable to connect to the server.")
88+
89+
If the connection succeeds before a five-second timeout, you will see a
90+
dictionary containing information about the server you connected to.
91+
92+
If the connection fails, you should see the following message:
93+
94+
.. code-block:: console
95+
:copyable: false
96+
97+
Unable to connect to the server.
8298

99+
For more information on the connection string, see the MongoDB Server
100+
Manual entry on :manual:`Connection String URI Format </reference/connection-string/>`.
83101

84102
Compatibility
85103
-------------

‎source/python.txt‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -23,20 +23,14 @@ MongoDB Python Drivers
2323
Introduction
2424
------------
2525

26-
:doc:`PyMongo </pymongo>` is the recommended way to work with MongoDB from Python.
26+
You can access MongoDB from your Python application using one of our
27+
official MongoDB Python drivers. Follow the links below to get started
28+
with each driver:
2729

28-
:doc:`Motor </motor>` is the recommended MongoDB Python async driver.
30+
- :doc:`PyMongo </pymongo>` is the recommended driver to work with MongoDB
31+
using Python.
32+
- :doc:`Motor </motor>` is the recommended driver for when you need
33+
non-blocking access to MongoDB using Python.
2934

30-
Take the free online course taught by MongoDB
31-
---------------------------------------------
32-
33-
.. list-table::
34-
35-
* - .. cssclass:: bordered-figure
36-
.. figure:: /figures/M220P_hero.jpg
37-
:alt: Banner for the M220P MongoDB University Course
38-
39-
- `M220P: MongoDB for Python Developers <https://university.mongodb.com/courses/M220P/about>`__
40-
41-
Learn the essentials of Python application development with MongoDB.
35+
.. include:: /includes/university-m220p.rst
4236

0 commit comments

Comments
 (0)