[Sqlalchemy-tickets] [sqlalchemy] #2816: clean up identity_key util documentation

[sqlalchemy <mi...@zz...>]

#2816: clean up identity_key util documentation
---------------------------+---------------------------------------
 Reporter:  zzzeek         |           Owner:  zzzeek
     Type:  defect         |          Status:  new
 Priority:  high           |       Milestone:  0.8.xx
Component:  documentation  |        Severity:  minor - half an hour
 Keywords:                 |  Progress State:  in queue
---------------------------+---------------------------------------
 these old functions are confusing esp when given an instance, as you
 usually just want inspect(obj).key.

 A patch with some partial wording:

 {{{
 #!diff
 --- a/lib/sqlalchemy/orm/mapper.py
 +++ b/lib/sqlalchemy/orm/mapper.py
 @@ -2225,7 +2225,9 @@ class Mapper(_InspectionAttr):

      def identity_key_from_instance(self, instance):
          """Return the identity key for the given instance, based on
 -        its primary key attributes.
 +        its primary key attributes. If the instance's state is expired
 this
 +        will check if the object has been deleted. If that is the case,
 +        :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised.

          This value is typically also found on the instance state under
 the
          attribute name `key`.
 @@ -2245,7 +2247,9 @@ class Mapper(_InspectionAttr):

      def primary_key_from_instance(self, instance):
          """Return the list of primary key values for the given
 -        instance.
 +        instance. If the instance's state is expired this
 +        will check if the object has been deleted. If that is the case,
 +        :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised.

          """
          state = attributes.instance_state(instance)
 diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
 index 9737072..f3f2c05 100644
 --- a/lib/sqlalchemy/orm/util.py
 +++ b/lib/sqlalchemy/orm/util.py
 @@ -176,6 +176,9 @@ def identity_key(*args, **kwargs):

        instance
            object instance (must be given as a keyword arg)
 +      If the instance's state is expired this will check if the object
 has
 +      been deleted. If that is the case,
 +      :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised.

      * ``identity_key(class, row=row)``

 }}}

--
Ticket URL: <http://www.sqlalchemy.org/trac/ticket/2816>
sqlalchemy <http://www.sqlalchemy.org/>
The Database Toolkit for Python