Skip to content

Commit 905a56b

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-37494 Get started (#38)
1 parent bf84e79 commit 905a56b

12 files changed

+316
-3
lines changed

‎snooty.toml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
name = "pymongo"
22
title = "PyMongo"
3-
toc_landing_pages = ["/write-operations", "/read", "/connect"]
4-
3+
toc_landing_pages = [
4+
"/get-started",
5+
"/write-operations",
6+
"/read",
7+
"/connect"
8+
]
59

610
intersphinx = [
711
"https://www.mongodb.com/docs/manual/objects.inv",

‎source/get-started.txt

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. _pymongo-get-started:
2+
3+
===========
4+
Get Started
5+
===========
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. meta::
18+
:description: Learn how to create an app to connect to MongoDB deployment by using the PyMongo driver.
19+
:keywords: quick start, tutorial, basics
20+
21+
.. toctree::
22+
23+
/get-started/download-and-install/
24+
/get-started/create-a-deployment/
25+
/get-started/create-a-connection-string/
26+
/get-started/connect-to-mongodb/
27+
/get-started/next-steps/
28+
29+
Overview
30+
--------
31+
32+
{+driver-short+} is a Python package that you can use to connect
33+
to and communicate with MongoDB. This guide shows you how to create an
34+
application that uses {+driver-short+} to connect to a MongoDB cluster hosted on
35+
MongoDB Atlas.
36+
37+
.. tip::
38+
39+
MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
40+
deployments. You can create your own free (no credit card required) MongoDB Atlas
41+
deployment by following the steps in this guide.
42+
43+
Follow this guide to connect a sample Python application to a MongoDB Atlas
44+
deployment. If you prefer to connect to MongoDB using a different driver or
45+
programming language, see our :driver:`list of official drivers <>`.
46+
47+
.. button:: Next: Download and Install
48+
:uri: /get-started/download-and-install/

‎source/get-started/connect-to-mongodb.txt

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _pymongo-get-started-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. procedure::
8+
:style: connected
9+
10+
.. step:: Create your {+driver-short+} Application
11+
12+
Copy and paste the following code into the ``quickstart.py`` file in your application:
13+
14+
.. literalinclude:: /includes/get-started/connect-and-query.py
15+
:language: python
16+
:copyable:
17+
18+
.. step:: Assign the Connection String
19+
20+
Replace the ``<connection string URI>`` placeholder with the
21+
connection string that you copied from the :ref:`pymongo-get-started-connection-string`
22+
step of this guide.
23+
24+
.. step:: Run your Application
25+
26+
In your shell, run the following command to start this application:
27+
28+
.. code-block:: sh
29+
30+
python3 quickstart.py
31+
32+
The output includes details of the retrieved movie document:
33+
34+
.. code-block:: none
35+
36+
{
37+
_id: ...,
38+
plot: 'A young man is accidentally sent 30 years into the past...',
39+
genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
40+
...
41+
title: 'Back to the Future',
42+
...
43+
}
44+
45+
.. tip::
46+
47+
If you encounter an error or see no output, check whether you specified the
48+
proper connection string, and that you loaded the
49+
sample data.
50+
51+
After you complete these steps, you have a working application that
52+
uses the driver to connect to your MongoDB deployment, runs a query on
53+
the sample data, and prints out the result.
54+
55+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
56+
57+
.. button:: Next Steps
58+
:uri: /get-started/next-steps/

‎source/get-started/create-a-connection-string.txt

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. _pymongo-get-started-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
.. TODO: Link to other connection options pages
17+
.. To connect to an instance or deployment not hosted on Atlas, see
18+
.. :ref:`Other Ways to Connect to MongoDB <pymongo-other-ways-to-connect>`.
19+
20+
.. procedure::
21+
:style: connected
22+
23+
.. step:: Find your MongoDB Atlas Connection String
24+
25+
To retrieve your connection string for the deployment that
26+
you created in the :ref:`previous step <pymongo-get-started-create-deployment>`,
27+
log into your Atlas account and navigate to the
28+
:guilabel:`Database` section and click the :guilabel:`Connect` button
29+
for your new deployment.
30+
31+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
32+
:alt: The connect button in the clusters section of the Atlas UI
33+
34+
Proceed to the :guilabel:`Connect your application` section and select
35+
"Python" from the :guilabel:`Driver` selection menu and the version
36+
that best matches the version you installed from the :guilabel:`Version`
37+
selection menu.
38+
39+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
40+
41+
Deselect the :guilabel:`Include full driver code example` option to view
42+
the connection string.
43+
44+
.. step:: Copy your Connection String
45+
46+
Click the button on the right of the connection string to copy it to
47+
your clipboard as shown in the following screenshot:
48+
49+
.. figure:: /includes/figures/atlas_connection_copy_string_python.png
50+
:alt: The connection string copy button in the Atlas UI
51+
52+
.. step:: Update the Placeholders
53+
54+
Paste this connection string into a file in your preferred text editor
55+
and replace the ``<username>`` and ``<password>`` placeholders with
56+
your database user's username and password.
57+
58+
Save this file to a safe location for use in the next step.
59+
60+
After completing these steps, you have a connection string that
61+
contains your database username and password.
62+
63+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
64+
65+
.. button:: Next: Connect to MongoDB
66+
:uri: /get-started/connect-to-mongodb/

‎source/get-started/create-a-deployment.txt

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. _pymongo-get-started-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
You can create a free tier MongoDB deployment on MongoDB Atlas
8+
to store and manage your data. MongoDB Atlas hosts and manages
9+
your MongoDB database in the cloud.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a Free MongoDB deployment on Atlas
15+
16+
Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_python>`
17+
guide to set up a new Atlas account and load sample data into a new free
18+
tier MongoDB deployment.
19+
20+
.. step:: Save your Credentials
21+
22+
After you create your database user, save that user's
23+
username and password to a safe location for use in an upcoming step.
24+
25+
After you complete these steps, you have a new free tier MongoDB
26+
deployment on Atlas, database user credentials, and sample data loaded
27+
in your database.
28+
29+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
30+
31+
.. button:: Next: Create a Connection String
32+
:uri: /get-started/create-a-connection-string/

‎source/get-started/download-and-install.txt

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. _pymongo-get-started-download-and-install:
2+
3+
====================
4+
Download and Install
5+
====================
6+
7+
.. procedure::
8+
:style: connected
9+
10+
.. step:: Install Dependencies
11+
12+
Ensure you have the following dependencies installed
13+
in your development environment:
14+
15+
- `Python3 version 3.7 or later <https://www.python.org/downloads/>`__
16+
- `pip <https://pip.pypa.io/en/stable/installation/>`__
17+
- `dnspython <https://pypi.org/project/dnspython/>`__
18+
19+
.. step:: Create a Project Directory
20+
21+
In your shell, run the following command to create a
22+
directory called ``pymongo-quickstart`` for this project:
23+
24+
.. code-block:: bash
25+
26+
mkdir pymongo-quickstart
27+
28+
Run the following command to navigate into the project
29+
directory:
30+
31+
.. code-block:: bash
32+
33+
cd pymongo-quickstart
34+
35+
Run the following command to create a file to contain your application:
36+
37+
.. code-block:: bash
38+
39+
touch quickstart.py
40+
41+
.. step:: Install {+driver-short+}
42+
43+
Run the following commands in your shell to create and activate a virtual
44+
environment in which to install the driver:
45+
46+
.. code-block:: bash
47+
48+
python3 -m venv venv
49+
source venv/bin/activate
50+
51+
With the virutal environment activated, run the following command to
52+
install the current version of {+driver-short+}:
53+
54+
.. code-block:: bash
55+
56+
python3 -m pip install pymongo
57+
58+
After you complete these steps, you have a new project directory
59+
and the driver dependencies installed.
60+
61+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
62+
63+
.. button:: Next: Create a MongoDB Deployment
64+
:uri: /get-started/create-a-deployment/

‎source/get-started/next-steps.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _pymongo-get-started-next-steps:
2+
3+
==========
4+
Next Steps
5+
==========
6+
7+
Congratulations on completing the tutorial!
8+
9+
In this tutorial, you created a Python application that
10+
connects to a MongoDB deployment hosted on MongoDB Atlas
11+
and retrieves a document that matches a query.
12+
13+
Learn more about {+driver-short+} from the following resources:
14+
15+
- Learn how to perform read operations in the :ref:`<pymongo-read>` section.
16+
- Learn how to perform write operations in the :ref:`<pymongo-write>` section.

‎source/includes/figures/atlas_connection_copy_string_python.png

291 KB
Loading

‎source/includes/figures/atlas_connection_select_cluster.png

34.6 KB
Loading

‎source/includes/get-started/connect-and-query.py

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
from pymongo import MongoClient
2+
3+
uri = "<connection string URI>"
4+
client = MongoClient(uri)
5+
6+
try:
7+
database = client.get_database("sample_mflix")
8+
movies = database.get_collection("movies")
9+
10+
# Query for a movie that has the title 'Back to the Future'
11+
query = { "title": "Back to the Future" }
12+
movie = movies.find_one(query)
13+
14+
print(movie)
15+
16+
client.close()
17+
18+
except Exception as e:
19+
raise Exception("Unable to find the document due to the following error: ", e)

0 commit comments

Comments
 (0)