diff options
| author | Kataev Denis <kataev@skydns.ru> | 2017-05-22 17:52:45 -0400 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2017-05-22 17:53:09 -0400 |
| commit | 42b6ef8ccd691f6ace30ae16ed70f92e748f763f (patch) | |
| tree | 04224f624e91ece3e2d8dde2564414068f33e6e5 | |
| parent | 990d4c799f2a48530616e289418af395d168b56c (diff) | |
| download | sqlalchemy-42b6ef8ccd691f6ace30ae16ed70f92e748f763f.tar.gz | |
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
88 files changed, 303 insertions, 303 deletions
diff --git a/doc/build/changelog/changelog_01.rst b/doc/build/changelog/changelog_01.rst index b0d95d45c..d2878f6d5 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 44b77b664..ef389f63f 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 349367c38..27eda474f 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 1bd49871c..7dcfa82e1 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 5bcfd5fdf..172caaa51 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 d1c7fe5db..1a3664f7d 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 a77945fc2..2b7654ec2 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 6eb58306a..548bc43e8 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 c912387cd..159c5acfe 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 b0047dd8e..d282fa3a1 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 9fba02c32..90a8bb3a5 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/changelog_12.rst b/doc/build/changelog/changelog_12.rst index 2d1535849..9cf441f81 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -1,6 +1,6 @@ -============== +============= 1.2 Changelog -============== +============= .. changelog_imports:: diff --git a/doc/build/changelog/index.rst b/doc/build/changelog/index.rst index 787d4766a..3d3cdf3a9 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 c3d0df1f3..54a553623 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 9c4ba3f81..589970c38 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 19faafa89..64ef46c26 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 <https://dogpilecache.readthedocs.io/>`_. 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 3056f6b62..175d96234 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 b3f8cb105..c790e4641 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 <https://pypi.python.org/pypi/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/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst index a46311f62..d321af871 100644 --- a/doc/build/changelog/migration_12.rst +++ b/doc/build/changelog/migration_12.rst @@ -1,6 +1,6 @@ -============================== +============================= What's New in SQLAlchemy 1.2? -============================== +============================= .. admonition:: About this Document @@ -516,7 +516,7 @@ Key Behavioral Changes - ORM .. _change_3740: Percent signs in literal_column() now conditionally escaped ------------------------------------------------------------- +----------------------------------------------------------- The :obj:`.literal_column` construct now escapes percent sign characters conditionally, based on whether or not the DBAPI in use makes use of a @@ -848,13 +848,13 @@ itself will also be present:: :ticket:`3959` Dialect Improvements and Changes - MySQL -============================================= +======================================== Dialect Improvements and Changes - SQLite -============================================= +========================================= Dialect Improvements and Changes - Oracle -============================================= +========================================= .. _change_3276: @@ -896,7 +896,7 @@ Dialect Improvements and Changes - SQL Server .. _change_2626: SQL Server schema names with embedded dots supported ------------------------------------------------------ +---------------------------------------------------- The SQL Server dialect has a behavior such that a schema name with a dot inside of it is assumed to be a "database"."owner" identifier pair, which is diff --git a/doc/build/core/api_basics.rst b/doc/build/core/api_basics.rst index e56a1117b..a7b6e2ede 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 5cdc5a3dd..29e884396 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 88d003678..ab9eae41f 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 f47640c92..64f91b23f 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 76692226e..db0905d72 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 bb6699cc6..f6cf4f4b3 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 f429ba561..dc5a8c996 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 <http://docs.python.org/library/logging.html>`_ module is used to diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst index edc16e603..018a46cd7 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 451cb9460..1dc56b053 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 7e76127f4..706db625e 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 1e762b188..21f101454 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 086b544db..257cd4420 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 @@ -286,7 +286,7 @@ a new DBAPI connection. Disconnect Handling - Optimistic -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When pessimistic handling is not employed, as well as when the database is shutdown and/or restarted in the middle of a connection's period of use within @@ -335,7 +335,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 @@ -456,7 +456,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 ca1e3bf20..139f4df7e 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 f368c7237..634abbfc5 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 7f0b68b64..f165df5a2 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 c5d239b67..b120d83eb 100644 --- a/doc/build/dialects/index.rst +++ b/doc/build/dialects/index.rst @@ -59,7 +59,7 @@ Production Ready on top of `pythone-tds <https://github.com/denisenkom/pytds>`_. 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 6173ffba1..490ecaccf 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 100f2d2e3..ebfc8a31c 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 4b4de3d4c..f8e9f891a 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 38b2e4741..03511b047 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 93a54ee8d..936ae253f 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 8e9695325..835e295fc 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 7e763d288..d2e33f3c5 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 120e0ba3a..5961226ce 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 7e4a55720..822076854 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 <https://bitbucket.org/zzzeek/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 1263906c4..589a7a151 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 d9684a44c..c6f51ebb1 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" @@ -463,7 +463,7 @@ Script:: .. _faq_compiled_cache_threshold: How do I deal with "compiled statement cache reaching its size threshhold"? ------------------------------------------------------------------------------ +--------------------------------------------------------------------------- Some parts of the ORM make use of a least-recently-used (LRU) cache in order to cache generated SQL statements for fast reuse. More generally, these @@ -509,4 +509,4 @@ the ORM should not generally require adjustment, and the LRU boundaries should never be reached. If this warning is occurring and the application is not generating hundreds of engines, please report the issue to the SQLAlchemy developers on the mailing list; see the guidelines -at http://www.sqlalchemy.org/support.html#mailinglist.
\ No newline at end of file +at http://www.sqlalchemy.org/support.html#mailinglist. diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index f7247aa21..2daba2969 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 fce6c47db..da956912a 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 1165d7fa9..116fb74ee 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 cd6389ab7..6a121be9f 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 53ac9e3ce..abd969933 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 76d4cd023..04f9b5110 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 38cbb4182..637afccb7 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 cadfe8e05..fd5584622 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 8d277011c..088705a0e 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 470a9386b..d373f253e 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 1a0007ca7..76afab26f 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 4b2b86f62..f20f01c18 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 7628bc1bd..18803c75f 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 67b66a970..5ef209b75 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 bc9f913f2..b23fa4044 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 577ed140f..c401b9bc8 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 9a621e6dd..f203c5580 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 060549a72..8639e5782 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 16084e319..422721ffe 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 2ef0a5adb..3e49b86cb 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 b7683a8ad..8434df62c 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 2d21e9e78..14b85420c 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 cbb087617..85e6af8bd 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 f40ad23de..b83b76fd5 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 95d0606a5..afa54078f 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 c5550d407..64dce643c 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 f2279a2b4..6d3beb94d 100644 --- a/doc/build/orm/loading_relationships.rst +++ b/doc/build/orm/loading_relationships.rst @@ -617,7 +617,7 @@ limitations of :func:`.subqueryload`. .. _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`, @@ -918,7 +918,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 @@ -992,7 +992,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 @@ -1036,7 +1036,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. @@ -1061,7 +1061,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. @@ -1146,7 +1146,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 fe98adc97..8a4510849 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 bc9e7a9f7..858e6973e 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 b36bfd2f1..4b31b9210 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 4645a8029..7e34bd55f 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 06b8faff7..7a7d9042d 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 1517cb997..8a857c057 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 1a855216c..225d26a16 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 f6ed35fd6..a3b288d5c 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 9c8523542..5523422e0 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 18610d3f0..de0dd1e3a 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 </faq/index>`) 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 f3ab57e59..7901d8f4a 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 e825568e5..40fda4c75 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 e686fd7f6..c508d8b35 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 afe097e85..f742151b0 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 bf25f78c1..f9ad0c5d5 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 |