PYTHON-798 - Improve docs and add examples.

behackett · behackett · commit a5cdb2f6524b · 2015-03-19T13:03:48.000-07:00
diff --git a/pymongo/collection.py b/pymongo/collection.py
@@ -241,14 +241,24 @@ def with_options(
             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
             default) the :attr:`codec_options` of this :class:`Collection`
             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
@@ -454,22 +454,27 @@ def __init__(self, codec_options, read_preference, write_concern):
 
     @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.
-
-        See :mod:`~pymongo.read_preferences` for available options.
+        """Read only access to the read preference of this instance.
 
-        .. 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
@@ -230,6 +230,21 @@ def get_collection(self, name, codec_options=None,
         """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 @@ def get_collection(self, name, codec_options=None,
             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
@@ -1012,6 +1012,21 @@ def get_database(self, name, codec_options=None,
         """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 @@ def get_database(self, name, codec_options=None,
             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
@@ -109,7 +109,7 @@ def tag_sets(self):
            .. seealso:: `Data-Center Awareness
                <http://www.mongodb.org/display/DOCS/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)" % (
