mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PYTHON-1477 PYTHON-1478 PYTHON-1480 - Doc improvements

Browse Source
This commit is contained in:
Bernie Hackett 2018-02-15 20:04:07 -08:00
parent b86c1e6019
commit 2c932dfe77
7 changed files with 79 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.rst
View File

@ -81,9 +81,9 @@ You can also download the project source and do::
$ python setup.py install
Do **not** install the "bson" package. PyMongo comes with its own bson package;
doing "easy_install bson" installs a third-party package that is incompatible
with PyMongo.
Do **not** install the "bson" package from pypi. PyMongo comes with its own
bson package; doing "easy_install bson" installs a third-party package that
is incompatible with PyMongo.
Dependencies
============
@ -123,10 +123,10 @@ Other optional packages:
- `backports.pbkdf2 <https://pypi.python.org/pypi/backports.pbkdf2/>`_,
improves authentication performance with SCRAM-SHA-1, the default
authentication mechanism for MongoDB 3.0+. It especially improves
performance on Python older than 2.7.8, or on Python 3 before Python 3.4.
performance on Python versions older than 2.7.8.
- `monotonic <https://pypi.python.org/pypi/monotonic>`_ adds support for
a monotonic clock, which improves reliability in environments
where clock adjustments are frequent. Not needed in Python 3.3+.
where clock adjustments are frequent. Not needed in Python 3.
Additional dependencies are:

42
RELEASE.rst
View File

@ -5,43 +5,43 @@ Versioning
----------
We shoot for a release every few months - that will generally just
increment the middle version number (e.g. 2.6.3 -> 2.7).
increment the middle / minor version number (e.g. 3.5.0 -> 3.6.0).
Minor releases are reserved for bug fixes (in general no new features
Patch releases are reserved for bug fixes (in general no new features
or deprecations) - they only happen in cases where there is a critical
bug in a recently released version, or when a release has no new
features or API changes.
In between releases we add .devN to the version number to denote the version
under development. So if we just released 3.0, then the current dev
version would be 3.1.dev0. When we make the next release we
replace all instances of 3.1.devN in the docs with the new version number.
under development. So if we just released 3.6.0, then the current dev
version might be 3.6.1.dev0 or 3.7.0.dev0. When we make the next release we
replace all instances of 3.x.x.devN in the docs with the new version number.
https://semver.org/
https://www.python.org/dev/peps/pep-0440/
Deprecation
-----------
Changes should be backwards compatible unless absolutely necessary. When making
API changes the approach is generally to add a deprecation warning but keeping
the existing API functional. Eventually (after at least ~4 releases) we can
remove the old API.
the existing API functional. Deprecated features can be removed in a release
that changes the major version number.
Doing a Release
---------------
1. Test release on Python 2.6-2.7 and 3.2-3.4 on Windows, Linux and OSX,
with and without the C extension. Generally enough to just run the tests on
2.6, 2.7, 3.2 and the latest 3.x version with and without the extension on
a single platform, and then just test any version on the other platforms
as a sanity check. `python setup.py test` will build the extension
and test. `python tools/clean.py` will remove the extension, and
then `python setup.py --no_ext test` will run the tests without
it. Run the replica set and mongos high-availability tests with
`PYTHONPATH=. python test/high_availability/test_ha.py`. Can also
run the doctests: `python setup.py doc -t`. For building extensions
on Windows check section below.
1. Test releases on Python 2.6-2.7 and 3.4+ on Windows, Linux and OSX,
with and without the C extensions. It's generally enough to just run the
tests on 2.6, 2.7, 3.4 and the latest 3.x version with and without the
extensions on a single platform, and then just test any version on the
other platforms as a sanity check. `python setup.py test` will build the
extensions and test. `python tools/clean.py` will remove the extensions,
and then `python setup.py --no_ext test` will run the tests without
them. You can also run the doctests: `python setup.py doc -t`.
2. Add release notes to doc/changelog.rst. Generally just summarize/clarify
the git log, but might add some more long form notes for big changes.
the git log, but you might add some more long form notes for big changes.
3. Search and replace the "devN" version number w/ the new version number (see
note above).
@ -58,8 +58,8 @@ Doing a Release
9. Push binaries to PyPI; for each version of python and platform do:`python
setup.py bdist_egg upload`. Probably best to do `python setup.py bdist_egg`
first, to make sure the egg builds properly. On Windows we also push a binary
installer. The setup.py target for that is `bdist_wininst`.
first, to make sure the egg builds properly. We also publish wheels.
`python setup.py bdist_wheel upload`.
10. Make sure to push a build of the new docs (see the apidocs repo).

3
doc/examples/authentication.rst
View File

@ -46,8 +46,7 @@ Or through the MongoDB URI::
>>> uri = "mongodb://user:password@example.com/the_database?authMechanism=SCRAM-SHA-1"
>>> client = MongoClient(uri)
For best performance install `backports.pbkdf2`_, especially on Python older
than 2.7.8, or on Python 3 before Python 3.4.
For best performance on Python versions older than 2.7.8 install `backports.pbkdf2`_.
.. _backports.pbkdf2: https://pypi.python.org/pypi/backports.pbkdf2/

3
doc/examples/tls.rst
View File

@ -30,8 +30,7 @@ When using CPython < 2.7.9 or PyPy < 2.5.1:
Python 3.x
``````````
On Windows, the `wincertstore`_ module is required when using CPython < 3.4.0
or any version of PyPy3.
On Windows, the `wincertstore`_ module is required when using PyPy3 < 3.5.
.. _ipaddress: https://pypi.python.org/pypi/ipaddress
.. _wincertstore: https://pypi.python.org/pypi/wincertstore

77
doc/installation.rst
View File

@ -5,9 +5,9 @@ Installing / Upgrading
**PyMongo** is in the `Python Package Index
<http://pypi.python.org/pypi/pymongo/>`_.
.. warning:: **Do not install the "bson" package.** PyMongo comes with its own
bson package; doing "pip install bson" or "easy_install bson" installs a
third-party package that is incompatible with PyMongo.
.. warning:: **Do not install the "bson" package from pypi.** PyMongo comes
with its own bson package; doing "pip install bson" or "easy_install bson"
installs a third-party package that is incompatible with PyMongo.
Installing with pip
-------------------
@ -19,7 +19,7 @@ to install pymongo on all platforms::
To get a specific version of pymongo::
$ python -m pip install pymongo==3.1.1
$ python -m pip install pymongo==3.5.1
To upgrade using pip::
@ -80,31 +80,12 @@ Other optional packages:
- `backports.pbkdf2 <https://pypi.python.org/pypi/backports.pbkdf2/>`_,
improves authentication performance with SCRAM-SHA-1, the default
authentication mechanism for MongoDB 3.0+. It especially improves
performance on Python older than 2.7.8, or on Python 3 before Python 3.4.
performance on Python versions older than 2.7.8.
- `monotonic <https://pypi.python.org/pypi/monotonic>`_ adds support for
a monotonic clock, which improves reliability in environments
where clock adjustments are frequent. Not needed in Python 3.3+.
where clock adjustments are frequent. Not needed in Python 3.
Dependencies for installing C Extensions on Unix
------------------------------------------------
MongoDB, Inc. does not provide statically linked binary packages for Unix
flavors other than OSX. To build the optional C extensions you must have the
GNU C compiler (gcc) installed. Depending on your flavor of Unix (or Linux
distribution) you may also need a python development package that provides
the necessary header files for your version of Python. The package name may
vary from distro to distro.
Debian and Ubuntu users should issue the following command::
$ sudo apt-get install build-essential python-dev
Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux,
Fedora, etc.) should issue the following command::
$ sudo yum install gcc python-devel
Installing from source
----------------------
@ -116,11 +97,36 @@ latest source from github and install the driver from the resulting tree::
$ cd pymongo/
$ python setup.py install
Installing from source on OSX
.............................
Installing from source on Unix
..............................
If you want to install PyMongo from source on OSX you will have to install the
following to build the C extensions:
To build the optional C extensions on Linux or another non-macOS Unix you must
have the GNU C compiler (gcc) installed. Depending on your flavor of Unix
(or Linux distribution) you may also need a python development package that
provides the necessary header files for your version of Python. The package
name may vary from distro to distro.
Debian and Ubuntu users should issue the following command::
$ sudo apt-get install build-essential python-dev
Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux,
Fedora, etc.) should issue the following command::
$ sudo yum install gcc python-devel
Installing from source on macOS / OSX
.....................................
If you want to install PyMongo with C extensions from source you will need
the command line developer tools. On modern versions of macOS they can be
installed by running the following in Terminal (found in
/Applications/Utilities/)::
xcode-select --install
For older versions of OSX you may need Xcode. See the notes below for various
OSX and Xcode versions.
**Snow Leopard (10.6)** - Xcode 3 with 'UNIX Development Support'.
@ -173,11 +179,10 @@ requirements apply to both CPython and ActiveState's ActivePython:
~~~~~~~~~~~~~~
For Python 3.5 and newer install Visual Studio 2015. For Python 3.4
install Visual Studio 2010. For Python 2.6 and 2.7 install Visual Studio
2008, or the Microsoft Visual C++ Compiler for Python 2.7. You must use the
full version of Visual Studio 2010 or 2008 as Visual C++ Express does not
provide 64-bit compilers. Make sure that you check the "x64 Compilers and
Tools" option under Visual C++.
install Visual Studio 2010. You must use the full version of Visual Studio
2010 as Visual C++ Express does not provide 64-bit compilers. Make sure that
you check the "x64 Compilers and Tools" option under Visual C++. For Python 2.6
and 2.7 install the `Microsoft Visual C++ Compiler for Python 2.7`_.
32-bit Windows
~~~~~~~~~~~~~~
@ -186,7 +191,9 @@ For Python 3.5 and newer install Visual Studio 2015.
For Python 3.4 install Visual C++ 2010 Express.
For Python 2.6 and 2.7 install Visual C++ 2008 Express SP1.
For Python 2.6 and 2.7 install the `Microsoft Visual C++ Compiler for Python 2.7`_
.. _`Microsoft Visual C++ Compiler for Python 2.7`: https://www.microsoft.com/en-us/download/details.aspx?id=44266
.. _install-no-c:

2
doc/tools.rst
View File

@ -77,7 +77,7 @@ uMongo
Its inception comes from two needs: the lack of async ODM and the
difficulty to do document (un)serialization with existing ODMs.
Works with multiple drivers: PyMongo, TxMongo, motor_asyncio, and
mongomock. The source `is on github
mongomock. The source `is available on github
<https://github.com/Scille/umongo>`_
No longer maintained

12
setup.py
View File

@ -262,12 +262,16 @@ Oracle Linux, Fedora, etc.) should issue the following command:
$ sudo yum install gcc python-devel
If you are seeing this message on Microsoft Windows please install
PyMongo using the MS Windows installer for your version of Python,
available on pypi here:
PyMongo using pip. Modern versions of pip will install PyMongo
from binary wheels available on pypi. If you must install from
source read the documentation here:
http://pypi.python.org/pypi/pymongo/#downloads
https://api.mongodb.com/python/current/installation.html#installing-from-source-on-windows
If you are seeing this message on OSX please read the documentation
If you are seeing this message on macOS / OSX please install PyMongo
using pip. Modern versions of pip will install PyMongo from binary
wheels available on pypi. If wheels are not available for your version
of macOS / OSX, or you must install from source read the documentation
here:
http://api.mongodb.org/python/current/installation.html#osx