Skip to content

Commit d70578f

Browse files
behackettbehackett
committed
PYTHON-881 - Backport CodecOptions class from 3.x.
1 parent f2c01af commit d70578f

17 files changed

+184
-38
lines changed

‎bson/binary.py‎

Lines changed: 34 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -67,29 +67,53 @@
6767
.. versionadded:: 1.5
6868
"""
6969

70+
STANDARD = UUID_SUBTYPE
71+
"""The standard UUID representation.
72+
73+
:class:`uuid.UUID` instances will automatically be encoded to
74+
and decoded from BSON binary, using RFC-4122 byte order with
75+
binary subtype :data:`UUID_SUBTYPE`.
76+
77+
.. versionadded:: 2.9
78+
"""
79+
80+
PYTHON_LEGACY = OLD_UUID_SUBTYPE
81+
"""The Python legacy UUID representation.
82+
83+
:class:`uuid.UUID` instances will automatically be encoded to
84+
and decoded from BSON binary, using RFC-4122 byte order with
85+
binary subtype :data:`OLD_UUID_SUBTYPE`.
86+
87+
.. versionadded:: 2.9
88+
"""
89+
7090
JAVA_LEGACY = 5
71-
"""Used with :attr:`pymongo.collection.Collection.uuid_subtype`
72-
to specify that UUIDs should be stored in the legacy byte order
73-
used by the Java driver.
91+
"""The Java legacy UUID representation.
7492
75-
:class:`uuid.UUID` instances will automatically be encoded
76-
by :mod:`bson` using :data:`OLD_UUID_SUBTYPE`.
93+
:class:`uuid.UUID` instances will automatically be encoded to
94+
and decoded from BSON binary, using the Java driver's legacy
95+
byte order with binary subtype :data:`OLD_UUID_SUBTYPE`.
7796
7897
.. versionadded:: 2.3
7998
"""
8099

81100
CSHARP_LEGACY = 6
82-
"""Used with :attr:`pymongo.collection.Collection.uuid_subtype`
83-
to specify that UUIDs should be stored in the legacy byte order
84-
used by the C# driver.
101+
"""The C#/.net legacy UUID representation.
85102
86-
:class:`uuid.UUID` instances will automatically be encoded
87-
by :mod:`bson` using :data:`OLD_UUID_SUBTYPE`.
103+
:class:`uuid.UUID` instances will automatically be encoded to
104+
and decoded from BSON binary, using the C# driver's legacy
105+
byte order and binary subtype :data:`OLD_UUID_SUBTYPE`.
88106
89107
.. versionadded:: 2.3
90108
"""
91109

92110
ALL_UUID_SUBTYPES = (OLD_UUID_SUBTYPE, UUID_SUBTYPE, JAVA_LEGACY, CSHARP_LEGACY)
111+
ALL_UUID_REPRESENTATIONS = (STANDARD, PYTHON_LEGACY, JAVA_LEGACY, CSHARP_LEGACY)
112+
UUID_REPRESENTATION_NAMES = {
113+
PYTHON_LEGACY: 'PYTHON_LEGACY',
114+
STANDARD: 'STANDARD',
115+
JAVA_LEGACY: 'JAVA_LEGACY',
116+
CSHARP_LEGACY: 'CSHARP_LEGACY'}
93117

94118
MD5_SUBTYPE = 5
95119
"""BSON binary subtype for an MD5 hash.

‎bson/codec_options.py‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Copyright 2014-2015 MongoDB, Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Tools for specifying BSON codec options."""
16+
17+
from bson.binary import (ALL_UUID_REPRESENTATIONS,
18+
PYTHON_LEGACY,
19+
UUID_REPRESENTATION_NAMES)
20+
21+
22+
class CodecOptions(tuple):
23+
"""Encapsulates BSON options used in CRUD operations.
24+
25+
:Parameters:
26+
- `document_class`: BSON documents returned in queries will be decoded
27+
to an instance of this class.
28+
- `tz_aware`: If ``True``, BSON datetimes will be decoded to timezone
29+
aware instances of :class:`~datetime.datetime`. Otherwise they will be
30+
naive. Defaults to ``False``.
31+
- `uuid_representation`: The BSON representation to use when encoding
32+
and decoding instances of :class:`~uuid.UUID`. Defaults to
33+
:data:`~bson.binary.PYTHON_LEGACY`.
34+
"""
35+
36+
__slots__ = ()
37+
38+
def __new__(cls, document_class=dict,
39+
tz_aware=False, uuid_representation=PYTHON_LEGACY):
40+
if not isinstance(tz_aware, bool):
41+
raise TypeError("tz_aware must be True or False")
42+
if uuid_representation not in ALL_UUID_REPRESENTATIONS:
43+
raise ValueError("uuid_representation must be a value "
44+
"from bson.binary.ALL_UUID_REPRESENTATIONS")
45+
46+
return tuple.__new__(
47+
cls, (document_class, tz_aware, uuid_representation))
48+
49+
def __repr__(self):
50+
if self.document_class is dict:
51+
document_class_repr = 'dict'
52+
else:
53+
document_class_repr = repr(self.document_class)
54+
55+
uuid_rep_repr = UUID_REPRESENTATION_NAMES.get(self.uuid_representation,
56+
self.uuid_representation)
57+
58+
return (
59+
'CodecOptions(document_class=%s, tz_aware=%r, uuid_representation='
60+
'%s)' % (document_class_repr, self.tz_aware, uuid_rep_repr))
61+
62+
def __getnewargs__(self):
63+
return tuple(self)
64+
65+
@property
66+
def document_class(self):
67+
return self[0]
68+
69+
@property
70+
def tz_aware(self):
71+
return self[1]
72+
73+
@property
74+
def uuid_representation(self):
75+
return self[2]
76+
77+
DEFAULT_CODEC_OPTIONS = CodecOptions()

‎doc/api/bson/binary.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
.. autodata:: OLD_BINARY_SUBTYPE
1010
.. autodata:: OLD_UUID_SUBTYPE
1111
.. autodata:: UUID_SUBTYPE
12+
.. autodata:: STANDARD
13+
.. autodata:: PYTHON_LEGACY
1214
.. autodata:: JAVA_LEGACY
1315
.. autodata:: CSHARP_LEGACY
1416
.. autodata:: MD5_SUBTYPE

‎doc/api/bson/codec_options.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:mod:`codec_options` -- Tools for specifying BSON codec options
2+
===============================================================
3+
4+
.. automodule:: bson.codec_options
5+
:synopsis: Tools for specifying BSON codec options.
6+
:members:

‎doc/api/bson/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,15 @@ Sub-modules:
1111
:maxdepth: 2
1212

1313
binary
14-
regex
1514
code
15+
codec_options
1616
dbref
1717
errors
1818
json_util
1919
max_key
2020
min_key
2121
objectid
22+
regex
2223
son
2324
timestamp
2425
tz_util

‎doc/api/pymongo/collection.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
.. autoattribute:: full_name
2525
.. autoattribute:: name
2626
.. autoattribute:: database
27+
.. autoattribute:: codec_options
2728
.. autoattribute:: read_preference
2829
.. autoattribute:: tag_sets
2930
.. autoattribute:: secondary_acceptable_latency_ms

‎doc/api/pymongo/connection.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
.. autoattribute:: max_message_size
3030
.. autoattribute:: min_wire_version
3131
.. autoattribute:: max_wire_version
32+
.. autoattribute:: codec_options
3233
.. autoattribute:: read_preference
3334
.. autoattribute:: tag_sets
3435
.. autoattribute:: secondary_acceptable_latency_ms

‎doc/api/pymongo/database.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
.. note:: Use dictionary style access if `collection_name` is an
2424
attribute of the :class:`Database` class eg: db[`collection_name`].
2525

26+
.. autoattribute:: codec_options
2627
.. autoattribute:: read_preference
2728
.. autoattribute:: tag_sets
2829
.. autoattribute:: secondary_acceptable_latency_ms

‎doc/api/pymongo/mongo_client.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
.. autoattribute:: max_message_size
3030
.. autoattribute:: min_wire_version
3131
.. autoattribute:: max_wire_version
32+
.. autoattribute:: codec_options
3233
.. autoattribute:: read_preference
3334
.. autoattribute:: tag_sets
3435
.. autoattribute:: secondary_acceptable_latency_ms

‎doc/api/pymongo/mongo_replica_set_client.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
.. autoattribute:: min_wire_version
3131
.. autoattribute:: max_wire_version
3232
.. autoattribute:: auto_start_request
33+
.. autoattribute:: codec_options
3334
.. autoattribute:: read_preference
3435
.. autoattribute:: tag_sets
3536
.. autoattribute:: secondary_acceptable_latency_ms

0 commit comments

Comments
 (0)