diff --git a/README.rst b/README.rst index 2c6adc7d1..09a43c4e2 100644 --- a/README.rst +++ b/README.rst @@ -8,8 +8,10 @@ About ===== The PyMongo distribution contains tools for interacting with MongoDB -database from Python. The ``pymongo`` package is a native Python -driver for MongoDB. The ``gridfs`` package is a `gridfs +database from Python. The ``bson`` package is an implementation of +the `BSON format `_ for Python. The ``pymongo`` +package is a native Python driver for MongoDB. The ``gridfs`` package +is a `gridfs `_ implementation on top of ``pymongo``. diff --git a/bson/tz_util.py b/bson/tz_util.py index 8c2abeeb6..eb9614b63 100644 --- a/bson/tz_util.py +++ b/bson/tz_util.py @@ -41,5 +41,5 @@ class FixedOffset(tzinfo): return ZERO -"""UTC""" utc = FixedOffset(0, "UTC") +"""Fixed offset timezone representing UTC.""" diff --git a/doc/api/bson/binary.rst b/doc/api/bson/binary.rst new file mode 100644 index 000000000..8ddf3a892 --- /dev/null +++ b/doc/api/bson/binary.rst @@ -0,0 +1,16 @@ +:mod:`binary` -- Tools for representing binary data to be stored in MongoDB +=========================================================================== + +.. automodule:: bson.binary + :synopsis: Tools for representing binary data to be stored in MongoDB + + .. autodata:: BINARY_SUBTYPE + .. autodata:: FUNCTION_SUBTYPE + .. autodata:: OLD_BINARY_SUBTYPE + .. autodata:: UUID_SUBTYPE + .. autodata:: MD5_SUBTYPE + .. autodata:: USER_DEFINED_SUBTYPE + + .. autoclass:: Binary(data[, subtype=BINARY_SUBTYPE]) + :members: + :show-inheritance: diff --git a/doc/api/bson/code.rst b/doc/api/bson/code.rst new file mode 100644 index 000000000..80b3b78b9 --- /dev/null +++ b/doc/api/bson/code.rst @@ -0,0 +1,9 @@ +:mod:`code` -- Tools for representing JavaScript code +===================================================== + +.. automodule:: bson.code + :synopsis: Tools for representing JavaScript code + + .. autoclass:: Code(code[, scope=None[, **kwargs]]) + :members: + :show-inheritance: diff --git a/doc/api/bson/dbref.rst b/doc/api/bson/dbref.rst new file mode 100644 index 000000000..07d50f1b6 --- /dev/null +++ b/doc/api/bson/dbref.rst @@ -0,0 +1,6 @@ +:mod:`dbref` -- Tools for manipulating DBRefs (references to documents stored in MongoDB) +========================================================================================= + +.. automodule:: bson.dbref + :synopsis: Tools for manipulating DBRefs (references to documents stored in MongoDB) + :members: diff --git a/doc/api/bson/errors.rst b/doc/api/bson/errors.rst new file mode 100644 index 000000000..cfb9e9816 --- /dev/null +++ b/doc/api/bson/errors.rst @@ -0,0 +1,6 @@ +:mod:`errors` -- Exceptions raised by the :mod:`bson` package +================================================================ + +.. automodule:: bson.errors + :synopsis: Exceptions raised by the bson package + :members: diff --git a/doc/api/bson/index.rst b/doc/api/bson/index.rst new file mode 100644 index 000000000..745dc0dd6 --- /dev/null +++ b/doc/api/bson/index.rst @@ -0,0 +1,23 @@ +:mod:`bson` -- BSON (Binary JSON) Encoding and Decoding +======================================================= + +.. automodule:: bson + :synopsis: BSON (Binary JSON) Encoding and Decoding + :members: + +Sub-modules: + +.. toctree:: + :maxdepth: 2 + + binary + code + dbref + errors + json_util + max_key + min_key + objectid + son + timestamp + tz_util diff --git a/doc/api/bson/json_util.rst b/doc/api/bson/json_util.rst new file mode 100644 index 000000000..6348269f9 --- /dev/null +++ b/doc/api/bson/json_util.rst @@ -0,0 +1,8 @@ +:mod:`json_util` -- Tools for using Python's :mod:`json` module with BSON documents +====================================================================================== +.. versionadded:: 1.1.1 + +.. automodule:: bson.json_util + :synopsis: Tools for using Python's json module with BSON documents + :members: + :undoc-members: diff --git a/doc/api/bson/max_key.rst b/doc/api/bson/max_key.rst new file mode 100644 index 000000000..e3adf9a5c --- /dev/null +++ b/doc/api/bson/max_key.rst @@ -0,0 +1,7 @@ +:mod:`max_key` -- Representation for the MongoDB internal MaxKey type +===================================================================== +.. versionadded:: 1.7 + +.. automodule:: bson.max_key + :synopsis: Representation for the MongoDB internal MaxKey type + :members: diff --git a/doc/api/bson/min_key.rst b/doc/api/bson/min_key.rst new file mode 100644 index 000000000..582568176 --- /dev/null +++ b/doc/api/bson/min_key.rst @@ -0,0 +1,7 @@ +:mod:`min_key` -- Representation for the MongoDB internal MinKey type +===================================================================== +.. versionadded:: 1.7 + +.. automodule:: bson.min_key + :synopsis: Representation for the MongoDB internal MinKey type + :members: diff --git a/doc/api/bson/objectid.rst b/doc/api/bson/objectid.rst new file mode 100644 index 000000000..8fb0cdd6a --- /dev/null +++ b/doc/api/bson/objectid.rst @@ -0,0 +1,27 @@ +:mod:`objectid` -- Tools for working with MongoDB ObjectIds +=========================================================== + +.. automodule:: bson.objectid + :synopsis: Tools for working with MongoDB ObjectIds + + .. autoclass:: pymongo.objectid.ObjectId([oid=None]) + :members: + + .. describe:: str(o) + + Get a hex encoded version of :class:`ObjectId` `o`. + + The following property always holds: + + .. testsetup:: + + from bson.objectid import ObjectId + + .. doctest:: + + >>> o = ObjectId() + >>> o == ObjectId(str(o)) + True + + This representation is useful for urls or other places where + ``o.binary`` is inappropriate. diff --git a/doc/api/bson/son.rst b/doc/api/bson/son.rst new file mode 100644 index 000000000..eae68e86f --- /dev/null +++ b/doc/api/bson/son.rst @@ -0,0 +1,6 @@ +:mod:`son` -- Tools for working with SON, an ordered mapping +============================================================ + +.. automodule:: bson.son + :synopsis: Tools for working with SON, an ordered mapping + :members: diff --git a/doc/api/bson/timestamp.rst b/doc/api/bson/timestamp.rst new file mode 100644 index 000000000..964730e32 --- /dev/null +++ b/doc/api/bson/timestamp.rst @@ -0,0 +1,7 @@ +:mod:`timestamp` -- Tools for representing MongoDB internal Timestamps +====================================================================== +.. versionadded:: 1.5 + +.. automodule:: bson.timestamp + :synopsis: Tools for representing MongoDB internal Timestamps + :members: diff --git a/doc/api/bson/tz_util.rst b/doc/api/bson/tz_util.rst new file mode 100644 index 000000000..653367fd1 --- /dev/null +++ b/doc/api/bson/tz_util.rst @@ -0,0 +1,6 @@ +:mod:`tz_util` -- Utilities for dealing with timezones in Python +================================================================ + +.. automodule:: bson.tz_util + :synopsis: Utilities for dealing with timezones in Python + :members: diff --git a/doc/api/index.rst b/doc/api/index.rst index 375e9b3d8..64c407fd0 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,14 +1,17 @@ API Documentation ================= -The PyMongo distribution contains two root packages for interacting with -MongoDB. :mod:`pymongo` is a full-featured driver for MongoDB and -:mod:`gridfs` is a set of tools for working with the `GridFS +The PyMongo distribution contains three top-level packages for +interacting with MongoDB. :mod:`bson` is an implementation of the +`BSON format `_, :mod:`pymongo` is a +full-featured driver for MongoDB, and :mod:`gridfs` is a set of tools +for working with the `GridFS `_ storage specification. .. toctree:: :maxdepth: 2 + bson/index pymongo/index gridfs/index diff --git a/doc/api/pymongo/binary.rst b/doc/api/pymongo/binary.rst index abaeab1e3..e598c8335 100644 --- a/doc/api/pymongo/binary.rst +++ b/doc/api/pymongo/binary.rst @@ -1,16 +1,8 @@ -:mod:`binary` -- Tools for representing binary data to be stored in MongoDB -=========================================================================== +:mod:`binary` -- MOVED +====================== -.. automodule:: pymongo.binary - :synopsis: Tools for representing binary data to be stored in MongoDB +This module has been deprecated in favor of :mod:`bson.binary`. Please +use that module instead. - .. autodata:: BINARY_SUBTYPE - .. autodata:: FUNCTION_SUBTYPE - .. autodata:: OLD_BINARY_SUBTYPE - .. autodata:: UUID_SUBTYPE - .. autodata:: MD5_SUBTYPE - .. autodata:: USER_DEFINED_SUBTYPE - - .. autoclass:: Binary(data[, subtype=BINARY_SUBTYPE]) - :members: - :show-inheritance: +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/bson.rst b/doc/api/pymongo/bson.rst index 9f8eb9275..31601194a 100644 --- a/doc/api/pymongo/bson.rst +++ b/doc/api/pymongo/bson.rst @@ -1,7 +1,8 @@ -:mod:`bson` -- Tools for working with `BSON `_ in Python -================================================================================================== +:mod:`bson` -- MOVED +==================== -.. automodule:: pymongo.bson - :synopsis: Tools for working with BSON in Python - :members: - :show-inheritance: +This module has been deprecated in favor of :mod:`bson`. Please use +that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/code.rst b/doc/api/pymongo/code.rst index 42821bbf1..d67046d1e 100644 --- a/doc/api/pymongo/code.rst +++ b/doc/api/pymongo/code.rst @@ -1,9 +1,8 @@ -:mod:`code` -- Tools for representing JavaScript code to be evaluated by MongoDB -================================================================================ +:mod:`code` -- MOVED +==================== -.. automodule:: pymongo.code - :synopsis: Tools for representing JavaScript code to be evaluated by MongoDB +This module has been deprecated in favor of :mod:`bson.code`. Please +use that module instead. - .. autoclass:: Code(code[, scope=None[, **kwargs]]) - :members: - :show-inheritance: +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/dbref.rst b/doc/api/pymongo/dbref.rst index aa7f78904..2795655fe 100644 --- a/doc/api/pymongo/dbref.rst +++ b/doc/api/pymongo/dbref.rst @@ -1,6 +1,8 @@ -:mod:`dbref` -- Tools for manipulating DBRefs (references to documents stored in MongoDB) -========================================================================================= +:mod:`dbref` -- MOVED +===================== -.. automodule:: pymongo.dbref - :synopsis: Tools for manipulating DBRefs (references to documents stored in MongoDB) - :members: +This module has been deprecated in favor of :mod:`bson.dbref`. Please +use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/index.rst b/doc/api/pymongo/index.rst index 192d5bb31..88e6f92ab 100644 --- a/doc/api/pymongo/index.rst +++ b/doc/api/pymongo/index.rst @@ -22,16 +22,23 @@ Sub-modules: cursor errors master_slave_connection + message + son_manipulator + cursor_manager + +Deprecated sub-modules (moved to the :mod:`bson` package): + +.. toctree:: + :maxdepth: 2 + + bson + binary code dbref - binary - objectid - bson - message - son - son_manipulator - timestamp - min_key - max_key json_util - cursor_manager + max_key + min_key + objectid + son + timestamp + tz_util diff --git a/doc/api/pymongo/json_util.rst b/doc/api/pymongo/json_util.rst index 35d63bae3..b9b64745d 100644 --- a/doc/api/pymongo/json_util.rst +++ b/doc/api/pymongo/json_util.rst @@ -1,8 +1,8 @@ -:mod:`json_util` -- Tools for using Python's :mod:`json` module with MongoDB documents -====================================================================================== -.. versionadded:: 1.1.1 +:mod:`json_util` -- MOVED +========================= -.. automodule:: pymongo.json_util - :synopsis: Tools for using Python's json module with MongoDB documents - :members: - :undoc-members: +This module has been deprecated in favor of +:mod:`bson.json_util`. Please use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/max_key.rst b/doc/api/pymongo/max_key.rst index 64d9ccacc..72c857dcb 100644 --- a/doc/api/pymongo/max_key.rst +++ b/doc/api/pymongo/max_key.rst @@ -1,7 +1,8 @@ -:mod:`max_key` -- Representation for the MongoDB internal MaxKey type -===================================================================== -.. versionadded:: 1.7 +:mod:`max_key` -- MOVED +======================= -.. automodule:: pymongo.max_key - :synopsis: Representation for the MongoDB internal MaxKey type - :members: +This module has been deprecated in favor of +:mod:`bson.max_key`. Please use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/min_key.rst b/doc/api/pymongo/min_key.rst index fd9222bd9..505798f41 100644 --- a/doc/api/pymongo/min_key.rst +++ b/doc/api/pymongo/min_key.rst @@ -1,7 +1,8 @@ -:mod:`min_key` -- Representation for the MongoDB internal MinKey type -===================================================================== -.. versionadded:: 1.7 +:mod:`min_key` -- MOVED +======================= -.. automodule:: pymongo.min_key - :synopsis: Representation for the MongoDB internal MinKey type - :members: +This module has been deprecated in favor of +:mod:`bson.min_key`. Please use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/objectid.rst b/doc/api/pymongo/objectid.rst index 6cca3d927..63f0c378e 100644 --- a/doc/api/pymongo/objectid.rst +++ b/doc/api/pymongo/objectid.rst @@ -1,27 +1,8 @@ -:mod:`objectid` -- Tools for working with MongoDB ObjectIds -=========================================================== +:mod:`objectid` -- MOVED +======================== -.. automodule:: pymongo.objectid - :synopsis: Tools for working with MongoDB ObjectIds +This module has been deprecated in favor of +:mod:`bson.objectid`. Please use that module instead. - .. autoclass:: pymongo.objectid.ObjectId([oid=None]) - :members: - - .. describe:: str(o) - - Get a hex encoded version of :class:`ObjectId` `o`. - - The following property always holds: - - .. testsetup:: - - from pymongo.objectid import ObjectId - - .. doctest:: - - >>> o = ObjectId() - >>> o == ObjectId(str(o)) - True - - This representation is useful for urls or other places where - ``o.binary`` is inappropriate. +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/son.rst b/doc/api/pymongo/son.rst index 530cd2fbf..e3190103d 100644 --- a/doc/api/pymongo/son.rst +++ b/doc/api/pymongo/son.rst @@ -1,6 +1,8 @@ -:mod:`son` -- Tools for working with SON, an ordered mapping -============================================================ +:mod:`son` -- MOVED +=================== -.. automodule:: pymongo.son - :synopsis: Tools for working with SON, an ordered mapping - :members: +This module has been deprecated in favor of :mod:`bson.son`. Please +use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/timestamp.rst b/doc/api/pymongo/timestamp.rst index 6ec3d856d..8c366a34a 100644 --- a/doc/api/pymongo/timestamp.rst +++ b/doc/api/pymongo/timestamp.rst @@ -1,7 +1,8 @@ -:mod:`timestamp` -- Tools for representing MongoDB internal Timestamps -====================================================================== -.. versionadded:: 1.5 +:mod:`timestamp` -- MOVED +========================= -.. automodule:: pymongo.timestamp - :synopsis: Tools for representing MongoDB internal Timestamps - :members: +This module has been deprecated in favor of +:mod:`bson.timestamp`. Please use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated. diff --git a/doc/api/pymongo/tz_util.rst b/doc/api/pymongo/tz_util.rst new file mode 100644 index 000000000..0f1518d61 --- /dev/null +++ b/doc/api/pymongo/tz_util.rst @@ -0,0 +1,8 @@ +:mod:`tz_util` -- MOVED +======================= + +This module has been deprecated in favor of +:mod:`bson.tz_util`. Please use that module instead. + +.. versionchanged:: 1.8.1+ + Deprecated.