Skip to content

Commit a46a956

Browse files
mongoKartmongoKart
authored
DOCSP-37009 - Quick Start page (#1)
1 parent 07de38d commit a46a956

File tree

1 file changed

+131
-111
lines changed

1 file changed

+131
-111
lines changed

‎source/quick-start.txt

Lines changed: 131 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -11,215 +11,235 @@ Quick Start
1111
:depth: 2
1212
:class: singlecol
1313

14+
.. facet::
15+
:name: genre
16+
:values: tutorial
17+
18+
.. meta::
19+
:keywords: pypi, pip, xcode
20+
1421
This tutorial is intended as an introduction to working with
1522
**MongoDB** and **PyMongo**.
1623

1724
Download and Install
1825
--------------------
1926

20-
**PyMongo** is in the `Python Package Index
21-
<http://pypi.python.org/pypi/pymongo/>`_.
27+
**PyMongo** is in the `Python Package Index.
28+
<http://pypi.python.org/pypi/pymongo/>`__
2229

23-
.. warning:: **Do not install the "bson" package from pypi.** PyMongo comes
24-
with its own bson package; doing "pip install bson" or "easy_install bson"
30+
.. warning::
31+
32+
Do not install the ``bson`` package from PyPI. PyMongo comes
33+
with its own ``bson`` package. Running ``pip install bson`` or ``easy_install bson``
2534
installs a third-party package that is incompatible with PyMongo.
2635

2736
Installing with pip
2837
-------------------
2938

30-
We recommend using `pip <http://pypi.python.org/pypi/pip>`_
31-
to install pymongo on all platforms:
39+
We recommend using `pip <http://pypi.python.org/pypi/pip>`__
40+
to install PyMongo on all platforms:
3241

3342
.. code-block:: python
3443

35-
$ python3 -m pip install pymongo
44+
$ python3 -m pip install pymongo
3645

37-
To get a specific version of pymongo:
46+
To get a specific version of PyMongo:
3847

3948
.. code-block:: python
4049

41-
$ python3 -m pip install pymongo==3.5.1
50+
$ python3 -m pip install pymongo==3.5.1
4251

43-
To upgrade using pip:
52+
To upgrade by using pip:
4453

4554
.. code-block:: python
4655

47-
$ python3 -m pip install --upgrade pymongo
56+
$ python3 -m pip install --upgrade pymongo
4857

4958
Dependencies
5059
------------
5160

5261
PyMongo supports CPython 3.7+ and PyPy3.7+.
5362

54-
Required dependencies
55-
.....................
56-
57-
Support for mongodb+srv:// URIs requires `dnspython
58-
<https://pypi.python.org/pypi/dnspython>`_
63+
Support for mongodb+srv:// URIs requires `dnspython.
64+
<https://pypi.python.org/pypi/dnspython>`__
5965

60-
Installing from source
66+
Installing from Source
6167
----------------------
6268

63-
If you'd rather install directly from the source (i.e. to stay on the
64-
bleeding edge), install the C extension dependencies then check out the
69+
If you'd rather install PyMongo directly from the source,
70+
install the C-extension dependencies, and then check out the
6571
latest source from GitHub and install the driver from the resulting tree:
6672

6773
.. code-block:: python
6874

69-
$ git clone https://github.com/mongodb/mongo-python-driver.git pymongo
70-
$ cd pymongo/
71-
$ pip install .
75+
$ git clone https://github.com/mongodb/mongo-python-driver.git pymongo
76+
$ cd pymongo/
77+
$ pip install .
7278

73-
Installing from source on Unix
74-
..............................
79+
Installing from Source on Unix
80+
``````````````````````````````
7581

76-
To build the optional C extensions on Linux or another non-macOS Unix you must
77-
have the GNU C compiler (gcc) installed. Depending on your flavor of Unix
78-
(or Linux distribution) you may also need a python development package that
82+
To build the optional C extensions on Linux or another non-macOS Unix, you must
83+
have the GNU C compiler (``gcc``) installed. Depending on your flavor of Unix
84+
(or Linux distribution), you may also need a Python development package that
7985
provides the necessary header files for your version of Python. The package
80-
name may vary from distro to distro.
86+
name might vary among distrubutions.
8187

82-
Debian and Ubuntu users should issue the following command:
88+
If you're using Debian or Ubuntu, run the following command:
8389

8490
.. code-block:: python
8591

86-
$ sudo apt-get install build-essential python-dev
87-
88-
Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux,
89-
Fedora, etc.) should issue the following command:
90-
91-
.. code-block:: python
92-
93-
$ sudo yum install gcc python-devel
94-
95-
Installing from source on macOS / OSX
96-
.....................................
92+
$ sudo apt-get install build-essential python-dev
9793

98-
If you want to install PyMongo with C extensions from source you will need
99-
the command line developer tools. On modern versions of macOS they can be
100-
installed by running the following in Terminal (found in
101-
/Applications/Utilities/):
94+
If you're using a Red Hat-based distribution (RHEL, CentOS, Amazon Linux, Oracle Linux,
95+
Fedora, etc.), run the following command:
10296

10397
.. code-block:: python
10498

105-
xcode-select --install
99+
$ sudo yum install gcc python-devel
106100

107-
For older versions of OSX you may need Xcode. See the notes below for various
108-
OSX and Xcode versions.
101+
Installing from Source on macOS or OSX
102+
``````````````````````````````````````
109103

110-
**Snow Leopard (10.6)** - Xcode 3 with 'UNIX Development Support'.
104+
If you want to install PyMongo with C extensions from source, you will need
105+
the command line developer tools. On modern versions of macOS, you can
106+
install these tools by running the following command in your terminal:
111107

112-
**Snow Leopard Xcode 4**: The Python versions shipped with OSX 10.6.x
113-
are universal binaries. They support i386, PPC, and x86_64. Xcode 4 removed
114-
support for PPC, causing the distutils version shipped with Apple's builds of
115-
Python to fail to build the C extensions if you have Xcode 4 installed. There
116-
is a workaround:
108+
.. code-block:: bash
117109

118-
.. code-block:: python
110+
xcode-select --install
119111

120-
# For some Python builds from python.org
121-
$ env ARCHFLAGS='-arch i386 -arch x86_64' python -m easy_install pymongo
112+
The following list describes the installation requirements for older versions of OSX:
122113

123-
See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`_
124-
for a more detailed explanation.
114+
- **Lion (10.7) and newer**: PyMongo's C extensions can be built against
115+
versions of Python 3.7+ downloaded from python.org. In all cases, you must install Xcode
116+
with "UNIX Development Support".
117+
118+
Starting with Xcode version 5.1, ``clang``
119+
throws an error when it encounters compiler flags that it doesn't recognize.
120+
This may cause C extension builds to fail with an error similar to the following:
125121

126-
**Lion (10.7) and newer** - PyMongo's C extensions can be built against
127-
versions of Python 3.7+ downloaded from python.org. In all cases Xcode must be
128-
installed with 'UNIX Development Support'.
122+
.. code-block:: bash
129123

130-
**Xcode 5.1**: Starting with version 5.1 the version of clang that ships with
131-
Xcode throws an error when it encounters compiler flags it doesn't recognize.
132-
This may cause C extension builds to fail with an error similar to:
124+
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
133125

134-
.. code-block:: python
126+
You can run one of the following commands as a workaround:
135127

136-
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
128+
.. code-block:: python
137129

138-
There are workarounds:
130+
# Apple specified workaround for Xcode 5.1
131+
# easy_install
132+
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future easy_install pymongo
133+
# or pip
134+
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pymongo
139135

140-
.. code-block:: python
136+
# Alternative workaround using CFLAGS
137+
# easy_install
138+
$ CFLAGS=-Qunused-arguments easy_install pymongo
139+
# or pip
140+
$ CFLAGS=-Qunused-arguments pip install pymongo
141141

142-
# Apple specified workaround for Xcode 5.1
143-
# easy_install
144-
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future easy_install pymongo
145-
# or pip
146-
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pymongo
142+
- **Snow Leopard (10.6)**: Xcode 3 with "UNIX Development Support".
147143

148-
# Alternative workaround using CFLAGS
149-
# easy_install
150-
$ CFLAGS=-Qunused-arguments easy_install pymongo
151-
# or pip
152-
$ CFLAGS=-Qunused-arguments pip install pymongo
144+
The Python versions that shipped with OSX 10.6.x
145+
are universal binaries. They support i386, PPC, and x86_64 architectures. Xcode 4 removed
146+
support for PPC, causing the ``distutils`` version shipped with Apple's builds of
147+
Python to fail to build the C extensions if you have Xcode 4 installed. There
148+
is a workaround:
153149

150+
.. code-block:: python
154151

155-
Installing from source on Windows
156-
.................................
152+
# For some Python builds from python.org
153+
$ env ARCHFLAGS='-arch i386 -arch x86_64' python -m easy_install pymongo
157154

158-
If you want to install PyMongo with C extensions from source the following
159-
requirements apply to both CPython and ActiveState's ActivePython:
155+
See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`__
156+
for a more detailed explanation.
160157

161-
Windows
162-
~~~~~~~
158+
Installing from Source on Windows
159+
`````````````````````````````````
163160

164-
Install Visual Studio 2015+.
161+
If you want to install PyMongo with C extensions from source,
162+
CPython and ActiveState's ActivePython require Visual Studio 2015 or later.
165163

166164
.. _install-no-c:
167165

168166
Installing Without C Extensions
169167
-------------------------------
170168

171-
By default, the driver attempts to build and install optional C
169+
By default, PyMongo attempts to build and install optional C
172170
extensions (used for increasing performance) when it is installed. If
173-
any extension fails to build the driver will be installed anyway but a
171+
any extension fails to build, the driver will still be installed, but a
174172
warning will be printed.
175173

176-
If you wish to install PyMongo without the C extensions, even if the
177-
extensions build properly, it can be done using a command line option to
178-
*pip install*:
174+
If you wish to install PyMongo without the C extensions, run the following command:
179175

180176
.. code-block:: python
181177

182-
$ NO_EXT=1 python -m pip install .
178+
$ NO_EXT=1 python -m pip install .
179+
180+
Installing a Beta or Release-Candidate Version
181+
----------------------------------------------
183182

184-
Installing a beta or release candidate
185-
--------------------------------------
183+
MongoDB will occasionally tag a beta or release-candidate version for testing by
184+
the community before final release. These releases will not be uploaded to PyPI, but you
185+
can find them on the `GitHub tags page <https://github.com/mongodb/mongo-python-driver/tags>`__
186+
for PyMongo.
186187

187-
MongoDB, Inc. may occasionally tag a beta or release candidate for testing by
188-
the community before final release. These releases will not be uploaded to pypi
189-
but can be found on the
190-
`GitHub tags page <https://github.com/mongodb/mongo-python-driver/tags>`_.
191-
They can be installed by passing the full URL for the tag to pip:
188+
To install one of these versions, pass the full URL for the version as an argument pip,
189+
as follows:
192190

193191
.. code-block:: python
194192

195-
$ python3 -m pip install https://github.com/mongodb/mongo-python-driver/archive/4.4.0b0.tar.gz
193+
$ python3 -m pip install https://github.com/mongodb/mongo-python-driver/archive/4.4.0b0.tar.gz
196194

197195
Test Your PyMongo Installation
198196
------------------------------
199197

200-
In the Python shell, the following should run without raising an exception:
198+
In the Python shell, the following command should run without raising an exception:
201199

202200
.. code-block:: python
203201

204-
>>> import pymongo
202+
>>> import pymongo
205203

206204
Create a Deployment
207205
-------------------
208206

209-
This tutorial assumes that a MongoDB instance is running on the
210-
default host and port. Assuming you have `downloaded and installed
211-
<https://www.mongodb.com/docs/manual/installation/>`_ MongoDB, you
212-
can start it like so:
207+
Follow the `Install MongoDB
208+
<https://www.mongodb.com/docs/manual/installation/>`__ guide to install MongoDB locally.
209+
210+
Create a Python Application
211+
---------------------------
212+
213+
In your shell, run the following command to create a directory for your application:
213214

214215
.. code-block:: bash
215216

216-
$ mongod
217+
mkdir python_quickstart
217218

218-
To test your code:
219+
Run the following command to navigate into the project directory:
219220

220-
.. code-block:: python
221+
.. code-block:: bash
222+
223+
cd python_quickstart
224+
225+
Create a file named ``quickstart.py`` to contain your application, and then copy
226+
the following code into ``quickstart.py``:
227+
228+
.. code-block:: python
229+
230+
from pymongo import MongoClient
231+
232+
client = MongoClient()
233+
client.drop_database("test-database")
234+
235+
In the terminal, run the following command to start your application:
236+
237+
.. code-block:: bash
238+
239+
python3 quickstart.py
221240

222-
from pymongo import MongoClient
241+
.. note::
223242

224-
client = MongoClient()
225-
client.drop_database("test-database")
243+
This application has no output, but should return you to the command prompt if
244+
successful.
245+

0 commit comments

Comments
 (0)