In Python 2, objects automatically inherit the __hash__ of their parent
class. In Python 3, objects that override __eq__ do not automatically inherit
__hash__, so these objects were not hashable under Python 3. Additionally,
mutable BSON types and types that overide __eq__ but did not explicitly define
__hash__ had broken __hash__ methods under Python 2. This commit unifies the
hashing behavior between Python versions and fixes the __hash__ methods such
that two BSON objects hash the same only if they are equal.
N.B.: bson.code.Code and bson.regex.Regex are no longer hashable under Python 2
because they are mutable.
This commit deprecates insert, update, save, and remove. Each
now raises DeprecationWarning at stacklevel 2. This change also
updates all tutorials and example documentation to use the new
CRUD API, tests the deprecations, and fixes up a few more tests
that were still using the legacy API.
This change resolves four issues:
PYTHON-826 The new codec_options submodule is moved from pymongo to bson.
PYTHON-827 Use codec_options in BSON APIs.
Functions and methods of the bson module that accepted the options as_class,
tz_aware, and uuid_subtype now accept a codec_options parameter instead.
For example, the function definition for bson.decode_all changes from this:
def decode_all(data, as_class=dict, tz_aware=True,
uuid_subtype=OLD_UUID_SUBTYPE)
to:
def decode_all(data, codec_options=CodecOptions())
The following functions are changed:
- decode_all
- decode_iter
- decode_file_iter
The following methods are changed:
- BSON.encode
- BSON.decode
This is a breaking change for any application that uses the BSON API directly
and changes any of the named parameter defaults. No changes are required for
applications that use the default values for these options. The behavior
remains the same.
PYTHON-828 Internal BSON module changes to support CodecOptions
The pure Python BSON module passes around a CodecOptions instance instead of
as_class, tz_aware, and uuid_subtype. C extensions pass these values around in
a struct.
PYTHON-801 Rename uuid_subtype to uuid_representation.
And use them in place of UUID_SUBTYPE and OLD_UUID_SUBTYPE. This
change also cleans up and clarifies the documentation for
JAVA_LEGACY and CSHARP_LEGACY. None of these are binary subtypes,
but instead UUID representations in the Python, C#, and Java drivers.
When encoding a document in C while running in a python sub interpreter
(e.g. mod_wsgi spawning sub interpreters) PyMongo would often have
to reload its cache of pure python types - ObjectId, Timestamp,
UUID, etc. - raising RuntimeWarning in the process. The reason this was
necessary is described in the mod_wsgi documentation here:
https://code.google.com/p/modwsgi/wiki/ApplicationIssues#Multiple_Python_Sub_Interpreters
With workarounds documented here:
http://api.mongodb.org/python/2.6.2/faq.html#does-pymongo-work-with-mod-wsgi
With this commit PyMongo will no longer use cached pure python types
when running in a sub interpreter. Instead it will look up pure python
types as needed (primarily when decoding BSON). This eliminates the
problem described in the mod_wsgi docs and eliminates the need for the
Runtime warning.
The default binary subtype for UUIDs has changed
to 4. You can use bson.binary.UUIDLegacy to query
on UUIDs previously stored as subtype 3. See the
UUIDLegacy docstring for more details.
Many of the pymongo modules have been moved into the bson
package. Aliases for those modules have been added to the pymongo
package, without deprecation warnings for now. Application developers
should begin to use the bson namespace, as deprecation of moved
modules will probably begin in the next release.
