Compatibility Policy

Semantic Versioning

PyMongo’s version numbers follow semantic versioning: each version numberis structured “major.minor.patch”. Patch releases fix bugs, minor releasesadd features (and may fix bugs), and major releases include API changes thatbreak backwards compatibility (and may add features and fix bugs).

Deprecation

Before we remove a feature in a major release, PyMongo’s maintainers make aneffort to release at least one minor version that deprecates it. We add“DEPRECATED” to the feature’s documentation, and update the code to raise aDeprecationWarning. You can ensure your code is future-proof by runningyour code with the latest PyMongo release and looking for DeprecationWarnings.

Starting with Python 2.7, the interpreter silences DeprecationWarnings bydefault. For example, the following code uses the deprecated insertmethod but does not raise any warning:

  1. # "insert.py"
  2. from pymongo import MongoClient
  3.  
  4. client = MongoClient()
  5. client.test.test.insert({})

To print deprecation warnings to stderr, run python with “-Wd”:

  1. $ python -Wd insert.py
  2. insert.py:4: DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.
  3.   client.test.test.insert({})

You can turn warnings into exceptions with “python -We”:

  1. $ python -We insert.py
  2. Traceback (most recent call last):
  3.   File "insert.py", line 4, in <module>
  4.     client.test.test.insert({})
  5.   File "/home/durin/work/mongo-python-driver/pymongo/collection.py", line 2906, in insert
  6.     "instead.", DeprecationWarning, stacklevel=2)
  7. DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.

If your own code’s test suite passes with “python -We” then it uses nodeprecated PyMongo features.

See also

The Python documentation on the warnings module,and the -W command line option.