From: Kataev Denis Date: Mon, 22 May 2017 21:52:45 +0000 (-0400) Subject: Repair formatting throughout documentation X-Git-Tag: rel_1_1_11~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9461fd8771903462ffec38258942d621e6a627ab;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Repair formatting throughout documentation 1. Section decorators to [one style](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections): without inset at both side and with same length as text. 2. Fix broken [reference](http://docs.sqlalchemy.org/en/latest/core/type_basics.html#generic-types). 3. Convert tabs to space in some small files. 4. Some python code snippets have python+sql syntax hint. Change-Id: I39a7a41ef0b0591c6bf1e610748e2b5c19fc5379 Pull-request: https://github.com/zzzeek/sqlalchemy/pull/361 (cherry picked from commit 42b6ef8ccd691f6ace30ae16ed70f92e748f763f) --- diff --git a/doc/build/changelog/changelog_01.rst b/doc/build/changelog/changelog_01.rst index b0d95d45c9..d2878f6d5c 100644 --- a/doc/build/changelog/changelog_01.rst +++ b/doc/build/changelog/changelog_01.rst @@ -1,7 +1,7 @@ -============== +============= 0.1 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_02.rst b/doc/build/changelog/changelog_02.rst index 44b77b6649..ef389f63f4 100644 --- a/doc/build/changelog/changelog_02.rst +++ b/doc/build/changelog/changelog_02.rst @@ -1,7 +1,7 @@ -============== +============= 0.2 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_03.rst b/doc/build/changelog/changelog_03.rst index 349367c38e..27eda474f5 100644 --- a/doc/build/changelog/changelog_03.rst +++ b/doc/build/changelog/changelog_03.rst @@ -1,7 +1,7 @@ -============== +============= 0.3 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_04.rst b/doc/build/changelog/changelog_04.rst index 1bd49871c1..7dcfa82e1c 100644 --- a/doc/build/changelog/changelog_04.rst +++ b/doc/build/changelog/changelog_04.rst @@ -1,7 +1,7 @@ -============== +============= 0.4 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_05.rst b/doc/build/changelog/changelog_05.rst index 5bcfd5fdfc..172caaa517 100644 --- a/doc/build/changelog/changelog_05.rst +++ b/doc/build/changelog/changelog_05.rst @@ -1,7 +1,7 @@ -============== +============= 0.5 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_06.rst b/doc/build/changelog/changelog_06.rst index d1c7fe5dbe..1a3664f7de 100644 --- a/doc/build/changelog/changelog_06.rst +++ b/doc/build/changelog/changelog_06.rst @@ -1,7 +1,7 @@ -============== +============= 0.6 Changelog -============== +============= .. changelog:: diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst index a77945fc26..2b7654ec2e 100644 --- a/doc/build/changelog/changelog_07.rst +++ b/doc/build/changelog/changelog_07.rst @@ -1,7 +1,7 @@ -============== +============= 0.7 Changelog -============== +============= .. changelog:: :version: 0.7.11 diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index 6eb58306ab..548bc43e8c 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -1,7 +1,7 @@ -============== +============= 0.8 Changelog -============== +============= .. changelog_imports:: diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst index c912387cd4..159c5acfe9 100644 --- a/doc/build/changelog/changelog_09.rst +++ b/doc/build/changelog/changelog_09.rst @@ -1,7 +1,7 @@ -============== +============= 0.9 Changelog -============== +============= .. changelog_imports:: diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index b0047dd8e7..d282fa3a11 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -1,8 +1,8 @@ -============== +============= 1.0 Changelog -============== +============= .. changelog_imports:: diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst index 9fba02c320..90a8bb3a50 100644 --- a/doc/build/changelog/changelog_11.rst +++ b/doc/build/changelog/changelog_11.rst @@ -1,8 +1,8 @@ -============== +============= 1.1 Changelog -============== +============= .. changelog_imports:: diff --git a/doc/build/changelog/index.rst b/doc/build/changelog/index.rst index a9f294e877..58a4b59e22 100644 --- a/doc/build/changelog/index.rst +++ b/doc/build/changelog/index.rst @@ -7,7 +7,7 @@ SQLAlchemy changelogs and migration guides are now integrated within the main documentation. Current Migration Guide ------------------------- +----------------------- .. toctree:: :titlesonly: diff --git a/doc/build/changelog/migration_06.rst b/doc/build/changelog/migration_06.rst index c3d0df1f35..54a553623e 100644 --- a/doc/build/changelog/migration_06.rst +++ b/doc/build/changelog/migration_06.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 0.6? -============================== +============================= .. admonition:: About this Document diff --git a/doc/build/changelog/migration_07.rst b/doc/build/changelog/migration_07.rst index 9c4ba3f816..589970c381 100644 --- a/doc/build/changelog/migration_07.rst +++ b/doc/build/changelog/migration_07.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 0.7? -============================== +============================= .. admonition:: About this Document diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst index 19faafa89c..64ef46c263 100644 --- a/doc/build/changelog/migration_08.rst +++ b/doc/build/changelog/migration_08.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 0.8? -============================== +============================= .. admonition:: About this Document @@ -527,7 +527,7 @@ the :class:`.Table` to which ``User`` is mapped. :ticket:`2245` Query.update() supports UPDATE..FROM -------------------------------------- +------------------------------------ The new UPDATE..FROM mechanics work in query.update(). Below, we emit an UPDATE against ``SomeEntity``, adding @@ -576,7 +576,7 @@ that were not flushed in the current transaction. :ticket:`2452` Caching Example now uses dogpile.cache ---------------------------------------- +-------------------------------------- The caching example now uses `dogpile.cache `_. Dogpile.cache is a rewrite of the caching portion @@ -607,7 +607,7 @@ this change is needed as illustrated in the Beaker example:: :ticket:`2589` New Core Features -================== +================= Fully extensible, type-level operator support in Core ----------------------------------------------------- @@ -686,7 +686,7 @@ as more string, integer and date operators. .. _feature_2623: Multiple-VALUES support for Insert ------------------------------------ +---------------------------------- The :meth:`.Insert.values` method now supports a list of dictionaries, which will render a multi-VALUES statement such as @@ -708,7 +708,7 @@ remains unchanged:: :ticket:`2623` Type Expressions ------------------ +---------------- SQL expressions can now be associated with types. Historically, :class:`.TypeEngine` has always allowed Python-side functions which @@ -753,7 +753,7 @@ to embed PostGIS expressions inline in SQL based on type rules. :ticket:`1534` Core Inspection System ------------------------ +---------------------- The :func:`.inspect` function introduced in :ref:`feature_orminspection_08` also applies to the core. Applied to an :class:`.Engine` it produces @@ -1241,7 +1241,7 @@ the previous behavior. :ticket:`2664` Repaired the Event Targeting of :class:`.InstrumentationEvents` ----------------------------------------------------------------- +--------------------------------------------------------------- The :class:`.InstrumentationEvents` series of event targets have documented that the events will only be fired off according to diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst index 3056f6b62c..175d962343 100644 --- a/doc/build/changelog/migration_10.rst +++ b/doc/build/changelog/migration_10.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 1.0? -============================== +============================= .. admonition:: About this Document @@ -41,7 +41,7 @@ to proceed at speeds that rival direct use of the Core. :ticket:`3100` New Performance Example Suite ------------------------------- +----------------------------- Inspired by the benchmarking done for the :ref:`bulk_operations` feature as well as for the :ref:`faq_how_to_profile` section of the FAQ, a new @@ -94,7 +94,7 @@ once, a query as a pre-compiled unit begins to be feasible:: .. _feature_3150: Improvements to declarative mixins, ``@declared_attr`` and related features ----------------------------------------------------------------------------- +--------------------------------------------------------------------------- The declarative system in conjunction with :class:`.declared_attr` has been overhauled to support new capabilities. @@ -322,7 +322,7 @@ object totally smokes both namedtuple and KeyedTuple:: .. _feature_slots: Significant Improvements in Structural Memory Use --------------------------------------------------- +------------------------------------------------- Structural memory use has been improved via much more significant use of ``__slots__`` for many internal objects. This optimization is @@ -353,7 +353,7 @@ well as weakrefs, within a basic import of "nova.db.sqlalchemy.models":: .. _feature_updatemany: UPDATE statements are now batched with executemany() in a flush ----------------------------------------------------------------- +--------------------------------------------------------------- UPDATE statements can now be batched within an ORM flush into more performant executemany() call, similarly to how INSERT @@ -418,7 +418,7 @@ of inheritance-oriented scenarios, including: .. _bug_3227: Session.get_bind() will receive the Mapper in all relevant Query cases ------------------------------------------------------------------------ +---------------------------------------------------------------------- A series of issues were repaired where the :meth:`.Session.get_bind` would not receive the primary :class:`.Mapper` of the :class:`.Query`, @@ -501,7 +501,7 @@ as remaining ORM constructs such as :func:`.orm.synonym`. .. _bug_3188: ColumnProperty constructs work a lot better with aliases, order_by -------------------------------------------------------------------- +------------------------------------------------------------------ A variety of issues regarding :func:`.column_property` have been fixed, most specifically with regards to the :func:`.aliased` construct as well @@ -583,7 +583,7 @@ New Features and Improvements - Core .. _feature_3034: Select/Query LIMIT / OFFSET may be specified as an arbitrary SQL expression ----------------------------------------------------------------------------- +--------------------------------------------------------------------------- The :meth:`.Select.limit` and :meth:`.Select.offset` methods now accept any SQL expression, in addition to integer values, as arguments. The ORM @@ -826,7 +826,7 @@ the :class:`.Constraint` is constructed:: .. _feature_insert_from_select_defaults: INSERT FROM SELECT now includes Python and SQL-expression defaults -------------------------------------------------------------------- +------------------------------------------------------------------ :meth:`.Insert.from_select` now includes Python and SQL-expression defaults if otherwise unspecified; the limitation where non-server column defaults @@ -1354,7 +1354,7 @@ joined loader options can still be used:: .. _bug_3233: Changes and fixes in handling of duplicate join targets --------------------------------------------------------- +------------------------------------------------------- Changes here encompass bugs where an unexpected and inconsistent behavior would occur in some scenarios when joining to an entity @@ -2155,7 +2155,7 @@ state. .. _feature_3084: MetaData.sorted_tables accessor is "deterministic" ------------------------------------------------------ +-------------------------------------------------- The sorting of tables resulting from the :attr:`.MetaData.sorted_tables` accessor is "deterministic"; the ordering should be the same in all cases @@ -2264,7 +2264,7 @@ flag:: :ticket:`3319` New PostgreSQL Table options ------------------------------ +---------------------------- Added support for PG table options TABLESPACE, ON COMMIT, WITH(OUT) OIDS, and INHERITS, when rendering DDL via @@ -2398,14 +2398,14 @@ by PostgreSQL as of 9.4. SQLAlchemy allows this using :class:`.FunctionFilter` PG8000 dialect supports client side encoding ---------------------------------------------- +-------------------------------------------- The :paramref:`.create_engine.encoding` parameter is now honored by the pg8000 dialect, using on connect handler which emits ``SET CLIENT_ENCODING`` matching the selected encoding. PG8000 native JSONB support --------------------------------------- +--------------------------- Support for PG8000 versions greater than 1.10.1 has been added, where JSONB is supported natively. @@ -2421,12 +2421,12 @@ Support for the pypy psycopg2cffi dialect is added. :mod:`sqlalchemy.dialects.postgresql.psycopg2cffi` Dialect Improvements and Changes - MySQL -============================================= +======================================== .. _change_3155: MySQL TIMESTAMP Type now renders NULL / NOT NULL in all cases --------------------------------------------------------------- +------------------------------------------------------------- The MySQL dialect has always worked around MySQL's implicit NOT NULL default associated with TIMESTAMP columns by emitting NULL for @@ -2449,7 +2449,7 @@ columns. .. _change_3283: MySQL SET Type Overhauled to support empty sets, unicode, blank value handling -------------------------------------------------------------------------------- +------------------------------------------------------------------------------ The :class:`.mysql.SET` type historically not included a system of handling blank sets and empty values separately; as different drivers had different @@ -2582,7 +2582,7 @@ and is generally in decent working order, if someone wants to pick up on polishing it. Dialect Improvements and Changes - SQLite -============================================= +========================================= SQLite named and unnamed UNIQUE and FOREIGN KEY constraints will inspect and reflect ------------------------------------------------------------------------------------- @@ -2632,7 +2632,7 @@ to control the behavior completely, based on deprecation guidelines from Microsoft. See :ref:`mssql_large_type_deprecation` for details. Dialect Improvements and Changes - Oracle -============================================= +========================================= .. _change_3220: @@ -2653,7 +2653,7 @@ CTE support has been fixed up for Oracle, and there is also a new feature :ticket:`3220` New Oracle Keywords for DDL ------------------------------ +--------------------------- Keywords such as COMPRESS, ON COMMIT, BITMAP: diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst index b3f8cb1055..c790e46411 100644 --- a/doc/build/changelog/migration_11.rst +++ b/doc/build/changelog/migration_11.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 1.1? -============================== +============================= .. admonition:: About this Document @@ -32,7 +32,7 @@ as things like "extras", ``setup.py`` now depends on Setuptools fully. .. seealso:: - :ref:`installation` + :ref:`installation` :ticket:`3489` @@ -47,7 +47,7 @@ as it relies on deprecated features of setuptools. .. seealso:: - :ref:`c_extensions` + :ref:`c_extensions` :ticket:`3500` @@ -625,7 +625,7 @@ for an attribute being replaced. .. _change_3749: Same-named relationships on inheriting mappers no longer warn --------------------------------------------------------------- +------------------------------------------------------------- When creating two mappers in an inheritance scenario, placing a relationship on both with the same name would emit the warning @@ -1220,7 +1220,7 @@ RANGE and ROWS expressions for window functions:: .. _change_2857: Support for the SQL LATERAL keyword ------------------------------------- +----------------------------------- The LATERAL keyword is currently known to only be supported by PostgreSQL 9.3 and greater, however as it is part of the SQL standard support for this keyword @@ -1378,7 +1378,7 @@ will not have much impact on the behavior of the column during an INSERT. .. _change_is_distinct_from: Support for IS DISTINCT FROM and IS NOT DISTINCT FROM ------------------------------------------------------- +----------------------------------------------------- New operators :meth:`.ColumnOperators.is_distinct_from` and :meth:`.ColumnOperators.isnot_distinct_from` allow the IS DISTINCT @@ -1533,7 +1533,7 @@ used for the fetch. .. _change_3292: Support for Python's native ``enum`` type and compatible forms ---------------------------------------------------------------- +-------------------------------------------------------------- The :class:`.Enum` type can now be constructed using any PEP-435 compliant enumerated type. When using this mode, input values @@ -1562,7 +1562,7 @@ string/integer/etc values:: assert e.scalar(t.select()) is MyEnum.two The ``Enum.enums`` collection is now a list instead of a tuple -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As part of the changes to :class:`.Enum`, the :attr:`.Enum.enums` collection of elements is now a list instead of a tuple. This because lists @@ -2444,7 +2444,7 @@ in order to have an array value present in a composed ORM row. .. _change_3503: Correct SQL Types are Established from Indexed Access of ARRAY, JSON, HSTORE ------------------------------------------------------------------------------ +---------------------------------------------------------------------------- For all three of :class:`~.postgresql.ARRAY`, :class:`~.postgresql.JSON` and :class:`.HSTORE`, the SQL type assigned to the expression returned by indexed access, e.g. @@ -2495,7 +2495,7 @@ This includes: .. _change_3503_cast: The JSON cast() operation now requires ``.astext`` is called explicitly ------------------------------------------------------------------------- +----------------------------------------------------------------------- As part of the changes in :ref:`change_3503`, the workings of the :meth:`.ColumnElement.cast` operator on :class:`.postgresql.JSON` and @@ -2596,7 +2596,7 @@ The `PyGreSQL `_ DBAPI is now supported. :ref:`dialect-postgresql-pygresql` The "postgres" module is removed ---------------------------------- +-------------------------------- The ``sqlalchemy.dialects.postgres`` module, long deprecated, is removed; this has emitted a warning for many years and projects @@ -2625,7 +2625,7 @@ or "SELECT...FOR SHARE" query on the PostgreSQL backend: stmt = select([table]).with_for_update(read=True, key_share=True) Dialect Improvements and Changes - MySQL -============================================= +======================================== .. _change_3547: @@ -2732,7 +2732,7 @@ directives are no longer needed:: Dialect Improvements and Changes - SQLite -============================================= +========================================= .. _change_3634: @@ -2797,7 +2797,7 @@ given schema in the results. Cross-schema foreign keys aren't supported. .. _change_3629: Reflection of the name of PRIMARY KEY constraints --------------------------------------------------- +------------------------------------------------- The SQLite backend now takes advantage of the "sqlite_master" view of SQLite in order to extract the name of the primary key constraint @@ -2932,7 +2932,7 @@ on this behavior, set the flag back to True. :ticket:`3434` Dialect Improvements and Changes - Oracle -============================================= +========================================= Support for SKIP LOCKED ----------------------- diff --git a/doc/build/core/api_basics.rst b/doc/build/core/api_basics.rst index e56a1117b3..a7b6e2edec 100644 --- a/doc/build/core/api_basics.rst +++ b/doc/build/core/api_basics.rst @@ -1,6 +1,6 @@ -================= +=============== Core API Basics -================= +=============== .. toctree:: :maxdepth: 2 diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 5cdc5a3ddc..29e884396e 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -1,8 +1,8 @@ .. _connections_toplevel: -===================================== +==================================== Working with Engines and Connections -===================================== +==================================== .. module:: sqlalchemy.engine @@ -148,7 +148,7 @@ is available as well:: .. _connections_nested_transactions: Nesting of Transaction Blocks ------------------------------- +----------------------------- The :class:`.Transaction` object also handles "nested" behavior by keeping track of the outermost begin/commit pair. In this example, @@ -241,7 +241,7 @@ it so that a SELECT statement will issue a COMMIT:: .. _dbengine_implicit: Connectionless Execution, Implicit Execution -============================================= +============================================ Recall from the first section we mentioned executing with and without explicit usage of :class:`.Connection`. "Connectionless" execution diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst index 88d0036786..ab9eae41f3 100644 --- a/doc/build/core/constraints.rst +++ b/doc/build/core/constraints.rst @@ -3,9 +3,9 @@ .. module:: sqlalchemy.schema -================================= +================================ Defining Constraints and Indexes -================================= +================================ This section will discuss SQL :term:`constraints` and indexes. In SQLAlchemy the key classes include :class:`.ForeignKeyConstraint` and :class:`.Index`. @@ -391,7 +391,7 @@ option of being configured directly:: :class:`.PrimaryKeyConstraint` - detailed API documentation. Setting up Constraints when using the Declarative ORM Extension ----------------------------------------------------------------- +--------------------------------------------------------------- The :class:`.Table` is the SQLAlchemy Core construct that allows one to define table metadata, which among other things can be used by the SQLAlchemy ORM @@ -568,7 +568,7 @@ name as follows:: .. _naming_check_constraints: Naming CHECK Constraints -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ The :class:`.CheckConstraint` object is configured against an arbitrary SQL expression, which can have any number of columns present, and additionally @@ -640,7 +640,7 @@ structure of the expression will determine which column is noted as .. _naming_schematypes: Configuring Naming for Boolean, Enum, and other schema types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :class:`.SchemaType` class refers to type objects such as :class:`.Boolean` and :class:`.Enum` which generate a CHECK constraint accompanying the type. @@ -828,7 +828,7 @@ The :class:`~sqlalchemy.schema.Index` object also supports its own ``create()`` .. _schema_indexes_functional: Functional Indexes -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ :class:`.Index` supports SQL and function expressions, as supported by the target backend. To create an index against a column using a descending diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst index f47640c927..64f91b23fc 100644 --- a/doc/build/core/custom_types.rst +++ b/doc/build/core/custom_types.rst @@ -166,7 +166,7 @@ binary in CHAR(16) if desired:: return uuid.UUID(value) Marshal JSON Strings -^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ This type uses ``simplejson`` to marshal Python data structures to/from JSON. Can be modified to use Python's builtin json encoder:: diff --git a/doc/build/core/ddl.rst b/doc/build/core/ddl.rst index 76692226e3..db0905d726 100644 --- a/doc/build/core/ddl.rst +++ b/doc/build/core/ddl.rst @@ -132,7 +132,7 @@ first looking within the PostgreSQL catalogs to see if it exists: DROP TABLE users{stop} Using the built-in DDLElement Classes --------------------------------------- +------------------------------------- The ``sqlalchemy.schema`` package contains SQL expression constructs that provide DDL expressions. For example, to produce a ``CREATE TABLE`` statement: diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index bb6699cc62..f6cf4f4b3a 100644 --- a/doc/build/core/defaults.rst +++ b/doc/build/core/defaults.rst @@ -5,7 +5,7 @@ .. _metadata_defaults: Column Insert/Update Defaults -============================== +============================= SQLAlchemy provides a very rich featureset regarding column level events which take place during INSERT and UPDATE statements. Options include: @@ -227,7 +227,7 @@ the database side normally. .. _triggered_columns: Triggered Columns ------------------- +----------------- Columns with values set by a database trigger or other external process may be called out using :class:`.FetchedValue` as a marker:: @@ -273,7 +273,7 @@ rows should be performed after an insert or update. Defining Sequences -------------------- +------------------ SQLAlchemy represents database sequences using the :class:`~sqlalchemy.schema.Sequence` object, which is considered to be a diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index f429ba561f..dc5a8c996b 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -42,7 +42,7 @@ applications. .. _supported_dbapis: Supported Databases -==================== +=================== SQLAlchemy includes many :class:`.Dialect` implementations for various backends. Dialects for the most common databases are included with SQLAlchemy; a handful @@ -212,7 +212,7 @@ For more information on connection pooling, see :ref:`pooling_toplevel`. .. _custom_dbapi_args: Custom DBAPI connect() arguments -================================= +================================ Custom arguments used when issuing the ``connect()`` call to the underlying DBAPI may be issued in three distinct ways. String-based arguments can be @@ -246,7 +246,7 @@ argument, which specifies a callable that returns a DBAPI connection: .. _dbengine_logging: Configuring Logging -==================== +=================== Python's standard `logging `_ module is used to diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst index edc16e6035..018a46cd7d 100644 --- a/doc/build/core/event.rst +++ b/doc/build/core/event.rst @@ -117,7 +117,7 @@ and objects:: listen(my_engine, 'connect', my_on_connect) Modifiers ----------- +--------- Some listeners allow modifiers to be passed to :func:`.listen`. These modifiers sometimes provide alternate calling signatures for @@ -136,7 +136,7 @@ this value can be supported:: listen(UserContact.phone, 'set', validate_phone, retval=True) Event Reference ----------------- +--------------- Both SQLAlchemy Core and SQLAlchemy ORM feature a wide variety of event hooks: diff --git a/doc/build/core/events.rst b/doc/build/core/events.rst index 451cb9460c..1dc56b053b 100644 --- a/doc/build/core/events.rst +++ b/doc/build/core/events.rst @@ -1,7 +1,7 @@ .. _core_event_toplevel: Core Events -============ +=========== This section describes the event interfaces provided in SQLAlchemy Core. @@ -12,13 +12,13 @@ ORM events are described in :ref:`orm_event_toplevel`. :members: Connection Pool Events ------------------------ +---------------------- .. autoclass:: sqlalchemy.events.PoolEvents :members: SQL Execution and Connection Events ------------------------------------- +----------------------------------- .. autoclass:: sqlalchemy.events.ConnectionEvents :members: @@ -27,7 +27,7 @@ SQL Execution and Connection Events :members: Schema Events ------------------------ +------------- .. autoclass:: sqlalchemy.events.DDLEvents :members: diff --git a/doc/build/core/interfaces.rst b/doc/build/core/interfaces.rst index 7e76127f4d..706db625ee 100644 --- a/doc/build/core/interfaces.rst +++ b/doc/build/core/interfaces.rst @@ -1,7 +1,7 @@ .. _dep_interfaces_core_toplevel: Deprecated Event Interfaces -============================ +=========================== .. module:: sqlalchemy.interfaces diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst index 1e762b188e..21f1014545 100644 --- a/doc/build/core/metadata.rst +++ b/doc/build/core/metadata.rst @@ -256,7 +256,7 @@ There are two major migration tools available for SQLAlchemy: Specifying the Schema Name ---------------------------- +-------------------------- Some databases support the concept of multiple schemas. A :class:`~sqlalchemy.schema.Table` can reference this by specifying the diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index 65b5ca9cd0..8716a81096 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -102,7 +102,7 @@ a last resort for when a DBAPI has some form of ``connect`` that is not at all supported by SQLAlchemy. Constructing a Pool ------------------------- +------------------- To use a :class:`.Pool` by itself, the ``creator`` function is the only argument that's required and is passed first, followed @@ -171,7 +171,7 @@ when the database server has been restarted, and all previously established conn are no longer functional. There are two approaches to this. Disconnect Handling - Optimistic -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The most common approach is to let SQLAlchemy handle disconnects as they occur, at which point the pool is refreshed. This assumes the :class:`.Pool` @@ -212,7 +212,7 @@ database restarts are not anticipated. .. _pool_setting_recycle: Setting Pool Recycle -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~ An additional setting that can augment the "optimistic" approach is to set the pool recycle parameter. This parameter prevents the pool from using a particular @@ -231,7 +231,7 @@ of the :class:`.Pool` itself, independent of whether or not an :class:`.Engine` .. _pool_disconnects_pessimistic: Disconnect Handling - Pessimistic -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ At the expense of some extra SQL emitted for each connection checked out from the pool, a "ping" operation established by a checkout event handler can @@ -419,7 +419,7 @@ coercing the pool to recycle the connection record to make a new connection. API Documentation - Available Pool Implementations ---------------------------------------------------- +-------------------------------------------------- .. autoclass:: sqlalchemy.pool.Pool diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst index ca1e3bf20c..139f4df7ee 100644 --- a/doc/build/core/reflection.rst +++ b/doc/build/core/reflection.rst @@ -55,7 +55,7 @@ hasn't already been loaded; once loaded, new calls to reflection queries. Overriding Reflected Columns ------------------------------ +---------------------------- Individual columns can be overridden with explicit values when reflecting tables; this is handy for specifying custom datatypes, constraints such as @@ -67,7 +67,7 @@ primary keys that may not be configured within the database, etc.:: ... autoload=True) Reflecting Views ------------------ +---------------- The reflection system can also reflect views. Basic usage is the same as that of a table:: diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index f42f54039b..1628987d3c 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -100,7 +100,7 @@ database, which is then used to emit the SQL. connecting to several kinds of databases with links to more information. Define and Create Tables -========================= +======================== The SQL Expression Language constructs its expressions in most cases against table columns. In SQLAlchemy, a column is most often represented by an object @@ -244,7 +244,7 @@ compiled form of the statement:: {'fullname': 'Jack Jones', 'name': 'jack'} Executing -========== +========= The interesting part of an :class:`~sqlalchemy.sql.expression.Insert` is executing it. In this tutorial, we will generally focus on the most explicit @@ -311,7 +311,7 @@ function, to using ``INSERT..RETURNING`` syntax; this all occurs transparently. .. _execute_multiple: Executing Multiple Statements -============================== +============================= Our insert example above was intentionally a little drawn out to show some various behaviors of expression language constructs. In the usual case, an @@ -372,7 +372,7 @@ The "executemany" style of invocation is available for each of the .. _coretutorial_selecting: Selecting -========== +========= We began with inserts just so that our test database had some data in it. The more interesting part of the data is selecting it! We'll cover UPDATE and @@ -542,7 +542,7 @@ are working with is ultimately the same type of object. SQLAlchemy terms the base class of all of these expressions as :class:`~.expression.ColumnElement`. Operators -========== +========= Since we've stumbled upon SQLAlchemy's operator paradigm, let's go through some of its capabilities. We've seen how to equate two columns to each other: @@ -631,7 +631,7 @@ This function can also be used to make bitwise operators explicit. For example:: is a bitwise AND of the value in `somecolumn`. Operator Customization ------------------------ +---------------------- While :meth:`.ColumnOperators.op` is handy to get at a custom operator in a hurry, the Core supports fundamental customization and extension of the operator system at @@ -643,7 +643,7 @@ for a description. Conjunctions -============= +============ We'd like to show off some of our operators inside of :func:`.select` @@ -794,7 +794,7 @@ parameters, we passed them into the :meth:`~.Connection.execute` method as additional arguments. Specifying Bound Parameter Behaviors ------------------------------------------- +------------------------------------ The :func:`~.expression.text` construct supports pre-established bound values using the :meth:`.TextClause.bindparams` method:: @@ -817,7 +817,7 @@ or special SQL-side processing provided by the datatype. .. _sqlexpression_text_columns: Specifying Result-Column Behaviors ----------------------------------------------- +---------------------------------- We may also specify information about the result columns using the :meth:`.TextClause.columns` method; this method can be used to specify @@ -1067,7 +1067,7 @@ by a column name that appears more than once: Using Aliases -============== +============= The alias in SQL corresponds to a "renamed" version of a table or SELECT statement, which occurs anytime you say "SELECT .. FROM sometable AS @@ -1145,7 +1145,7 @@ to "correlate" the inner ``users`` table with the outer one: {stop}[(u'jack',)] Using Joins -============ +=========== We're halfway along to being able to construct any SELECT expression. The next cornerstone of the SELECT is the JOIN expression. We've already been doing @@ -1231,7 +1231,7 @@ Oracle DBAs don't want their black magic being found out ;). :class:`.Join` Everything Else -================ +=============== The concepts of creating SQL expressions have been introduced. What's left are more variants of the same themes. So now we'll catalog the rest of the @@ -1412,7 +1412,7 @@ of our selectable: .. _window_functions: Window Functions ------------------ +---------------- Any :class:`.FunctionElement`, including functions generated by :data:`~.expression.func`, can be turned into a "window function", that is an @@ -2046,7 +2046,7 @@ by the database if this syntax is not supported. .. _updates_order_parameters: Parameter-Ordered Updates --------------------------- +------------------------- The default behavior of the :func:`.update` construct when rendering the SET clauses is to render them using the column ordering given in the @@ -2131,7 +2131,7 @@ The value is available as :attr:`~.ResultProxy.rowcount`: 1 Further Reference -================== +================= Expression Language Reference: :ref:`expression_api_toplevel` diff --git a/doc/build/core/type_api.rst b/doc/build/core/type_api.rst index 7f0b68b64b..f165df5a26 100644 --- a/doc/build/core/type_api.rst +++ b/doc/build/core/type_api.rst @@ -3,7 +3,7 @@ .. _types_api: Base Type API --------------- +------------- .. autoclass:: TypeEngine :members: diff --git a/doc/build/dialects/index.rst b/doc/build/dialects/index.rst index c5d239b67f..b120d83eb1 100644 --- a/doc/build/dialects/index.rst +++ b/doc/build/dialects/index.rst @@ -59,7 +59,7 @@ Production Ready on top of `pythone-tds `_. Experimental / Incomplete -^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^ Dialects that are in an incomplete state or are considered somewhat experimental. diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst index 6173ffba19..490ecaccf5 100644 --- a/doc/build/dialects/mssql.rst +++ b/doc/build/dialects/mssql.rst @@ -6,7 +6,7 @@ Microsoft SQL Server .. automodule:: sqlalchemy.dialects.mssql.base SQL Server Data Types ------------------------ +--------------------- As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with SQL server are importable from the top level dialect, whether @@ -110,7 +110,7 @@ pymssql .. automodule:: sqlalchemy.dialects.mssql.pymssql zxjdbc --------------- +------ .. automodule:: sqlalchemy.dialects.mssql.zxjdbc diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst index 100f2d2e34..ebfc8a31cc 100644 --- a/doc/build/dialects/mysql.rst +++ b/doc/build/dialects/mysql.rst @@ -6,7 +6,7 @@ MySQL .. automodule:: sqlalchemy.dialects.mysql.base MySQL Data Types ------------------- +---------------- As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with MySQL are importable from the top level dialect:: @@ -158,32 +158,32 @@ construction arguments, are as follows: MySQL-Python --------------------- +------------ .. automodule:: sqlalchemy.dialects.mysql.mysqldb pymysql -------------- +------- .. automodule:: sqlalchemy.dialects.mysql.pymysql MySQL-Connector ----------------------- +--------------- .. automodule:: sqlalchemy.dialects.mysql.mysqlconnector cymysql ------------- +------- .. automodule:: sqlalchemy.dialects.mysql.cymysql OurSQL --------------- +------ .. automodule:: sqlalchemy.dialects.mysql.oursql Google App Engine ------------------------ +----------------- .. automodule:: sqlalchemy.dialects.mysql.gaerdbms @@ -193,6 +193,6 @@ pyodbc .. automodule:: sqlalchemy.dialects.mysql.pyodbc zxjdbc --------------- +------ .. automodule:: sqlalchemy.dialects.mysql.zxjdbc diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst index 4b4de3d4c6..f8e9f891ae 100644 --- a/doc/build/dialects/oracle.rst +++ b/doc/build/dialects/oracle.rst @@ -6,7 +6,7 @@ Oracle .. automodule:: sqlalchemy.dialects.oracle.base Oracle Data Types -------------------- +----------------- As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with Oracle are importable from the top level dialect, whether @@ -54,11 +54,11 @@ construction arguments, are as follows: cx_Oracle ----------- +--------- .. automodule:: sqlalchemy.dialects.oracle.cx_oracle zxjdbc -------- +------ .. automodule:: sqlalchemy.dialects.oracle.zxjdbc diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index 38b2e47411..03511b0474 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -6,7 +6,7 @@ PostgreSQL .. automodule:: sqlalchemy.dialects.postgresql.base PostgreSQL Data Types ------------------------- +--------------------- As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with PostgreSQL are importable from the top level dialect, whether @@ -182,7 +182,7 @@ For example:: ) PostgreSQL DML Constructs ---------------------------- +------------------------- .. autofunction:: sqlalchemy.dialects.postgresql.dml.insert diff --git a/doc/build/dialects/sqlite.rst b/doc/build/dialects/sqlite.rst index 93a54ee8d7..936ae253f1 100644 --- a/doc/build/dialects/sqlite.rst +++ b/doc/build/dialects/sqlite.rst @@ -6,7 +6,7 @@ SQLite .. automodule:: sqlalchemy.dialects.sqlite.base SQLite Data Types ------------------------- +----------------- As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with SQLite are importable from the top level dialect, whether diff --git a/doc/build/dialects/sybase.rst b/doc/build/dialects/sybase.rst index 8e9695325a..835e295fcf 100644 --- a/doc/build/dialects/sybase.rst +++ b/doc/build/dialects/sybase.rst @@ -6,17 +6,17 @@ Sybase .. automodule:: sqlalchemy.dialects.sybase.base python-sybase -------------------- +------------- .. automodule:: sqlalchemy.dialects.sybase.pysybase pyodbc ------------- +------ .. automodule:: sqlalchemy.dialects.sybase.pyodbc mxodbc ------------- +------ .. automodule:: sqlalchemy.dialects.sybase.mxodbc diff --git a/doc/build/faq/connections.rst b/doc/build/faq/connections.rst index 7e763d288c..d2e33f3c57 100644 --- a/doc/build/faq/connections.rst +++ b/doc/build/faq/connections.rst @@ -22,7 +22,7 @@ refers to a :class:`.QueuePool` as a source of connectivity. For more detail, see :ref:`engines_toplevel` and :ref:`pooling_toplevel`. How do I pass custom connect arguments to my database API? ------------------------------------------------------------ +---------------------------------------------------------- The :func:`.create_engine` call accepts additional arguments either directly via the ``connect_args`` keyword argument:: @@ -56,7 +56,7 @@ on how :class:`.Session` should be used in a multithreaded environment, see :ref:`session_faq_threadsafe`. Why does SQLAlchemy issue so many ROLLBACKs? ---------------------------------------------- +-------------------------------------------- SQLAlchemy currently assumes DBAPI connections are in "non-autocommit" mode - this is the default behavior of the Python database API, meaning it @@ -74,7 +74,7 @@ isolation. For background on why you might see stale data even on MySQL, see http://dev.mysql.com/doc/refman/5.1/en/innodb-transaction-model.html I'm on MyISAM - how do I turn it off? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The behavior of the connection pool's connection return behavior can be configured using ``reset_on_return``:: @@ -85,7 +85,7 @@ configured using ``reset_on_return``:: engine = create_engine('mysql://scott:tiger@localhost/myisam_database', pool=QueuePool(reset_on_return=False)) I'm on SQL Server - how do I turn those ROLLBACKs into COMMITs? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``reset_on_return`` accepts the values ``commit``, ``rollback`` in addition to ``True``, ``False``, and ``None``. Setting to ``commit`` will cause diff --git a/doc/build/faq/index.rst b/doc/build/faq/index.rst index 120e0ba3a2..5961226ce4 100644 --- a/doc/build/faq/index.rst +++ b/doc/build/faq/index.rst @@ -1,8 +1,8 @@ .. _faq_toplevel: -============================ +========================== Frequently Asked Questions -============================ +========================== The Frequently Asked Questions section is a growing collection of commonly observed questions to well-known issues. diff --git a/doc/build/faq/metadata_schema.rst b/doc/build/faq/metadata_schema.rst index 7e4a557202..8220768546 100644 --- a/doc/build/faq/metadata_schema.rst +++ b/doc/build/faq/metadata_schema.rst @@ -1,6 +1,6 @@ -================== +================= MetaData / Schema -================== +================= .. contents:: :local: @@ -56,7 +56,7 @@ A more comprehensive option is to use schema migration tools, such as Alembic or SQLAlchemy-Migrate; see :ref:`schema_migrations` for discussion on this. How can I sort Table objects in order of their dependency? -=========================================================================== +========================================================== This is available via the :attr:`.MetaData.sorted_tables` function:: @@ -67,7 +67,7 @@ This is available via the :attr:`.MetaData.sorted_tables` function:: print(t) How can I get the CREATE TABLE/ DROP TABLE output as a string? -=========================================================================== +============================================================== Modern SQLAlchemy has clause constructs which represent DDL operations. These can be rendered to strings like any other SQL expression:: @@ -92,7 +92,7 @@ The `Alembic `_ tool also supports an "offline" SQL generation mode that renders database migrations as SQL scripts. How can I subclass Table/Column to provide certain behaviors/configurations? -============================================================================= +============================================================================ :class:`.Table` and :class:`.Column` are not good targets for direct subclassing. However, there are simple ways to get on-construction behaviors using creation diff --git a/doc/build/faq/ormconfiguration.rst b/doc/build/faq/ormconfiguration.rst index 5baa5effe5..d545574b24 100644 --- a/doc/build/faq/ormconfiguration.rst +++ b/doc/build/faq/ormconfiguration.rst @@ -1,5 +1,5 @@ ORM Configuration -================== +================= .. contents:: :local: @@ -72,7 +72,7 @@ columns:: How do I configure a Column that is a Python reserved word or similar? ----------------------------------------------------------------------------- +---------------------------------------------------------------------- Column-based attributes can be given any name desired in the mapping. See :ref:`mapper_column_distinct_names`. diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index 3b76c83264..7067050db1 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -17,7 +17,7 @@ Looking for performance issues typically involves two stratgies. One is query profiling, and the other is code profiling. Query Profiling -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ Sometimes just plain SQL logging (enabled via python's logging module or via the ``echo=True`` argument on :func:`.create_engine`) can give an @@ -154,7 +154,7 @@ analysis of the query plan is warranted, using a system such as EXPLAIN, SHOW PLAN, etc. as is provided by the database backend. Result Fetching Slowness - Core -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If on the other hand you see many thousands of calls related to fetching rows, or very long calls to ``fetchall()``, it may @@ -223,7 +223,7 @@ that could indicate that everything is fast except for the actual network connec and too much time is spent with data moving over the network. Result Fetching Slowness - ORM -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To detect slowness in ORM fetching of rows (which is the most common area of performance concern), calls like ``populate_state()`` and ``_instance()`` will @@ -269,7 +269,7 @@ practice they are very easy to read. with bundled profiling capabilities. I'm inserting 400,000 rows with the ORM and it's really slow! --------------------------------------------------------------- +------------------------------------------------------------- The SQLAlchemy ORM uses the :term:`unit of work` pattern when synchronizing changes to the database. This pattern goes far beyond simple "inserts" diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index f7247aa210..2daba29698 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -1,5 +1,5 @@ Sessions / Queries -=================== +================== .. contents:: :local: @@ -135,7 +135,7 @@ For a detailed discussion on how to organize usage of the :class:`.Session`, please see :ref:`session_faq_whentocreate`. But why does flush() insist on issuing a ROLLBACK? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It would be great if :meth:`.Session.flush` could partially complete and then not roll back, however this is beyond its current capabilities since its internal @@ -297,7 +297,7 @@ output:: LEN! How Do I use Textual SQL with ORM Queries? -------------------------------------------- +------------------------------------------ See: @@ -316,7 +316,7 @@ why isn't my ``__init__()`` called when I load objects? See :ref:`mapping_constructors` for a description of this behavior. how do I use ON DELETE CASCADE with SA's ORM? ----------------------------------------------- +--------------------------------------------- SQLAlchemy will always issue UPDATE or DELETE statements for dependent rows which are currently loaded in the :class:`.Session`. For rows which diff --git a/doc/build/faq/sqlexpressions.rst b/doc/build/faq/sqlexpressions.rst index c3504218b1..604a138ebc 100644 --- a/doc/build/faq/sqlexpressions.rst +++ b/doc/build/faq/sqlexpressions.rst @@ -1,5 +1,5 @@ SQL Expressions -================= +=============== .. contents:: :local: diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst index 1165d7fa9a..116fb74eec 100644 --- a/doc/build/orm/backref.rst +++ b/doc/build/orm/backref.rst @@ -105,7 +105,7 @@ exactly the same as if the above two relationships were created individually using :paramref:`~.relationship.back_populates` on each. Backref Arguments -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ We've established that the :paramref:`~.relationship.backref` keyword is merely a shortcut for building two individual :func:`.relationship` constructs that refer to each other. Part of @@ -187,7 +187,7 @@ it into a form that is interpreted by the receiving :func:`.relationship` as add arguments to be applied to the new relationship it creates. One Way Backrefs -~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ An unusual case is that of the "one way backref". This is where the "back-populating" behavior of the backref is only desirable in one diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst index cd6389ab7e..6a121be9fd 100644 --- a/doc/build/orm/basic_relationships.rst +++ b/doc/build/orm/basic_relationships.rst @@ -1,7 +1,7 @@ .. _relationship_patterns: Basic Relationship Patterns ----------------------------- +--------------------------- A quick walkthrough of the basic relational patterns. @@ -15,7 +15,7 @@ The imports used for each of the following sections is as follows:: One To Many -~~~~~~~~~~~~ +~~~~~~~~~~~ A one to many relationship places a foreign key on the child table referencing the parent. :func:`.relationship` is then specified on the parent, as referencing @@ -59,7 +59,7 @@ on a single :func:`.relationship` instead of using Many To One -~~~~~~~~~~~~ +~~~~~~~~~~~ Many to one places a foreign key in the parent table referencing the child. :func:`.relationship` is declared on the parent, where a new scalar-holding @@ -102,7 +102,7 @@ may be applied to a single :func:`.relationship`, such as ``Parent.child``:: .. _relationships_one_to_one: One To One -~~~~~~~~~~~ +~~~~~~~~~~ One To One is essentially a bidirectional relationship with a scalar attribute on both sides. To achieve this, the :paramref:`~.relationship.uselist` flag indicates @@ -149,7 +149,7 @@ to specify ``uselist`` on a backref, use the :func:`.backref` function:: .. _relationships_many_to_many: Many To Many -~~~~~~~~~~~~~ +~~~~~~~~~~~~ Many to Many adds an association table between two classes. The association table is indicated by the :paramref:`~.relationship.secondary` argument to diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index 53ac9e3ce4..abd9699336 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -16,7 +16,7 @@ and techniques. .. currentmodule:: sqlalchemy.orm Working with Large Collections -=============================== +============================== The default behavior of :func:`.relationship` is to fully load the collection of items in, as according to the loading strategy of the @@ -31,7 +31,7 @@ loading of child items both at load time as well as deletion time. .. _dynamic_relationship: Dynamic Relationship Loaders ------------------------------ +---------------------------- A key feature to enable management of a large collection is the so-called "dynamic" relationship. This is an optional form of :func:`~sqlalchemy.orm.relationship` which @@ -140,7 +140,7 @@ loader option. .. _passive_deletes: Using Passive Deletes ----------------------- +--------------------- Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database @@ -222,7 +222,7 @@ default list, by specifying the :paramref:`~.relationship.collection_class` opti assert child in parent.children Dictionary Collections ------------------------ +---------------------- A little extra detail is needed when using a dictionary as a collection. This because objects are always loaded from the database as lists, and a key-generation @@ -350,7 +350,7 @@ for examples. .. autofunction:: mapped_collection Custom Collection Implementations -================================== +================================= You can use your own types for collections as well. In simple cases, inherting from ``list`` or ``set``, adding custom behavior, is all that's needed. @@ -454,7 +454,7 @@ collections. Use them when your class doesn't quite meet the regular interface for its container type, or when you otherwise would like to use a different method to get the job done. -.. sourcecode:: python+sql +.. sourcecode:: python from sqlalchemy.orm.collections import collection @@ -599,7 +599,7 @@ The ORM uses this approach for built-ins, quietly substituting a trivial subclass when a ``list``, ``set`` or ``dict`` is used directly. Collection Internals -===================== +==================== Various internal methods. diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst index b18cedb31e..43521ac991 100644 --- a/doc/build/orm/composites.rst +++ b/doc/build/orm/composites.rst @@ -3,7 +3,7 @@ .. _mapper_composite: Composite Column Types -======================= +====================== Sets of columns can be associated with a single user-defined datatype. The ORM provides a single attribute which represents the group of columns using the diff --git a/doc/build/orm/constructors.rst b/doc/build/orm/constructors.rst index 38cbb41820..637afccb7b 100644 --- a/doc/build/orm/constructors.rst +++ b/doc/build/orm/constructors.rst @@ -3,7 +3,7 @@ .. _mapping_constructors: Constructors and Object Initialization -======================================= +====================================== Mapping imposes no restrictions or requirements on the constructor (``__init__``) method for the class. You are free to require any arguments for diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst index cadfe8e050..fd55846220 100644 --- a/doc/build/orm/contextual.rst +++ b/doc/build/orm/contextual.rst @@ -1,7 +1,7 @@ .. _unitofwork_contextual: Contextual/Thread-local Sessions -================================= +================================ Recall from the section :ref:`session_faq_whentocreate`, the concept of "session scopes" was introduced, with an emphasis on web applications diff --git a/doc/build/orm/deprecated.rst b/doc/build/orm/deprecated.rst index 8d277011c4..088705a0e6 100644 --- a/doc/build/orm/deprecated.rst +++ b/doc/build/orm/deprecated.rst @@ -3,7 +3,7 @@ .. _dep_interfaces_orm_toplevel: Deprecated ORM Event Interfaces -================================ +=============================== .. module:: sqlalchemy.orm.interfaces @@ -17,19 +17,19 @@ until SQLAlchemy 0.5. The non-ORM analogue is described at :ref:`dep_interfaces a consistent interface to all events without the need for subclassing. Mapper Events ------------------ +------------- .. autoclass:: MapperExtension :members: Session Events ------------------ +-------------- .. autoclass:: SessionExtension :members: Attribute Events --------------------- +---------------- .. autoclass:: AttributeExtension :members: diff --git a/doc/build/orm/events.rst b/doc/build/orm/events.rst index 470a9386bb..d373f253ee 100644 --- a/doc/build/orm/events.rst +++ b/doc/build/orm/events.rst @@ -17,7 +17,7 @@ Attribute Events :members: Mapper Events ---------------- +------------- .. autoclass:: sqlalchemy.orm.events.MapperEvents :members: @@ -35,13 +35,13 @@ Session Events :members: Query Events -------------- +------------ .. autoclass:: sqlalchemy.orm.events.QueryEvents :members: Instrumentation Events ------------------------ +---------------------- .. automodule:: sqlalchemy.orm.instrumentation diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst index 1a0007ca7e..76afab26f1 100644 --- a/doc/build/orm/examples.rst +++ b/doc/build/orm/examples.rst @@ -36,19 +36,19 @@ Directed Graphs .. automodule:: examples.graphs Dynamic Relations as Dictionaries ------------------------------------- +--------------------------------- .. automodule:: examples.dynamic_dict .. _examples_generic_associations: Generic Associations ------------------------- +-------------------- .. automodule:: examples.generic_associations Large Collections ------------------------- +----------------- .. automodule:: examples.large_collection @@ -58,7 +58,7 @@ Materialized Paths .. automodule:: examples.materialized_paths Nested Sets ------------- +----------- .. automodule:: examples.nested_sets @@ -79,12 +79,12 @@ Relationship Join Conditions .. _examples_xmlpersistence: XML Persistence ------------------------- +--------------- .. automodule:: examples.elementtree Versioning Objects ------------------------- +------------------ .. _examples_versioned_history: @@ -101,7 +101,7 @@ Versioning using Temporal Rows .. automodule:: examples.versioned_rows Vertical Attribute Mapping ------------------------------------- +-------------------------- .. automodule:: examples.vertical @@ -109,10 +109,10 @@ Vertical Attribute Mapping .. _examples_inheritance: Inheritance Mapping Recipes -============================ +=========================== Basic Inheritance Mappings ----------------------------------- +-------------------------- .. automodule:: examples.inheritance @@ -122,14 +122,14 @@ Special APIs .. _examples_instrumentation: Attribute Instrumentation ------------------------------------- +------------------------- .. automodule:: examples.custom_attributes .. _examples_sharding: Horizontal Sharding ------------------------- +------------------- .. automodule:: examples.sharding @@ -139,14 +139,14 @@ Extending the ORM .. _examples_caching: Dogpile Caching ------------------------- +--------------- .. automodule:: examples.dogpile_caching .. _examples_postgis: PostGIS Integration ------------------------- +------------------- .. automodule:: examples.postgis diff --git a/doc/build/orm/extending.rst b/doc/build/orm/extending.rst index 4b2b86f621..f20f01c18a 100644 --- a/doc/build/orm/extending.rst +++ b/doc/build/orm/extending.rst @@ -3,10 +3,10 @@ Events and Internals ==================== .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - events - internals - exceptions - deprecated + events + internals + exceptions + deprecated diff --git a/doc/build/orm/extensions/associationproxy.rst b/doc/build/orm/extensions/associationproxy.rst index 7628bc1bdf..18803c75ff 100644 --- a/doc/build/orm/extensions/associationproxy.rst +++ b/doc/build/orm/extensions/associationproxy.rst @@ -114,7 +114,7 @@ or dictionary is taken into account, so that the proxy should act just like the underlying collection or attribute does. Creation of New Values ------------------------ +---------------------- When a list append() event (or set add(), dictionary __setitem__(), or scalar assignment event) is intercepted by the association proxy, it instantiates a @@ -256,7 +256,7 @@ by all these operations:: .. _proxying_dictionaries: Proxying to Dictionary Based Collections ------------------------------------------ +---------------------------------------- The association proxy can proxy to dictionary based collections as well. SQLAlchemy mappings usually use the :func:`.attribute_mapped_collection` collection type to diff --git a/doc/build/orm/extensions/declarative/api.rst b/doc/build/orm/extensions/declarative/api.rst index 67b66a9709..5ef209b75f 100644 --- a/doc/build/orm/extensions/declarative/api.rst +++ b/doc/build/orm/extensions/declarative/api.rst @@ -68,7 +68,7 @@ configuration via the :meth:`.MapperEvents.before_configured` event:: .. _declarative_abstract: ``__abstract__`` -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ ``__abstract__`` causes declarative to skip the production of a table or mapper for the class entirely. A class can be added within a diff --git a/doc/build/orm/extensions/declarative/basic_use.rst b/doc/build/orm/extensions/declarative/basic_use.rst index bc9f913f2e..b23fa4044d 100644 --- a/doc/build/orm/extensions/declarative/basic_use.rst +++ b/doc/build/orm/extensions/declarative/basic_use.rst @@ -69,7 +69,7 @@ so that string-configured :class:`~sqlalchemy.schema.ForeignKey` references can be resolved without issue. Accessing the MetaData -======================= +====================== The :func:`declarative_base` base class contains a :class:`.MetaData` object where newly defined diff --git a/doc/build/orm/extensions/declarative/mixins.rst b/doc/build/orm/extensions/declarative/mixins.rst index 577ed140f4..c401b9bc8f 100644 --- a/doc/build/orm/extensions/declarative/mixins.rst +++ b/doc/build/orm/extensions/declarative/mixins.rst @@ -1,7 +1,7 @@ .. _declarative_mixins: Mixin and Custom Base Classes -============================== +============================= A common need when using :mod:`~sqlalchemy.ext.declarative` is to share some functionality, such as a set of common columns, some common @@ -292,7 +292,7 @@ the :class:`.declared_attr` is invoked:: that will be mapped. Mixing in Association Proxy and Other Attributes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Mixins can specify user-defined attributes as well as other extension units such as :func:`.association_proxy`. The usage of @@ -373,7 +373,7 @@ and ``TypeB`` classes. .. _decl_mixin_inheritance: Controlling table inheritance with mixins -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``__tablename__`` attribute may be used to provide a function that will determine the name of the table used for each class in an inheritance @@ -434,7 +434,7 @@ against the parent:: .. _mixin_inheritance_columns: Mixing in Columns in Inheritance Scenarios -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In constrast to how ``__tablename__`` and other special names are handled when used with :class:`.declared_attr`, when we mix in columns and properties (e.g. diff --git a/doc/build/orm/extensions/declarative/table_config.rst b/doc/build/orm/extensions/declarative/table_config.rst index 9a621e6dd9..f203c55806 100644 --- a/doc/build/orm/extensions/declarative/table_config.rst +++ b/doc/build/orm/extensions/declarative/table_config.rst @@ -38,7 +38,7 @@ specifying the last argument as a dictionary:: ) Using a Hybrid Approach with __table__ -======================================= +====================================== As an alternative to ``__tablename__``, a direct :class:`~sqlalchemy.schema.Table` construct may be used. The diff --git a/doc/build/orm/extensions/indexable.rst b/doc/build/orm/extensions/indexable.rst index 060549a726..8639e5782d 100644 --- a/doc/build/orm/extensions/indexable.rst +++ b/doc/build/orm/extensions/indexable.rst @@ -9,5 +9,5 @@ API Reference ------------- .. autoclass:: sqlalchemy.ext.indexable.index_property - :members: + :members: diff --git a/doc/build/orm/extensions/instrumentation.rst b/doc/build/orm/extensions/instrumentation.rst index 16084e3191..422721ffee 100644 --- a/doc/build/orm/extensions/instrumentation.rst +++ b/doc/build/orm/extensions/instrumentation.rst @@ -1,7 +1,7 @@ .. _instrumentation_toplevel: Alternate Class Instrumentation -================================ +=============================== .. automodule:: sqlalchemy.ext.instrumentation diff --git a/doc/build/orm/extensions/mutable.rst b/doc/build/orm/extensions/mutable.rst index 2ef0a5adbc..3e49b86cb1 100644 --- a/doc/build/orm/extensions/mutable.rst +++ b/doc/build/orm/extensions/mutable.rst @@ -1,7 +1,7 @@ .. _mutable_toplevel: Mutation Tracking -================== +================= .. automodule:: sqlalchemy.ext.mutable @@ -20,15 +20,15 @@ API Reference :members: .. autoclass:: MutableDict - :members: - :undoc-members: + :members: + :undoc-members: .. autoclass:: MutableList - :members: - :undoc-members: + :members: + :undoc-members: .. autoclass:: MutableSet - :members: - :undoc-members: + :members: + :undoc-members: diff --git a/doc/build/orm/index.rst b/doc/build/orm/index.rst index b7683a8ad0..8434df62c7 100644 --- a/doc/build/orm/index.rst +++ b/doc/build/orm/index.rst @@ -1,7 +1,7 @@ .. _orm_toplevel: SQLAlchemy ORM -=============== +============== Here, the Object Relational Mapper is introduced and fully described. If you want to work with higher-level SQL which is constructed automatically for you, diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index 2d21e9e788..14b85420c9 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -1,7 +1,7 @@ .. _inheritance_toplevel: Mapping Class Inheritance Hierarchies -====================================== +===================================== SQLAlchemy supports three forms of inheritance: **single table inheritance**, where several types of classes are represented by a single table, **concrete @@ -25,7 +25,7 @@ return objects of multiple types. .. _joined_inheritance: Joined Table Inheritance -------------------------- +------------------------ In joined table inheritance, each class along a hierarchy of classes is represented by a distinct table. Querying for a particular subclass diff --git a/doc/build/orm/inheritance_loading.rst b/doc/build/orm/inheritance_loading.rst index cbb0876174..85e6af8bdd 100644 --- a/doc/build/orm/inheritance_loading.rst +++ b/doc/build/orm/inheritance_loading.rst @@ -30,7 +30,7 @@ tables will be available in the SELECT. .. _with_polymorphic: Using with_polymorphic ------------------------ +---------------------- For the following sections, assume the ``Employee`` / ``Engineer`` / ``Manager`` examples introduced in :ref:`inheritance_toplevel`. @@ -339,7 +339,7 @@ narrowing the criterion to specific derived aliases or subclasses. Suppose the with a ``Company`` object. We'll add a ``company_id`` column to the ``employees`` table and a new table ``companies``: -.. sourcecode:: python+sql +.. sourcecode:: python class Company(Base): __tablename__ = 'company' @@ -464,7 +464,7 @@ eager-loaded ``Engineer`` class, we access this class from the namespace of the .. _loading_joined_inheritance: Loading objects with joined table inheritance ------------------------------------------------ +--------------------------------------------- When using joined table inheritance, if we query for a specific subclass that represents a JOIN of two tables such as our ``Engineer`` example @@ -567,7 +567,7 @@ function and its configurational variants. .. _loading_single_inheritance: Loading objects with single table inheritance ------------------------------------------------ +--------------------------------------------- In modern Declarative, single inheritance mappings produce :class:`.Column` objects that are mapped only to a subclass, and not available from the @@ -655,6 +655,6 @@ Since we specified ``"*"`` for the entities, both ``Engineer`` and Inheritance Loading API ------------------------- +----------------------- .. autofunction:: sqlalchemy.orm.with_polymorphic diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index f40ad23de1..b83b76fd55 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -1,7 +1,7 @@ .. _relationship_configure_joins: Configuring how Relationship Joins ------------------------------------- +---------------------------------- :func:`.relationship` will normally create a join between two tables by examining the foreign key relationship between the two tables @@ -104,7 +104,7 @@ one :class:`.Column` we need:: .. _relationship_primaryjoin: Specifying Alternate Join Conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The default behavior of :func:`.relationship` when constructing a join is that it equates the value of primary key columns @@ -248,7 +248,7 @@ SQL expressions:: .. _relationship_custom_operator: Using custom operators in join conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another use case for relationships is the use of custom operators, such as PostgreSQL's "is contained within" ``<<`` operator when joining with @@ -468,7 +468,7 @@ we seek for a load of ``Element.descendants`` to look like:: .. _self_referential_many_to_many: Self-Referential Many-to-Many Relationship -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Many to many relationships can be customized by one or both of :paramref:`~.relationship.primaryjoin` and :paramref:`~.relationship.secondaryjoin` - the latter is significant for a relationship that @@ -718,7 +718,7 @@ additional columns when we query; these can be ignored: Building Query-Enabled Properties -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Very ambitious custom join conditions may fail to be directly persistable, and in some cases may not even load correctly. To remove the persistence part of @@ -728,7 +728,7 @@ attribute (data written to the collection will be ignored on flush()). However, in extreme cases, consider using a regular Python property in conjunction with :class:`.Query` as follows: -.. sourcecode:: python+sql +.. sourcecode:: python class User(Base): __tablename__ = 'user' diff --git a/doc/build/orm/loading_columns.rst b/doc/build/orm/loading_columns.rst index 95d0606a50..afa54078f1 100644 --- a/doc/build/orm/loading_columns.rst +++ b/doc/build/orm/loading_columns.rst @@ -9,7 +9,7 @@ This section presents additional options regarding the loading of columns. .. _deferred: Deferred Column Loading -======================== +======================= This feature allows particular columns of a table be loaded only upon direct access, instead of when the entity is queried using @@ -76,7 +76,7 @@ using :func:`.orm.undefer_group`, sending in the group name:: query.options(undefer_group('photos')).all() Load Only Cols ---------------- +-------------- An arbitrary set of columns can be selected as "load only" columns, which will be loaded while deferring all other columns on a given entity, using :func:`.orm.load_only`:: @@ -145,7 +145,7 @@ Column Deferral API .. _bundles: Column Bundles -=============== +============== The :class:`.Bundle` may be used to query for groups of columns under one namespace. diff --git a/doc/build/orm/loading_objects.rst b/doc/build/orm/loading_objects.rst index c5550d4079..64dce643c7 100644 --- a/doc/build/orm/loading_objects.rst +++ b/doc/build/orm/loading_objects.rst @@ -1,6 +1,6 @@ -======================= +=============== Loading Objects -======================= +=============== Notes and features regarding the general loading of mapped objects. diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst index aaddb87f9b..d5f8344689 100644 --- a/doc/build/orm/loading_relationships.rst +++ b/doc/build/orm/loading_relationships.rst @@ -601,7 +601,7 @@ and scalar relationships. .. _subqueryload_ordering: The Importance of Ordering -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^ A query which makes use of :func:`.subqueryload` in conjunction with a limiting modifier such as :meth:`.Query.first`, :meth:`.Query.limit`, @@ -757,7 +757,7 @@ Above, all relationships on ``Address`` will be set to a lazy load. .. _contains_eager: Routing Explicit Joins/Statements into Eagerly Loaded Collections ------------------------------------------------------------------- +----------------------------------------------------------------- The behavior of :func:`~sqlalchemy.orm.joinedload()` is such that joins are created automatically, using anonymous aliases as targets, the results of which @@ -831,7 +831,7 @@ Or using the class-bound descriptor:: contains_eager(Order.items)) Using contains_eager() to load a custom-filtered collection result -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When we use :func:`.contains_eager`, *we* are constructing ourselves the SQL that will be used to populate collections. From this, it naturally follows @@ -875,7 +875,7 @@ in fact associated with the collection. Advanced Usage with Arbitrary Statements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``alias`` argument can be more creatively used, in that it can be made to represent any set of arbitrary names to match up into a statement. @@ -900,7 +900,7 @@ to a string SQL statement:: options(contains_eager(User.addresses, alias=eager_columns)) Creating Custom Load Rules ---------------------------- +-------------------------- .. warning:: This is an advanced technique! Great care and testing should be applied. @@ -985,7 +985,7 @@ and ``A.b.a`` from our event: Relationship Loader API ------------------------- +----------------------- .. autofunction:: contains_alias diff --git a/doc/build/orm/mapped_attributes.rst b/doc/build/orm/mapped_attributes.rst index fe98adc97d..8a45108493 100644 --- a/doc/build/orm/mapped_attributes.rst +++ b/doc/build/orm/mapped_attributes.rst @@ -1,7 +1,7 @@ .. module:: sqlalchemy.orm Changing Attribute Behavior -============================ +=========================== .. _simple_validators: diff --git a/doc/build/orm/mapped_sql_expr.rst b/doc/build/orm/mapped_sql_expr.rst index bc9e7a9f76..858e6973e1 100644 --- a/doc/build/orm/mapped_sql_expr.rst +++ b/doc/build/orm/mapped_sql_expr.rst @@ -3,7 +3,7 @@ .. _mapper_sql_expressions: SQL Expressions as Mapped Attributes -===================================== +==================================== Attributes on a mapped class can be linked to SQL expressions, which can be used in queries. @@ -174,7 +174,7 @@ here with a classical mapping:: }) Using a plain descriptor -------------------------- +------------------------ In cases where a SQL query more elaborate than what :func:`.orm.column_property` or :class:`.hybrid_property` can provide must be emitted, a regular Python diff --git a/doc/build/orm/mapping_columns.rst b/doc/build/orm/mapping_columns.rst index b36bfd2f10..4b31b92102 100644 --- a/doc/build/orm/mapping_columns.rst +++ b/doc/build/orm/mapping_columns.rst @@ -105,7 +105,7 @@ tables, a more flexible approach is to use that described in Using column_property for column level options ------------------------------------------------ +---------------------------------------------- Options can be specified when mapping a :class:`.Column` using the :func:`.column_property` function. This function diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst index 4645a8029c..7e34bd55ff 100644 --- a/doc/build/orm/nonstandard_mappings.rst +++ b/doc/build/orm/nonstandard_mappings.rst @@ -5,7 +5,7 @@ Non-Traditional Mappings .. _maptojoin: Mapping a Class against Multiple Tables -======================================== +======================================= Mappers can be constructed against arbitrary relational units (called *selectables*) in addition to plain tables. For example, the :func:`~.expression.join` diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index 06b8faff73..7a7d9042d4 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -5,7 +5,7 @@ Additional Persistence Techniques .. _flush_embedded_sql_expressions: Embedding SQL Insert/Update Expressions into a Flush -===================================================== +==================================================== This feature allows the value of a database column to be set to a SQL expression instead of a literal value. It's especially useful for atomic @@ -32,7 +32,7 @@ from the database. .. _session_sql_expressions: Using SQL Expressions with Sessions -==================================== +=================================== SQL expressions and strings can be executed via the :class:`~sqlalchemy.orm.session.Session` within its transactional context. diff --git a/doc/build/orm/query.rst b/doc/build/orm/query.rst index 1517cb997a..8a857c057f 100644 --- a/doc/build/orm/query.rst +++ b/doc/build/orm/query.rst @@ -26,13 +26,13 @@ ORM-Specific Query Constructs .. autoclass:: sqlalchemy.orm.util.AliasedInsp .. autoclass:: sqlalchemy.orm.query.Bundle - :members: + :members: .. autoclass:: sqlalchemy.util.KeyedTuple - :members: keys, _fields, _asdict + :members: keys, _fields, _asdict .. autoclass:: sqlalchemy.orm.strategy_options.Load - :members: + :members: .. autofunction:: join diff --git a/doc/build/orm/relationship_persistence.rst b/doc/build/orm/relationship_persistence.rst index 1a855216c8..225d26a16c 100644 --- a/doc/build/orm/relationship_persistence.rst +++ b/doc/build/orm/relationship_persistence.rst @@ -167,7 +167,7 @@ the foreign key for the purposes of joining and cross-population. .. _passive_updates: Mutable Primary Keys / Update Cascades ---------------------------------------- +-------------------------------------- When the primary key of an entity changes, related items which reference the primary key must also be updated as diff --git a/doc/build/orm/self_referential.rst b/doc/build/orm/self_referential.rst index f6ed35fd6e..a3b288d5cd 100644 --- a/doc/build/orm/self_referential.rst +++ b/doc/build/orm/self_referential.rst @@ -1,7 +1,7 @@ .. _self_referential: Adjacency List Relationships ------------------------------ +---------------------------- The **adjacency list** pattern is a common relational pattern whereby a table contains a foreign key reference to itself. This is the most common @@ -119,7 +119,7 @@ the "remote" side. where a column points to itself. Self-Referential Query Strategies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Querying of self-referential structures works like any other query:: @@ -218,7 +218,7 @@ arbitrarily join along a chain of self-referential nodes, see .. _self_referential_eager_loading: Configuring Self-Referential Eager Loading -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Eager loading of relationships occurs using joins or outerjoins from parent to child table during a normal query operation, such that the parent and its diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst index 55194ba5ce..8b1ba660ff 100644 --- a/doc/build/orm/session_api.rst +++ b/doc/build/orm/session_api.rst @@ -1,10 +1,10 @@ .. module:: sqlalchemy.orm.session Session API -============ +=========== Session and sessionmaker() ---------------------------- +-------------------------- .. autoclass:: sessionmaker :members: @@ -29,7 +29,7 @@ Session Utilities .. autofunction:: sqlalchemy.orm.util.was_deleted Attribute and State Management Utilities ------------------------------------------ +---------------------------------------- These functions are provided by the SQLAlchemy attribute instrumentation API to provide a detailed interface for dealing diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 18610d3f03..de0dd1e3a8 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -1,6 +1,6 @@ -========================== +============== Session Basics -========================== +============== What does the Session do ? ========================== @@ -98,7 +98,7 @@ is then maintained by the helper. Some of these helpers are discussed in the section :ref:`session_faq_whentocreate`. Adding Additional Configuration to an Existing sessionmaker() --------------------------------------------------------------- +------------------------------------------------------------- A common scenario is where the :class:`.sessionmaker` is invoked at module import time, however the generation of one or more :class:`.Engine` @@ -125,7 +125,7 @@ when the construct is invoked:: session = Session() Creating Ad-Hoc Session Objects with Alternate Arguments ---------------------------------------------------------- +-------------------------------------------------------- For the use case where an application needs to create a new :class:`.Session` with special arguments that deviate from what is normally used throughout the application, @@ -155,14 +155,14 @@ transaction - see :ref:`session_external_transaction` for an example of this. .. _session_faq: Session Frequently Asked Questions -=================================== +================================== By this point, many users already have questions about sessions. This section presents a mini-FAQ (note that we have also a :doc:`real FAQ `) of the most basic issues one is presented with when using a :class:`.Session`. When do I make a :class:`.sessionmaker`? ------------------------------------------- +---------------------------------------- Just one time, somewhere in your application's global scope. It should be looked upon as part of your application's configuration. If your @@ -391,7 +391,7 @@ doing its work. For example, we can further separate concerns using a `context Is the Session a cache? ----------------------------------- +----------------------- Yeee...no. It's somewhat used as a cache, in that it implements the :term:`identity map` pattern, and stores objects keyed to their primary key. @@ -429,7 +429,7 @@ The newer :ref:`core_inspection_toplevel` system can also be used:: .. _session_faq_threadsafe: Is the session thread-safe? ------------------------------- +--------------------------- The :class:`.Session` is very much intended to be used in a **non-concurrent** fashion, which usually means in only one thread at a @@ -475,7 +475,7 @@ using the :meth:`.Session.merge` method to copy the state of an object into a new object local to a different :class:`.Session`. Basics of Using a Session -=========================== +========================= The most basic :class:`.Session` use patterns are presented here. @@ -559,7 +559,7 @@ into the Session's list of objects to be marked as deleted:: .. _session_deleting_from_collections: Deleting from Collections -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ A common confusion that arises regarding :meth:`~.Session.delete` is when objects which are members of a collection are being deleted. While the diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst index f3ab57e599..7901d8f4a8 100644 --- a/doc/build/orm/session_events.rst +++ b/doc/build/orm/session_events.rst @@ -243,7 +243,7 @@ now has an identity key. Track pending to persistent with the print("pending to persistent: %s" % object_) Pending to Transient -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ The :term:`pending` object can revert back to :term:`transient` if the :meth:`.Session.rollback` method is called before the pending object @@ -256,7 +256,7 @@ for the object before it is flushed. Track pending to transient with the print("transient to pending: %s" % object_) Loaded as Persistent -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^ Objects can appear in the :class:`.Session` directly in the :term:`persistent` state when they are loaded from the database. Tracking this state transition @@ -316,7 +316,7 @@ Track the persistent to deleted transition with Deleted to Detached -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^ The deleted object becomes :term:`detached` when the session's transaction is committed. After the :meth:`.Session.commit` method is called, the @@ -340,7 +340,7 @@ the deleted to detached transition using :meth:`.SessionEvents.deleted_to_detach Persistent to Detached -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ The persistent object becomes :term:`detached` when the object is de-associated with the :class:`.Session`, via the :meth:`.Session.expunge`, @@ -360,7 +360,7 @@ Track objects as they move from persistent to detached using the print("object became detached: %s" % object_) Detached to Persistent -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ The detached object becomes persistent when it is re-associated with a session using the :meth:`.Session.add` or equivalent method. Track @@ -373,7 +373,7 @@ objects moving back to persistent from detached using the Deleted to Persistent -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^ The :term:`deleted` object can be reverted to the :term:`persistent` state when the transaction in which it was DELETEd was rolled back diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst index e825568e51..40fda4c759 100644 --- a/doc/build/orm/session_state_management.rst +++ b/doc/build/orm/session_state_management.rst @@ -574,7 +574,7 @@ or loaded with :meth:`~.Session.refresh` varies based on several factors, includ When to Expire or Refresh -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ The :class:`.Session` uses the expiration feature automatically whenever the transaction referred to by the session ends. Meaning, whenever :meth:`.Session.commit` diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst index e686fd7f6d..c508d8b35b 100644 --- a/doc/build/orm/session_transaction.rst +++ b/doc/build/orm/session_transaction.rst @@ -1,6 +1,6 @@ -======================================= +====================================== Transactions and Connection Management -======================================= +====================================== .. _unitofwork_transaction: diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 91c6202e1f..1deaf09450 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -1111,7 +1111,7 @@ implies a basic one to many association from the ``users`` to a new table which stores email addresses, which we will call ``addresses``. Using declarative, we define this table along with its mapped class, ``Address``: -.. sourcecode:: python+sql +.. sourcecode:: python >>> from sqlalchemy import ForeignKey >>> from sqlalchemy.orm import relationship @@ -1217,7 +1217,7 @@ already been created: COMMIT Working with Related Objects -============================= +============================ Now when we create a ``User``, a blank ``addresses`` collection will be present. Various collection types, such as sets and dictionaries, are possible @@ -1309,7 +1309,7 @@ to optimize the loading of this collection in a bit. .. _ormtutorial_joins: Querying with Joins -==================== +=================== Now that we have two tables, we can show some more features of :class:`.Query`, specifically how to create queries that deal with both tables at the same time. @@ -1691,7 +1691,7 @@ very easy to use: ensure correct results. See :ref:`subqueryload_ordering`. Joined Load -------------- +----------- The other automatic eager loading function is more well known and is called :func:`.orm.joinedload`. This style of loading emits a JOIN, by default @@ -1750,7 +1750,7 @@ for both the lead and the related object. a detailed description of how this is used. Explicit Join + Eagerload --------------------------- +------------------------- A third style of eager loading is when we are constructing a JOIN explicitly in order to locate the primary rows, and would like to additionally apply the extra diff --git a/doc/build/orm/versioning.rst b/doc/build/orm/versioning.rst index bf25f78c15..f9ad0c5d5f 100644 --- a/doc/build/orm/versioning.rst +++ b/doc/build/orm/versioning.rst @@ -210,7 +210,7 @@ e.g. PostgreSQL, Oracle, SQL Server (though SQL Server has Support for server side version identifier tracking. Programmatic or Conditional Version Counters ---------------------------------------------- +-------------------------------------------- When ``version_id_generator`` is set to False, we can also programmatically (and conditionally) set the version identifier on our object in the same way