- add new section to ORM referring to runtime inspection API,

more links, attempt to fix #3290

diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst
index e6be00ef7b4494d459d5abe347f34c465e830897..7571ce650ec7c4027236f370452a92752ca14659 100644 (file)
--- a/doc/build/orm/mapping_styles.rst
+++ b/doc/build/orm/mapping_styles.rst
@@ -119,3 +119,52 @@ systems ultimately create the same configuration, consisting of a :class:`.Table
 user-defined class, linked together with a :func:`.mapper`.  When we talk about
 "the behavior of :func:`.mapper`", this includes when using the Declarative system
 as well - it's still used, just behind the scenes.
+
+Runtime Intropsection of Mappings, Objects
+==========================================
+
+The :class:`.Mapper` object is available from any mapped class, regardless
+of method, using the :ref:`core_inspection_toplevel` system.  Using the
+:func:`.inspect` function, one can acquire the :class:`.Mapper` from a
+mapped class::
+
+    >>> from sqlalchemy import inspect
+    >>> insp = inspect(User)
+
+Detailed information is available including :attr:`.Mapper.columns`::
+
+    >>> insp.columns
+    <sqlalchemy.util._collections.OrderedProperties object at 0x102f407f8>
+
+This is a namespace that can be viewed in a list format or
+via individual names::
+
+    >>> list(insp.columns)
+    [Column('id', Integer(), table=<user>, primary_key=True, nullable=False), Column('name', String(length=50), table=<user>), Column('fullname', String(length=50), table=<user>), Column('password', String(length=12), table=<user>)]
+    >>> insp.columns.name
+    Column('name', String(length=50), table=<user>)
+
+Other namespaces include :attr:`.Mapper.all_orm_descriptors`, which includes all mapped
+attributes as well as hybrids, association proxies::
+
+    >>> insp.all_orm_descriptors
+    <sqlalchemy.util._collections.ImmutableProperties object at 0x1040e2c68>
+    >>> insp.all_orm_descriptors.keys()
+    ['fullname', 'password', 'name', 'id']
+
+As well as :attr:`.Mapper.column_attrs`::
+
+    >>> list(insp.column_attrs)
+    [<ColumnProperty at 0x10403fde0; id>, <ColumnProperty at 0x10403fce8; name>, <ColumnProperty at 0x1040e9050; fullname>, <ColumnProperty at 0x1040e9148; password>]
+    >>> insp.column_attrs.name
+    <ColumnProperty at 0x10403fce8; name>
+    >>> insp.column_attrs.name.expression
+    Column('name', String(length=50), table=<user>)
+
+.. seealso::
+
+    :ref:`core_inspection_toplevel`
+
+    :class:`.Mapper`
+
+    :class:`.InstanceState`