Preen docs on orm

Author: chadwhitacre

postgres/orm.py

@@ -1,19 +1,20 @@
 """:py:mod:`postgres` implements an object-relational mapper based on
 :py:mod:`psycopg2` composite casters. The fundamental technique, introduced by
 `Michael Robbelard at PyOhio 2013`_, is to write SQL queries that typecast
-results to table types, and then use :py:mod:`psycopg2`
+results to table types, and then use a :py:mod:`psycopg2`
 :py:class:`~psycopg2.extra.CompositeCaster` to map these to Python objects.
 This means we get to define our schema in SQL, and we get to write our queries
 in SQL, and we get to explicitly indicate in our SQL queries how Python should
-map the result to an object, and then we can write Python objects that contain
+map the results to objects, and then we can write Python objects that contain
 only business logic and not schema definitions.
 
 .. _Michael Robbelard at PyOhio 2013: https://www.youtube.com/watch?v=Wz1_GYc4GmU#t=25m06s
 
 Every table in PostgreSQL has a type associated with it, which is the column
-definition for that table. These are composite types just like any other in
-PostgreSQL, meaning we can use them to cast query results. When we do, we get a
-single field that contains our query data, nested one level::
+definition for that table. These are composite types just like any other
+composite type in PostgreSQL, meaning we can use them to cast query results.
+When we do, we get a single field that contains our query result, nested one
+level::
 
     test=# CREATE TABLE foo (bar text, baz int);
     CREATE TABLE
@@ -68,7 +69,7 @@
 :py:mod:`psycopg2` provides a :py:func:`~psycopg2.extras.register_composite`
 function that lets us map PostgreSQL composite types to Python objects. This
 includes table and view types, and that is the basis for
-:py:mod:`postgres.orm`.
+:py:mod:`postgres.orm`. We map based on types, not tables.
 
 
 ORM Tutorial
@@ -82,20 +83,20 @@
     ...
 
 Your model must have a :py:attr:`typname` attribute, which is the name of the
-PostgreSQL type that this class is intended to be an object mapping for.
-(``typname`` is the name of the relevant column in the ``pg_type`` table in
-your database.)
+PostgreSQL type for which this class is an object mapping. (``typname``,
+spelled without an "e," is the name of the relevant column in the ``pg_type``
+table in your database.)
 
 Second, register your model with your :py:class:`~postgres.Postgres` instance:
 
     >>> db.register_model(Foo)
 
 That will plug your model into the :py:mod:`psycopg2` composite casting
-machinery, and you'll get instances of your model back from
-:py:meth:`~postgres.Postgres.all` and
-:py:meth:`~postgres.Postgres.one_or_zero`. If your query returns more than one
-column, you'll need to dereference the column containing the model just as with
-any other query:
+machinery, and you'll now get instances of your model back from
+:py:meth:`~postgres.Postgres.all` and :py:meth:`~postgres.Postgres.one_or_zero`
+when you cast your query results to the relevant type. If your query returns
+more than one column, you'll need to dereference the column containing the
+model just as with any other query:
 
     >>> rec = db.one_or_zero("SELECT foo.*::foo, bar.* "
     ...                      "FROM foo JOIN bar ON foo.bar = bar.bar "
@@ -105,9 +106,9 @@
     >>> rec.bar
     'blam'
 
-As a special case, if your query only returns one column, and it's a
-:py:class:`~postgres.orm.Model`, then :py:meth:`~postgres.Postgres.all` and
-:py:meth:`~postgres.Postgres.one_or_zero` will do the dereferencing for you:
+As usual, if your query only returns one column, then
+:py:meth:`~postgres.Postgres.all` and :py:meth:`~postgres.Postgres.one_or_zero`
+will do the dereferencing for you:
 
     >>> foo = db.one_or_zero("SELECT foo.*::foo FROM foo WHERE bar='blam'")
     >>> foo.bar
@@ -116,6 +117,8 @@
     ['blam', 'whit']
 
 
+The Model Base Class
+--------------------
 
 """
 from __future__ import print_function, unicode_literals
@@ -151,7 +154,17 @@ def __str__(self):
 # =====
 
 class Model(object):
-    """This is the base class for models under :py:mod:`postgres.orm`.
+    """
+
+    This is the base class for models in :py:mod:`postgres.orm`. Instances of
+    subclasses of :py:class:`~postgres.orm.Model` will have an attribute for
+    each field in the composite type for which the subclass is registered (for
+    table and view types, these will be the columns of the table or view).
+    These attributes are read-only. We don't update your database. You are
+    expected to do that yourself in methods on your subclass. To keep instance
+    attributes in sync after a database update, use the
+    :py:meth:`~postgres.orm.Model.update_attributes` helper.
+
     """
 
     typname = None                          # an entry in pg_type
@@ -173,16 +186,18 @@ def __setattr__(self, name, value):
             raise ReadOnly(name)
         return super(Model, self).__setattr__(name, value)
 
-    def update_local(self, **kw):
-        """Update self.__dict__ with kw.
+    def update_attributes(self, **kw):
+        """Update instance attributes, according to :py:attr:`kw`.
 
         :raises: :py:exc:`~postgres.orm.UnknownAttributes`
 
         Call this when you update state in the database and you want to keep
-        the attributes of your object in sync. Note that the only attributes we
-        can update here are the ones that were given to us by the
+        instance attributes in sync. Note that the only attributes we can
+        update here are the ones that were given to us by the
         :py:mod:`psycopg2` composite caster machinery when we were first
-        instantiated.
+        instantiated. These will be the fields of the composite type for which
+        we were registered, which will be column names for table and view
+        types.
 
         """
         unknown = []