:tickets: 2957
:versions: 0.9.3
- Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless
+ Fixed bug where :meth:`.ColumnOperators.in_` would go into an endless
loop if erroneously passed a column expression whose comparator
included the ``__getitem__()`` method, such as a column that uses the
:class:`_postgresql.ARRAY` type.
to a modern pool invalidation in that connections aren't actively
closed, but are recycled only on next checkout; this is essentially
a per-connection version of that feature. A new event
- :class:`_events.PoolEvents.soft_invalidate` is added to complement it.
+ :meth:`_events.PoolEvents.soft_invalidate` is added to complement it.
Also added new flag
:attr:`.ExceptionContext.invalidate_pool_on_disconnect`.
:version: 1.1.15
:released: November 3, 2017
- .. change:
+ .. change::
:tags: bug, sqlite
:tickets: 4099
:versions: 1.2.0b3
for single inheritance discriminator criteria inappropriately re-applying
the criteria to the outer query.
- .. change:
+ .. change::
:tags: bug, mysql
:tickets: 4096
:versions: 1.2.0b3
in the MariaDB 10.2 series due to a syntax change, where the function
is now represented as ``current_timestamp()``.
- .. change:
+ .. change::
:tags: bug, mysql
:tickets: 4098
:versions: 1.2.0b3
Fixed bug in cache key generation for baked queries which could cause a
too-short cache key to be generated for the case of eager loads across
subclasses. This could in turn cause the eagerload query to be cached in
- place of a non-eagerload query, or vice versa, for a polymorhic "selectin"
+ place of a non-eagerload query, or vice versa, for a polymorphic "selectin"
load, or possibly for lazy loads or selectin loads as well.
.. change::
Fixed issue where an :class:`.Index` that is deferred in being associated
with a table, such as as when it contains a :class:`.Column` that is not
associated with any :class:`.Table` yet, would fail to attach correctly if
- it also contained a non table-oriented expession.
+ it also contained a non table-oriented expression.
.. change::
:tags: bug, mysql
:tickets: 5239
- Fixed issue in MySQL dialect when connecting to a psuedo-MySQL database
+ Fixed issue in MySQL dialect when connecting to a pseudo-MySQL database
such as that provided by ProxySQL, the up front check for isolation level
when it returns no row will not prevent the dialect from continuing to
connect. A warning is emitted that the isolation level could not be
This change applies specifically to the use of the :func:`_orm.joinedload` loading
strategy in conjunction with a row limited query, e.g. using :meth:`_query.Query.first`
-or :meth:`_query.Query.limit`, as well as with use of the :class:`_query.Query.with_for_update` method.
+or :meth:`_query.Query.limit`, as well as with use of the :meth:`_query.Query.with_for_update` method.
Given a query as::
engine = create_engine('mysql://scott:tiger@localhost/test')
-The typical usage of :func:`_sa.create_engine()` is once per particular database
+The typical usage of :func:`_sa.create_engine` is once per particular database
URL, held globally for the lifetime of a single application process. A single
:class:`_engine.Engine` manages many individual :term:`DBAPI` connections on behalf of
the process and is intended to be called upon in a concurrent fashion. The
engine is initialized per process. See :ref:`pooling_multiprocessing` for
details.
-
The most basic function of the :class:`_engine.Engine` is to provide access to a
:class:`_engine.Connection`, which can then invoke SQL statements. To emit
a textual statement to the database looks like::
.. _dbengine_implicit:
+
Connectionless Execution, Implicit Execution
============================================
Recall from the first section we mentioned executing with and without explicit
usage of :class:`_engine.Connection`. "Connectionless" execution
refers to the usage of the ``execute()`` method on an object which is not a
-:class:`_engine.Connection`. This was illustrated using the :meth:`_engine.Engine.execute` method
-of :class:`_engine.Engine`::
+:class:`_engine.Connection`. This was illustrated using the
+:meth:`_engine.Engine.execute` method of :class:`_engine.Engine`::
result = engine.execute("select username from users")
for row in result:
.. versionchanged:: 1.0.0 - The DDL system invoked by
:meth:`_schema.MetaData.create_all`
and :meth:`_schema.MetaData.drop_all` will now automatically resolve mutually
- depdendent foreign keys between tables declared by
+ dependent foreign keys between tables declared by
:class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` objects, without
the need to explicitly set the :paramref:`_schema.ForeignKeyConstraint.use_alter`
flag.
-------------------------------------
SQLAlchemy Core defines a fixed set of expression operators available to all column expressions.
-Some of these operations have the effect of overloading Python's built in operators;
+Some of these operations have the effect of overloading Python's built-in operators;
examples of such operators include
:meth:`.ColumnOperators.__eq__` (``table.c.somecolumn == 'foo'``),
:meth:`.ColumnOperators.__invert__` (``~table.c.flag``),
The Core expression constructs in all cases consult the type of the expression in order to determine
the behavior of existing operators, as well as to locate additional operators that aren't part of
-the built in set. The :class:`.TypeEngine` base class defines a root "comparison" implementation
+the built-in set. The :class:`.TypeEngine` base class defines a root "comparison" implementation
:class:`.TypeEngine.Comparator`, and many specific types provide their own sub-implementations of this
class. User-defined :class:`.TypeEngine.Comparator` implementations can be built directly into a
simple subclass of a particular type in order to override or define new operations. Below,
.. sourcecode:: python+sql
from sqlalchemy.schema import CreateTable
- with engine.connecT() as conn:
+ with engine.connect() as conn:
{sql} conn.execute(CreateTable(mytable))
CREATE TABLE mytable (
col1 INTEGER,
in the execution for the ``counter`` column, plus the number 12.
For a single statement that is being executed using "executemany" style, e.g.
-with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the user-
-defined function is called once for each set of parameters. For the use case of
+with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the
+user-defined function is called once for each set of parameters. For the use case of
a multi-valued :class:`_expression.Insert` construct (e.g. with more than one VALUES
clause set up via the :meth:`_expression.Insert.values` method), the user-defined function
is also called once for each set of parameters.
:meth:`_engine.ResultProxy.last_updated_params` collections on
:class:`~sqlalchemy.engine.ResultProxy`. The
:attr:`_engine.ResultProxy.inserted_primary_key` collection contains a list of primary
-key values for the row inserted (a list so that single-column and composite-
-column primary keys are represented in the same format).
+key values for the row inserted (a list so that single-column and
+composite-column primary keys are represented in the same format).
.. _server_defaults:
SQLAlchemy represents database sequences using the
:class:`~sqlalchemy.schema.Sequence` object, which is considered to be a
-special case of "column default". It only has an effect on databases which
-have explicit support for sequences, which currently includes PostgreSQL,
-Oracle, and Firebird. The :class:`~sqlalchemy.schema.Sequence` object is
-otherwise ignored.
+special case of "column default". It only has an effect on databases which have
+explicit support for sequences, which currently includes PostgreSQL, Oracle,
+MariaDB 10.3 or greater, and Firebird. The :class:`~sqlalchemy.schema.Sequence`
+object is otherwise ignored.
The :class:`~sqlalchemy.schema.Sequence` may be placed on any column as a
"default" generator to be used during INSERT operations, and can also be
PostgreSQL's SERIAL datatype is an auto-incrementing type that implies
the implicit creation of a PostgreSQL sequence when CREATE TABLE is emitted.
If a :class:`_schema.Column` specifies an explicit :class:`.Sequence` object
-which also specifies a true value for the :paramref:`.Sequence.optional`
+which also specifies a ``True`` value for the :paramref:`.Sequence.optional`
boolean flag, the :class:`.Sequence` will not take effect under PostgreSQL,
and the SERIAL datatype will proceed normally. Instead, the :class:`.Sequence`
will only take effect when used against other sequence-supporting
Some key internal constructs are listed here.
-.. currentmodule: sqlalchemy
+.. currentmodule:: sqlalchemy
.. autoclass:: sqlalchemy.engine.interfaces.Compiled
:members:
specific lexical element within a SQL string. Composed together
into a larger structure, they form a statement construct that may
be *compiled* into a string representation that can be passed to a database.
-The classes are organized into a
-hierarchy that begins at the basemost ClauseElement class. Key subclasses
-include ColumnElement, which represents the role of any column-based expression
+The classes are organized into a hierarchy that begins at the basemost
+:class:`.ClauseElement` class. Key subclasses include :class:`.ColumnElement`,
+which represents the role of any column-based expression
in a SQL statement, such as in the columns clause, WHERE clause, and ORDER BY
-clause, and FromClause, which represents the role of a token that is placed in
-the FROM clause of a SELECT statement.
+clause, and :class:`.FromClause`, which represents the role of a token that
+is placed in the FROM clause of a SELECT statement.
.. autofunction:: all_
executing it. In this tutorial, we will generally focus on the most explicit
method of executing a SQL construct, and later touch upon some "shortcut" ways
to do it. The ``engine`` object we created is a repository for database
-connections capable of issuing SQL to the database. To acquire a connection,
-we use the ``connect()`` method::
+connections capable of issuing SQL to the database. To acquire a
+connection, we will use the :meth:`.Engine.connect` method::
>>> conn = engine.connect()
>>> conn
>>> row[addresses.c.email_address]
'jack@yahoo.com'
-If on the other hand we used a string column key, the usual rules of name-
-based matching still apply, and we'd get an ambiguous column error for
+If on the other hand we used a string column key, the usual rules of
+name-based matching still apply, and we'd get an ambiguous column error for
the ``id`` value::
>>> row["id"]
available.
However in some cases, the order of parameters rendered in the SET clause of an
-UPDATE statement can be significant. The main example of this is when using
-MySQL and providing updates to column values based on that of other
+UPDATE statement may need to be explicitly stated. The main example of this is
+when using MySQL and providing updates to column values based on that of other
column values. The end result of the following statement::
UPDATE some_table SET x = y + 10, y = 20
.. autoclass:: Variant
-
:members: with_variant, __init__
resources until a SQL statement is invoked, at which point a connection-level
and DBAPI-level transaction is started. However, whether or not
database-level transactions are part of its state, the logical transaction will
-stay in place until it is ended using :meth:`.Session.commit()`,
+stay in place until it is ended using :meth:`.Session.commit`,
:meth:`.Session.rollback`, or :meth:`.Session.close`.
When the ``flush()`` above fails, the code is still within the transaction
relational
relational algebra
- An algrebraic system developed by Edgar F. Codd that is used for
+ An algebraic system developed by Edgar F. Codd that is used for
modelling and querying the data stored in relational databases.
.. seealso::
A term used in SQLAlchemy to describe a SQL construct that represents
a collection of rows. It's largely similar to the concept of a
"relation" in :term:`relational algebra`. In SQLAlchemy, objects
- that subclass the :class:`expression.Selectable` class are considered to be
+ that subclass the :class:`_expression.Selectable` class are considered to be
usable as "selectables" when using SQLAlchemy Core. The two most
common constructs are that of the :class:`_schema.Table` and that of the
:class:`_expression.Select` statement.
within the join expression.
crud
+ CRUD
An acronym meaning "Create, Update, Delete". The term in SQL refers to the
set of operations that create, modify and delete data from the database,
also known as :term:`DML`, and typically refers to the ``INSERT``,
An acronym for **Data Manipulation Language**. DML is the subset of
SQL that relational databases use to *modify* the data in tables. DML
typically refers to the three widely familiar statements of INSERT,
- UPDATE and DELETE, otherwise known as :term:`CRUD` (acronoym for "CReate,
+ UPDATE and DELETE, otherwise known as :term:`CRUD` (acronym for "CReate,
Update, Delete").
.. seealso::
In SQLAlchemy, the "dialect" is a Python object that represents information
and methods that allow database operations to proceed on a particular
kind of database backend and a particular kind of Python driver (or
- :term`DBAPI`) for that database. SQLAlchemy dialects are subclasses
+ :term:`DBAPI`) for that database. SQLAlchemy dialects are subclasses
of the :class:`.Dialect` class.
.. seealso::
identity map
A mapping between Python objects and their database identities.
The identity map is a collection that's associated with an
- ORM :term:`session` object, and maintains a single instance
+ ORM :term:`Session` object, and maintains a single instance
of every database object keyed to its identity. The advantage
to this pattern is that all operations which occur for a particular
database identity are transparently coordinated onto a single
.. seealso::
- :ref:`pooling_toplevel`
+ :ref:`pooling_toplevel`
DBAPI
DBAPI is shorthand for the phrase "Python Database API
expire
expires
expiring
+ Expiring
In the SQLAlchemy ORM, refers to when the data in a :term:`persistent`
or sometimes :term:`detached` object is erased, such that when
the object's attributes are next accessed, a :term:`lazy load` SQL
isolation
isolated
+ Isolation
isolation level
The isolation property of the :term:`ACID` model
ensures that the concurrent execution
transient
This describes one of the major object states which
- an object can have within a :term:`session`; a transient object
+ an object can have within a :term:`Session`; a transient object
is a new object that doesn't have any database identity
and has not been associated with a session yet. When the
object is added to the session, it moves to the
pending
This describes one of the major object states which
- an object can have within a :term:`session`; a pending object
+ an object can have within a :term:`Session`; a pending object
is a new object that doesn't have any database identity,
but has been recently associated with a session. When
the session emits a flush and the row is inserted, the
deleted
This describes one of the major object states which
- an object can have within a :term:`session`; a deleted object
+ an object can have within a :term:`Session`; a deleted object
is an object that was formerly persistent and has had a
DELETE statement emitted to the database within a flush
to delete its row. The object will move to the :term:`detached`
persistent
This describes one of the major object states which
- an object can have within a :term:`session`; a persistent object
+ an object can have within a :term:`Session`; a persistent object
is an object that has a database identity (i.e. a primary key)
and is currently associated with a session. Any object
that was previously :term:`pending` and has now been inserted
detached
This describes one of the major object states which
- an object can have within a :term:`session`; a detached object
+ an object can have within a :term:`Session`; a detached object
is an object that has a database identity (i.e. a primary key)
but is not associated with any session. An object that
was previously :term:`persistent` and was removed from its
In the above example, it is **not** as intuitive that the ``Address`` would
automatically be added to the :class:`.Session`. However, the backref behavior
of ``Address.user`` indicates that the ``Address`` object is also appended to
-the ``User.addresses`` collection. This in turn intiates a **cascade**
+the ``User.addresses`` collection. This in turn initiates a **cascade**
operation which indicates that this ``Address`` should be placed into the
:class:`.Session` as a :term:`pending` object.
class User(Base):
# ...
- addresses = relationship("Address", back_populates="user", cascade_backefs=False)
+ addresses = relationship("Address", back_populates="user", cascade_backrefs=False)
See the example in :ref:`backref_cascade` for further information.
created perhaps within distinct databases::
DefaultBase.metadata.create_all(some_engine)
- OtherBase.metadata_create_all(some_other_engine)
+ OtherBase.metadata.create_all(some_other_engine)
``__table_cls__``
traditional way. The :class:`_schema.Table` usually shares
the :class:`_schema.MetaData` object used by the declarative base::
- keywords = Table(
- 'keywords', Base.metadata,
+ keyword_author = Table(
+ 'keyword_author', Base.metadata,
Column('author_id', Integer, ForeignKey('authors.id')),
Column('keyword_id', Integer, ForeignKey('keywords.id'))
)
class Author(Base):
__tablename__ = 'authors'
id = Column(Integer, primary_key=True)
- keywords = relationship("Keyword", secondary=keywords)
+ keywords = relationship("Keyword", secondary=keyword_author)
Like other :func:`~sqlalchemy.orm.relationship` arguments, a string is accepted
as well, passing the string name of the table as defined in the
class Author(Base):
__tablename__ = 'authors'
id = Column(Integer, primary_key=True)
- keywords = relationship("Keyword", secondary="keywords")
+ keywords = relationship("Keyword", secondary="keyword_author")
As with traditional mapping, its generally not a good idea to use
a :class:`_schema.Table` as the "secondary" argument which is also mapped to
WHERE employee.id IN (?) ORDER BY employee.id
(1,)
-Combining "selectin" polymorhic loading with query-time
+Combining "selectin" polymorphic loading with query-time
:func:`_orm.with_polymorphic` usage is also possible (though this is very
outer-space stuff!); assuming the above mappings had no ``polymorphic_load``
set up, we could get the same result as follows::
Key ORM constructs, not otherwise covered in other
sections, are listed here.
-.. currentmodule: sqlalchemy.orm
+.. currentmodule:: sqlalchemy.orm
.. autoclass:: sqlalchemy.orm.state.AttributeState
:members:
As far as the use case of a class that can actually be fully persisted
to different tables under different scenarios, very early versions of
SQLAlchemy offered a feature for this adapted from Hibernate, known
-as the "entity name" feature. However, this use case became infeasable
+as the "entity name" feature. However, this use case became infeasible
within SQLAlchemy once the mapped class itself became the source of SQL
expression construction; that is, the class' attributes themselves link
directly to mapped table columns. The feature was removed and replaced
For server-generating columns that are not primary key columns or that are not
simple autoincrementing integer columns, the ORM requires that these columns
-are marked with an appropriate server_default directive that allows the ORM to
+are marked with an appropriate ``server_default`` directive that allows the ORM to
retrieve this value. Not all methods are supported on all backends, however,
so care must be taken to use the appropriate method. The two questions to be
answered are, 1. is this column part of the primary key or not, and 2. does the
----------------------------
:meth:`~.Session.add` is used to place instances in the
-session. For *transient* (i.e. brand new) instances, this will have the effect
+session. For :term:`transient` (i.e. brand new) instances, this will have the effect
of an INSERT taking place for those instances upon the next flush. For
-instances which are *persistent* (i.e. were loaded by this session), they are
-already present and do not need to be added. Instances which are *detached*
+instances which are :term:`persistent` (i.e. were loaded by this session), they are
+already present and do not need to be added. Instances which are :term:`detached`
(i.e. have been removed from a session) may be re-associated with a session
using this method::
# ...
addresses = relationship(
- "Address", cascade="all, delete, delete-orphan")
+ "Address", cascade="all, delete-orphan")
# ...
# ...
preference = relationship(
- "Preference", cascade="all, delete, delete-orphan",
+ "Preference", cascade="all, delete-orphan",
single_parent=True)
we can pass additional arguments to :meth:`.Session.connection` in order to
affect how the bind is procured::
- sess = my_sesssionmaker()
+ sess = my_sessionmaker()
# set up a transaction for the bind associated with
# the User mapper
immediately issue SQL and return a value containing loaded
database results. Here's a brief tour:
-* :meth:`_query.Query.all()` returns a list:
+* :meth:`_query.Query.all` returns a list:
.. sourcecode:: python+sql
:ref:`faq_query_deduplicating`
-* :meth:`_query.Query.first()` applies a limit of one and returns
+* :meth:`_query.Query.first` applies a limit of one and returns
the first result as a scalar:
.. sourcecode:: python+sql
('%ed', 1, 0)
{stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')>
-* :meth:`_query.Query.one()` fully fetches all rows, and if not
+* :meth:`_query.Query.one` fully fetches all rows, and if not
exactly one object identity or composite row is present in the result, raises
an error. With multiple rows found:
:class:`~sqlalchemy.orm.query.Query`, by specifying their use
with the :func:`_expression.text` construct, which is accepted
by most applicable methods. For example,
-:meth:`~sqlalchemy.orm.query.Query.filter()` and
-:meth:`~sqlalchemy.orm.query.Query.order_by()`:
+:meth:`_query.Query.filter` and
+:meth:`_query.Query.order_by`:
.. sourcecode:: python+sql
fred
Bind parameters can be specified with string-based SQL, using a colon. To
-specify the values, use the :meth:`~sqlalchemy.orm.query.Query.params()`
+specify the values, use the :meth:`_query.Query.params`
method:
.. sourcecode:: python+sql
To use an entirely string-based statement, a :func:`_expression.text` construct
representing a complete statement can be passed to
-:meth:`~sqlalchemy.orm.query.Query.from_statement()`. Without additional
+:meth:`_query.Query.from_statement`. Without additional
specifiers, the columns in the string SQL are matched to the model columns
based on name, such as below where we use just an asterisk to represent
loading all columns:
.. sourcecode:: python+sql
{sql}>>> session.query(User).from_statement(
- ... text("SELECT * FROM users where name=:name")).\
- ... params(name='ed').all()
+ ... text("SELECT * FROM users where name=:name")).params(name='ed').all()
SELECT * FROM users where name=?
('ed',)
{stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>]
--------
:class:`~sqlalchemy.orm.query.Query` includes a convenience method for
-counting called :meth:`~sqlalchemy.orm.query.Query.count()`:
+counting called :meth:`_query.Query.count`:
.. sourcecode:: python+sql
and always returns the right answer. Use ``func.count()`` if a
particular statement absolutely cannot tolerate the subquery being present.
-The :meth:`_query.Query.count()` method is used to determine
+The :meth:`_query.Query.count` method is used to determine
how many rows the SQL statement would return. Looking
at the generated SQL above, SQLAlchemy always places whatever it is we are
querying into a subquery, then counts the rows from that. In some cases
join techniques, several of which we'll illustrate here.
To construct a simple implicit join between ``User`` and ``Address``,
-we can use :meth:`_query.Query.filter()` to equate their related columns together.
+we can use :meth:`_query.Query.filter` to equate their related columns together.
Below we load the ``User`` and ``Address`` entities at once using this method:
.. sourcecode:: python+sql
# for row in conn.execute(
# "select session_id from sys.dm_exec_sessions "
# "where database_id=db_id('%s')" % ident):
- # log.info("killing SQL server sesssion %s", row['session_id'])
+ # log.info("killing SQL server session %s", row['session_id'])
# conn.execute("kill %s" % row['session_id'])
conn.execute("drop database %s" % ident)
As is the case for all DBAPIs under Python 3, all strings are inherently
Unicode strings. Under Python 2, cx_Oracle also supports Python Unicode
-objects directly. In all cases however, the driver requires an explcit
+objects directly. In all cases however, the driver requires an explicit
encoding configuration.
Ensuring the Correct Client Encoding
class JSONB(JSON):
"""Represent the PostgreSQL JSONB type.
- The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e.
- g.::
+ The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data,
+ e.g.::
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
)
The :class:`_postgresql.JSONB` type includes all operations provided by
- :class:`_types.JSON`, including the same behaviors for indexing operations
- .
+ :class:`_types.JSON`, including the same behaviors for indexing
+ operations.
It also adds additional operators specific to JSONB, including
:meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`,
:meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`,
possible that the underlying DBAPI connection may not support shared
access between threads. Check the DBAPI documentation for details.
- The Connection object represents a single dbapi connection checked out
+ The Connection object represents a single DBAPI connection checked out
from the connection pool. In this state, the connection pool has no affect
upon the connection, including its expiration or timeout state. For the
connection pool to properly manage connections, connections should be
@property
def _root(self):
- """return the 'root' connection.
+ """Return the 'root' connection.
Returns 'self' if this connection is not a branch, else
returns the root connection from which we ultimately branched.
return self
def _clone(self):
- """Create a shallow copy of this Connection.
+ """Create a shallow copy of this Connection."""
- """
c = self.__class__.__new__(self.__class__)
c.__dict__ = self.__dict__.copy()
return c
self, dialect, constructor, statement, parameters, *args
):
"""Create an :class:`.ExecutionContext` and execute, returning
- a :class:`_engine.ResultProxy`."""
+ a :class:`_engine.ResultProxy`.
+
+ """
try:
try:
return "Engine(%r)" % self.url
def dispose(self):
- """Dispose of the connection pool used by this :class:`_engine.Engine`
- .
+ """Dispose of the connection pool used by this
+ :class:`_engine.Engine`.
This has the effect of fully closing all **currently checked in**
database connections. Connections that are still checked out
"""True if this dialect supports sane rowcount even if RETURNING is
in use.
- For dialects that don't support RETURNING, this is synomous
- with supports_sane_rowcount.
+ For dialects that don't support RETURNING, this is synonymous with
+ ``supports_sane_rowcount``.
"""
return self.supports_sane_rowcount
`table_name`, and an optional string `schema`, return column
information as a list of dictionaries with these keys:
- name
+ * ``name`` -
the column's name
- type
+ * ``type`` -
[sqlalchemy.types#TypeEngine]
- nullable
+ * ``nullable`` -
boolean
- default
+ * ``default`` -
the column's default value
- autoincrement
+ * ``autoincrement`` -
boolean
- sequence
+ * ``sequence`` -
a dictionary of the form
- {'name' : str, 'start' :int, 'increment': int, 'minvalue': int,
- 'maxvalue': int, 'nominvalue': bool, 'nomaxvalue': bool,
- 'cycle': bool, 'cache': int, 'order': bool}
+ {'name' : str, 'start' :int, 'increment': int, 'minvalue': int,
+ 'maxvalue': int, 'nominvalue': bool, 'nomaxvalue': bool,
+ 'cycle': bool, 'cache': int, 'order': bool}
Additional column attributes may be present.
+
"""
raise NotImplementedError()
":meth:`.Dialect.get_pk_constraint` method. ",
)
def get_primary_keys(self, connection, table_name, schema=None, **kw):
- """Return information about primary keys in `table_name`.
-
- """
+ """Return information about primary keys in `table_name`."""
raise NotImplementedError()
`table_name`, and an optional string `schema`, return primary
key information as a dictionary with these keys:
- constrained_columns
+ * ``constrained_columns`` -
a list of column names that make up the primary key
- name
+ * ``name`` -
optional name of the primary key constraint.
"""
`table_name`, and an optional string `schema`, return foreign
key information as a list of dicts with these keys:
- name
+ * ``name`` -
the constraint's name
- constrained_columns
+ * ``constrained_columns`` -
a list of column names that make up the foreign key
- referred_schema
+ * ``referred_schema`` -
the name of the referred schema
- referred_table
+ * ``referred_table`` -
the name of the referred table
- referred_columns
+ * ``referred_columns`` -
a list of column names in the referred table that correspond to
constrained_columns
"""
def get_view_names(self, connection, schema=None, **kw):
"""Return a list of all view names available in the database.
- schema:
+ :param schema:
Optional, retrieve names from a non-default schema.
"""
`table_name` and an optional string `schema`, return index
information as a list of dictionaries with these keys:
- name
+ * ``name`` -
the index's name
- column_names
+ * ``column_names`` -
list of column names in order
- unique
+ * ``unique`` -
boolean
+
"""
raise NotImplementedError()
Given a string `table_name` and an optional string `schema`, return
unique constraint information as a list of dicts with these keys:
- name
+ * ``name`` -
the unique constraint's name
- column_names
+ * ``column_names`` -
list of column names in order
- \**kw
+ * ``**kw`` -
other options passed to the dialect's get_unique_constraints()
method.
Given a string `table_name` and an optional string `schema`, return
check constraint information as a list of dicts with these keys:
- name
+ * ``name`` -
the check constraint's name
- sqltext
+ * ``sqltext`` -
the check constraint's SQL expression
- \**kw
+ * ``**kw`` -
other options passed to the dialect's get_check_constraints()
method.
"""convert the given name to lowercase if it is detected as
case insensitive.
- this method is only used if the dialect defines
+ This method is only used if the dialect defines
requires_name_normalize=True.
"""
"""convert the given name to a case insensitive identifier
for the backend if it is an all-lowercase name.
- this method is only used if the dialect defines
+ This method is only used if the dialect defines
requires_name_normalize=True.
"""
`table_name`, return True if the given table (possibly within
the specified `schema`) exists in the database, False
otherwise.
+
"""
raise NotImplementedError()
Given a :class:`_engine.Connection` object and a string
`sequence_name`, return True if the given sequence exists in
the database, False otherwise.
+
"""
raise NotImplementedError()
def do_executemany(self, cursor, statement, parameters, context=None):
"""Provide an implementation of ``cursor.executemany(statement,
- parameters)``."""
+ parameters)``.
+
+ """
raise NotImplementedError()
def do_execute(self, cursor, statement, parameters, context=None):
"""Provide an implementation of ``cursor.execute(statement,
- parameters)``."""
+ parameters)``.
+
+ """
raise NotImplementedError()
def is_disconnect(self, e, connection, cursor):
"""Return True if the given DB-API error indicates an invalid
- connection"""
+ connection.
+
+ """
raise NotImplementedError()
"""
def on_connect(self):
- """return a callable which sets up a newly created DBAPI connection.
+ """Return a callable which sets up a newly created DBAPI connection.
The callable should accept a single argument "conn" which is the
DBAPI connection itself. The inner callable has no
@classmethod
def load_provisioning(cls):
- """set up the provision.py module for this dialect.
+ """Set up the provision.py module for this dialect.
For dialects that include a provision.py module that sets up
provisioning followers, this method should initiate that process.
what it needs here as well as remove its custom arguments from the
:attr:`.URL.query` collection. The URL can be modified in-place
in any other way as well.
- :param kwargs: The keyword arguments passed to :func`.create_engine`.
+ :param kwargs: The keyword arguments passed to :func:`.create_engine`.
The plugin can read and modify this dictionary in-place, to affect
the ultimate arguments used to create the engine. It should
remove its custom arguments from the dictionary as well.
"""Return a result object corresponding to this ExecutionContext.
Returns a ResultProxy.
+
"""
raise NotImplementedError()
def handle_dbapi_exception(self, e):
"""Receive a DBAPI exception which occurred upon execute, result
- fetch, etc."""
+ fetch, etc.
+
+ """
raise NotImplementedError()
def should_autocommit_text(self, statement):
"""Parse the given textual statement and return True if it refers to
- a "committable" statement"""
+ a "committable" statement
+
+ """
raise NotImplementedError()
def lastrow_has_defaults(self):
"""Return True if the last INSERT or UPDATE row contained
inlined or database-side defaults.
+
"""
raise NotImplementedError()
:meth:`_reflection.Inspector.get_table_names`
:func:`.sort_tables_and_constraints` - similar method which works
- with an already-given :class:`_schema.MetaData`.
+ with an already-given :class:`_schema.MetaData`.
"""
if hasattr(self.dialect, "get_table_names"):
] + [(None, list(remaining_fkcs))]
def get_temp_table_names(self):
- """return a list of temporary table names for the current bind.
+ """Return a list of temporary table names for the current bind.
This method is unsupported by most dialects; currently
only SQLite implements it.
)
def get_temp_view_names(self):
- """return a list of temporary view names for the current bind.
+ """Return a list of temporary view names for the current bind.
This method is unsupported by most dialects; currently
only SQLite implements it.
* ``autoincrement`` - indicates that the column is auto incremented -
this is returned as a boolean or 'auto'
- * ``comment`` - (optional) the commnet on the column. Only some
+ * ``comment`` - (optional) the comment on the column. Only some
dialects return this key
* ``computed`` - (optional) when present it indicates that this column
Given a string `table_name`, and an optional string `schema`, return
primary key information as a dictionary with these keys:
- constrained_columns
+ * ``constrained_columns`` -
a list of column names that make up the primary key
- name
+ * ``name`` -
optional name of the primary key constraint.
:param table_name: string name of the table. For special quoting,
Given a string `table_name`, and an optional string `schema`, return
foreign key information as a list of dicts with these keys:
- constrained_columns
+ * ``constrained_columns`` -
a list of column names that make up the foreign key
- referred_schema
+ * ``referred_schema`` -
the name of the referred schema
- referred_table
+ * ``referred_table`` -
the name of the referred table
- referred_columns
+ * ``referred_columns`` -
a list of column names in the referred table that correspond to
constrained_columns
- name
+ * ``name`` -
optional name of the foreign key constraint.
:param table_name: string name of the table. For special quoting,
Given a string `table_name` and an optional string `schema`, return
index information as a list of dicts with these keys:
- name
+ * ``name`` -
the index's name
- column_names
+ * ``column_names`` -
list of column names in order
- unique
+ * ``unique`` -
boolean
- column_sorting
+ * ``column_sorting`` -
optional dict mapping column names to tuple of sort keywords,
which may include ``asc``, ``desc``, ``nullsfirst``, ``nullslast``.
.. versionadded:: 1.3.5
- dialect_options
+ * ``dialect_options`` -
dict of dialect-specific index options. May not be present
for all dialects.
Given a string `table_name` and an optional string `schema`, return
unique constraint information as a list of dicts with these keys:
- name
+ * ``name`` -
the unique constraint's name
- column_names
+ * ``column_names`` -
list of column names in order
:param table_name: string name of the table. For special quoting,
Given a string ``table_name`` and an optional string ``schema``,
return table comment information as a dictionary with these keys:
- text
+ * ``text`` -
text of the comment.
Raises ``NotImplementedError`` for a dialect that does not support
Given a string `table_name` and an optional string `schema`, return
check constraint information as a list of dicts with these keys:
- name
+ * ``name`` -
the check constraint's name
- sqltext
+ * ``sqltext`` -
the check constraint's SQL expression
- dialect_options
+ * ``dialect_options`` -
may or may not be present; a dictionary with additional
dialect-specific options for this CHECK constraint
resolve_fks=True,
_extend_on=None,
):
- """Given a Table object, load its internal constructs based on
- introspection.
+ """Given a :class:`_schema.Table` object, load its internal
+ constructs based on introspection.
This is the underlying method used by most dialects to produce
table reflection. Direct usage is like::
@property
def lastrowid(self):
- """return the 'lastrowid' accessor on the DBAPI cursor.
+ """Return the 'lastrowid' accessor on the DBAPI cursor.
This is a DBAPI specific method and is only functional
for those backends which support it, for statements
This object is suitable to be passed directly to a
:func:`~sqlalchemy.create_engine` call. The fields of the URL are parsed
- from a string by the :func:`.make_url` function. the string
+ from a string by the :func:`.make_url` function. The string
format of the URL is an RFC-1738-style string.
All initialization parameters are available as public attributes.
.. warning:: The ``once`` argument does not imply automatic de-registration
of the listener function after it has been invoked a first time; a
listener entry will remain associated with the target object.
- Associating an arbitrarily high number of listeners without explictitly
+ Associating an arbitrarily high number of listeners without explicitly
removing them will cause memory to grow unbounded even if ``once=True``
is specified.
.. warning:: The ``once`` argument does not imply automatic de-registration
of the listener function after it has been invoked a first time; a
listener entry will remain associated with the target object.
- Associating an arbitrarily high number of listeners without explictitly
+ Associating an arbitrarily high number of listeners without explicitly
removing them will cause memory to grow unbounded even if ``once=True``
is specified.
# This allows an Events subclass to define additional utility
# methods made available to the target via
# "self.dispatch._events.<utilitymethod>"
- # @staticemethod to allow easy "super" calls while in a metaclass
+ # @staticmethod to allow easy "super" calls while in a metaclass
# constructor.
cls.dispatch = dispatch_cls(None)
dispatch_cls._events = cls
"""Produce a proxied 'contains' expression using EXISTS.
This expression will be a composed product
- using the :meth:`.RelationshipProperty.Comparator.any`
- , :meth:`.RelationshipProperty.Comparator.has`,
+ using the :meth:`.RelationshipProperty.Comparator.any`,
+ :meth:`.RelationshipProperty.Comparator.has`,
and/or :meth:`.RelationshipProperty.Comparator.contains`
operators of the underlying proxied attributes.
"""
def id(cls):
if has_inherited_table(cls):
return Column(
- ForeignKey('myclass.id'), primary_key=True)
+ ForeignKey('myclass.id'), primary_key=True
+ )
else:
return Column(Integer, primary_key=True)
class _ModuleMarker(object):
- """"refers to a module name within
+ """Refers to a module name within
_decl_class_registry.
"""
from ..orm.query import Query
from ..orm.session import Session
-
__all__ = ["ShardedSession", "ShardedQuery"]
self._shard_id = None
def set_shard(self, shard_id):
- """return a new query, limited to a single shard ID.
+ """Return a new query, limited to a single shard ID.
- all subsequent operations with the returned query will
+ All subsequent operations with the returned query will
be against the single shard regardless of other state.
+
"""
q = self._clone()
lazy_loaded_from=None,
**kw
):
- """override the default Query._identity_lookup method so that we
+ """Override the default Query._identity_lookup method so that we
search for a given non-token primary key identity across all
possible identity tokens (e.g. shard ids).
or ``rowcount``, which is the sum of all the individual rowcount values.
.. versionadded:: 1.3
+
"""
__slots__ = ("result_proxies", "aggregate_rowcount")
return self.parent.parent
For the expression, things are not so clear. We'd need to construct a
-:class:`_query.Query` where we :meth:`_query.Query.join` twice along ``Node.
-parent`` to
-get to the ``grandparent``. We can instead return a transforming callable
-that we'll combine with the :class:`.Comparator` class to receive any
-:class:`_query.Query` object, and return a new one that's joined to the
-``Node.parent`` attribute and filtered based on the given criterion::
+:class:`_query.Query` where we :meth:`_query.Query.join` twice along
+``Node.parent`` to get to the ``grandparent``. We can instead return a
+transforming callable that we'll combine with the :class:`.Comparator` class to
+receive any :class:`_query.Query` object, and return a new one that's joined to
+the ``Node.parent`` attribute and filtered based on the given criterion::
from sqlalchemy.ext.hybrid import Comparator
class Node(Base):
__tablename__ = 'node'
- id =Column(Integer, primary_key=True)
+ id = Column(Integer, primary_key=True)
parent_id = Column(Integer, ForeignKey('node.id'))
parent = relationship("Node", remote_side=id)
will transform a :class:`_query.Query` first to join to ``Node.parent``,
then to
compare ``parent_alias`` using :attr:`.Operators.eq` against the left and right
-sides, passing into :class:`_query.Query.filter`:
+sides, passing into :meth:`_query.Query.filter`:
.. sourcecode:: pycon+sql
.. note::
- when referring to a hybrid property from an owning class (e.g.
+ When referring to a hybrid property from an owning class (e.g.
``SomeClass.some_hybrid``), an instance of
:class:`.QueryableAttribute` is returned, representing the
expression or comparator object as well as this hybrid object.
.. note::
- when referring to a hybrid property from an owning class (e.g.
+ When referring to a hybrid property from an owning class (e.g.
``SomeClass.some_hybrid``), an instance of
:class:`.QueryableAttribute` is returned, representing the
expression or comparator object as this hybrid object. However,
The value of this attribute must be a callable and will be passed a class
object. The callable must return one of:
- - An instance of an InstrumentationManager or subclass
+ - An instance of an :class:`.InstrumentationManager` or subclass
- An object implementing all or some of InstrumentationManager (TODO)
- A dictionary of callables, implementing all or some of the above (TODO)
- - An instance of a ClassManager or subclass
+ - An instance of a :class:`.ClassManager` or subclass
This attribute is consulted by SQLAlchemy instrumentation
resolution, once the :mod:`sqlalchemy.ext.instrumentation` module
__slots__ = ()
is_selectable = False
- """Return True if this object is an instance of """
- """:class:`expression.Selectable`."""
+ """Return True if this object is an instance of
+ :class:`_expression.Selectable`."""
is_aliased_class = False
"""True if this object is an instance of :class:`.AliasedClass`."""
"""
is_clause_element = False
- """True if this object is an instance of """
- """:class:`_expression.ClauseElement`."""
+ """True if this object is an instance of
+ :class:`_expression.ClauseElement`."""
extension_type = NOT_EXTENSION
"""The extension type, if any.
# this is a hack right now. The Query only knows how to
# make subsequent joins() without a given left-hand side
# from self._from_obj[0]. We need to ensure prop.secondary
- # is in the FROM. So we purposly put the mapper selectable
+ # is in the FROM. So we purposely put the mapper selectable
# in _from_obj[0] to ensure a user-defined join() later on
# doesn't fail, and secondary is then in _from_obj[1].
self._from_obj = (prop.mapper.selectable, prop.secondary)
class ClassManager(dict):
- """tracks state information at the class level."""
+ """Tracks state information at the class level."""
MANAGER_ATTR = base.DEFAULT_MANAGER_ATTR
STATE_ATTR = base.DEFAULT_STATE_ATTR
setattr(self.class_, self.MANAGER_ATTR, self)
def dispose(self):
- """Dissasociate this manager from its class."""
+ """Disassociate this manager from its class."""
delattr(self.class_, self.MANAGER_ATTR)
# this attribute is replaced by sqlalchemy.ext.instrumentation
-# when importred.
+# when imported.
_instrumentation_factory = InstrumentationFactory()
# these attributes are replaced by sqlalchemy.ext.instrumentation
from .. import util
from ..sql import util as sql_util
-
_new_runid = util.counter()
for key, set_callable in populators["expire"]:
if set_callable:
state.expired_attributes.add(key)
+
for key, populator in populators["new"]:
populator(state, dict_, row)
for key, populator in populators["delayed"]:
# concrete inheritance, the class manager might have some keys
# of attributes on the superclass that we didn't actually map.
# These could be mapped as "concrete, dont load" or could be completely
- # exluded from the mapping and we know nothing about them. Filter them
+ # excluded from the mapping and we know nothing about them. Filter them
# here to prevent them from coming through.
if attribute_names:
attribute_names = attribute_names.intersection(mapper.attrs.keys())
that specify ``delete-orphan`` cascade. This behavior is more
consistent with that of a persistent object, and allows behavior to
be consistent in more scenarios independently of whether or not an
- orphanable object has been flushed yet or not.
+ orphan object has been flushed yet or not.
See the change note and example at :ref:`legacy_is_orphan_addition`
for more detail on this change.
return self.class_
local_table = None
- """The :class:`expression.Selectable` which this :class:`_orm.Mapper`
+ """The :class:`_expression.Selectable` which this :class:`_orm.Mapper`
manages.
Typically is an instance of :class:`_schema.Table` or
"""
persist_selectable = None
- """The :class:`expression.Selectable` to which this :class:`_orm.Mapper`
+ """The :class:`_expression.Selectable` to which this :class:`_orm.Mapper`
is mapped.
- Typically an instance of :class:`_schema.Table`, :class:`_expression.Join`
- , or
- :class:`_expression.Alias`.
+ Typically an instance of :class:`_schema.Table`,
+ :class:`_expression.Join`, or :class:`_expression.Alias`.
The :attr:`_orm.Mapper.persist_selectable` is separate from
:attr:`_orm.Mapper.selectable` in that the former represents columns
database to return iterable result sets.
"""
-
from itertools import chain
from . import attributes
from ..sql.expression import _interpret_as_from
from ..sql.selectable import ForUpdateArg
-
__all__ = ["Query", "QueryContext", "aliased"]
lazy_loaded_from = None
"""An :class:`.InstanceState` that is using this :class:`_query.Query`
- for a
- lazy load operation.
+ for a lazy load operation.
The primary rationale for this attribute is to support the horizontal
sharding extension, where it is available within specific query
:meth:`_query.Query.with_session`
"""
+
self.session = session
self._polymorphic_adapters = {}
self._set_entities(entities)
return self._entities[0]
def _mapper_zero(self):
- """return the Mapper associated with the first QueryEntity."""
+ """Return the Mapper associated with the first QueryEntity."""
return self._entities[0].mapper
def _entity_zero(self):
return stmt
def subquery(self, name=None, with_labels=False, reduce_columns=False):
- """return the full SELECT statement represented by
+ """Return the full SELECT statement represented by
this :class:`_query.Query`, embedded within an
:class:`_expression.Alias`.
:class:`_query.Query`, converted
to a scalar subquery with a label of the given name.
- Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`.
+ Analogous to :meth:`_expression.SelectBase.label`.
"""
"""Return the full SELECT statement represented by this
:class:`_query.Query`, converted to a scalar subquery.
- Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.as_scalar`.
+ Analogous to :meth:`_expression.SelectBase.as_scalar`.
"""
.. note:: The :meth:`_query.Query.with_labels` method *only* applies
the output of :attr:`_query.Query.statement`, and *not* to any of
- the result-row invoking systems of :class:`_query.Query` itself, e.
- g.
- :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
+ the result-row invoking systems of :class:`_query.Query` itself,
+ e.g. :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
To execute
a query using :meth:`_query.Query.with_labels`, invoke the
:attr:`_query.Query.statement` using :meth:`.Session.execute`::
@_generative()
def _with_current_path(self, path):
- """indicate that this query applies to objects loaded
+ """Indicate that this query applies to objects loaded
within a certain path.
Used by deferred loaders (see strategies.py) which transfer
the order in which they correspond to the mapped
:class:`_schema.Table`
object's primary key columns, or if the
- :paramref:`_orm.Mapper.primary_key` configuration parameter were used
- , in
+ :paramref:`_orm.Mapper.primary_key` configuration parameter were
+ used, in
the order used for that parameter. For example, if the primary key
of a row is represented by the integer
digits "5, 10" the call would look like::
@_generative()
def correlate(self, *args):
- """Return a :class:`_query.Query`
- construct which will correlate the given
- FROM clauses to that of an enclosing :class:`_query.Query` or
- :func:`_expression.select`.
+ """Return a :class:`.Query` construct which will correlate the given
+ FROM clauses to that of an enclosing :class:`.Query` or
+ :func:`~.expression.select`.
The method here accepts mapped classes, :func:`.aliased` constructs,
and :func:`.mapper` constructs as arguments, which are resolved into
those being selected.
"""
+
fromclause = (
self.with_labels()
.enable_eagerloads(False)
def values(self, *columns):
"""Return an iterator yielding result tuples corresponding
- to the given list of columns"""
+ to the given list of columns.
+
+ """
if not columns:
return iter(())
def value(self, column):
"""Return a scalar result corresponding to the given
- column expression."""
+ column expression.
+
+ """
try:
return next(self.values(column))[0]
except StopIteration:
:ref:`relationship_loader_options`
"""
+
return self._options(False, *args)
def _conditional_options(self, *args):
this :class:`_query.Query`.
Functionality is passed straight through to
- :meth:`~sqlalchemy.sql.expression.Select.with_hint`,
+ :meth:`_expression.Select.with_hint`,
with the addition that ``selectable`` can be a
:class:`_schema.Table`, :class:`_expression.Alias`,
or ORM entity / mapped class
optimizer hints
"""
+
if selectable is not None:
selectable = inspect(selectable).selectable
self._with_hints += ((selectable, text, dialect_name),)
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`_expression.Select`.
+ """Add a statement hint to this :class:`_expression.Select`.
This method is similar to :meth:`_expression.Select.with_hint`
except that
@_generative()
def params(self, *args, **kwargs):
- r"""add values for bind parameters which may have been
+ r"""Add values for bind parameters which may have been
specified in filter().
- parameters may be specified using \**kwargs, or optionally a single
+ Parameters may be specified using \**kwargs, or optionally a single
dictionary as the first positional argument. The reason for both is
that \**kwargs is convenient, however some parameter dictionaries
contain unicode keys in which case \**kwargs cannot be used.
@_generative(_no_statement_condition, _no_limit_offset)
def filter(self, *criterion):
- r"""apply the given filtering criterion to a copy
+ r"""Apply the given filtering criterion to a copy
of this :class:`_query.Query`, using SQL expressions.
e.g.::
self._criterion = criterion
def filter_by(self, **kwargs):
- r"""apply the given filtering criterion to a copy
+ r"""Apply the given filtering criterion to a copy
of this :class:`_query.Query`, using keyword expressions.
e.g.::
@_generative(_no_statement_condition, _no_limit_offset)
def order_by(self, *criterion):
- """apply one or more ORDER BY criterion to the query and return
- the newly resulting ``Query``
+ """Apply one or more ORDER BY criterion to the query and return
+ the newly resulting :class:`_query.Query`.
All existing ORDER BY settings can be suppressed by
passing ``None`` - this will suppress any ordering configured
@_generative(_no_statement_condition, _no_limit_offset)
def group_by(self, *criterion):
- """apply one or more GROUP BY criterion to the query and return
- the newly resulting :class:`_query.Query`
+ """Apply one or more GROUP BY criterion to the query and return
+ the newly resulting :class:`_query.Query`.
All existing GROUP BY settings can be suppressed by
passing ``None`` - this will suppress any GROUP BY configured
on mappers as well.
- .. versionadded:: 1.1 GROUP BY can be cancelled by passing None,
- in the same way as ORDER BY.
+ .. versionadded:: 1.1 GROUP BY can be cancelled by passing
+ ``None``, in the same way as ORDER BY.
"""
@_generative(_no_statement_condition, _no_limit_offset)
def having(self, criterion):
- r"""apply a HAVING criterion to the query and return the
+ r"""Apply a HAVING criterion to the query and return the
newly resulting :class:`_query.Query`.
:meth:`_query.Query.having` is used in conjunction with
Where above, the call to :meth:`_query.Query.join` along
``User.addresses`` will result in SQL approximately equivalent to::
- SELECT user.id, User.name
+ SELECT user.id, user.name
FROM user JOIN address ON user.id = address.user_id
In the above example we refer to ``User.addresses`` as passed to
)
def outerjoin(self, *props, **kwargs):
- """Create a left outer join against this ``Query`` object's criterion
- and apply generatively, returning the newly resulting ``Query``.
+ """Create a left outer join against this :class:`_query.Query`
+ object's criterion and apply generatively, returning the newly
+ resulting :class:`_query.Query`.
- Usage is the same as the ``join()`` method.
+ Usage is the same as the :meth:`_query.Query.join` method.
"""
aliased, from_joinpoint, full = (
@_generative(_no_statement_condition, _no_limit_offset)
def _join(self, keys, outerjoin, full, create_aliases, from_joinpoint):
- """consumes arguments from join() or outerjoin(), places them into a
+ """Consumes arguments from :meth:`_query.Query.join` or
+ :meth:`_query.Query.outerjoin`, places them into a
consistent format with which to form the actual JOIN constructs.
"""
def _join_left_to_right(
self, left, right, onclause, prop, create_aliases, outerjoin, full
):
- """given raw "left", "right", "onclause" parameters consumed from
+ """Given raw "left", "right", "onclause" parameters consumed from
a particular key within _join(), add a real ORMJoin object to
our _from_obj list (or augment an existing one)
def _join_check_and_adapt_right_side(
self, left, right, onclause, prop, create_aliases
):
- """transform the "right" side of the join as well as the onclause
+ """Transform the "right" side of the join as well as the onclause
according to polymorphic mapping translations, aliasing on the query
or on the join, special cases where the right and left side have
overlapping tables.
@_generative(_no_statement_condition)
def limit(self, limit):
"""Apply a ``LIMIT`` to the query and return the newly resulting
- ``Query``.
+ :class:`_query.Query`.
"""
self._limit = limit
@_generative(_no_statement_condition)
def offset(self, offset):
"""Apply an ``OFFSET`` to the query and return the newly resulting
- ``Query``.
+ :class:`_query.Query`.
"""
self._offset = offset
@_generative(_no_statement_condition)
def distinct(self, *expr):
r"""Apply a ``DISTINCT`` to the query and return the newly resulting
- ``Query``.
+ :class:`_query.Query`.
.. note::
@_generative()
def prefix_with(self, *prefixes):
r"""Apply the prefixes to the query and return the newly resulting
- ``Query``.
+ :class:`_query.Query`.
:param \*prefixes: optional prefixes, typically strings,
not using any commas. In particular is useful for MySQL keywords
@_generative()
def suffix_with(self, *suffixes):
r"""Apply the suffix to the query and return the newly resulting
- ``Query``.
+ :class:`_query.Query`.
:param \*suffixes: optional suffixes, typically strings,
not using any commas.
class _QueryEntity(object):
- """represent an entity column returned within a Query result."""
+ """Represent an entity column returned within a Query result."""
def __new__(cls, *args, **kwargs):
if cls is _QueryEntity:
def set_with_polymorphic(
self, query, cls_or_mappers, selectable, polymorphic_on
):
- """Receive an update from a call to query.with_polymorphic().
+ """Receive an update from a call to
+ :meth:`_query.Query.with_polymorphic`.
- Note the newer style of using a free standing with_polymporphic()
- construct doesn't make use of this method.
+ Note the newer style of using a free standing
+ ``with_polymporphic()`` construct doesn't make use of this method.
"""
@inspection._self_inspects
class Bundle(InspectionAttr):
"""A grouping of SQL expressions that are returned by a
- :class:`_query.Query`
- under one namespace.
+ :class:`_query.Query` under one namespace.
The :class:`.Bundle` essentially allows nesting of the tuple-based
results returned by a column-oriented :class:`_query.Query` object.
class AliasOption(interfaces.MapperOption):
def __init__(self, alias):
r"""Return a :class:`.MapperOption` that will indicate to the
- :class:`_query.Query`
- that the main table has been aliased.
+ :class:`_query.Query` that the main table has been aliased.
This is a seldom-used option to suit the
very rare case that :func:`.contains_eager`
__all__ = ["Session", "SessionTransaction", "SessionExtension", "sessionmaker"]
_sessions = weakref.WeakValueDictionary()
-"""Weak-referencing dictionary of :class:`.Session` objects.
-"""
+"""Weak-referencing dictionary of :class:`.Session` objects."""
def _state_session(state):
"""Given an :class:`.InstanceState`, return the :class:`.Session`
- associated, if any.
+ associated, if any.
+
"""
if state.session_id:
try:
**Life Cycle**
- A :class:`.SessionTransaction` is associated with a :class:`.Session`
- in its default mode of ``autocommit=False`` immediately, associated
+ A :class:`.SessionTransaction` is associated with a :class:`.Session` in
+ its default mode of ``autocommit=False`` immediately, associated
with no database connections. As the :class:`.Session` is called upon
to emit SQL on behalf of various :class:`_engine.Engine` or
:class:`_engine.Connection`
:ref:`session_transaction_isolation`
:param \**kw:
- Additional keyword arguments are sent to :meth:`get_bind()`,
+ Additional keyword arguments are sent to :meth:`get_bind`,
allowing additional arguments to be passed to custom
implementations of :meth:`get_bind`.
def bind_mapper(self, mapper, bind):
"""Associate a :class:`_orm.Mapper` or arbitrary Python class with a
- "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`
- .
+ "bind", e.g. an :class:`_engine.Engine` or
+ :class:`_engine.Connection`.
The given entity is added to a lookup used by the
:meth:`.Session.get_bind` method.
The order of resolution is:
- 1. if mapper given and session.binds is present,
+ 1. if mapper given and :paramref:`.Session.binds` is present,
locate a bind based first on the mapper in use, then
on the mapped class in use, then on any base classes that are
present in the ``__mro__`` of the mapped class, from more specific
superclasses to more general.
- 2. if clause given and session.binds is present,
+ 2. if clause given and ``Session.binds`` is present,
locate a bind based on :class:`_schema.Table` objects
- found in the given clause present in session.binds.
- 3. if session.bind is present, return that.
+ found in the given clause present in ``Session.binds``.
+ 3. if ``Session.binds`` is present, return that.
4. if clause given, attempt to return a bind
linked to the :class:`_schema.MetaData` ultimately
associated with the clause.
.. seealso::
- ``load_on_pending`` at :func:`_orm.relationship` - this flag
+ :paramref:`_orm.relationship.load_on_pending` - this flag
allows per-relationship loading of many-to-ones on items that
are pending.
sess = Session()
- .. seealso:
+ .. seealso::
:ref:`session_getting` - introductory text on creating
sessions using :class:`.sessionmaker`.
@property
def transient(self):
- """Return true if the object is :term:`transient`.
+ """Return ``True`` if the object is :term:`transient`.
.. seealso::
@property
def pending(self):
- """Return true if the object is :term:`pending`.
+ """Return ``True`` if the object is :term:`pending`.
.. seealso::
@property
def deleted(self):
- """Return true if the object is :term:`deleted`.
+ """Return ``True`` if the object is :term:`deleted`.
An object that is in the deleted state is guaranteed to
not be within the :attr:`.Session.identity_map` of its parent
@property
def persistent(self):
- """Return true if the object is :term:`persistent`.
+ """Return ``True`` if the object is :term:`persistent`.
An object that is in the persistent state is guaranteed to
be within the :attr:`.Session.identity_map` of its parent
@property
def detached(self):
- """Return true if the object is :term:`detached`.
+ """Return ``True`` if the object is :term:`detached`.
.. seealso::
"""Return ``True`` if this object has an identity key.
This should always have the same value as the
- expression ``state.persistent or state.detached``.
+ expression ``state.persistent`` or ``state.detached``.
"""
return bool(self.key)
return bool(self.states)
def was_already_deleted(self, state):
- """return true if the given state is expired and was deleted
+ """Return ``True`` if the given state is expired and was deleted
previously.
"""
if state.expired:
return False
def is_deleted(self, state):
- """return true if the given state is marked as deleted
+ """Return ``True`` if the given state is marked as deleted
within this uowtransaction."""
return state in self.states and self.states[state][0]
return ret
def remove_state_actions(self, state):
- """remove pending actions for a state from the uowtransaction."""
+ """Remove pending actions for a state from the uowtransaction."""
isdelete = self.states[state][0]
def get_attribute_history(
self, state, key, passive=attributes.PASSIVE_NO_INITIALIZE
):
- """facade to attributes.get_state_history(), including
+ """Facade to attributes.get_state_history(), including
caching of results."""
hashkey = ("history", state, key)
rec.execute(self)
def finalize_flush_changes(self):
- """mark processed objects as clean / deleted after a successful
+ """Mark processed objects as clean / deleted after a successful
flush().
- this method is called within the flush() method after the
+ This method is called within the flush() method after the
execute() method has succeeded and the transaction has been committed.
"""
class CascadeOptions(frozenset):
- """Keeps track of the options sent to relationship().cascade"""
+ """Keeps track of the options sent to
+ :paramref:`.relationship.cascade`"""
_add_w_all_cascades = all_cascades.difference(
["all", "none", "delete-orphan"]
def identity_key(*args, **kwargs):
- """Generate "identity key" tuples, as are used as keys in the
+ r"""Generate "identity key" tuples, as are used as keys in the
:attr:`.Session.identity_map` dictionary.
This function has several call styles:
session.query(MyClass, my_alias).filter(MyClass.id > my_alias.id)
- The :func:`.aliased` function is used to create an ad-hoc mapping
- of a mapped class to a new selectable. By default, a selectable
- is generated from the normally mapped selectable (typically a
- :class:`_schema.Table`) using the :meth:`_expression.FromClause.alias`
- method.
- However, :func:`.aliased` can also be used to link the class to
- a new :func:`_expression.select` statement. Also, the
- :func:`.with_polymorphic`
- function is a variant of :func:`.aliased` that is intended to specify
- a so-called "polymorphic selectable", that corresponds to the union
- of several joined-inheritance subclasses at once.
+ The :func:`.aliased` function is used to create an ad-hoc mapping of a
+ mapped class to a new selectable. By default, a selectable is generated
+ from the normally mapped selectable (typically a :class:`_schema.Table`)
+ using the
+ :meth:`_expression.FromClause.alias` method. However, :func:`.aliased`
+ can also be
+ used to link the class to a new :func:`_expression.select` statement.
+ Also, the :func:`.with_polymorphic` function is a variant of
+ :func:`.aliased` that is intended to specify a so-called "polymorphic
+ selectable", that corresponds to the union of several joined-inheritance
+ subclasses at once.
For convenience, the :func:`.aliased` function also accepts plain
:class:`_expression.FromClause` constructs, such as a
:class:`_schema.Table` or
:func:`_expression.select` construct. In those cases, the
:meth:`_expression.FromClause.alias`
- method is called on the object and the new :class:`_expression.Alias`
- object
- returned. The returned :class:`_expression.Alias`
- is not ORM-mapped in this case.
+ method is called on the object and the new
+ :class:`_expression.Alias` object returned. The returned
+ :class:`_expression.Alias` is not
+ ORM-mapped in this case.
:param element: element to be aliased. Is normally a mapped class,
- but for convenience can also be a :class:`_expression.FromClause` element
- .
+ but for convenience can also be a :class:`_expression.FromClause`
+ element.
+
:param alias: Optional selectable unit to map the element to. This is
usually used to link the object to a subquery, and should be an aliased
select construct as one would produce from the
class Executable(Generative):
- """Mark a ClauseElement as supporting execution.
+ """Mark a :class:`_expression.ClauseElement` as supporting execution.
:class:`.Executable` is a superclass for all "statement" types
of objects, including :func:`select`, :func:`delete`, :func:`update`,
@_generative
def execution_options(self, **kw):
- """ Set non-SQL options for the statement which take effect during
+ """Set non-SQL options for the statement which take effect during
execution.
Execution options can be set on a per-statement or
self._execution_options = self._execution_options.union(kw)
def get_execution_options(self):
- """ Get the non-SQL options which will take effect during execution.
+ """Get the non-SQL options which will take effect during execution.
.. versionadded:: 1.3
.. seealso::
:meth:`.Executable.execution_options`
+
"""
return self._execution_options
@property
def bind(self):
"""Returns the :class:`_engine.Engine` or :class:`_engine.Connection`
- to
- which this :class:`.Executable` is bound, or None if none found.
+ to which this :class:`.Executable` is bound, or None if none found.
This is a traversal which checks locally, then
checks among the "from" clauses of associated objects
return repr([str(c) for c in self])
def replace(self, column):
- """add the given column to this collection, removing unaliased
+ """Add the given column to this collection, removing unaliased
versions of this column as well as existing columns with the
same key.
- e.g.::
+ E.g.::
t = Table('sometable', metadata, Column('col1', Integer))
t.columns.replace(Column('col1', Integer, key='columnone'))
- will remove the original 'col1' from the collection, and add
- the new column under the name 'columnname'.
+ will remove the original 'col1' from the collection, and add
+ the new column under the name 'columnname'.
Used by schema.Column to override columns during table reflection.
``.bind`` property.
:param target:
- Optional, defaults to None. The target SchemaItem for the
- execute call. Will be passed to the ``on`` callable if any,
- and may also provide string expansion data for the
- statement. See ``execute_at`` for more information.
+ Optional, defaults to None. The target :class:`_schema.SchemaItem`
+ for the execute call. Will be passed to the ``on`` callable if any,
+ and may also provide string expansion data for the statement.
+ See ``execute_at`` for more information.
"""
set during the call to ``create()``, ``create_all()``,
``drop()``, ``drop_all()``.
- If the callable returns a true value, the DDL statement will be
+ If the callable returns a True value, the DDL statement will be
executed.
:param state: any value which will be passed to the callable\_
def sort_tables(
tables, skip_fn=None, extra_dependencies=None,
):
- """sort a collection of :class:`_schema.Table` objects based on dependency
- .
+ """Sort a collection of :class:`_schema.Table` objects based on
+ dependency.
This is a dependency-ordered sort which will emit :class:`_schema.Table`
objects such that they will follow their dependent :class:`_schema.Table`
def sort_tables_and_constraints(
tables, filter_fn=None, extra_dependencies=None, _warn_for_cycles=False
):
- """sort a collection of :class:`_schema.Table` /
+ """Sort a collection of :class:`_schema.Table` /
:class:`_schema.ForeignKeyConstraint`
objects.
:param dialect_name: defaults to ``*``, if specified as the name
of a particular dialect, will apply these hints only when
that dialect is in use.
- """
+
+ """
if selectable is None:
selectable = self.table
@_generative
def values(self, *args, **kwargs):
- r"""specify a fixed VALUES clause for an INSERT statement, or the SET
+ r"""Specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.
Note that the :class:`_expression.Insert` and
as a single positional argument in order to form the VALUES or
SET clause of the statement. The forms that are accepted vary
based on whether this is an :class:`_expression.Insert` or an
- :class:`_expression.Update`
- construct.
+ :class:`_expression.Update` construct.
For either an :class:`_expression.Insert` or
- :class:`_expression.Update` construct, a
- single dictionary can be passed, which works the same as that of
- the kwargs form::
+ :class:`_expression.Update`
+ construct, a single dictionary can be passed, which works the same as
+ that of the kwargs form::
users.insert().values({"name": "some name"})
users.update().values({"name": "some new name"})
Also for either form but more typically for the
- :class:`_expression.Insert`
- construct, a tuple that contains an entry for every column in the
- table is also accepted::
+ :class:`_expression.Insert` construct, a tuple that contains an
+ entry for every column in the table is also accepted::
users.insert().values((5, "some name"))
- The :class:`_expression.Insert`
- construct also supports being passed a list
- of dictionaries or full-table-tuples, which on the server will
- render the less common SQL syntax of "multiple values" - this
- syntax is supported on backends such as SQLite, PostgreSQL, MySQL,
- but not necessarily others::
+ The :class:`_expression.Insert` construct also supports being
+ passed a list of dictionaries or full-table-tuples, which on the
+ server will render the less common SQL syntax of "multiple values" -
+ this syntax is supported on backends such as SQLite, PostgreSQL,
+ MySQL, but not necessarily others::
users.insert().values([
{"name": "some name"},
construct supports a special form which is a
list of 2-tuples, which when provided must be passed in conjunction
with the
- :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
+ :paramref:`_expression.update.preserve_parameter_order`
parameter.
This form causes the UPDATE statement to render the SET clauses
using the order of parameters given to
.. versionadded:: 1.0.10 - added support for parameter-ordered
UPDATE statements via the
- :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
+ :paramref:`_expression.update.preserve_parameter_order`
flag.
.. seealso::
:ref:`updates_order_parameters` - full example of the
- :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`
+ :paramref:`_expression.update.preserve_parameter_order`
flag
.. seealso::
added to any existing RETURNING clause, provided that
:meth:`.UpdateBase.returning` is not used simultaneously. The column
values will then be available on the result using the
- :attr:`_engine.ResultProxy.returned_defaults` accessor as a dictionary
- ,
+ :attr:`_engine.ResultProxy.returned_defaults` accessor as
+ a dictionary,
referring to values keyed to the :class:`_schema.Column`
object as well as
its ``.key``.
:param values: collection of values to be inserted; see
:meth:`_expression.Insert.values`
for a description of allowed formats here.
- Can be omitted entirely; a :class:`_expression.Insert`
- construct will also
- dynamically render the VALUES clause at execution time based on
- the parameters passed to :meth:`_engine.Connection.execute`.
+ Can be omitted entirely; a :class:`_expression.Insert` construct
+ will also dynamically render the VALUES clause at execution time
+ based on the parameters passed to :meth:`_engine.Connection.execute`.
:param inline: if True, no attempt will be made to retrieve the
SQL-generated default values to be provided within the statement;
@_generative
def where(self, whereclause):
- """return a new update() construct with the given expression added to
+ """Return a new update() construct with the given expression added to
its WHERE clause, joined to the existing clause via AND, if any.
"""
return d
def _annotate(self, values):
- """return a copy of this ClauseElement with annotations
+ """Return a copy of this ClauseElement with annotations
updated by the given dictionary.
"""
return Annotated(self, values)
def _with_annotations(self, values):
- """return a copy of this ClauseElement with annotations
+ """Return a copy of this ClauseElement with annotations
replaced by the given dictionary.
"""
return Annotated(self, values)
def _deannotate(self, values=None, clone=False):
- """return a copy of this :class:`_expression.ClauseElement`
+ """Return a copy of this :class:`_expression.ClauseElement`
with annotations
removed.
raise exc.ObjectNotExecutableError(self)
def unique_params(self, *optionaldict, **kwargs):
- """Return a copy with :func:`bindparam()` elements replaced.
+ """Return a copy with :func:`_expression.bindparam` elements
+ replaced.
- Same functionality as ``params()``, except adds `unique=True`
+ Same functionality as :meth:`_expression.ClauseElement.params`,
+ except adds `unique=True`
to affected bind parameters so that multiple statements can be
used.
return self._params(True, optionaldict, kwargs)
def params(self, *optionaldict, **kwargs):
- """Return a copy with :func:`bindparam()` elements replaced.
+ """Return a copy with :func:`_expression.bindparam` elements
+ replaced.
- Returns a copy of this ClauseElement with :func:`bindparam()`
+ Returns a copy of this ClauseElement with
+ :func:`_expression.bindparam`
elements replaced with values taken from the given dictionary::
>>> clause = column('x') + bindparam('foo')
return cloned_traverse(self, {}, {"bindparam": visit_bindparam})
def compare(self, other, **kw):
- r"""Compare this ClauseElement to the given ClauseElement.
+ r"""Compare this :class:`_expression.ClauseElement` to
+ the given :class:`_expression.ClauseElement`.
Subclasses should override the default behavior, which is a
straight identity comparison.
- \**kw are arguments consumed by subclass compare() methods and
- may be used to modify the criteria for comparison.
- (see :class:`_expression.ColumnElement`)
+ \**kw are arguments consumed by subclass ``compare()`` methods and
+ may be used to modify the criteria for comparison
+ (see :class:`_expression.ColumnElement`).
"""
return self is other
def self_group(self, against=None):
"""Apply a 'grouping' to this :class:`_expression.ClauseElement`.
- This method is overridden by subclasses to return a
- "grouping" construct, i.e. parenthesis. In particular
- it's used by "binary" expressions to provide a grouping
- around themselves when placed into a larger expression,
- as well as by :func:`_expression.select` constructs when placed into
- the FROM clause of another :func:`_expression.select`. (Note that
- subqueries should be normally created using the
- :meth:`_expression.Select.alias` method, as many platforms require
- nested SELECT statements to be named).
+ This method is overridden by subclasses to return a "grouping"
+ construct, i.e. parenthesis. In particular it's used by "binary"
+ expressions to provide a grouping around themselves when placed into a
+ larger expression, as well as by :func:`_expression.select`
+ constructs when placed into the FROM clause of another
+ :func:`_expression.select`. (Note that subqueries should be
+ normally created using the :meth:`_expression.Select.alias` method,
+ as many
+ platforms require nested SELECT statements to be named).
As expressions are composed together, the application of
:meth:`self_group` is automatic - end-user code should never
":meth:`_expression.ColumnElement.__and__`.",
)
def __and__(self, other):
- """'and' at the ClauseElement level.
- """
+ """'and' at the ClauseElement level."""
return and_(self, other)
@util.deprecated(
":meth:`_expression.ColumnElement.__or__`.",
)
def __or__(self, other):
- """'or' at the ClauseElement level.
- """
+ """'or' at the ClauseElement level."""
return or_(self, other)
def __invert__(self):
"""
key = None
- """the 'key' that in some circumstances refers to this object in a
+ """The 'key' that in some circumstances refers to this object in a
Python namespace.
This typically refers to the "key" of the column as present in the
- ``.c`` collection of a selectable, e.g. sometable.c["somekey"] would
- return a Column with a .key of "somekey".
+ ``.c`` collection of a selectable, e.g. ``sometable.c["somekey"]`` would
+ return a :class:`_schema.Column` with a ``.key`` of "somekey".
"""
else:
key = name
+
co = ColumnClause(
_as_truncated(name) if name_is_truncatable else name,
type_=getattr(self, "type", None),
This is a shortcut to the :func:`_expression.label` function.
- if 'name' is None, an anonymous label name will be generated.
+ If 'name' is ``None``, an anonymous label name will be generated.
"""
return Label(name, self, self.type)
@util.memoized_property
def anon_label(self):
- """provides a constant 'anonymous label' for this ColumnElement.
+ """Provides a constant 'anonymous label' for this ColumnElement.
This is a label() expression which will be named at compile time.
- The same label() is returned each time anon_label is called so
- that expressions can reference anon_label multiple times, producing
- the same label name at compile time.
+ The same label() is returned each time ``anon_label`` is called so
+ that expressions can reference ``anon_label`` multiple times,
+ producing the same label name at compile time.
- the compiler uses this function automatically at compile time
+ The compiler uses this function automatically at compile time
for expressions that are known to be 'unnamed' like binary
expressions and function calls.
while the placeholder ``:name_1`` is rendered in the appropriate form
for the target database, in this case the PostgreSQL database.
- Similarly, :func:`.bindparam` is invoked automatically
- when working with :term:`CRUD` statements as far as the "VALUES"
- portion is concerned. The :func:`_expression.insert`
- construct produces an
- ``INSERT`` expression which will, at statement execution time,
- generate bound placeholders based on the arguments passed, as in::
+ Similarly, :func:`.bindparam` is invoked automatically when working
+ with :term:`CRUD` statements as far as the "VALUES" portion is
+ concerned. The :func:`_expression.insert` construct produces an
+ ``INSERT`` expression which will, at statement execution time, generate
+ bound placeholders based on the arguments passed, as in::
stmt = users_table.insert()
result = connection.execute(stmt, name='Wendy')
INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}
- The :class:`_expression.Insert` construct,
- at compilation/execution time,
- rendered a single :func:`.bindparam` mirroring the column
- name ``name`` as a result of the single ``name`` parameter
- we passed to the :meth:`_engine.Connection.execute` method.
+ The :class:`_expression.Insert` construct, at
+ compilation/execution time, rendered a single :func:`.bindparam`
+ mirroring the column name ``name`` as a result of the single ``name``
+ parameter we passed to the :meth:`_engine.Connection.execute` method.
:param key:
the key (e.g. the name) for this bind param.
:func:`.outparam`
"""
+
if isinstance(key, ColumnClause):
type_ = key.type
key = key.key
def _with_value(self, value):
"""Return a copy of this :class:`.BindParameter` with the given value
set.
+
"""
cloned = self._clone()
cloned.value = value
def compare(self, other, **kw):
"""Compare this :class:`BindParameter` to the given
- clause."""
+ clause.
+
+ """
return (
isinstance(other, BindParameter)
)
def __getstate__(self):
- """execute a deferred value for serialization purposes."""
+ """Execute a deferred value for serialization purposes."""
d = self.__dict__.copy()
v = self.value
be eligible for autocommit if no transaction is in progress.
:param text:
- the text of the SQL statement to be created.
use ``:<param>``
+ the text of the SQL statement to be created.
Use ``:<param>``
to specify bind parameters; they will be compiled to their
engine-specific format.
@util.dependencies("sqlalchemy.sql.selectable")
def columns(self, selectable, *cols, **types):
- """Turn this :class:`_expression.TextClause` object into a
+ r"""Turn this :class:`_expression.TextClause` object into a
:class:`.TextAsFrom`
object that can be embedded into another statement.
@classmethod
def and_(cls, *clauses):
- """Produce a conjunction of expressions joined by ``AND``.
+ r"""Produce a conjunction of expressions joined by ``AND``.
E.g.::
clause being combined using :func:`.and_`::
stmt = select([users_table]).\
- where(users_table.c.name == 'wendy').\
- where(users_table.c.enrolled == True)
+ where(users_table.c.name == 'wendy').\
+ where(users_table.c.enrolled == True)
.. seealso::
:param type\_: an optional :class:`~sqlalchemy.types.TypeEngine`
object which will
provide result-set translation and additional expression semantics for
- this column. If left as None the type will be NullType.
+ this column. If left as ``None`` the type will be :class:`.NullType`.
.. seealso::
from sqlalchemy import desc, nullsfirst
- stmt = select([users_table]).\
- order_by(nullsfirst(desc(users_table.c.name)))
+ stmt = select([users_table]).order_by(
+ nullsfirst(desc(users_table.c.name)))
The SQL expression from the above would resemble::
rather than as its standalone
function version, as in::
- stmt = (select([users_table]).
- order_by(users_table.c.name.desc().nullsfirst())
- )
+ stmt = select([users_table]).order_by(
+ users_table.c.name.desc().nullsfirst())
.. seealso::
from sqlalchemy import desc, nullslast
- stmt = select([users_table]).\
- order_by(nullslast(desc(users_table.c.name)))
+ stmt = select([users_table]).order_by(
+ nullslast(desc(users_table.c.name)))
The SQL expression from the above would resemble::
rather than as its standalone
function version, as in::
- stmt = select([users_table]).\
- order_by(users_table.c.name.desc().nullslast())
+ stmt = select([users_table]).order_by(
+ users_table.c.name.desc().nullslast())
.. seealso::
ROW_NUMBER() OVER(ORDER BY some_column
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
- A value of None indicates "unbounded", a
+ A value of ``None`` indicates "unbounded", a
value of zero indicates "current row", and negative / positive
integers indicate "preceding" and "following":
of such, that will be used as the ORDER BY clause
of the OVER construct.
:param range\_: optional range clause for the window. This is a
- tuple value which can contain integer values or None, and will
- render a RANGE BETWEEN PRECEDING / FOLLOWING clause
+ tuple value which can contain integer values or ``None``,
+ and will render a RANGE BETWEEN PRECEDING / FOLLOWING clause.
.. versionadded:: 1.1
class _defer_name(_truncated_label):
- """mark a name as 'deferred' for the purposes of automated name
+ """Mark a name as 'deferred' for the purposes of automated name
generation.
"""
class _defer_none_name(_defer_name):
- """indicate a 'deferred' name that was ultimately the value None."""
+ """Indicate a 'deferred' name that was ultimately the value None."""
__slots__ = ()
def _as_truncated(value):
- """coerce the given value to :class:`._truncated_label`.
+ """Coerce the given value to :class:`._truncated_label`.
Existing :class:`._truncated_label` and
:class:`._anonymous_label` objects are passed
unchanged.
+
"""
if isinstance(value, _truncated_label):
def _expand_cloned(elements):
- """expand the given set of ClauseElements to be the set of all 'cloned'
+ """Expand the given set of ClauseElements to be the set of all 'cloned'
predecessors.
"""
def _select_iterables(elements):
- """expand tables into individual columns in the
+ """Expand tables into individual columns in the
given list of column expressions.
"""
def _cloned_intersection(a, b):
- """return the intersection of sets a and b, counting
+ """Return the intersection of sets a and b, counting
any overlap between 'cloned' predecessors.
The returned set is in terms of the entities present within 'a'.
def _is_column(col):
"""True if ``col`` is an instance of
- :class:`_expression.ColumnElement`. """
+ :class:`_expression.ColumnElement`."""
return isinstance(col, ColumnElement)
def _find_columns(clause):
- """locate Column objects within the given expression."""
+ """Locate Column objects within the given expression."""
cols = util.column_set()
traverse(clause, {}, {"column": cols.add})
@util.memoized_property
def name(self):
- """pull 'name' from parent, if not present"""
+ """Pull 'name' from parent, if not present"""
return self._Annotated__element.name
@util.memoized_property
def table(self):
- """pull 'table' from parent, if not present"""
+ """Pull 'table' from parent, if not present"""
return self._Annotated__element.table
@util.memoized_property
def key(self):
- """pull 'key' from parent, if not present"""
+ """Pull 'key' from parent, if not present"""
return self._Annotated__element.key
@util.memoized_property
if raw_identifier in case_sensitive_reg[identifier]:
util.warn(
"The GenericFunction '{}' is already registered and "
- "is going to be overriden.".format(identifier)
+ "is going to be overridden.".format(identifier)
)
reg[identifier] = fn
else:
@property
def columns(self):
- """The set of columns exported by this :class:`.FunctionElement`.
+ r"""The set of columns exported by this :class:`.FunctionElement`.
Function objects currently have no result column names built in;
this method returns a single-element column collection with
class array_agg(GenericFunction):
- """support for the ARRAY_AGG function.
+ """Support for the ARRAY_AGG function.
The ``func.array_agg(expr)`` construct returns an expression of
type :class:`_types.ARRAY`.
class mode(OrderedSetAgg):
- """implement the ``mode`` ordered-set aggregate function.
+ """Implement the ``mode`` ordered-set aggregate function.
This function must be used with the :meth:`.FunctionElement.within_group`
modifier to supply a sort expression to operate upon.
class percentile_cont(OrderedSetAgg):
- """implement the ``percentile_cont`` ordered-set aggregate function.
+ """Implement the ``percentile_cont`` ordered-set aggregate function.
This function must be used with the :meth:`.FunctionElement.within_group`
modifier to supply a sort expression to operate upon.
class percentile_disc(OrderedSetAgg):
- """implement the ``percentile_disc`` ordered-set aggregate function.
+ """Implement the ``percentile_disc`` ordered-set aggregate function.
This function must be used with the :meth:`.FunctionElement.within_group`
modifier to supply a sort expression to operate upon.
def op(
self, opstring, precedence=0, is_comparison=False, return_type=None
):
- """produce a generic operator function.
+ """Produce a generic operator function.
e.g.::
somecolumn LIKE :param || '%' ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
somecolumn LIKE '%' || :param ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
:param implicit_returning: True by default - indicates that
RETURNING can be used by default to fetch newly inserted primary key
values, for backends which support this. Note that
- create_engine() also provides an implicit_returning flag.
+ :func:`_sa.create_engine` also provides an ``implicit_returning``
+ flag.
:param include_columns: A list of strings indicating a subset of
columns to be loaded via the ``autoload`` operation; table columns who
:ref:`server_defaults` - complete discussion of server side
defaults
- :param server_onupdate: A :class:`.FetchedValue` instance
- representing a database-side default generation function,
- such as a trigger. This
- indicates to SQLAlchemy that a newly generated value will be
- available after updates. This construct does not actually
- implement any kind of generation function within the database,
- which instead must be specified separately.
+ :param server_onupdate: A :class:`.FetchedValue` instance
+ representing a database-side default generation function,
+ such as a trigger. This
+ indicates to SQLAlchemy that a newly generated value will be
+ available after updates. This construct does not actually
+ implement any kind of generation function within the database,
+ which instead must be specified separately.
.. seealso::
def copy(self, **kw):
"""Create a copy of this ``Column``, uninitialized.
- This is used in ``Table.tometadata``.
+ This is used in :meth:`_schema.Table.tometadata`.
"""
"""
def __init__(self, arg, **kwargs):
- """"Construct a new :class:`.ColumnDefault`.
+ """Construct a new :class:`.ColumnDefault`.
:param arg: argument representing the default value.
or minvalue has been reached.
:param cache: optional integer value; number of future values in the
sequence which are calculated in advance.
- :param order: optional boolean value; if true, renders the
+ :param order: optional boolean value; if ``True``, renders the
ORDER keyword.
name.
"""
.. versionadded:: 1.1.12
- :param order: optional boolean value; if true, renders the
+ :param order: optional boolean value; if ``True``, renders the
ORDER keyword, understood by Oracle, indicating the sequence is
definitively ordered. May be necessary to provide deterministic
ordering using Oracle RAC.
This list is either the original string arguments sent
to the constructor of the :class:`_schema.ForeignKeyConstraint`,
or if the constraint has been initialized with :class:`_schema.Column`
- objects, is the string .key of each element.
+ objects, is the string ``.key`` of each element.
.. versionadded:: 1.0.0
:param bind:
An Engine or Connection to bind to. May also be a string or URL
- instance, these are passed to create_engine() and this MetaData will
+ instance, these are passed to :func:`_sa.create_engine` and
+ this :class:`_schema.MetaData` will
be bound to the resulting engine.
:param reflect:
Optional, automatically load all tables from the bound database.
- Defaults to False. ``bind`` is required when this option is set.
+ Defaults to False. :paramref:`_schema.MetaData.bind` is required
+ when this option is set.
:param schema:
The default schema to use for the :class:`_schema.Table`,
Optional, controls how this column should be persisted by the
database. Possible values are:
- * None, the default, it will use the default persistence defined
- by the database.
- * True, will render ``GENERATED ALWAYS AS ... STORED``, or the
- equivalent for the target database if supported
- * False, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or the
+ * ``None``, the default, it will use the default persistence
+ defined by the database.
+ * ``True``, will render ``GENERATED ALWAYS AS ... STORED``, or the
equivalent for the target database if supported.
+ * ``False``, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or
+ the equivalent for the target database if supported.
Specifying ``True`` or ``False`` may raise an error when the DDL
- is emitted to the target database if the databse does not support
+ is emitted to the target database if the database does not support
that persistence option. Leaving this parameter at its default
of ``None`` is guaranteed to succeed for all databases that support
``GENERATED ALWAYS AS``.
r"""Return an :class:`_expression.Alias` object derived
from a :class:`_expression.Select`.
- name
- alias name
+ :param alias: the alias name
- \*args, \**kwargs
-
- all other arguments are delivered to the
- :func:`select` function.
+ :param \*args, \**kwargs: all other arguments are delivered to the
+ :func:`_expression.select` function.
"""
return Select(*args, **kwargs).alias(alias)
class Selectable(ClauseElement):
- """mark a class as being selectable"""
+ """Mark a class as being selectable."""
__visit_name__ = "selectable"
_is_lateral = False
_textual = False
- """a marker that allows us to easily distinguish a :class:`.TextAsFrom`
+ """A marker that allows us to easily distinguish a :class:`.TextAsFrom`
or similar object from other kinds of :class:`_expression.FromClause`
objects."""
)
@util.dependencies("sqlalchemy.sql.functions")
def count(self, functions, whereclause=None, **params):
- """return a SELECT COUNT generated against this
+ """Return a SELECT COUNT generated against this
:class:`_expression.FromClause`.
.. seealso::
)
def select(self, whereclause=None, **params):
- """return a SELECT of this :class:`_expression.FromClause`.
+ """Return a SELECT of this :class:`_expression.FromClause`.
.. seealso::
def join(self, right, onclause=None, isouter=False, full=False):
"""Return a :class:`_expression.Join` from this
- :class:`_expression.FromClause`
- to another :class:`FromClause`.
+ :class:`_expression.FromClause` to another
+ :class:`_expression.FromClause`.
E.g.::
return Join(self, right, onclause, True, full)
def alias(self, name=None, flat=False):
- """return an alias of this :class:`_expression.FromClause`.
+ """Return an alias of this :class:`_expression.FromClause`.
E.g.::
return TableSample._construct(self, sampling, name, seed)
def is_derived_from(self, fromclause):
- """Return True if this FromClause is 'derived' from the given
- FromClause.
+ """Return ``True`` if this :class:`_expression.FromClause` is
+ 'derived' from the given ``FromClause``.
An example would be an Alias of a Table is derived from that Table.
return fromclause in self._cloned_set
def _is_lexical_equivalent(self, other):
- """Return True if this FromClause and the other represent
- the same lexical identity.
+ """Return ``True`` if this :class:`_expression.FromClause` and
+ the other represent the same lexical identity.
This tests if either one is a copy of the other, or
if they are the same via annotation identity.
@util.dependencies("sqlalchemy.sql.util")
def replace_selectable(self, sqlutil, old, alias):
- """replace all occurrences of FromClause 'old' with the given Alias
+ """Replace all occurrences of FromClause 'old' with the given Alias
object, returning a copy of this :class:`_expression.FromClause`.
"""
@property
def description(self):
- """a brief description of this FromClause.
+ """A brief description of this :class:`_expression.FromClause`.
Used primarily for error message formatting.
return getattr(self, "name", self.__class__.__name__ + " object")
def _reset_exported(self):
- """delete memoized collections when a FromClause is cloned."""
+ """Delete memoized collections when a FromClause is cloned."""
self._memoized_property.expire_instance(self)
@_memoized_property
def primary_key(self):
- """Return the collection of Column objects which comprise the
- primary key of this FromClause."""
+ """Return the collection of :class:`_schema.Column` objects
+ which comprise the primary key of this FromClause.
+ """
self._init_collections()
self._populate_column_collection()
return self.primary_key
@_memoized_property
def foreign_keys(self):
- """Return the collection of ForeignKey objects which this
- FromClause references."""
+ """Return the collection of :class:`_schema.ForeignKey` objects
+ which this FromClause references.
+ """
self._init_collections()
self._populate_column_collection()
return self.foreign_keys
class Join(FromClause):
- """represent a ``JOIN`` construct between two
- :class:`_expression.FromClause`
- elements.
+ """Represent a ``JOIN`` construct between two
+ :class:`_expression.FromClause` elements.
The public constructor function for :class:`_expression.Join`
is the module-level
The returned object is an instance of :class:`_expression.Join`.
Similar functionality is also available via the
- :meth:`_expression.FromClause.outerjoin()` method on any
+ :meth:`_expression.FromClause.outerjoin` method on any
:class:`_expression.FromClause`.
:param left: The left side of the join.
.. seealso::
:meth:`_expression.FromClause.join` - method form,
- based on a given left side
+ based on a given left side.
- :class:`_expression.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced.
"""
a_subset=None,
consider_as_foreign_keys=None,
):
- """create a join condition between two tables or selectables.
+ """Create a join condition between two tables or selectables.
e.g.::
@util.dependencies("sqlalchemy.sql.util")
def alias(self, sqlutil, name=None, flat=False):
- r"""return an alias of this :class:`_expression.Join`.
+ r"""Return an alias of this :class:`_expression.Join`.
The default behavior here is to first produce a SELECT
construct from this :class:`_expression.Join`, then to produce an
clause when generated, e.g. ``SELECT * FROM table AS aliasname``.
Similar functionality is available via the
- :meth:`_expression.FromClause.alias` method
- available on all :class:`_expression.FromClause` subclasses.
- In terms of a
- SELECT object as generated from the :func:`_expression.select`
- function, the
- :meth:`_expression.SelectBase.alias` method returns an
- :class:`_expression.Alias` or
- similar object which represents a named, parenthesized subquery.
+ :meth:`_expression.FromClause.alias`
+ method available on all :class:`_expression.FromClause` subclasses.
+ In terms of
+ a SELECT object as generated from the :func:`_expression.select`
+ function, the :meth:`_expression.SelectBase.alias` method returns an
+ :class:`_expression.Alias` or similar object which represents a named,
+ parenthesized subquery.
When an :class:`_expression.Alias` is created from a
:class:`_schema.Table` object,
this has the effect of the table being rendered
as ``tablename AS aliasname`` in a SELECT statement.
- For :func:`_expression.select` objects,
- the effect is that of creating a named
- subquery, i.e. ``(select ...) AS aliasname``.
+ For :func:`_expression.select` objects, the effect is that of
+ creating a named subquery, i.e. ``(select ...) AS aliasname``.
The ``name`` parameter is optional, and provides the name
to use in the rendered SQL. If blank, an "anonymous" name
:class:`_expression.CTE`.
This method is a CTE-specific specialization of the
- :class:`_expression.FromClause.alias` method.
+ :meth:`_expression.FromClause.alias` method.
.. seealso::
In particular - MATERIALIZED and NOT MATERIALIZED.
:param name: name given to the common table expression. Like
- :meth:`._FromClause.alias`, the name can be left as ``None``
- in which case an anonymous symbol will be used at query
+ :meth:`_expression.FromClause.alias`, the name can be left as
+ ``None`` in which case an anonymous symbol will be used at query
compile time.
:param recursive: if ``True``, will render ``WITH RECURSIVE``.
A recursive common table expression is intended to be used in
def __init__(self, name, *columns, **kw):
"""Produce a new :class:`_expression.TableClause`.
- The object returned is an instance of :class:`_expression.TableClause`
- , which
+ The object returned is an instance of
+ :class:`_expression.TableClause`, which
represents the "syntactical" portion of the schema-level
:class:`_schema.Table` object.
It may be used to construct lightweight table constructs.
"""
def as_scalar(self):
- """return a 'scalar' representation of this selectable, which can be
+ """Return a 'scalar' representation of this selectable, which can be
used as a column expression.
Typically, a select statement which has only one column in its columns
return ScalarSelect(self)
def label(self, name):
- """return a 'scalar' representation of this selectable, embedded as a
+ """Return a 'scalar' representation of this selectable, embedded as a
subquery with a label.
.. seealso::
":meth:`.Executable.execution_options` method.",
)
def autocommit(self):
- """return a new selectable with the 'autocommit' flag set to
+ """Return a new selectable with the 'autocommit' flag set to
True.
+
"""
self._execution_options = self._execution_options.union(
@_generative
def apply_labels(self):
- """return a new selectable with the 'use_labels' flag set to True.
+ """Return a new selectable with the 'use_labels' flag set to True.
This will result in column expressions being generated using labels
against their table name, such as "SELECT somecolumn AS
@_generative
def limit(self, limit):
- """return a new selectable with the given LIMIT criterion
+ """Return a new selectable with the given LIMIT criterion
applied.
This is a numerical value which usually renders as a ``LIMIT``
@_generative
def offset(self, offset):
- """return a new selectable with the given OFFSET criterion
+ """Return a new selectable with the given OFFSET criterion
applied.
@_generative
def order_by(self, *clauses):
- r"""return a new selectable with the given list of ORDER BY
+ r"""Return a new selectable with the given list of ORDER BY
criterion applied.
e.g.::
stmt = select([table]).order_by(table.c.id, table.c.name)
- :param \*order_by: a series of :class:`_expression.ColumnElement`
+ :param \*clauses: a series of :class:`_expression.ColumnElement`
constructs
which will be used to generate an ORDER BY clause.
@_generative
def group_by(self, *clauses):
- r"""return a new selectable with the given list of GROUP BY
+ r"""Return a new selectable with the given list of GROUP BY
criterion applied.
e.g.::
stmt = select([table.c.name, func.max(table.c.stat)]).\
group_by(table.c.name)
- :param \*group_by: a series of :class:`_expression.ColumnElement`
+ :param \*clauses: a series of :class:`_expression.ColumnElement`
constructs
which will be used to generate an GROUP BY clause.
This is an **in-place** mutation method; the
:meth:`_expression.GenerativeSelect.group_by` method is preferred,
- as it
- provides standard :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
.. seealso::
class CompoundSelect(GenerativeSelect):
"""Forms the basis of ``UNION``, ``UNION ALL``, and other
- SELECT-based set operations.
+ SELECT-based set operations.
.. seealso::
A similar :func:`union()` method is available on all
:class:`_expression.FromClause` subclasses.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
- available keyword arguments are the same as those of
- :func:`select`.
+ :param \**kwargs:
+ available keyword arguments are the same as those of
+ :func:`select`.
"""
return CompoundSelect(CompoundSelect.UNION, *selects, **kwargs)
A similar :func:`union_all()` method is available on all
:class:`_expression.FromClause` subclasses.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_selectable.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_selectable.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_selectable.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_selectable.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
- """Represents a ``SELECT`` statement.
-
- """
+ """Represents a ``SELECT`` statement."""
__visit_name__ = "select"
All arguments which accept :class:`_expression.ClauseElement`
arguments also
accept string arguments, which will be converted as appropriate into
- either :func:`_expression.text()` or
- :func:`_expression.literal_column()` constructs.
+ either :func:`_expression.text` or
+ :func:`_expression.literal_column` constructs.
.. seealso::
for each column in the columns clause, which qualify each
column with its parent table's (or aliases) name so that name
conflicts between columns in different tables don't occur.
- The format of the label is <tablename>_<column>. The "c"
+ The format of the label is ``<tablename>_<column>``. The "c"
collection of the resulting :class:`_expression.Select`
object will use these
names as well for targeting column members.
return self._get_display_froms()
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`_expression.Select`.
+ """Add a statement hint to this :class:`_expression.Select`.
This method is similar to :meth:`_expression.Select.with_hint`
except that
@_memoized_property.method
def locate_all_froms(self):
- """return a Set of all FromClause elements referenced by this Select.
+ """Return a Set of all :class:`_expression.FromClause` elements
+ referenced by this Select.
This set is a superset of that returned by the ``froms`` property,
which is specifically for those FromClause elements that would
@property
def inner_columns(self):
- """an iterator of all ColumnElement expressions which would
+ """An iterator of all :class:`_expression.ColumnElement`
+ expressions which would
be rendered into the columns clause of the resulting SELECT statement.
"""
self._reset_exported()
def get_children(self, column_collections=True, **kwargs):
- """return child elements as per the ClauseElement specification."""
+ """Return child elements as per the ClauseElement specification."""
return (
(column_collections and list(self.columns) or [])
@_generative
def column(self, column):
- """return a new select() construct with the given column expression
- added to its columns clause.
+ """Return a new :func:`_expression.select` construct with
+ the given column expression added to its columns clause.
- E.g.::
+ E.g.::
- my_select = my_select.column(table.c.new_column)
+ my_select = my_select.column(table.c.new_column)
- See the documentation for
- :meth:`_expression.Select.with_only_columns`
- for guidelines on adding /replacing the columns of a
- :class:`_expression.Select` object.
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
+ for guidelines on adding /replacing the columns of a
+ :class:`_expression.Select` object.
"""
self.append_column(column)
@util.dependencies("sqlalchemy.sql.util")
def reduce_columns(self, sqlutil, only_synonyms=True):
- """Return a new :func`.select` construct with redundantly
+ """Return a new :func:`_expression.select` construct with redundantly
named, equivalently-valued columns removed from the columns clause.
"Redundant" here means two columns where one refers to the
comparison in the WHERE clause of the statement. The primary purpose
of this method is to automatically construct a select statement
with all uniquely-named columns, without the need to use
- table-qualified labels as :meth:`_expression.Select.apply_labels` does
- .
+ table-qualified labels as :meth:`_expression.Select.apply_labels`
+ does.
When columns are omitted based on foreign key, the referred-to
column is the one that's kept. When columns are omitted based on
>>> print(s2)
SELECT t2.b FROM t1 JOIN t2 ON t1.a=t2.a
- Care should also be taken to use the correct
- set of column objects passed to
- :meth:`_expression.Select.with_only_columns`.
- Since the method is essentially equivalent to calling the
- :func:`_expression.select` construct in the first place with the given
- columns, the columns passed to
- :meth:`_expression.Select.with_only_columns`
- should usually be a subset of those which were passed
- to the :func:`_expression.select` construct,
- not those which are available
- from the ``.c`` collection of that :func:`_expression.select`. That
- is::
+ Care should also be taken to use the correct set of column objects
+ passed to :meth:`_expression.Select.with_only_columns`.
+ Since the method is
+ essentially equivalent to calling the :func:`_expression.select`
+ construct in the first place with the given columns, the columns passed
+ to :meth:`_expression.Select.with_only_columns`
+ should usually be a subset of
+ those which were passed to the :func:`_expression.select`
+ construct, not those which are available from the ``.c`` collection of
+ that :func:`_expression.select`. That is::
s = select([table1.c.a, table1.c.b]).select_from(table1)
s = s.with_only_columns([table1.c.b])
FROM (SELECT t1.a AS a, t1.b AS b
FROM t1), t1
- Since the :func:`_expression.select` construct is essentially being
- asked to select both from ``table1`` as well as itself.
+ Since the :func:`_expression.select` construct is essentially
+ being asked to select both from ``table1`` as well as itself.
"""
self._reset_exported()
@_generative
def where(self, whereclause):
- """return a new select() construct with the given expression added to
+ """Return a new :func:`_expression.select` construct with
+ the given expression added to
its WHERE clause, joined to the existing clause via AND, if any.
"""
@_generative
def having(self, having):
- """return a new select() construct with the given expression added to
+ """Return a new :func:`_expression.select` construct with
+ the given expression added to
its HAVING clause, joined to the existing clause via AND, if any.
"""
@_generative
def distinct(self, *expr):
- r"""Return a new select() construct which will apply DISTINCT to its
- columns clause.
+ r"""Return a new :func:`_expression.select` construct which
+ will apply DISTINCT to its columns clause.
:param \*expr: optional column expressions. When present,
the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>>)``
@_generative
def select_from(self, fromclause):
- r"""return a new :func:`_expression.select` construct with the
- given FROM expression
+ r"""Return a new :func:`_expression.select` construct with the
+ given FROM expression(s)
merged into its list of FROM objects.
E.g.::
@_generative
def correlate(self, *fromclauses):
- r"""return a new :class:`_expression.Select`
+ r"""Return a new :class:`_expression.Select`
which will correlate the given FROM
clauses to that of an enclosing :class:`_expression.Select`.
:ref:`correlated_subqueries`
"""
+
self._auto_correlate = False
if fromclauses and fromclauses[0] is None:
self._correlate = ()
@_generative
def correlate_except(self, *fromclauses):
- r"""return a new :class:`_expression.Select`
+ r"""Return a new :class:`_expression.Select`
which will omit the given FROM
clauses from the auto-correlation process.
)
def append_correlation(self, fromclause):
- """append the given correlation expression to this select()
- construct.
+ """Append the given correlation expression to this
+ :func:`_expression.select` construct.
This is an **in-place** mutation method; the
:meth:`_expression.Select.correlate` method is preferred,
- as it provides
- standard :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
"""
)
def append_column(self, column):
- """append the given column expression to the columns clause of this
- select() construct.
+ """Append the given column expression to the columns clause of this
+ :func:`_expression.select` construct.
E.g.::
This is an **in-place** mutation method; the
:meth:`_expression.Select.column` method is preferred,
- as it provides standard
- :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
See the documentation for :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
self._raw_columns = self._raw_columns + [column]
def append_prefix(self, clause):
- """append the given columns clause prefix expression to this select()
- construct.
+ """Append the given columns clause prefix expression to this
+ :func:`_expression.select` construct.
This is an **in-place** mutation method; the
:meth:`_expression.Select.prefix_with` method is preferred,
- as it provides
- standard :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
"""
clause = _literal_as_text(clause)
self._prefixes = self._prefixes + (clause,)
def append_whereclause(self, whereclause):
- """append the given expression to this select() construct's WHERE
- criterion.
+ """Append the given expression to this :func:`_expression.select`
+ construct's WHERE criterion.
The expression will be joined to existing WHERE criterion via AND.
This is an **in-place** mutation method; the
:meth:`_expression.Select.where` method is preferred,
- as it provides standard
- :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
"""
self._whereclause = and_(True_._ifnone(self._whereclause), whereclause)
def append_having(self, having):
- """append the given expression to this select() construct's HAVING
- criterion.
+ """Append the given expression to this :func:`_expression.select`
+ construct's HAVING criterion.
The expression will be joined to existing HAVING criterion via AND.
This is an **in-place** mutation method; the
:meth:`_expression.Select.having` method is preferred,
- as it provides standard
- :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
"""
self._reset_exported()
self._having = and_(True_._ifnone(self._having), having)
def append_from(self, fromclause):
- """append the given FromClause expression to this select() construct's
- FROM clause.
+ """Append the given FromClause expression to this
+ :func:`_expression.select` construct's FROM clause.
This is an **in-place** mutation method; the
:meth:`_expression.Select.select_from` method is preferred,
- as it provides
- standard :term:`method chaining`.
+ as it provides standard :term:`method chaining`.
"""
self._reset_exported()
)
def self_group(self, against=None):
- """return a 'grouping' construct as per the ClauseElement
- specification.
+ """Return a 'grouping' construct as per the
+ :class:`_expression.ClauseElement` specification.
This produces an element that can be embedded in an expression. Note
that this method is called automatically as needed when constructing
return FromGrouping(self)
def union(self, other, **kwargs):
- """return a SQL UNION of this select() construct against the given
- selectable."""
+ """Return a SQL ``UNION`` of this select() construct against
+ the given selectable.
+ """
return CompoundSelect._create_union(self, other, **kwargs)
def union_all(self, other, **kwargs):
- """return a SQL UNION ALL of this select() construct against the given
- selectable.
+ """Return a SQL ``UNION ALL`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_union_all(self, other, **kwargs)
def except_(self, other, **kwargs):
- """return a SQL EXCEPT of this select() construct against the given
- selectable."""
+ """Return a SQL ``EXCEPT`` of this select() construct against
+ the given selectable.
+ """
return CompoundSelect._create_except(self, other, **kwargs)
def except_all(self, other, **kwargs):
- """return a SQL EXCEPT ALL of this select() construct against the
- given selectable.
+ """Return a SQL ``EXCEPT ALL`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_except_all(self, other, **kwargs)
def intersect(self, other, **kwargs):
- """return a SQL INTERSECT of this select() construct against the given
- selectable.
+ """Return a SQL ``INTERSECT`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_intersect(self, other, **kwargs)
def intersect_all(self, other, **kwargs):
- """return a SQL INTERSECT ALL of this select() construct against the
- given selectable.
+ """Return a SQL ``INTERSECT ALL`` of this select() construct
+ against the given selectable.
"""
return CompoundSelect._create_intersect_all(self, other, **kwargs)
return e
def select_from(self, clause):
- """return a new :class:`_expression.Exists` construct,
+ """Return a new :class:`_expression.Exists` construct,
applying the given
expression to the :meth:`_expression.Select.select_from`
method of the select
return e
def where(self, clause):
- """return a new exists() construct with the given expression added to
+ """Return a new :func:`_expression.exists` construct with the
+ given expression added to
its WHERE clause, joined to the existing clause via AND, if any.
"""
:class:`_expression.SelectBase`
interface.
- This allows the :class:`_expression.TextClause` object to gain a ``.
- c`` collection
+ This allows the :class:`_expression.TextClause` object to gain a
+ ``.c`` collection
and other FROM-like capabilities such as
:meth:`_expression.FromClause.alias`,
:meth:`_expression.SelectBase.cte`, etc.
type that is explicitly known to be a decimal type
(e.g. ``DECIMAL``, ``NUMERIC``, others) and not a floating point
type (e.g. ``FLOAT``, ``REAL``, others).
- If the database column on the server is in fact a floating-point type
+ If the database column on the server is in fact a floating-point
type, such as ``FLOAT`` or ``REAL``, use the :class:`.Float`
type or a subclass, otherwise numeric coercion between
``float``/``Decimal`` may or may not function as expected.
return self.metadata and self.metadata.bind or None
def create(self, bind=None, checkfirst=False):
- """Issue CREATE ddl for this type, if applicable."""
+ """Issue CREATE DDL for this type, if applicable."""
if bind is None:
bind = _bind_or_error(self)
t.create(bind=bind, checkfirst=checkfirst)
def drop(self, bind=None, checkfirst=False):
- """Issue DROP ddl for this type, if applicable."""
+ """Issue DROP DDL for this type, if applicable."""
if bind is None:
bind = _bind_or_error(self)
default, the database value of the enumeration is used as the
sorting function.
- .. versionadded:: 1.3.8
+ .. versionadded:: 1.3.8
)
While it is possible to use :attr:`_types.JSON.NULL` in this context, the
- :attr:`_types.JSON.NULL` value will be returned as the value of the column
- ,
+ :attr:`_types.JSON.NULL` value will be returned as the value of the
+ column,
which in the context of the ORM or other repurposing of the default
value, may not be desirable. Using a SQL expression means the value
will be re-fetched from the database within the context of retrieving
self.none_as_null = none_as_null
class JSONElementType(TypeEngine):
- """common function for index / path elements in a JSON expression."""
+ """Common function for index / path elements in a JSON expression."""
_integer = Integer()
_string = String()
__visit_name__ = "ARRAY"
zero_indexes = False
- """if True, Python zero-based indexes should be interpreted as one-based
+ """If True, Python zero-based indexes should be interpreted as one-based
on the SQL expression side."""
class Comparator(Indexable.Comparator, Concatenable.Comparator):
)
def bind_expression(self, bindvalue):
- """"Given a bind value (i.e. a :class:`.BindParameter` instance),
+ """Given a bind value (i.e. a :class:`.BindParameter` instance),
return a SQL expression in its place.
This is typically a SQL function that wraps the existing bound
"""Return the corresponding type object from the underlying DB-API, if
any.
- This can be useful for calling ``setinputsizes()``, for example.
+ This can be useful for calling ``setinputsizes()``, for example.
"""
return None
def copy(self, **kw):
return MyType(self.impl.length)
- The class-level "impl" attribute is required, and can reference any
- TypeEngine class. Alternatively, the load_dialect_impl() method
- can be used to provide different type classes based on the dialect
- given; in this case, the "impl" variable can reference
+ The class-level ``impl`` attribute is required, and can reference any
+ :class:`.TypeEngine` class. Alternatively, the :meth:`load_dialect_impl`
+ method can be used to provide different type classes based on the dialect
+ given; in this case, the ``impl`` variable can reference
``TypeEngine`` as a placeholder.
Types that receive a Python type that isn't similar to the ultimate type
coerce_to_is_types = (util.NoneType,)
"""Specify those Python types which should be coerced at the expression
level to "IS <constant>" when compared using ``==`` (and same for
- ``IS NOT`` in conjunction with ``!=``.
+ ``IS NOT`` in conjunction with ``!=``).
For most SQLAlchemy types, this includes ``NoneType``, as well as
``bool``.
def _generate_dispatch(cls):
"""Return an optimized visit dispatch function for the cls
for use by the compiler.
+
"""
if "__visit_name__" in cls.__dict__:
visit_name = cls.__visit_name__
return meth(obj, **kw)
def iterate(self, obj):
- """traverse the given expression structure, returning an iterator
+ """Traverse the given expression structure, returning an iterator
of all elements.
"""
return iterate(obj, self.__traverse_options__)
def traverse(self, obj):
- """traverse and visit the given expression structure."""
+ """Traverse and visit the given expression structure."""
return traverse(obj, self.__traverse_options__, self._visitor_dict)
@property
def visitor_iterator(self):
- """iterate through this visitor and each 'chained' visitor."""
+ """Iterate through this visitor and each 'chained' visitor."""
v = self
while v:
v = getattr(v, "_next", None)
def chain(self, visitor):
- """'chain' an additional ClauseVisitor onto this ClauseVisitor.
+ """'Chain' an additional ClauseVisitor onto this ClauseVisitor.
- the chained visitor will receive all visit events after this one.
+ The chained visitor will receive all visit events after this one.
"""
tail = list(self.visitor_iterator)[-1]
return [self.traverse(x) for x in list_]
def traverse(self, obj):
- """traverse and visit the given expression structure."""
+ """Traverse and visit the given expression structure."""
return cloned_traverse(
obj, self.__traverse_options__, self._visitor_dict
"""
def replace(self, elem):
- """receive pre-copied elements during a cloning traversal.
+ """Receive pre-copied elements during a cloning traversal.
If the method returns a new element, the element is used
instead of creating a simple copy of the element. Traversal
return None
def traverse(self, obj):
- """traverse and visit the given expression structure."""
+ """Traverse and visit the given expression structure."""
def replace(elem):
for v in self.visitor_iterator:
def iterate(obj, opts):
- r"""traverse the given expression structure, returning an iterator.
+ r"""Traverse the given expression structure, returning an iterator.
- traversal is configured to be breadth-first.
+ Traversal is configured to be breadth-first.
The central API feature used by the :func:`.visitors.iterate` and
:func:`.visitors.iterate_depthfirst` functions is the
:meth:`_expression.ClauseElement.get_children` method of
- :class:`_expression.ClauseElement`
- objects. This method should return all the
- :class:`_expression.ClauseElement` objects
- which are associated with a particular :class:`_expression.ClauseElement`
- object.
- For example, a :class:`.Case` structure will refer to a series of
- :class:`_expression.ColumnElement`
- objects within its "whens" and "else\_" member
- variables.
+ :class:`_expression.ClauseElement` objects. This method should return all
+ the :class:`_expression.ClauseElement` objects which are associated with a
+ particular :class:`_expression.ClauseElement` object. For example, a
+ :class:`.Case` structure will refer to a series of
+ :class:`_expression.ColumnElement` objects within its "whens" and "else\_"
+ member variables.
:param obj: :class:`_expression.ClauseElement` structure to be traversed
def iterate_depthfirst(obj, opts):
- """traverse the given expression structure, returning an iterator.
+ """Traverse the given expression structure, returning an iterator.
- traversal is configured to be depth-first.
+ Traversal is configured to be depth-first.
:param obj: :class:`_expression.ClauseElement` structure to be traversed
def traverse_using(iterator, obj, visitors):
- """visit the given expression structure using the given iterator of
+ """Visit the given expression structure using the given iterator of
objects.
:func:`.visitors.traverse_using` is usually called internally as the result
def traverse(obj, opts, visitors):
- """traverse and visit the given expression structure using the default
+ """Traverse and visit the given expression structure using the default
iterator.
e.g.::
def cloned_traverse(obj, opts, visitors):
- """clone the given expression structure, allowing modifications by
+ """Clone the given expression structure, allowing modifications by
visitors.
Traversal usage is the same as that of :func:`.visitors.traverse`.
if obj is not None:
obj = clone(obj)
-
clone = None # remove gc cycles
-
return obj
def replacement_traverse(obj, opts, replace):
- """clone the given expression structure, allowing element
+ """Clone the given expression structure, allowing element
replacement by a given replacement function.
This function is very similar to the :func:`.visitors.cloned_traverse`
function, except instead of being passed a dictionary of visitors, all
elements are unconditionally passed into the given replace function.
The replace function then has the option to return an entirely new object
- which will replace the one given. if it returns ``None``, then the object
+ which will replace the one given. If it returns ``None``, then the object
is kept in place.
The difference in usage between :func:`.visitors.cloned_traverse` and
}
def combinations(self, *arg_sets, **kw):
- """facade for pytest.mark.paramtrize.
+ """Facade for pytest.mark.parametrize.
Automatically derives argument names from the callable which in our
case is always a method on a class with positional arguments.
class ProfileStatsFile(object):
- """"Store per-platform/fn profiling results in a file.
+ """Store per-platform/fn profiling results in a file.
We're still targeting Py2.5, 2.4 on 0.7 with no dependencies,
so no json lib :( need to roll something silly
"""
The underlying reflect call accepts an optional schema argument.
This is for determining which database schema to load.
- This test verifies that prepare can accept an optiona schema argument
- and pass it to reflect.
+ This test verifies that prepare can accept an optional schema
+ argument and pass it to reflect.
"""
Base = automap_base(metadata=self.metadata)
engine_mock = Mock()
"""Exercises for eager loading.
-Derived from mailing list-reported problems and trac tickets.
+Derived from mailing list-reported problems and issue tracker issues.
These are generally very old 0.1-era tests and at some point should
be cleaned up and modernized.
).engine
is e2
)
-
sess.close()
def test_bind_arg(self):
class DeprecatedMapperExtensionTest(_fixtures.FixtureTest):
-
"""Superseded by MapperEventsTest - test backwards
- compatibility of MapperExtension."""
+ compatibility of MapperExtension.
+
+ """
run_inserts = None
with expect_warnings(
"The GenericFunction 'replaceable_func' is already registered and "
- "is going to be overriden.",
+ "is going to be overridden.",
regex=False,
):
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
