diff --git a/doc/atlas.rst b/doc/atlas.rst new file mode 100644 index 000000000..e7c7ab517 --- /dev/null +++ b/doc/atlas.rst @@ -0,0 +1,18 @@ +Using PyMongo with MongoDB Atlas +================================ + +`Atlas `_ is MongoDB, Inc.'s hosted MongoDB as a +service offering. To connect to Atlas, pass the connection string provided by +Atlas to :class:`~pymongo.mongo_client.MongoClient`:: + + client = pymongo.MongoClient() + +Connections to Atlas require TLS/SSL. For connections using TLS/SSL, PyMongo +may require third party dependencies as determined by your version of Python. +With PyMongo 3.3+, you can install PyMongo 3.3+ and any TLS/SSL-related +dependencies using the following pip command:: + + $ python -m pip install pymongo[tls] + +Earlier versions of PyMongo require you to manually install the dependencies. +For a list of TLS/SSL-related dependencies, see :doc:`examples/tls`. diff --git a/doc/examples/tls.rst b/doc/examples/tls.rst index 0133c362b..2b649825d 100644 --- a/doc/examples/tls.rst +++ b/doc/examples/tls.rst @@ -6,6 +6,37 @@ configuration options supported by PyMongo. See `the server documentation `_ to configure MongoDB. +Dependencies +............ + +For connections using TLS/SSL, PyMongo may require third party dependencies as +determined by your version of Python. With PyMongo 3.3+, you can install +PyMongo 3.3+ and any TLS/SSL-related dependencies using the following pip +command:: + + $ python -m pip install pymongo[tls] + +Earlier versions of PyMongo require you to manually install the dependencies +listed below. + +Python 2.x +`````````` +The `ipaddress`_ module is required on all platforms. + +When using CPython < 2.7.9 or PyPy < 2.5.1: + +- On Windows, the `wincertstore`_ module is required. +- On all other platforms, the `certifi`_ module is required. + +Python 3.x +`````````` +On Windows, the `wincertstore`_ module is required when using CPython < 3.4.0 +or any version of PyPy3. + +.. _ipaddress: https://pypi.python.org/pypi/ipaddress +.. _wincertstore: https://pypi.python.org/pypi/wincertstore +.. _certifi: https://pypi.python.org/pypi/certifi + Basic configuration ................... @@ -23,19 +54,6 @@ This configures PyMongo to connect to the server using TLS, verify the server's certificate and verify that the host you are attempting to connect to is listed by that certificate. -PyMongo attempts to use the operating system's CA certificates to verify the -server's certificate when possible. Some versions of python may require an -extra third party module for this to work properly. Users of Python 2 on -Windows are encouraged to upgrade to python 2.7.9 or newer. Users of Python 3 -on Windows should upgrade to python 3.4.0 or newer. If upgrading is not -possible `wincertstore `_ can be -used with older python versions. Users of operating systems other than Windows -that are stuck on python versions older than 2.7.9 can install -`certifi `_ to use the Mozilla CA bundle -for certificate verification. Users of python 2.x that require IP address -support for hostname matching must install the `ipaddress -`_ module. - Certificate verification policy ............................... diff --git a/doc/index.rst b/doc/index.rst index d8d519471..6e95c7274 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,6 +19,12 @@ everything you need to know to use **PyMongo**. :doc:`examples/index` Examples of how to perform specific tasks. +:doc:`atlas` + Using PyMongo with MongoDB Atlas. + +:doc:`examples/tls` + Using PyMongo with TLS / SSL. + :doc:`faq` Some questions that come up often. @@ -85,6 +91,7 @@ Indices and tables .. toctree:: :hidden: + atlas installation tutorial examples/index