From: Mike Bayer Date: Sun, 20 Mar 2011 18:00:16 +0000 (-0400) Subject: - add attrstrings for all the important mapper() attrbutes, [ticket:2094]. X-Git-Tag: rel_0_7b3~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=50764fd641af80fcfbe258cb22aed4d891893560;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - add attrstrings for all the important mapper() attrbutes, [ticket:2094]. Sticking with quotes here since that's what's used everywhere else. - rename "API Documentation - XYZ" to "XYZ API". - move connection API docs to the bottom of that section. still floating between separate API sections vs. inline API sections, not sure how to be consistent. - fix outdated paragraph about derived_attrbutes - other target function fixes --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index ce67c0428c..f6fd874896 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -102,27 +102,6 @@ The :meth:`~.Connection.execute` method can of course accommodate more than that, including the variety of SQL expression constructs described in :ref:`sqlexpression_toplevel`. -API Documentation - Connection, Engine, result objects -======================================================= - -.. autoclass:: Connection - :show-inheritance: - :members: - -.. autoclass:: Connectable - :show-inheritance: - :members: - -.. autoclass:: Engine - :show-inheritance: - :members: - -.. autoclass:: sqlalchemy.engine.base.ResultProxy - :members: - -.. autoclass:: sqlalchemy.engine.base.RowProxy - :members: - Using Transactions ================== @@ -198,9 +177,6 @@ one exists. .. index:: single: thread safety; transactions -.. autoclass:: Transaction - :members: - Understanding Autocommit ======================== @@ -375,3 +351,28 @@ call :meth:`.Engine.contextual_connect`:: Calling :meth:`~.Connection.close` on the "contextual" connection does not release its resources until all other usages of that resource are closed as well, including that any ongoing transactions are rolled back or committed. + +Connection / Engine API +======================= + +.. autoclass:: Connection + :show-inheritance: + :members: + +.. autoclass:: Connectable + :show-inheritance: + :members: + +.. autoclass:: Engine + :show-inheritance: + :members: + +.. autoclass:: sqlalchemy.engine.base.ResultProxy + :members: + +.. autoclass:: sqlalchemy.engine.base.RowProxy + :members: + +.. autoclass:: Transaction + :members: + diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index f7ec9c72ef..dbc0255105 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -131,8 +131,8 @@ Further detail on dialects is available at :ref:`dialect_toplevel`. .. _create_engine_args: -API Documentation - Creating Engines -===================================== +Engine Creation API +=================== Keyword options can also be specified to :func:`~sqlalchemy.create_engine`, following the string URL as follows: diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst index bcd5286893..decd2ba60b 100644 --- a/doc/build/core/expression_api.rst +++ b/doc/build/core/expression_api.rst @@ -1,7 +1,7 @@ .. _expression_api_toplevel: -API Documentation - SQL Statements and Expressions -================================================== +SQL Statements and Expressions API +================================== .. module:: sqlalchemy.sql.expression diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst index a4c201e090..d7fa8ad24b 100644 --- a/doc/build/core/schema.rst +++ b/doc/build/core/schema.rst @@ -377,8 +377,8 @@ example, MySQL has different table backend types, including "MyISAM" and Other backends may support table-level options as well - these would be described in the individual documentation sections for each dialect. -API Documenation - Column, Table, MetaData -------------------------------------------- +Column, Table, MetaData API +--------------------------- .. autoclass:: Column :members: @@ -815,8 +815,8 @@ executed standalone like a SQL expression, which has the effect of calling its seq = Sequence('some_sequence') nextid = connection.execute(seq) -API Documentation - Default Objects ------------------------------------ +Default Objects API +------------------- .. autoclass:: ColumnDefault :show-inheritance: @@ -1055,8 +1055,8 @@ MySQL. CONSTRAINT check1 CHECK (col2 > col3 + 5) ){stop} -API Documentation - Constraints --------------------------------- +Constraints API +--------------- .. autoclass:: Constraint :show-inheritance: @@ -1381,8 +1381,8 @@ details. .. _schema_api_ddl: -API Documentation - DDL Expression Constructs ---------------------------------------------- +DDL Expression Constructs API +----------------------------- .. autoclass:: DDLElement :members: diff --git a/doc/build/core/types.rst b/doc/build/core/types.rst index 020d3ee8f4..1590041185 100644 --- a/doc/build/core/types.rst +++ b/doc/build/core/types.rst @@ -264,6 +264,8 @@ to and from the database is required. :inherited-members: :show-inheritance: +TypeDecorator Recipes +~~~~~~~~~~~~~~~~~~~~~ A few key :class:`.TypeDecorator` recipes follow. Rounding Numerics diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index e51edf7c29..98de8e2059 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -390,8 +390,8 @@ authoring custom types. See the :mod:`sqlalchemy.orm.collections` package for more information and discussion of advanced usage and Python 2.3-compatible decoration options. -API Documentation - Collections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Collections API +~~~~~~~~~~~~~~~ .. autofunction:: attribute_mapped_collection diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst index 06018d30e4..96c641f905 100644 --- a/doc/build/orm/mapper_config.rst +++ b/doc/build/orm/mapper_config.rst @@ -143,8 +143,8 @@ together using a list, as below where we map to a :func:`~.expression.join`:: For further examples on this particular use case, see :ref:`maptojoin`. -API Documentation - column_property ------------------------------------- +Using column_property for column level options +----------------------------------------------- The establishment of a :class:`.Column` on a :func:`.mapper` can be further customized using the :func:`.column_property` function, as specified @@ -252,8 +252,8 @@ to :func:`~sqlalchemy.orm.deferred()`, can be undeferred using query = session.query(Book) query.options(undefer_group('photos')).all() -API Documentation - Column Deferral ------------------------------------ +Column Deferral API +------------------- .. autofunction:: deferred @@ -327,11 +327,9 @@ transactional context from which to emit a statement:: where(addresses_table.c.user_id==self.user_id) ) -On the subject of object-level methods, be sure to see the :mod:`.derived_attributes` example, -which provides a simple method of reusing instance-level expressions simultaneously -as SQL expressions. The :mod:`.derived_attributes` example is slated to become a -built-in feature of SQLAlchemy in a future release. - +See also :ref:`synonyms` for details on building expression-enabled +descriptors on mapped classes, which are invoked independently of the +mapping. Changing Attribute Behavior ============================ @@ -846,8 +844,8 @@ the ORM, allowing mappers to be compiled automatically and will fire a :func:`~s .. autofunction:: reconstructor -API Documentation - Class Mapping -================================= +Class Mapping API +================= .. autofunction:: mapper @@ -857,6 +855,8 @@ API Documentation - Class Mapping .. autofunction:: compile_mappers +.. autofunction:: configure_mappers + .. autofunction:: clear_mappers .. autofunction:: sqlalchemy.orm.util.identity_key diff --git a/doc/build/orm/query.rst b/doc/build/orm/query.rst index 4930794ea9..0f273e4b57 100644 --- a/doc/build/orm/query.rst +++ b/doc/build/orm/query.rst @@ -1,7 +1,7 @@ .. _query_api_toplevel: -API Documentation - Querying -============================ +Querying +======== This section provides API documentation for the :class:`.Query` object and related constructs. diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index ed20cb0081..0c68bcccc9 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -782,8 +782,8 @@ unit of work searches only through the current identity map for objects that may be referencing the one with a mutating primary key, not throughout the database. -API Documentation - Relationships ----------------------------------- +Relationships API +----------------- .. autofunction:: relationship diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index a995c87a31..359f1a6c1d 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -1396,8 +1396,8 @@ its connections to the pool and removes any existing transactional context. Doing nothing is an option too, if individual controller methods take responsibility for ensuring that no transactions remain open after a request ends. -API Documentation - Contextual Session --------------------------------------- +Contextual Session API +---------------------- .. autofunction:: sqlalchemy.orm.scoped_session @@ -1438,8 +1438,8 @@ tables) across multiple databases. See the "sharding" example: :ref:`examples_sharding`. -API Documentation - Sessions -============================ +Sessions API +============ Session and sessionmaker() --------------------------- diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 0cc28c8e86..f5f8ea1efc 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -104,7 +104,7 @@ class Mapper(object): self.class_manager = None - self.primary_key_argument = util.to_list(primary_key) + self._primary_key_argument = util.to_list(primary_key) self.non_primary = non_primary if order_by is not False: @@ -217,6 +217,218 @@ class Mapper(object): finally: _COMPILE_MUTEX.release() + # major attributes initialized at the classlevel so that + # they can be Sphinx-documented. + + local_table = None + """The :class:`.Selectable` which this :class:`.Mapper` manages. + + Typically is an instance of :class:`.Table` or :class:`.Alias`. + May also be ``None``. + + The "local" table is the + selectable that the :class:`.Mapper` is directly responsible for + managing from an attribute access and flush perspective. For + non-inheriting mappers, the local table is the same as the + "mapped" table. For joined-table inheritance mappers, local_table + will be the particular sub-table of the overall "join" which + this :class:`.Mapper` represents. If this mapper is a + single-table inheriting mapper, local_table will be ``None``. + + See also :attr:`~.Mapper.mapped_table`. + + """ + + mapped_table = None + """The :class:`.Selectable` to which this :class:`.Mapper` is mapped. + + Typically an instance of :class:`.Table`, :class:`.Join`, or + :class:`.Alias`. + + The "mapped" table is the selectable that + the mapper selects from during queries. For non-inheriting + mappers, the mapped table is the same as the "local" table. + For joined-table inheritance mappers, mapped_table references the + full :class:`.Join` representing full rows for this particular + subclass. For single-table inheritance mappers, mapped_table + references the base table. + + See also :attr:`~.Mapper.local_table`. + + """ + + inherits = None + """References the :class:`.Mapper` which this :class:`.Mapper` + inherits from, if any. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + configured = None + """Represent ``True`` if this :class:`.Mapper` has been configured. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + See also :func:`.configure_mappers`. + + """ + + concrete = None + """Represent ``True`` if this :class:`.Mapper` is a concrete + inheritance mapper. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + tables = None + """An iterable containing the collection of :class:`.Table` objects + which this :class:`.Mapper` is aware of. + + If the mapper is mapped to a :class:`.Join`, or an :class:`.Alias` + representing a :class:`.Select`, the individual :class:`.Table` + objects that comprise the full construct will be represented here. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + primary_key = None + """An iterable containing the collection of :class:`.Column` objects + which comprise the 'primary key' of the mapped table, from the + perspective of this :class:`.Mapper`. + + This list is against the selectable in :attr:`~.Mapper.mapped_table`. In the + case of inheriting mappers, some columns may be managed by a superclass + mapper. For example, in the case of a :class:`.Join`, the primary + key is determined by all of the primary key columns across all tables + referenced by the :class:`.Join`. + + The list is also not necessarily the same as the primary key column + collection associated with the underlying tables; the :class:`.Mapper` + features a ``primary_key`` argument that can override what the + :class:`.Mapper` considers as primary key columns. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + class_ = None + """The Python class which this :class:`.Mapper` maps. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + class_manager = None + """The :class:`.ClassManager` which maintains event listeners + and class-bound descriptors for this :class:`.Mapper`. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + single = None + """Represent ``True`` if this :class:`.Mapper` is a single table + inheritance mapper. + + :attr:`~.Mapper.local_table` will be ``None`` if this flag is set. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + non_primary = None + """Represent ``True`` if this :class:`.Mapper` is a "non-primary" + mapper, e.g. a mapper that is used only to selet rows but not for + persistence management. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + polymorphic_on = None + """The :class:`.Column` specified as the ``polymorphic_on`` column + for this :class:`.Mapper`, within an inheritance scenario. + + This attribute may also be of other types besides :class:`.Column` + in a future SQLAlchemy release. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + polymorphic_map = None + """A mapping of "polymorphic identity" identifiers mapped to :class:`.Mapper` + instances, within an inheritance scenario. + + The identifiers can be of any type which is comparable to the + type of column represented by :attr:`~.Mapper.polymorphic_on`. + + An inheritance chain of mappers will all reference the same + polymorphic map object. The object is used to correlate incoming + result rows to target mappers. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + polymorphic_identity = None + """Represent an identifier which is matched against the :attr:`~.Mapper.polymorphic_on` + column during result row loading. + + Used only with inheritance, this object can be of any type which is + comparable to the type of column represented by :attr:`~.Mapper.polymorphic_on`. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + base_mapper = None + """The base-most :class:`.Mapper` in an inheritance chain. + + In a non-inheriting scenario, this attribute will always be this + :class:`.Mapper`. In an inheritance scenario, it references + the :class:`.Mapper` which is parent to all other :class:`.Mapper` + objects in the inheritance chain. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + columns = None + """A collection of :class:`.Column` or other scalar expression + objects maintained by this :class:`.Mapper`. + + The collection behaves the same as that of the ``c`` attribute on + any :class:`.Table` object, except that only those columns included in + this mapping are present, and are keyed based on the attribute name + defined in the mapping, not necessarily the ``key`` attribute of the + :class:`.Column` itself. Additionally, scalar expressions mapped + by :func:`.column_property` are also present here. + + This is a *read only* attribute determined during mapper construction. + Behavior is undefined if directly modified. + + """ + + c = None + """A synonym for :attr:`~.Mapper.columns`.""" + dispatch = event.dispatcher(events.MapperEvents) def _configure_inheritance(self): @@ -493,8 +705,8 @@ class Mapper(object): # if explicit PK argument sent, add those columns to the # primary key mappings - if self.primary_key_argument: - for k in self.primary_key_argument: + if self._primary_key_argument: + for k in self._primary_key_argument: if k.table not in self._pks_by_table: self._pks_by_table[k.table] = util.OrderedSet() self._pks_by_table[k.table].add(k) @@ -515,17 +727,17 @@ class Mapper(object): if self.inherits and \ not self.concrete and \ - not self.primary_key_argument: + not self._primary_key_argument: # if inheriting, the "primary key" for this mapper is # that of the inheriting (unless concrete or explicit) self.primary_key = self.inherits.primary_key else: # determine primary key from argument or mapped_table pks - # reduce to the minimal set of columns - if self.primary_key_argument: + if self._primary_key_argument: primary_key = sqlutil.reduce_columns( [self.mapped_table.corresponding_column(c) for c in - self.primary_key_argument], + self._primary_key_argument], ignore_nonexistent_tables=True) else: primary_key = sqlutil.reduce_columns( @@ -745,9 +957,8 @@ class Mapper(object): break path.append(m) - # otherwise, col might not be present! the selectable given - # to the mapper need not include "deferred" - # columns (included in zblog tests) + # subquery expression, column not present in the mapped + # selectable. if col is None: col = prop.columns[0] @@ -2468,7 +2679,7 @@ def validates(*names): case of a collection, the value to be added to the collection. The function can then raise validation exceptions to halt the process from continuing (where Python's built-in ``ValueError`` and ``AssertionError`` exceptions are - reasonable choices), or can modify or replace the value before proceeding. + reasonable choices), or can modify or replace the value before proceeding. The function should otherwise return the given value. Note that a validator for a collection **cannot** issue a load of that