The above will respond to ``create_engine("mysql+foodialect://")`` and load the
``MyMySQLDialect`` class from the ``myapp.dialect`` module.
-.. versionadded:: 0.8
Connection / Engine API
=======================
Index('idx_col34', 'col3', 'col4', unique=True)
)
-.. versionadded:: 0.7
- Support of "inline" definition inside the :class:`.Table`
- for :class:`.Index`\ .
-
The :class:`~sqlalchemy.schema.Index` object also supports its own ``create()`` method:
.. sourcecode:: python+sql
Index('someindex', func.lower(mytable.c.somecol))
-.. versionadded:: 0.8 :class:`.Index` supports SQL expressions and functions
- as well as plain columns.
-
Index API
---------
{'pgp_sym_decrypt_1': 'this is my passphrase', 'username_1': 'some user'}
-.. versionadded:: 0.8 Added the :meth:`.TypeEngine.bind_expression` and
- :meth:`.TypeEngine.column_expression` methods.
-
-See also:
+.. seealso::
-:ref:`examples_postgis`
+ :ref:`examples_postgis`
.. _types_operators:
SQLAlchemy includes an event API which publishes a wide variety of hooks into
the internals of both SQLAlchemy Core and ORM.
-.. versionadded:: 0.7
- The system supersedes the previous system of "extension", "proxy",
- and "listener" classes.
-
Event Registration
------------------
Multiple Table Updates
----------------------
-.. versionadded:: 0.7.4
-
The PostgreSQL, Microsoft SQL Server, and MySQL backends all support UPDATE statements
that refer to multiple tables. For PG and MSSQL, this is the "UPDATE FROM" syntax,
which updates one table at a time, but can reference additional tables in an additional
to associate each user-defined composite object with all parent associations.
Please see the example in :ref:`mutable_composites`.
-.. versionchanged:: 0.7
- In-place changes to an existing composite value are no longer
- tracked automatically; the functionality is superseded by the
- :class:`.MutableComposite` class.
-
.. _composite_operations:
Redefining Comparison Operations for Composites
hv = s.query(HasVertex).filter(
HasVertex.vertex == Vertex(Point(1, 2), Point(3, 4))).first()
print(hv.vertex.start)
- print(hv.vertex.end)
\ No newline at end of file
+ print(hv.vertex.end)
q = session.query(User).join(*User.keywords.attr)
-.. versionadded:: 0.7.3
- :attr:`~.AssociationProxy.attr` attribute in a star-args context.
-
:attr:`~.AssociationProxy.attr` is composed of :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`,
which are just synonyms for the actual proxied attributes, and can also
be used for querying::
join(uka, User.keywords.local_attr).\
join(ka, User.keywords.remote_attr)
-.. versionadded:: 0.7.3
- :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`,
- synonyms for the actual proxied attributes, and usable for querying.
-
API Documentation
-----------------
indicates an existing :class:`.Column` is trying to be re-assigned to
a different owning :class:`.Table`.
-.. versionadded:: 0.8 :class:`.declared_attr` can be used on a non-mixin
- class, and the returned :class:`.Column` or other mapped attribute
- will be applied to the mapping as any other attribute. Previously,
- the resulting attribute would be ignored, and also result in a warning
- being emitted when a subclass was created.
-
-.. versionadded:: 0.8 :class:`.declared_attr`, when used either with a
- mixin or non-mixin declarative class, can return an existing
- :class:`.Column` already assigned to the parent :class:`.Table`,
- to indicate that the re-assignment of the :class:`.Column` should be
- skipped, however should still be mapped on the target class,
- in order to resolve duplicate column conflicts.
-
The same concept can be used with mixin classes (see
:ref:`declarative_mixins`)::
extension can use the resulting :class:`.Column` object as returned by
the method without the need to copy it.
-.. versionchanged:: 0.6.5 Rename ``sqlalchemy.util.classproperty``
- into :class:`~.declared_attr`.
-
Columns generated by :class:`~.declared_attr` can also be
referenced by ``__mapper_args__`` to a limited degree, currently
by ``polymorphic_on`` and ``version_id_col``; the declarative extension
:func:`.association_proxy` object is created for each of the ``TypeA``
and ``TypeB`` classes.
-.. versionadded:: 0.8 :class:`.declared_attr` is usable with non-mapped
- attributes, including user-defined attributes as well as
- :func:`.association_proxy`.
-
.. _decl_mixin_inheritance:
Controlling table inheritance with mixins
primaryjoin="address.Address.user_id=="
"User.id")
-.. versionadded:: 0.8
- module-qualified paths can be used when specifying string arguments
- with Declarative, in order to specify specific modules.
-
Two alternatives also exist to using string-based attributes. A lambda
can also be used, which will be evaluated after all mappers have been
configured::
Base.prepare(e)
-.. versionadded:: 0.8
- Added :class:`.DeferredReflection`.
:func:`.column_property`, :func:`.relationship`, or :func:`.composite`
functions.
- .. versionadded:: 0.8 Added support for .info to all
- :class:`.MapperProperty` subclasses.
-
.. versionchanged:: 1.0.0 :attr:`.InspectionAttr.info` moved
from :class:`.MapperProperty` so that it can apply to a wider
variety of ORM and extension constructs.
billing_address = relationship("Address", foreign_keys="Customer.billing_address_id")
-.. versionchanged:: 0.8
- :func:`.relationship` can resolve ambiguity between foreign key targets on the
- basis of the ``foreign_keys`` argument alone; the :paramref:`~.relationship.primaryjoin`
- argument is no longer needed in this situation.
-
.. _relationship_primaryjoin:
Specifying Alternate Join Conditions
``folder_id`` column, which it recognizes as uniquely present on
the "remote" side.
-.. versionadded:: 0.8
- Support for self-referential composite keys in :func:`.relationship`
- where a column points to itself.
-
Self-Referential Query Strategies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
fdb is a kinterbasdb compatible DBAPI for Firebird.
- .. versionadded:: 0.8 - Support for the fdb Firebird driver.
-
.. versionchanged:: 0.9 - The fdb dialect is now the default dialect
under the ``firebird://`` URL space, as ``fdb`` is now the official
Python driver for Firebird.
Please read the fdb and/or kinterbasdb DBAPI documentation in order to
understand the implications of this flag.
- .. versionadded:: 0.8.2 - ``retaining`` keyword argument specifying
- transaction retaining behavior - in 0.8 it defaults to ``True``
- for backwards compatibility.
-
.. versionchanged:: 0.9.0 - the ``retaining`` flag defaults to ``False``.
In 0.8 it defaulted to ``True``.
login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL
-.. versionadded:: 0.8 Character collations are now part of the base string
- types.
-
LIMIT/OFFSET Support
--------------------
would render the index as ``CREATE INDEX my_index ON table (x) INCLUDE (y)``
-.. versionadded:: 0.8
-
Index ordering
^^^^^^^^^^^^^^
would render the index as ``CREATE INDEX my_index ON table (x DESC)``
-.. versionadded:: 0.8
-
.. seealso::
:ref:`schema_indexes_functional`
existing database structures. The detection is entirely automatic and
no special configuration is needed to use either quoting style.
-.. versionchanged:: 0.6 detection of ANSI quoting style is entirely automatic,
- there's no longer any end-user ``create_engine()`` options in this regard.
-
MySQL SQL Extensions
--------------------
a column of an index if it is for a CHAR, VARCHAR, TEXT, BINARY, VARBINARY and
BLOB.
-.. versionadded:: 0.8.2 ``mysql_length`` may now be specified as a dictionary
- for use with composite indexes.
-
Index Prefixes
~~~~~~~~~~~~~~
This dialect is based primarily on the :mod:`.mysql.mysqldb` dialect with
minimal changes.
- .. versionadded:: 0.7.8
-
.. deprecated:: 1.0 This dialect is **no longer necessary** for
Google Cloud SQL; the MySQLdb dialect can be used directly.
Cloud SQL now recommends creating connections via the
be limited; current support includes
MySQL Connector/Python.
- .. versionadded:: 0.8 The MySQL-specific TIME
- type as well as fractional seconds support.
-
"""
super(TIME, self).__init__(timezone=timezone)
self.fsp = fsp
be limited; current support includes
MySQL Connector/Python.
- .. versionadded:: 0.8.5 Added MySQL-specific :class:`.mysql.TIMESTAMP`
- with fractional seconds support.
-
"""
super(TIMESTAMP, self).__init__(timezone=timezone)
self.fsp = fsp
be limited; current support includes
MySQL Connector/Python.
- .. versionadded:: 0.8.5 Added MySQL-specific :class:`.mysql.DATETIME`
- with fractional seconds support.
-
"""
super(DATETIME, self).__init__(timezone=timezone)
self.fsp = fsp
array(['foo', 'bar'], type_=CHAR)
- .. versionadded:: 0.8 Added the :class:`~.postgresql.array` literal type.
-
- See also:
+ .. seealso::
- :class:`.postgresql.ARRAY`
+ :class:`.postgresql.ARRAY`
"""
:meth:`~.postgresql.ENUM.drop` methods can
be used to emit SQL to a target bind.
- .. versionadded:: 0.7.4
-
"""
self.create_type = kw.pop("create_type", True)
super(ENUM, self).__init__(*enums, **kw)
dictionary, unless that dictionary value is re-assigned to the
HSTORE-attribute itself, thus generating a change event.
- .. versionadded:: 0.8
-
.. seealso::
:class:`.hstore` - render the PostgreSQL ``hstore()`` function.
)
])
- .. versionadded:: 0.8
-
.. seealso::
:class:`.HSTORE` - the PostgreSQL ``HSTORE`` datatype.
* ``SERIALIZABLE``
* ``AUTOCOMMIT``
-.. versionadded:: 0.8.2 support for AUTOCOMMIT isolation level when using
- psycopg2.
-
.. seealso::
:ref:`postgresql_isolation_level`
Table 9-45 of the postgres documentation. For these, the normal
:func:`~sqlalchemy.sql.expression.func` object should be used.
- .. versionadded:: 0.8.2 Support for PostgreSQL RANGE operations.
-
"""
class comparator_factory(sqltypes.Concatenable.Comparator):
class INT4RANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL INT4RANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "INT4RANGE"
class INT8RANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL INT8RANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "INT8RANGE"
class NUMRANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL NUMRANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "NUMRANGE"
class DATERANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL DATERANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "DATERANGE"
class TSRANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL TSRANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "TSRANGE"
class TSTZRANGE(RangeOperators, sqltypes.TypeEngine):
"""Represent the PostgreSQL TSTZRANGE type.
- .. versionadded:: 0.8.2
-
"""
__visit_name__ = "TSTZRANGE"
necessary. The scheme also prevents a connection from being used again in
a different thread and works best with SQLite's coarse-grained file locking.
- .. versionchanged:: 0.7
- Default selection of :class:`.NullPool` for SQLite file-based databases.
- Previous versions select :class:`.SingletonThreadPool` by
- default for all SQLite databases.
-
-
Using a Memory Database in Multiple Threads
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
will match in a case-insensitive fashion, that is,
``row['SomeColumn']``.
- .. versionchanged:: 0.8
- By default, result row names match case-sensitively.
- In version 0.7 and prior, all matches were case-insensitive.
-
:param connect_args: a dictionary of options which will be
passed directly to the DBAPI's ``connect()`` method as
additional keyword arguments. See the example
or piped into a script that's later invoked by
command line tools.
- .. versionadded:: 0.7.6
-
:param stream_results: Available on: Connection, statement.
Indicate to the dialect that results should be
"streamed" and not pre-buffered, if possible. This is a limitation
cursor.execute("use %s" % shards[shard_id])
conn.info["current_shard"] = shard_id
- .. versionadded:: 0.8
-
.. seealso::
:meth:`.Connection.execution_options` - update execution options
:meth:`.Connection.execute` will close the :class:`.Connection` when
that :class:`.ResultProxy` has exhausted all result rows.
- .. versionadded:: 0.7.6
-
- See also:
+ .. seealso::
- :meth:`.Engine.connect` - procure a :class:`.Connection` from
- an :class:`.Engine`.
+ :meth:`.Engine.connect` - procure a :class:`.Connection` from
+ an :class:`.Engine`.
- :meth:`.Connection.begin` - start a :class:`.Transaction`
- for a particular :class:`.Connection`.
+ :meth:`.Connection.begin` - start a :class:`.Transaction`
+ for a particular :class:`.Connection`.
"""
conn = self.contextual_connect(close_with_result=close_with_result)
detached from the pool, or is being returned beyond the normal
capacity of the pool.
- .. versionadded:: 0.8
-
"""
raise NotImplementedError()
more comprehensive solution to resolving foreign key cycles
between tables.
- .. versionchanged:: 0.8 the "foreign_key" sorting sorts tables
- in order of dependee to dependent; that is, in creation
- order, rather than in drop order. This is to maintain
- consistency with similar features such as
- :attr:`.MetaData.sorted_tables` and :func:`.util.sort_tables`.
-
.. seealso::
:meth:`.Inspector.get_sorted_table_and_fkc_names`
of the database connection. For special quoting,
use :class:`.quoted_name`.
- .. versionadded:: 0.8.4
-
"""
return self.dialect.get_unique_constraints(
:param connection_record: the :class:`._ConnectionRecord` managing the
DBAPI connection.
- .. versionadded:: 0.8
-
.. seealso::
:meth:`.ConnectionEvents.rollback`
and parameters. See those methods for a description of
specific return arguments.
- .. versionchanged:: 0.8 :class:`.ConnectionEvents` can now be associated
- with any :class:`.Connectable` including :class:`.Connection`,
- in addition to the existing support for :class:`.Engine`.
-
"""
_target_class_doc = "SomeEngine"
class UnsupportedCompilationError(CompileError):
"""Raised when an operation is not supported by the given compiler.
-
- .. versionadded:: 0.8.3
-
"""
def __init__(self, compiler, element_type):
else:
return {"polymorphic_identity":cls.__name__}
- .. versionchanged:: 0.8 :class:`.declared_attr` can be used with
- non-ORM or extension attributes, such as user-defined attributes
- or :func:`.association_proxy` objects, which will be assigned
- to the class at class construction time.
-
-
"""
def __init__(self, fget, cascading=False):
All keyword arguments passed to :func:`.as_declarative` are passed
along to :func:`.declarative_base`.
- .. versionadded:: 0.8.3
-
.. seealso::
:func:`.declarative_base`
ReflectedOne.prepare(engine_one)
ReflectedTwo.prepare(engine_two)
- .. versionadded:: 0.8
-
"""
@classmethod
For examples of how the instrumentation extension is used,
see the example :ref:`examples_instrumentation`.
-.. versionchanged:: 0.8
- The :mod:`sqlalchemy.orm.instrumentation` was split out so
- that all functionality having to do with non-standard
- instrumentation was moved out to :mod:`sqlalchemy.ext.instrumentation`.
- When imported, the module installs itself within
- :mod:`sqlalchemy.orm.instrumentation` so that it
- takes effect, including recognition of
- ``__sa_instrumentation_manager__`` on mapped classes, as
- well :data:`.instrumentation_finders`
- being used to determine class instrumentation resolution.
-
"""
import weakref
The API for this class should be considered as semi-stable,
and may change slightly with new releases.
- .. versionchanged:: 0.8
- :class:`.InstrumentationManager` was moved from
- :mod:`sqlalchemy.orm.instrumentation` to
- :mod:`sqlalchemy.ext.instrumentation`.
-
"""
# r4361 added a mandatory (cls) constructor to this interface.
r"""Provide support for tracking of in-place changes to scalar values,
which are propagated into ORM change events on owning parent objects.
-.. versionadded:: 0.7 :mod:`sqlalchemy.ext.mutable` replaces SQLAlchemy's
- legacy approach to in-place mutations of scalar values; see
- :ref:`07_migration_mutation_extension`.
-
.. _mutable_scalars:
Establishing Mutability on Scalar Column Values
or more columns from the underlying mapped table. The usual example is that of
a geometric "point", and is introduced in :ref:`mapper_composite`.
-.. versionchanged:: 0.7
- The internals of :func:`.orm.composite` have been
- greatly simplified and in-place mutation detection is no longer enabled by
- default; instead, the user-defined value must detect changes on its own and
- propagate them to all owning parents. The :mod:`sqlalchemy.ext.mutable`
- extension provides the helper class :class:`.MutableComposite`, which is a
- slight variant on the :class:`.Mutable` class.
-
As is the case with :class:`.Mutable`, the user-defined composite class
subclasses :class:`.MutableComposite` as a mixin, and detects and delivers
change events to its parents via the :meth:`.MutableComposite.changed` method.
raise ValueError("tuple or Point expected")
return value
-.. versionadded:: 0.7.10,0.8.0b2
- Support for the :meth:`.MutableBase.coerce` method in conjunction with
- objects of type :class:`.MutableComposite`.
-
Supporting Pickling
--------------------
coersion to the values placed in the dictionary so that they too are
"mutable", and emit events up to their parent structure.
- .. versionadded:: 0.8
-
.. seealso::
:class:`.MutableList`
tools which build on top of SQLAlchemy configurations to be constructed
in a forwards-compatible way.
-.. versionadded:: 0.8 The :func:`.inspect` system is introduced
- as of version 0.8.
-
"""
from . import exc
:attr:`.QueryableAttribute.property` attribute, as
``MyClass.someattribute.property.info``.
- .. versionadded:: 0.8.0
-
.. seealso::
:attr:`.SchemaItem.info`
"""The extension type, if any.
Defaults to :data:`.interfaces.NOT_EXTENSION`
- .. versionadded:: 0.8.0
-
.. seealso::
:data:`.HYBRID_METHOD`
:func:`.column_property`, :func:`.relationship`, or :func:`.composite`
functions.
- .. versionadded:: 0.8 Added support for .info to all
- :class:`.MapperProperty` subclasses.
-
.. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also
available on extension types via the
:attr:`.InspectionAttrInfo.info` attribute, so that it can apply
scalar attribute should be loaded when replaced, if not
already loaded. See the same flag on :func:`.column_property`.
- .. versionchanged:: 0.7
- This flag specifically becomes meaningful
- - previously it was a placeholder.
-
:param group:
A group name for this property when marked as deferred.
:param info: Optional data dictionary which will be populated into the
:attr:`.MapperProperty.info` attribute of this object.
- .. versionadded:: 0.8
-
:param extension:
an :class:`.AttributeExtension` instance,
or list of extensions, which will be prepended to the list of
"""Provides a method of applying a :class:`.PropComparator`
to any Python descriptor attribute.
- .. versionchanged:: 0.7
+ .. deprecated:: 0.7
:func:`.comparable_property` is superseded by
the :mod:`~sqlalchemy.ext.hybrid` extension. See the example
at :ref:`hybrid_custom_comparators`.
be the subject of these events, when a listener
is established on a superclass.
- .. versionchanged:: 0.8 - events here will emit based
- on comparing the incoming class to the type of class
- passed to :func:`.event.listen`. Previously, the
- event would fire for any class unconditionally regardless
- of what class was sent for listening, despite
- documentation which stated the contrary.
-
"""
_target_class_doc = "SomeBaseClass"
* the :class:`.Mapper` class itself and the :func:`.mapper`
function indicate listening for all mappers.
- .. versionchanged:: 0.8.0 instance events can be associated with
- unmapped superclasses of mapped classes.
-
Instance events are closely related to mapper events, but
are more specific to the instance and its instrumentation,
rather than its system of persistence.
* the :class:`.Mapper` class itself and the :func:`.mapper`
function indicate listening for all mappers.
- .. versionchanged:: 0.8.0 mapper events can be associated with
- unmapped superclasses of mapped classes.
-
Mapper events provide hooks into critical sections of the
mapper, including those related to object instrumentation,
object loading, and object persistence. In particular, the
:class:`.SessionTransaction` for the given :class:`.Session` is
available via the :attr:`.Session.transaction` attribute.
- .. versionadded:: 0.7.3
-
"""
def before_flush(self, session, flush_context, instances):
This is called before an add, delete or merge causes
the object to be part of the session.
- .. versionadded:: 0.8. Note that :meth:`~.SessionEvents.after_attach`
- now fires off after the item is part of the session.
- :meth:`.before_attach` is provided for those cases where
- the item should not yet be part of the session state.
-
.. seealso::
:meth:`~.SessionEvents.after_attach`
cannot be made if the new parent was really the most
recent "parent".
- .. versionadded:: 0.7.4
-
"""
:func:`.column_property`, :func:`.relationship`, or :func:`.composite`
functions.
- .. versionadded:: 0.8 Added support for .info to all
- :class:`.MapperProperty` subclasses.
-
.. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also
available on extension types via the
:attr:`.InspectionAttrInfo.info` attribute, so that it can apply
See the change note and example at :ref:`legacy_is_orphan_addition`
for more detail on this change.
- .. versionadded:: 0.8 - the consideration of a pending object as
- an "orphan" has been modified to more closely match the
- behavior as that of persistent objects, which is that the object
- is expunged from the :class:`.Session` as soon as it is
- de-associated from any of its orphan-enabled parents. Previously,
- the pending object would be expunged only if de-associated
- from all of its orphan-enabled parents. The new flag
- ``legacy_is_orphan`` is added to :func:`.orm.mapper` which
- re-establishes the legacy behavior.
-
:param non_primary: Specify that this :class:`.Mapper` is in addition
to the "primary" mapper, that is, the one used for persistence.
The :class:`.Mapper` created here may be used for ad-hoc
"polymorphic_identity":"employee"
}
- .. versionchanged:: 0.7.4
- ``polymorphic_on`` may be specified as a SQL expression,
- or refer to any attribute configured with
- :func:`.column_property`, or to the string name of one.
-
When setting ``polymorphic_on`` to reference an
attribute or expression that's not present in the
locally mapped :class:`.Table`, yet the value
``getattr(mapper.all_orm_descriptors, somename)`` to avoid name
collisions.
- .. versionadded:: 0.8.0
-
.. seealso::
:attr:`.Mapper.attrs`
sent as well - the validation function must accept an additional
argument "is_remove" which will be a boolean.
- .. versionadded:: 0.7.7
:param include_backrefs: defaults to ``True``; if ``False``, the
validation function will not emit if the originator is an attribute
event related via a backref. This can be used for bi-directional
which also need to know
the "previous" value of the attribute.
- .. versionadded:: 0.6.6
-
:param comparator_factory: a class which extends
:class:`.ColumnProperty.Comparator` which provides custom SQL
clause generation for comparison operations.
settings still expires
all attributes after a :meth:`.Session.commit` call, however.
- .. versionadded:: 0.7.3
-
:param info: Optional data dictionary which will be populated into the
:attr:`.MapperProperty.info` attribute of this object.
- .. versionadded:: 0.8
-
:param extension:
an :class:`.AttributeExtension` instance, or list of extensions,
which will be prepended to the list of attribute listeners for the
to remove same-named columns where one also refers to the other
via foreign key or WHERE clause equivalence.
- .. versionchanged:: 0.8 the ``with_labels`` and ``reduce_columns``
- keyword arguments were added.
-
"""
q = self.enable_eagerloads(False)
if with_labels:
Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`.
- .. versionadded:: 0.6.5
-
"""
return self.enable_eagerloads(False).statement.label(name)
Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.as_scalar`.
- .. versionadded:: 0.6.5
-
"""
return self.enable_eagerloads(False).statement.as_scalar()
See the documentation section :ref:`with_polymorphic` for
details on how this method is used.
- .. versionchanged:: 0.8
- A new and more flexible function
- :func:`.orm.with_polymorphic` supersedes
- :meth:`.Query.with_polymorphic`, as it can apply the equivalent
- functionality to any set of columns or classes in the
- :class:`.Query`, not just the "zero mapper". See that
- function for a description of arguments.
-
"""
if not self._primary_entity:
q = q.join((subq, subq.c.email < Address.email)).\
limit(1)
- .. versionadded:: 0.6.5
-
"""
self._set_entities(entities)
This allows ad-hoc recipes to be created for :class:`.Query`
objects. See the example at :ref:`hybrid_transformers`.
- .. versionadded:: 0.7.4
-
"""
return fn(self)
q = session.query(User).join(Address, User.id==Address.user_id)
- .. versionchanged:: 0.7
- In SQLAlchemy 0.6 and earlier, the two argument form of
- :meth:`~.Query.join` requires the usage of a tuple:
- ``query(User).join((Address, User.id==Address.user_id))``\ .
- This calling form is accepted in 0.7 and further, though
- is not necessary unless multiple join conditions are passed to
- a single :meth:`~.Query.join` call, which itself is also not
- generally necessary as it is now equivalent to multiple
- calls (this wasn't always the case).
-
**Advanced Join Targeting and Adaption**
There is a lot of flexibility in what the "target" can be when using
SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name
FROM users
- .. versionadded:: 0.7.7
-
.. seealso::
:meth:`.HasPrefixes.prefix_with`
session.query(literal(True)).filter(q.exists()).scalar()
- .. versionadded:: 0.8.1
-
"""
# .add_columns() for the case that we are a query().select_from(X),
SELECT <rest of query follows...>
) AS anon_1
- .. versionchanged:: 0.7
- The above scheme is newly refined as of 0.7b3.
-
For fine grained control over specific columns
to count, to skip the usage of a subquery or
otherwise control of the FROM clause,
See the section :ref:`relationship_custom_foreign` for a
description of use.
- .. versionadded:: 0.8
-
.. seealso::
:ref:`relationship_custom_foreign`
See the section :ref:`relationship_custom_foreign` for a
description of use.
- .. versionadded:: 0.8
-
.. seealso::
:ref:`relationship_custom_foreign`
reducing performance of the innermost subquery beyond that of what
duplicate innermost rows may be causing.
- .. versionadded:: 0.8.3 -
- :paramref:`~.relationship.distinct_target_key` allows the
- subquery eager loader to apply a DISTINCT modifier to the
- innermost SELECT.
-
.. versionchanged:: 0.9.0 -
:paramref:`~.relationship.distinct_target_key` now defaults to
``None``, so that the feature enables itself automatically for
:func:`.relationship` to consider just those columns specified
here as "foreign".
- .. versionchanged:: 0.8
- A multiple-foreign key join ambiguity can be resolved by
- setting the :paramref:`~.relationship.foreign_keys`
- parameter alone, without the need to explicitly set
- :paramref:`~.relationship.primaryjoin` as well.
-
2. The :class:`.Table` being mapped does not actually have
:class:`.ForeignKey` or :class:`.ForeignKeyConstraint`
constructs present, often because the table
:func:`.foreign` - allows direct annotation of the "foreign"
columns within a :paramref:`~.relationship.primaryjoin` condition.
- .. versionadded:: 0.8
- The :func:`.foreign` annotation can also be applied
- directly to the :paramref:`~.relationship.primaryjoin`
- expression, which is an alternate, more specific system of
- describing which columns in a particular
- :paramref:`~.relationship.primaryjoin` should be considered
- "foreign".
-
:param info: Optional data dictionary which will be populated into the
:attr:`.MapperProperty.info` attribute of this object.
- .. versionadded:: 0.8
-
:param innerjoin=False:
when ``True``, joined eager loads will use an inner join to join
against related tables instead of an outer join. The purpose
and may be passed as a Python-evaluable string when using
Declarative.
- .. versionchanged:: 0.8
- The :func:`.remote` annotation can also be applied
- directly to the ``primaryjoin`` expression, which is an
- alternate, more specific system of describing which columns in a
- particular ``primaryjoin`` should be considered "remote".
-
.. seealso::
:ref:`self_referential` - in-depth explanation of how
of objects which involve existing database queries,
where the uncompleted object should not yet be flushed.
- .. versionadded:: 0.7.6
-
"""
autoflush = self.autoflush
self.autoflush = False
that they are present in an ordinary way before flush()
proceeds. This method is not intended for general use.
- .. versionadded:: 0.8
-
.. seealso::
``load_on_pending`` at :func:`.relationship` - this flag
return session.is_modified(someobject)
- .. versionchanged:: 0.8
- When using SQLAlchemy 0.7 and earlier, the ``passive``
- flag should **always** be explicitly set to ``True``,
- else SQL loads/autoflushes may proceed which can affect
- the modified state itself:
- ``session.is_modified(someobject, passive=True)``\ .
- In 0.8 and above, the behavior is corrected and
- this flag is ignored.
-
A few caveats to this method apply:
* Instances present in the :attr:`.Session.dirty` collection may
instance upon flush.
:param passive:
- .. versionchanged:: 0.8
- Ignored for backwards compatibility.
- When using SQLAlchemy 0.7 and earlier, this flag should always
- be set to ``True``.
+ .. deprecated:: 0.8
+ The ``passive`` flag is deprecated and will be removed
+ in a future release. The flag is no longer used and is ignored.
"""
state = object_state(instance)
wouldn't have any "column correspondence" to the actual
``UnitPrice.price`` column as it is not a proxy of the original.
- .. versionadded:: 0.7.3
-
-
"""
if isinstance(element, expression.FromClause):
if adapt_on_names:
This is regardless of whether or not the object is
persistent or detached.
- .. versionadded:: 0.8.0
-
.. seealso::
:attr:`.InstanceState.was_deleted`
This utility is also available when running the test suite via the
``--reversetop`` flag.
- .. versionadded:: 0.8.1 created a standalone version of the
- ``--reversetop`` feature.
-
"""
from sqlalchemy.orm import unitofwork, session, mapper, dependency
from sqlalchemy.util import topological
invalidation are not supported by this Pool implementation, since
no connections are held persistently.
- .. versionchanged:: 0.7
- :class:`.NullPool` is used by the SQlite dialect automatically
- when a file-based database is used. See :ref:`sqlite_toplevel`.
-
"""
def status(self):
at a time. Useful for debugging code that is using more connections
than desired.
- .. versionchanged:: 0.7
- :class:`.AssertionPool` also logs a traceback of where
- the original connection was checked out, and reports
- this in the assertion error raised.
-
"""
def __init__(self, *args, **kw):
class CreateSchema(_CreateDropBase):
"""Represent a CREATE SCHEMA statement.
- .. versionadded:: 0.7.4
-
The argument here is the string name of the schema.
"""
The argument here is the string name of the schema.
- .. versionadded:: 0.7.4
-
"""
__visit_name__ = "drop_schema"
which only includes the ``id`` column in the string; the ``xmin`` column
will be omitted, but only against the PostgreSQL backend.
- .. versionadded:: 0.8.3 The :class:`.CreateColumn` construct supports
- skipping of columns by returning ``None`` from a custom compilation
- rule.
-
- .. versionadded:: 0.8 The :class:`.CreateColumn` construct was added
- to support custom column creation styles.
-
"""
__visit_name__ = "create_column"
mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
- .. versionadded:: 0.7.6
-
:param text: Text of the hint.
:param selectable: optional :class:`.Table` that specifies
an element of the FROM clause within an UPDATE or DELETE
deals with an arbitrary number of rows, so the
:attr:`.ResultProxy.inserted_primary_key` accessor does not apply.
- .. versionadded:: 0.8.3
-
"""
if self.parameters:
raise exc.InvalidRequestError(
as_scalar()
)
- .. versionchanged:: 0.7.4
- The WHERE clause of UPDATE can refer to multiple tables.
-
:param values:
Optional dictionary which specifies the ``SET`` conditions of the
``UPDATE``. If left as ``None``, the ``SET``
parameters are present, then :paramref:`.bindparam.required`
defaults to ``False``.
- .. versionchanged:: 0.8 If the ``required`` flag is not specified,
- it will be set automatically to ``True`` or ``False`` depending
- on whether or not the ``value`` or ``callable`` parameters
- were specified.
-
:param quote:
True if this parameter name requires quoting and is not
currently known as a SQLAlchemy reserved word; this currently
See :func:`~.expression.over` for a full description.
- .. versionadded:: 0.7
-
"""
return Over(
self,
but are not exactly the same as "functions" from a SQLAlchemy
perspective.
- .. versionadded:: 0.8 :data:`.func` can return non-function expression
- constructs for common quasi-functional names like :func:`.cast`
- and :func:`.extract`.
-
Functions which are interpreted as "generic" functions know how to
calculate their return type automatically. For a listing of known generic
functions, see :ref:`generic_functions`.
>>> print func.geo.buffer()
ST_Buffer()
- .. versionadded:: 0.8 :class:`.GenericFunction` now supports
- automatic registration of new functions as well as package
- and custom naming support.
-
- .. versionchanged:: 0.8 The attribute name ``type`` is used
- to specify the function's return type at the class level.
- Previously, the name ``__return_type__`` was used. This
- name is still recognized for backwards-compatibility.
-
"""
coerce_arguments = True
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.
- .. versionadded:: 0.8 - added the 'precedence' argument.
-
:param is_comparison: if True, the operator will be considered as a
"comparison" operator, that is which evaluates to a boolean
true/false value, like ``==``, ``>``, etc. This flag should be set
This is equivalent to using negation with
:meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
- .. versionadded:: 0.8
-
.. seealso::
:meth:`.ColumnOperators.like`
This is equivalent to using negation with
:meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
- .. versionadded:: 0.8
-
.. seealso::
:meth:`.ColumnOperators.ilike`
usage of ``IS`` may be desirable if comparing to boolean values
on certain platforms.
- .. versionadded:: 0.7.9
-
.. seealso:: :meth:`.ColumnOperators.isnot`
"""
usage of ``IS NOT`` may be desirable if comparing to boolean values
on certain platforms.
- .. versionadded:: 0.7.9
-
.. seealso:: :meth:`.ColumnOperators.is_`
"""
replace existing columns of the same name when
:paramref:`.Table.extend_existing` is ``True``.
- .. versionadded:: 0.7.5
-
.. seealso::
:paramref:`.Table.autoload`
:class:`.Table`, potentially overwriting existing columns
and options of the same name.
- .. versionchanged:: 0.7.4 :paramref:`.Table.extend_existing` will
- invoke a new reflection operation when combined with
- :paramref:`.Table.autoload` set to True.
-
As is always the case with :paramref:`.Table.autoload`,
:class:`.Column` objects can be specified in the same :class:`.Table`
constructor, which will take precedence. Below, the existing
conditionally rendered differently on different backends,
consider custom compilation rules for :class:`.CreateColumn`.
- .. versionadded:: 0.8.3 Added the ``system=True`` parameter to
- :class:`.Column`.
-
:param comment: Optional string that will render an SQL comment on
table creation.
(defaults to the column name itself), unless ``link_to_name`` is
``True`` in which case the rendered name of the column is used.
- .. versionadded:: 0.7.4
- Note that if the schema name is not included, and the
- underlying :class:`.MetaData` has a "schema", that value will
- be used.
-
:param name: Optional string. An in-database name for the key if
`constraint` is not provided.
Index("some_index", func.lower(sometable.c.name))
- .. versionadded:: 0.8 support for functional and expression-based indexes.
-
An :class:`.Index` can also be manually associated with a :class:`.Table`,
either through inline declaration or using
:meth:`.Table.append_constraint`. When this approach is used, the names
:meth:`.SelectBase.cte` method from any selectable.
See that method for complete examples.
- .. versionadded:: 0.7.6
-
"""
__visit_name__ = "cte"
to those which have the same name as the equivalent. Otherwise,
all columns that are equivalent to another are removed.
- .. versionadded:: 0.8
-
"""
return self.with_only_columns(
sqlutil.reduce_columns(
constructs, or other compatible constructs (i.e. ORM-mapped
classes) to become part of the correlate collection.
- .. versionchanged:: 0.8.0 ORM-mapped classes are accepted by
- :meth:`.Select.correlate`.
-
- .. versionchanged:: 0.8.0 The :meth:`.Select.correlate` method no
- longer unconditionally removes entries from the FROM clause;
- instead, the candidate FROM entries must also be matched by a FROM
- entry located in an enclosing :class:`.Select`, which ultimately
- encloses this one as present in the WHERE clause, ORDER BY clause,
- HAVING clause, or columns clause of an enclosing :meth:`.Select`.
-
- .. versionchanged:: 0.8.2 explicit correlation takes place
- via any level of nesting of :class:`.Select` objects; in previous
- 0.8 versions, correlation would only occur relative to the
- immediate enclosing :class:`.Select` construct.
-
.. seealso::
:meth:`.Select.correlate_except`
all other FROM elements remain subject to normal auto-correlation
behaviors.
- .. versionchanged:: 0.8.2 The :meth:`.Select.correlate_except`
- method was improved to fully prevent FROM clauses specified here
- from being omitted from the immediate FROM clause of this
- :class:`.Select`.
-
If ``None`` is passed, the :class:`.Select` object will correlate
all of its FROM entries.
- .. versionchanged:: 0.8.2 calling ``correlate_except(None)`` will
- correctly auto-correlate all FROM clauses.
-
:param \*fromclauses: a list of one or more :class:`.FromClause`
constructs, or other compatible constructs (i.e. ORM-mapped
classes) to become part of the correlate-exception collection.
>>> print select([cast('some string', String(collation='utf8'))])
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- .. versionadded:: 0.8 Added support for COLLATE to all
- string types.
-
:param convert_unicode: When set to ``True``, the
:class:`.String` type will assume that
input is to be passed as Python Unicode objects under Python 2,
of existing types, or alternatively by using :class:`.TypeDecorator`.
See the documentation section :ref:`types_operators` for examples.
- .. versionadded:: 0.8 The expression system was enhanced to support
- customization of operators on a per-type level.
-
"""
should_evaluate_none = False
:param dialect_name: base name of the dialect which uses
this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
- .. versionadded:: 0.7.2
-
"""
return Variant(self, {dialect_name: to_instance(type_)})
the same type as this one. See
:meth:`.TypeDecorator.coerce_compared_value` for more detail.
- .. versionchanged:: 0.8 :meth:`.UserDefinedType.coerce_compared_value`
- now returns ``self`` by default, rather than falling onto the
- more fundamental behavior of
- :meth:`.TypeEngine.coerce_compared_value`.
-
"""
return self
return an empty tuple, in which case no values will be coerced to
constants.
- .. versionadded:: 0.8.2
- Added :attr:`.TypeDecorator.coerce_to_is_types` to allow for easier
- control of ``__eq__()`` ``__ne__()`` operations.
-
"""
class Comparator(TypeEngine.Comparator):
The :class:`.Variant` type is typically constructed
using the :meth:`.TypeEngine.with_variant` method.
- .. versionadded:: 0.7.2
-
.. seealso:: :meth:`.TypeEngine.with_variant` for an example of use.
"""
and performance overhead, which is not necessary for the
:class:`.Query` object's use case.
- .. versionchanged:: 0.8
- Compatibility methods with ``collections.namedtuple()`` have been
- added including :attr:`.KeyedTuple._fields` and
- :meth:`.KeyedTuple._asdict`.
-
.. seealso::
:ref:`ormtutorial_querying`
This method provides compatibility with ``collections.namedtuple()``.
- .. versionadded:: 0.8
-
.. seealso::
:meth:`.KeyedTuple.keys`
This method provides compatibility with ``collections.namedtuple()``,
with the exception that the dictionary returned is **not** ordered.
- .. versionadded:: 0.8
-
"""
return {key: self.__dict__[key] for key in self.keys()}
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
