__init__.py

SQLAlchemy. 经典的Python ORM框架。学习必看。

      polymorphic_fetch
        specifies how subclasses mapped through joined-table
        inheritance will be fetched.  options are 'union',
        'select', and 'deferred'.  if the select_table argument
        is present, defaults to 'union', otherwise defaults to
        'select'.

      properties
        A dictionary mapping the string names of object attributes
        to ``MapperProperty`` instances, which define the
        persistence behavior of that attribute.  Note that the
        columns in the mapped table are automatically converted into
        ``ColumnProperty`` instances based on the `key` property of
        each ``Column`` (although they can be overridden using this
        dictionary).

      include_properties
        An inclusive list of properties to map.  Columns present in the
        mapped table but not present in this list will not be automatically
        converted into properties.

      exclude_properties
        A list of properties not to map.  Columns present in the
        mapped table and present in this list will not be automatically
        converted into properties.  Note that neither this option nor
        include_properties will allow an end-run around Python inheritance.
        If mapped class ``B`` inherits from mapped class ``A``, no combination
        of includes or excludes will allow ``B`` to have fewer properties
        than its superclass, ``A``.

      primary_key
        A list of ``Column`` objects which define the *primary key*
        to be used against this mapper's selectable unit.  This is
        normally simply the primary key of the `local_table`, but
        can be overridden here.

      select_table
        A [sqlalchemy.schema#Table] or any [sqlalchemy.sql#Selectable]
        which will be used to select instances of this mapper's class.
        usually used to provide polymorphic loading among several
        classes in an inheritance hierarchy.

      version_id_col
        A ``Column`` which must have an integer type that will be
        used to keep a running *version id* of mapped entities in
        the database.  this is used during save operations to ensure
        that no other thread or process has updated the instance
        during the lifetime of the entity, else a
        ``ConcurrentModificationError`` exception is thrown.
    """

    return Mapper(class_, local_table, *args, **params)

def synonym(name, map_column=False, proxy=False):
    """Set up `name` as a synonym to another mapped property.

    Used with the ``properties`` dictionary sent to  [sqlalchemy.orm#mapper()].

    Any existing attributes on the class which map the key name sent
    to the ``properties`` dictionary will be used by the synonym to
    provide instance-attribute behavior (that is, any Python property object,
    provided by the ``property`` builtin or providing a ``__get__()``,
    ``__set__()`` and ``__del__()`` method).  If no name exists for the key,
    the ``synonym()`` creates a default getter/setter object automatically
    and applies it to the class.

    `name` refers to the name of the existing mapped property, which
    can be any other ``MapperProperty`` including column-based
    properties and relations.

    If `map_column` is ``True``, an additional ``ColumnProperty`` is created
    on the mapper automatically, using the synonym's name as the keyname of
    the property, and the keyname of this ``synonym()`` as the name of the
    column to map.  For example, if a table has a column named ``status``::

        class MyClass(object):
            def _get_status(self):
                return self._status
            def _set_status(self, value):
                self._status = value
            status = property(_get_status, _set_status)

        mapper(MyClass, sometable, properties={
            "status":synonym("_status", map_column=True)
        })

    The column named ``status`` will be mapped to the attribute named
    ``_status``, and the ``status`` attribute on ``MyClass`` will be used to
    proxy access to the column-based attribute.

    The `proxy` keyword argument is deprecated and currently does nothing;
    synonyms now always establish an attribute getter/setter function if one
    is not already available.
    """

    return SynonymProperty(name, map_column=map_column)

def compile_mappers():
    """Compile all mappers that have been defined.

    This is equivalent to calling ``compile()`` on any individual mapper.
    """

    for m in list(_mapper_registry):
        m.compile()

def clear_mappers():
    """Remove all mappers that have been created thus far.

    The mapped classes will return to their initial "unmapped"
    state and can be re-mapped with new mappers.
    """
    mapperlib._COMPILE_MUTEX.acquire()
    try:
        for mapper in list(_mapper_registry):
            mapper.dispose()
    finally:
        mapperlib._COMPILE_MUTEX.release()

def extension(ext):
    """Return a ``MapperOption`` that will insert the given
    ``MapperExtension`` to the beginning of the list of extensions
    that will be called in the context of the ``Query``.

    Used with ``query.options()``.
    """

    return ExtensionOption(ext)

def eagerload(name, mapper=None):
    """Return a ``MapperOption`` that will convert the property of the given name into an eager load.

    Used with ``query.options()``.
    """

    return strategies.EagerLazyOption(name, lazy=False, mapper=mapper)

def eagerload_all(name, mapper=None):
    """Return a ``MapperOption`` that will convert all properties along the given dot-separated path into an eager load.

    For example, this::

        query.options(eagerload_all('orders.items.keywords'))...

    will set all of 'orders', 'orders.items', and 'orders.items.keywords'
    to load in one eager load.

    Used with ``query.options()``.
    """

    return strategies.EagerLazyOption(name, lazy=False, chained=True, mapper=mapper)

def lazyload(name, mapper=None):
    """Return a ``MapperOption`` that will convert the property of the
    given name into a lazy load.

    Used with ``query.options()``.
    """

    return strategies.EagerLazyOption(name, lazy=True, mapper=mapper)

def fetchmode(name, type):
    return strategies.FetchModeOption(name, type)

def noload(name):
    """Return a ``MapperOption`` that will convert the property of the
    given name into a non-load.

    Used with ``query.options()``.
    """

    return strategies.EagerLazyOption(name, lazy=None)

def contains_alias(alias):
    """Return a ``MapperOption`` that will indicate to the query that
    the main table has been aliased.

    `alias` is the string name or ``Alias`` object representing the
    alias.
    """

    class AliasedRow(MapperExtension):
        def __init__(self, alias):
            self.alias = alias
            if isinstance(self.alias, basestring):
                self.selectable = None
            else:
                self.selectable = alias
            self._row_translators = {}
        def get_selectable(self, mapper):
            if self.selectable is None:
                self.selectable = mapper.mapped_table.alias(self.alias)
            return self.selectable
        def translate_row(self, mapper, context, row):
            if mapper in self._row_translators:
                return self._row_translators[mapper](row)
            else:
                translator = create_row_adapter(self.get_selectable(mapper), mapper.mapped_table)
                self._row_translators[mapper] = translator
                return translator(row)

    return ExtensionOption(AliasedRow(alias))

def contains_eager(key, alias=None, decorator=None):
    """Return a ``MapperOption`` that will indicate to the query that
    the given attribute will be eagerly loaded.

    Used when feeding SQL result sets directly into
    ``query.instances()``.  Also bundles an ``EagerLazyOption`` to
    turn on eager loading in case it isn't already.

    `alias` is the string name of an alias, **or** an ``sql.Alias``
    object, which represents the aliased columns in the query.  This
    argument is optional.

    `decorator` is mutually exclusive of `alias` and is a
    row-processing function which will be applied to the incoming row
    before sending to the eager load handler.  use this for more
    sophisticated row adjustments beyond a straight alias.
    """

    return (strategies.EagerLazyOption(key, lazy=False), strategies.RowDecorateOption(key, alias=alias, decorator=decorator))

def defer(name):
    """Return a ``MapperOption`` that will convert the column property
    of the given name into a deferred load.

    Used with ``query.options()``"""
    return strategies.DeferredOption(name, defer=True)

def undefer(name):
    """Return a ``MapperOption`` that will convert the column property
    of the given name into a non-deferred (regular column) load.

    Used with ``query.options()``.
    """

    return strategies.DeferredOption(name, defer=False)

def undefer_group(name):
    """Return a ``MapperOption`` that will convert the given
    group of deferred column properties into a non-deferred (regular column) load.

    Used with ``query.options()``.
    """
    return strategies.UndeferGroupOption(name)