From: Mike Bayer Date: Sat, 7 Dec 2013 23:00:34 +0000 (-0500) Subject: - documentation cleanup in ORM including [ticket:2816] X-Git-Tag: rel_0_9_0~45^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7af17459ca23bbf7afcb2bf53531a9e029e05175;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - documentation cleanup in ORM including [ticket:2816] --- diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 9b91d06383..b3b872f389 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -154,10 +154,10 @@ class Mapper(_InspectionAttr): 'alt':my_table.c.some_alt }) - See also: + .. seealso:: - :ref:`classical_mapping` - discussion of direct usage of - :func:`.mapper` + :ref:`classical_mapping` - discussion of direct usage of + :func:`.mapper` :param class\_: The class to be mapped. When using Declarative, this argument is automatically passed as the declared class @@ -246,9 +246,9 @@ class Mapper(_InspectionAttr): is passed automatically as a result of the natural class hierarchy of the declared classes. - See also: + .. seealso:: - :ref:`inheritance_toplevel` + :ref:`inheritance_toplevel` :param inherit_condition: For joined table inheritance, a SQL expression which will @@ -315,10 +315,10 @@ class Mapper(_InspectionAttr): emit an UPDATE statement for the dependent columns during a primary key change. - See also: + ..seealso:: - :ref:`passive_updates` - description of a similar feature as - used with :func:`.relationship` + :ref:`passive_updates` - description of a similar feature as + used with :func:`.relationship` :param polymorphic_on: Specifies the column, attribute, or SQL expression used to determine the target class for an @@ -642,7 +642,9 @@ class Mapper(_InspectionAttr): this :class:`.Mapper` represents. If this mapper is a single-table inheriting mapper, local_table will be ``None``. - See also :attr:`~.Mapper.mapped_table`. + .. seealso:: + + :attr:`~.Mapper.mapped_table`. """ @@ -660,7 +662,9 @@ class Mapper(_InspectionAttr): subclass. For single-table inheritance mappers, mapped_table references the base table. - See also :attr:`~.Mapper.local_table`. + .. seealso:: + + :attr:`~.Mapper.local_table`. """ @@ -679,7 +683,9 @@ class Mapper(_InspectionAttr): This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. - See also :func:`.configure_mappers`. + .. seealso:: + + :func:`.configure_mappers`. """ @@ -1976,10 +1982,10 @@ class Mapper(_InspectionAttr): """Return a namespace of all :class:`.SynonymProperty` properties maintained by this :class:`.Mapper`. - See also: + .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` - objects. + :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + objects. """ return self._filter_properties(properties.SynonymProperty) @@ -1989,10 +1995,10 @@ class Mapper(_InspectionAttr): """Return a namespace of all :class:`.ColumnProperty` properties maintained by this :class:`.Mapper`. - See also: + .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` - objects. + :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + objects. """ return self._filter_properties(properties.ColumnProperty) @@ -2002,10 +2008,10 @@ class Mapper(_InspectionAttr): """Return a namespace of all :class:`.RelationshipProperty` properties maintained by this :class:`.Mapper`. - See also: + .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` - objects. + :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + objects. """ return self._filter_properties(properties.RelationshipProperty) @@ -2015,10 +2021,10 @@ class Mapper(_InspectionAttr): """Return a namespace of all :class:`.CompositeProperty` properties maintained by this :class:`.Mapper`. - See also: + .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` - objects. + :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + objects. """ return self._filter_properties(properties.CompositeProperty) @@ -2200,10 +2206,11 @@ class Mapper(_InspectionAttr): """Return an identity-map key for use in storing/retrieving an item from the identity map. - row - A ``sqlalchemy.engine.RowProxy`` instance or a - dictionary corresponding result-set ``ColumnElement`` - instances to their values within a row. + :param row: A :class:`.RowProxy` instance. The columns which are mapped + by this :class:`.Mapper` should be locatable in the row, preferably + via the :class:`.Column` object directly (as is the case when a + :func:`.select` construct is executed), or via string names of the form + ``_``. """ pk_cols = self.primary_key @@ -2217,8 +2224,7 @@ class Mapper(_InspectionAttr): """Return an identity-map key for use in storing/retrieving an item from an identity map. - primary_key - A list of values indicating the identifier. + :param primary_key: A list of values indicating the identifier. """ return self._identity_class, tuple(primary_key) @@ -2227,6 +2233,11 @@ class Mapper(_InspectionAttr): """Return the identity key for the given instance, based on its primary key attributes. + If the instance's state is expired, calling this method + will result in a database check to see if the object has been deleted. + If the row no longer exists, + :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. + This value is typically also found on the instance state under the attribute name `key`. @@ -2247,6 +2258,11 @@ class Mapper(_InspectionAttr): """Return the list of primary key values for the given instance. + If the instance's state is expired, calling this method + will result in a database check to see if the object has been deleted. + If the row no longer exists, + :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. + """ state = attributes.instance_state(instance) return self._primary_key_from_state(state) diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 6f5773474a..553f6de972 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -2134,9 +2134,10 @@ class Session(_SessionClassMethods): access to the full set of persistent objects (i.e., those that have row identity) currently in the session. - See also: + .. seealso:: - :func:`.identity_key` - operations involving identity keys. + :func:`.identity_key` - helper function to produce the keys used + in this dictionary. """ diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index b866721757..68e293eb6e 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -178,31 +178,59 @@ def polymorphic_union(table_map, typecolname, def identity_key(*args, **kwargs): - """Get an identity key. + """Generate "identity key" tuples, as are used as keys in the + :attr:`.Session.identity_map` dictionary. - Valid call signatures: + This function has several call styles: * ``identity_key(class, ident)`` - class - mapped class (must be a positional argument) + This form receives a mapped class and a primary key scalar or + tuple as an argument. - ident - primary key, if the key is composite this is a tuple + E.g.:: + + >>> identity_key(MyClass, (1, 2)) + (, (1, 2)) + + :param class: mapped class (must be a positional argument) + :param ident: primary key, may be a scalar or tuple argument. * ``identity_key(instance=instance)`` - instance - object instance (must be given as a keyword arg) + This form will produce the identity key for a given instance. The + instance need not be persistent, only that its primary key attributes + are populated (else the key will contain ``None`` for those missing + values). + + E.g.:: + + >>> instance = MyClass(1, 2) + >>> identity_key(instance=instance) + (, (1, 2)) + + In this form, the given instance is ultimately run though + :meth:`.Mapper.identity_key_from_instance`, which will have the + effect of performing a database check for the corresponding row + if the object is expired. + + :param instance: object instance (must be given as a keyword arg) * ``identity_key(class, row=row)`` - class - mapped class (must be a positional argument) + This form is similar to the class/tuple form, except is passed a + database result row as a :class:`.RowProxy` object. + + E.g.:: + + >>> row = engine.execute("select * from table where a=1 and b=2").first() + >>> identity_key(MyClass, row=row) + (, (1, 2)) - row - result proxy row (must be given as a keyword arg) + :param class: mapped class (must be a positional argument) + :param row: :class:`.RowProxy` row returned by a :class:`.ResultProxy` + (must be given as a keyword arg) """ if args: