From a5cdb2f6524b3fbfd0217349a1b510273dbbc5a4 Mon Sep 17 00:00:00 2001 From: Bernie Hackett Date: Thu, 19 Mar 2015 13:03:48 -0700 Subject: [PATCH] PYTHON-798 - Improve docs and add examples. --- pymongo/collection.py | 12 +++++++++++- pymongo/common.py | 17 +++++++++++------ pymongo/database.py | 18 +++++++++++++++++- pymongo/mongo_client.py | 18 +++++++++++++++++- pymongo/read_preferences.py | 2 +- 5 files changed, 57 insertions(+), 10 deletions(-) diff --git a/pymongo/collection.py b/pymongo/collection.py index d9784cfe4..d89dd26a2 100644 --- a/pymongo/collection.py +++ b/pymongo/collection.py @@ -241,6 +241,15 @@ class Collection(common.BaseObject): self, codec_options=None, read_preference=None, write_concern=None): """Get a clone of this collection changing the specified settings. + >>> coll1.read_preference + Primary() + >>> from pymongo import ReadPreference + >>> coll2 = coll.with_options(read_preference=ReadPreference.SECONDARY) + >>> coll1.read_preference + Primary() + >>> coll2.read_preference + Secondary(tag_sets=None) + :Parameters: - `codec_options` (optional): An instance of :class:`~bson.codec_options.CodecOptions`. If ``None`` (the @@ -248,7 +257,8 @@ class Collection(common.BaseObject): is used. - `read_preference` (optional): The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`Collection` is used. + :class:`Collection` is used. See :mod:`~pymongo.read_preferences` + for options. - `write_concern` (optional): An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the default) the :attr:`write_concern` of this :class:`Collection` diff --git a/pymongo/common.py b/pymongo/common.py index 7035a28c9..a957381e5 100644 --- a/pymongo/common.py +++ b/pymongo/common.py @@ -454,22 +454,27 @@ class BaseObject(object): @property def codec_options(self): - """An instance of :class:`~bson.codec_options.CodecOptions`.""" + """Read only access to the :class:`~bson.codec_options.CodecOptions` + of this instance. + """ return self.__codec_options @property def write_concern(self): - """The :class:`~pymongo.write_concern.WriteConcern` for this instance. + """Read only access to the :class:`~pymongo.write_concern.WriteConcern` + of this instance. + + .. versionchanged:: 3.0 + The :attr:`write_concern` attribute is now read only. """ return self.__write_concern @property def read_preference(self): - """The read preference mode for this instance. + """Read only access to the read preference of this instance. - See :mod:`~pymongo.read_preferences` for available options. - - .. versionadded:: 2.1 + .. versionchanged:: 3.0 + The :attr:`read_preference` attribute is now read only. """ return self.__read_preference diff --git a/pymongo/database.py b/pymongo/database.py index e2204d89f..ebd3a4cca 100644 --- a/pymongo/database.py +++ b/pymongo/database.py @@ -230,6 +230,21 @@ class Database(common.BaseObject): """Get a :class:`~pymongo.collection.Collection` with the given name and options. + Useful for creating a :class:`~pymongo.collection.Collection` with + different codec options, read preference, and/or write concern from + this :class:`Database`. + + >>> db.read_preference + Primary() + >>> coll1 = db.test + >>> coll1.read_preference + Primary() + >>> from pymongo import ReadPreference + >>> coll2 = db.get_collection( + ... 'test', read_preference=ReadPreference.SECONDARY) + >>> coll2.read_preference + Secondary(tag_sets=None) + :Parameters: - `name`: The name of the collection - a string. - `codec_options` (optional): An instance of @@ -238,7 +253,8 @@ class Database(common.BaseObject): used. - `read_preference` (optional): The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`Database` is used. + :class:`Database` is used. See :mod:`~pymongo.read_preferences` + for options. - `write_concern` (optional): An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the default) the :attr:`write_concern` of this :class:`Database` is diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 7c592e7f2..81df06285 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -1012,6 +1012,21 @@ class MongoClient(common.BaseObject): """Get a :class:`~pymongo.database.Database` with the given name and options. + Useful for creating a :class:`~pymongo.database.Database` with + different codec options, read preference, and/or write concern from + this :class:`MongoClient`. + + >>> client.read_preference + Primary() + >>> db1 = client.test + >>> db1.read_preference + Primary() + >>> from pymongo import ReadPreference + >>> db2 = client.get_database( + ... 'test', read_preference=ReadPreference.SECONDARY) + >>> db2.read_preference + Secondary(tag_sets=None) + :Parameters: - `name`: The name of the database - a string. - `codec_options` (optional): An instance of @@ -1020,7 +1035,8 @@ class MongoClient(common.BaseObject): used. - `read_preference` (optional): The read preference to use. If ``None`` (the default) the :attr:`read_preference` of this - :class:`MongoClient` is used. + :class:`MongoClient` is used. See :mod:`~pymongo.read_preferences` + for options. - `write_concern` (optional): An instance of :class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the default) the :attr:`write_concern` of this :class:`MongoClient` is diff --git a/pymongo/read_preferences.py b/pymongo/read_preferences.py index 969ee3f21..ea5a86124 100644 --- a/pymongo/read_preferences.py +++ b/pymongo/read_preferences.py @@ -109,7 +109,7 @@ class _ServerMode(object): .. seealso:: `Data-Center Awareness `_ """ - return self.__tag_sets or [{}] + return list(self.__tag_sets) if self.__tag_sets else [{}] def __repr__(self): return "%s(tag_sets=%r)" % (