Merge pull request #53 from zopefoundation/issue52

Expose PersistentList/Mapping docs. Fixes #52.

docs/api.rst

@@ -5,6 +5,7 @@
    :maxdepth: 2
 
    api/interfaces
+   api/collections
    api/attributes
    api/pickling
    api/cache

docs/api/collections.rst

+========================
+ Persistent Collections
+========================
+
+The ``persistent`` package provides two simple collections that are
+persistent and keep track of when they are mutated in place.
+
+.. autoclass:: persistent.mapping.PersistentMapping
+			   :members:
+			   :show-inheritance:
+
+.. autoclass:: persistent.list.PersistentList
+			   :members:
+			   :show-inheritance:

docs/api/interfaces.rst

@@ -15,3 +15,12 @@
      :members:
      :member-order: bysource
 
+Implementations
+===============
+
+This package provides one implementation of :class:`IPersistent` that
+should be extended.
+
+  .. autoclass:: persistent.Persistent
+				 :members:
+				 :show-inheritance:

docs/conf.py

@@ -50,16 +50,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'persistent'
-copyright = u'2011, ZODB Developers <zope-dev@zope.org>'
+copyright = u'2011,2016 ZODB Developers <zope-dev@zope.org>'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '3.10'
+version = '4.2'
 # The full version, including alpha/beta/rc tags.
-release = '3.10b1'
+release = '4.2.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -266,4 +266,4 @@ epub_copyright = u'2011, ZODB Developers <zope-dev@zope.org>'
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/': None}

docs/using.rst

@@ -212,12 +212,17 @@ manager.  Subsequent modifications don't have additional side-effects.
 Object which register themselves with the data manager are candidates
 for storage to the backing store at a later point in time.
 
+Note that mutating a non-persistent attribute of a persistent object
+such as a :class:`dict` or :class:`list` will *not* cause the
+containing object to be changed. Instead you can either explicitly
+control the state as described below, or use a
+:class:`~.PersistentList` or :class:`~.PersistentMapping`.
 
 Explicitly controlling ``_p_state``
 -----------------------------------
 
 Persistent objects expose three methods for moving an object into and out
-of the "ghost" state::  :meth:`persistent.Persistent._p_activate`, 
+of the "ghost" state::  :meth:`persistent.Persistent._p_activate`,
 :meth:`persistent.Persistent._p_activate_p_deactivate`, and
 :meth:`persistent.Persistent._p_invalidate`:
 
@@ -412,18 +417,19 @@ Overriding the attribute protocol
 Subclasses which override the attribute-management methods provided by
 :class:`persistent.Persistent`, but must obey some constraints:
 
-:meth:`__getattribute__``
+
+:meth:`__getattribute__`
   When overriding ``__getattribute__``, the derived class implementation
-  **must** first call :meth:`persistent.Persistent._p_getattr`, passing the
+  **must** first call :meth:`persistent.IPersistent._p_getattr`, passing the
   name being accessed.  This method ensures that the object is activated,
   if needed, and handles the "special" attributes which do not require
-  activation (e.g., ``_p_oid``, ``__class__``, ``__dict__``, etc.) 
+  activation (e.g., ``_p_oid``, ``__class__``, ``__dict__``, etc.)
   If ``_p_getattr`` returns ``True``, the derived class implementation
   **must** delegate to the base class implementation for the attribute.
 
 :meth:`__setattr__`
   When overriding ``__setattr__``, the derived class implementation
-  **must** first call :meth:`persistent.Persistent._p_setattr`, passing the
+  **must** first call :meth:`persistent.IPersistent._p_setattr`, passing the
   name being accessed and the value.  This method ensures that the object is
   activated, if needed, and handles the "special" attributes which do not
   require activation (``_p_*``).  If ``_p_setattr`` returns ``True``, the
@@ -432,7 +438,7 @@ Subclasses which override the attribute-management methods provided by
 
 :meth:`__detattr__`
   When overriding ``__detattr__``, the derived class implementation
-  **must** first call :meth:`persistent.Persistent._p_detattr`, passing the
+  **must** first call :meth:`persistent.IPersistent._p_detattr`, passing the
   name being accessed.  This method ensures that the object is
   activated, if needed, and handles the "special" attributes which do not
   require activation (``_p_*``).  If ``_p_delattr`` returns ``True``, the
@@ -440,5 +446,5 @@ Subclasses which override the attribute-management methods provided by
   base class.
 
 :meth:`__getattr__`
-  For the `__getattr__` method, the behavior is like that for regular Python
+  For the ``__getattr__`` method, the behavior is like that for regular Python
   classes and for earlier versions of ZODB 3.

persistent/list.py

@@ -21,6 +21,11 @@ from persistent._compat import UserList
 from persistent._compat import PYTHON2
 
 class PersistentList(UserList, persistent.Persistent):
+    """A persistent wrapper for list objects.
+
+    Mutating instances of this class will cause them to be marked
+    as changed and automatically persisted.
+    """
     __super_setitem = UserList.__setitem__
     __super_delitem = UserList.__delitem__
     if PYTHON2:  # pragma: no cover