actually called via the TableSingleton metaclass. Arguments
are:
- name:
+ name
The name of this table, exactly as it appears, or will
appear, in the database.
Further tables constructed with the same name/schema
combination will return the same Table instance.
- \*args:
+ \*args
Should contain a listing of the Column objects for this table.
- \**kwargs:
+ \**kwargs
Options include:
schema
Arguments are:
- name:
+ name
The name of the index
- \*columns:
+ \*columns
Columns to include in the index. All columns must belong to
the same table, and no column may appear more than once.
- \**kwargs:
+ \**kwargs
Keyword arguments include:
unique
class MetaData(SchemaItem):
"""A collection of Tables and their associated schema constructs.
- Holds a collection of Tables and an optional binding to an ``Engine``
- or ``Connection``. If bound, the tables in the collection may participate
- in implicit SQL expressions and execution.
+ Holds a collection of Tables and an optional binding to an
+ ``Engine`` or ``Connection``. If bound, the
+ [sqlalchemy.schema#Table] objects in the collection and their
+ columns may participate in implicit SQL execution.
- The ``.bind`` may be assigned to dynamically. A common pattern is to
- begin bound to None and then later bind when an engine is available::
+ The ``bind`` property may be assigned to dynamically. A common
+ pattern is to start unbound and then bind later when an engine is
+ available::
metadata = MetaData()
# define tables
def __init__(self, bind=None, reflect=False, case_sensitive=None):
"""Create a new MetaData object.
- bind:
- An Engine, or a string or URL instance which will be passed
- to create_engine(), this MetaData will be bound to the resulting
- engine.
+ 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 be bound to the resulting engine.
- reflect:
+ reflect
Optional, automatically load all tables from the bound database.
- Defaults to false. ``bind`` is required when this option is
- set. For finer control over loaded tables, use the `reflect`
+ Defaults to False. ``bind`` is required when this option is
+ set. For finer control over loaded tables, use the ``reflect``
method of ``MetaData``.
- case_sensitive:
+ case_sensitive
A default case sensitive setting for all contained objects.
Defaults to sensitive.
-
"""
self.tables = {}
def connect(self, bind, **kwargs):
"""Bind this MetaData to an Engine.
- Use metadata.bind = <engine> or metadata.bind = <url>.
-
- bind:
- A string, URL or Engine instance. If a string or URL,
- will be passed to create_engine() along with \**kwargs to
- produce the engine which to connect to. Otherwise connects
- directly to the given Engine.
+ Use ``metadata.bind = <engine>`` or ``metadata.bind = <url>``.
+
+ bind
+ A string, ``URL``, ``Engine`` or ``Connection`` instance. If
+ a string or ``URL``, will be passed to ``create_engine()`` along
+ with ``\**kwargs`` to produce the engine which to connect to.
+ Otherwise connects directly to the given ``Engine``.
"""
global URL
connect = util.deprecated(connect)
def _bind_to(self, bind):
- """Bind this MetaData to an Engine, Connection or URL."""
+ """Bind this MetaData to an Engine, Connection, string or URL."""
global URL
if URL is None:
self._bind = bind
bind = property(lambda self: self._bind, _bind_to, doc=
- "An Engine or Connection to which this MetaData is bound. "
- "This is a settable property as well.")
+ """An Engine or Connection to which this MetaData is bound.
+
+ This property may be assigned an ``Engine`` or
+ ``Connection``, or assigned a string or URL to
+ automatically create a basic ``Engine`` for this bind
+ with ``create_engine()``.""")
def clear(self):
self.tables.clear()
"""Load all available table definitions from the database.
Automatically creates ``Table`` entries in this ``MetaData`` for any
- table available in the database but not yet present in the MetaData.
+ table available in the database but not yet present in the ``MetaData``.
May be called multiple times to pick up tables recently added to the
database, however no special action is taken if a table in this
- MetaData no longer exists in the database.
+ ``MetaData`` no longer exists in the database.
- bind:
+ bind
A ``Connectable`` used to access the database; if None, uses
the existing bind on this ``MetaData``, if any.
- schema:
+ schema
Optional, query and reflect tables from an alterate schema.
- only:
+ only
Optional. Load only a sub-set of available named tables. May
be specified as a sequence of names or a callable.
This will conditionally create tables depending on if they do
not yet exist in the database.
- bind:
+ bind
A ``Connectable`` used to access the database; if None, uses
the existing bind on this ``MetaData``, if any.
- tables:
+ tables
Optional list of ``Table`` objects, which is a subset of the
total tables in the ``MetaData`` (others are ignored).
"""
This will conditionally drop tables depending on if they
currently exist in the database.
- bind:
+ bind
A ``Connectable`` used to access the database; if None, uses
the existing bind on this ``MetaData``, if any.
- tables:
+ tables
Optional list of ``Table`` objects, which is a subset of the
total tables in the ``MetaData`` (others are ignored).
"""
implementations or connections in each thread.
The ThreadLocalMetaData starts off bound to None in each thread.
- Binds must be made explicitly by assigning to the ``.bind`` property or
+ Binds must be made explicitly by assigning to the ``bind`` property or
using ``connect()``. You can also re-bind dynamically multiple times per
thread, just like a regular ``MetaData``.
# @deprecated
def connect(self, bind, **kwargs):
- """Bind this MetaData to an Engine.
+ """Bind to an Engine in the caller's thread.
Use ``metadata.bind=<engine>`` or ``metadata.bind=<url>``.
- bind:
- A string, URL or Engine instance. If a string or URL,
- will be passed to create_engine() along with \**kwargs to
- produce the engine which to connect to. Otherwise connects
- directly to the given Engine.
+ bind
+ A string, ``URL``, ``Engine`` or ``Connection`` instance. If
+ a string or ``URL``, will be passed to ``create_engine()`` along
+ with ``\**kwargs`` to produce the engine which to connect to.
+ Otherwise connects directly to the given ``Engine``.
"""
global URL
return None
def _bind_to(self, bind):
- """Bind this MetaData to an ``Engine`` or ``Connection``."""
+ """Bind to a Connectable in the caller's thread."""
global URL
if URL is None:
self.__engines[bind] = bind
self.context._engine = bind
- bind = property(_get_bind, _bind_to)
+ bind = property(_get_bind, _bind_to, doc=
+ """The bound Engine or Connection for this thread.
+ This property may be assigned an Engine or Connection,
+ or assigned a string or URL to automatically create a
+ basic Engine for this bind with ``create_engine()``.""")
def is_bound(self):
- return hasattr(self.context, '_engine') and self.context._engine is not None
+ """True if there is a bind for this thread."""
+ return (hasattr(self.context, '_engine') and
+ self.context._engine is not None)
def dispose(self):
- """Dispose all ``Engines`` to which this ``ThreadLocalMetaData`` has been connected."""
+ """Dispose any and all ``Engines`` to which this ``ThreadLocalMetaData`` has been connected."""
for e in self.__engines.values():
- e.dispose()
+ if e.hasattr('dispose'):
+ e.dispose()
class SchemaVisitor(sql.ClauseVisitor):
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
