diff --git a/README.rst b/README.rst index b2979fa1e..ffe04c5c4 100644 --- a/README.rst +++ b/README.rst @@ -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 `_, 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 `_ 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: diff --git a/RELEASE.rst b/RELEASE.rst index 10fa2fdce..506d1d898 100644 --- a/RELEASE.rst +++ b/RELEASE.rst @@ -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). diff --git a/doc/examples/authentication.rst b/doc/examples/authentication.rst index 447a90ff9..3ea30af91 100644 --- a/doc/examples/authentication.rst +++ b/doc/examples/authentication.rst @@ -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/ diff --git a/doc/examples/tls.rst b/doc/examples/tls.rst index 2b649825d..789c46aa9 100644 --- a/doc/examples/tls.rst +++ b/doc/examples/tls.rst @@ -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 diff --git a/doc/installation.rst b/doc/installation.rst index 60e4d7f5a..bc9cd7ffd 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -5,9 +5,9 @@ Installing / Upgrading **PyMongo** is in the `Python Package Index `_. -.. 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 `_, 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 `_ 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: diff --git a/doc/tools.rst b/doc/tools.rst index fbd5bbf79..056623557 100644 --- a/doc/tools.rst +++ b/doc/tools.rst @@ -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 `_ No longer maintained diff --git a/setup.py b/setup.py index 64265b0c5..bbf94bbf0 100755 --- a/setup.py +++ b/setup.py @@ -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