clean up identity_key util documentation

[Mike Bayer]

these old functions are confusing esp when given an instance, as you usually just want inspect(obj).key.

A patch with some partial wording:

--- 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)``

[Mike Bayer]

also figure out this part:

@@ -196,6 +199,7 @@ def identity_key(*args, **kwargs):
         elif len(args) == 2:
             class_, ident = args
         elif len(args) == 3:
+            # XXX: How can this work? I'd expect a ValueError here  -- Torsten Landschoff
             class_, ident = args
         else:
             raise sa_exc.ArgumentError("expected up to three "

[Mike Bayer]

6817592180ac2ecd52d543029431f3f803967ce6 0.8

7af17459ca23bbf7afcb2bf53531a9e029e05175 master / 0.9

[Mike Bayer]

Removing milestone: 0.8.xx (automated comment)