__init__.py

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

        secondaryjoin
          a ClauseElement that will be used as the join of an association table
          to the child object. By default, this value is computed based on the
          foreign key relationships of the association and child tables.

        uselist=(True|False)
          a boolean that indicates if this property should be loaded as a list or
          a scalar. In most cases, this value is determined automatically by
          ``relation()``, based on the type and direction of the relationship - one
          to many forms a list, many to one forms a scalar, many to many is a
          list. If a scalar is desired where normally a list would be present,
          such as a bi-directional one-to-one relationship, set uselist to False.

        viewonly=False
          when set to True, the relation is used only for loading objects within
          the relationship, and has no effect on the unit-of-work flush process.
          Relations with viewonly can specify any kind of join conditions to
          provide additional views of related objects onto a parent object. Note
          that the functionality of a viewonly relationship has its limits -
          complicated join conditions may not compile into eager or lazy loaders
          properly. If this is the case, use an alternative method.

    """

    return PropertyLoader(argument, secondary=secondary, **kwargs)

def dynamic_loader(argument, secondary=None, primaryjoin=None, secondaryjoin=None, entity_name=None,
    foreign_keys=None, backref=None, post_update=False, cascade=None, remote_side=None, enable_typechecks=True,
    passive_deletes=False):
    """construct a dynamically-loading mapper property.

    This property is similar to relation(), except read operations
    return an active Query object, which reads from the database in all
    cases.  Items may be appended to the attribute via append(), or
    removed via remove(); changes will be persisted
    to the database during a flush().  However, no other list mutation
    operations are available.

    A subset of arguments available to relation() are available here.
    """

    from sqlalchemy.orm.strategies import DynaLoader

    return PropertyLoader(argument, secondary=secondary, primaryjoin=primaryjoin,
            secondaryjoin=secondaryjoin, entity_name=entity_name, foreign_keys=foreign_keys, backref=backref,
            post_update=post_update, cascade=cascade, remote_side=remote_side, enable_typechecks=enable_typechecks,
            passive_deletes=passive_deletes,
            strategy_class=DynaLoader)

#def _relation_loader(mapper, secondary=None, primaryjoin=None, secondaryjoin=None, lazy=True, **kwargs):

def column_property(*args, **kwargs):
    """Provide a column-level property for use with a Mapper.

    Column-based properties can normally be applied to the mapper's
    ``properties`` dictionary using the ``schema.Column`` element directly.
    Use this function when the given column is not directly present within
    the mapper's selectable; examples include SQL expressions, functions,
    and scalar SELECT queries.

    Columns that aren't present in the mapper's selectable won't be persisted
    by the mapper and are effectively "read-only" attributes.

      \*cols
          list of Column objects to be mapped.

      group
          a group name for this property when marked as deferred.

      deferred
          when True, the column property is "deferred", meaning that
          it does not load immediately, and is instead loaded when the
          attribute is first accessed on an instance.  See also
          [sqlalchemy.orm#deferred()].

    """

    return ColumnProperty(*args, **kwargs)

def composite(class_, *cols, **kwargs):
    """Return a composite column-based property for use with a Mapper.

    This is very much like a column-based property except the given class
    is used to represent "composite" values composed of one or more columns.

    The class must implement a constructor with positional arguments matching
    the order of columns supplied here, as well as a __composite_values__()
    method which returns values in the same order.

    A simple example is representing separate two columns in a table as a
    single, first-class "Point" object::

      class Point(object):
          def __init__(self, x, y):
              self.x = x
              self.y = y
          def __composite_values__(self):
              return (self.x, self.y)

      # and then in the mapping:
      ... composite(Point, mytable.c.x, mytable.c.y) ...

    Arguments are:

    class\_
      The "composite type" class.

    \*cols
      List of Column objects to be mapped.

    group
      A group name for this property when marked as deferred.

    deferred
      When True, the column property is "deferred", meaning that
      it does not load immediately, and is instead loaded when the
      attribute is first accessed on an instance.  See also
      [sqlalchemy.orm#deferred()].

    comparator
      An optional instance of [sqlalchemy.orm#PropComparator] which
      provides SQL expression generation functions for this composite
      type.
    """

    return CompositeProperty(class_, *cols, **kwargs)


def backref(name, **kwargs):
    """Create a BackRef object with explicit arguments, which are the same arguments one
    can send to ``relation()``.

    Used with the `backref` keyword argument to ``relation()`` in
    place of a string argument.
    """

    return BackRef(name, **kwargs)

def deferred(*columns, **kwargs):
    """Return a ``DeferredColumnProperty``, which indicates this
    object attributes should only be loaded from its corresponding
    table column when first accessed.

    Used with the `properties` dictionary sent to ``mapper()``.
    """

    return ColumnProperty(deferred=True, *columns, **kwargs)

def mapper(class_, local_table=None, *args, **params):
    """Return a new [sqlalchemy.orm#Mapper] object.

      class\_
        The class to be mapped.

      local_table
        The table to which the class is mapped, or None if this
        mapper inherits from another mapper using concrete table
        inheritance.

      entity_name
        A name to be associated with the `class`, to allow alternate
        mappings for a single class.

      always_refresh
        If True, all query operations for this mapped class will
        overwrite all data within object instances that already
        exist within the session, erasing any in-memory changes with
        whatever information was loaded from the database.  Usage
        of this flag is highly discouraged; as an alternative,
        see the method `populate_existing()` on [sqlalchemy.orm.query#Query].

      allow_column_override
        If True, allows the usage of a ``relation()`` which has the
        same name as a column in the mapped table.  The table column
        will no longer be mapped.

      allow_null_pks
        Indicates that composite primary keys where one or more (but
        not all) columns contain NULL is a valid primary key.
        Primary keys which contain NULL values usually indicate that
        a result row does not contain an entity and should be
        skipped.

      batch
        Indicates that save operations of multiple entities can be
        batched together for efficiency.  setting to False indicates
        that an instance will be fully saved before saving the next
        instance, which includes inserting/updating all table rows
        corresponding to the entity as well as calling all
        ``MapperExtension`` methods corresponding to the save
        operation.

      column_prefix
        A string which will be prepended to the `key` name of all
        Columns when creating column-based properties from the given
        Table.  Does not affect explicitly specified column-based
        properties

      concrete
        If True, indicates this mapper should use concrete table
        inheritance with its parent mapper.

      extension
        A [sqlalchemy.orm#MapperExtension] instance or list of
        ``MapperExtension`` instances which will be applied to all
        operations by this ``Mapper``.

      inherits
        Another ``Mapper`` for which this ``Mapper`` will have an
        inheritance relationship with.

      inherit_condition
        For joined table inheritance, a SQL expression (constructed
        ``ClauseElement``) which will define how the two tables are
        joined; defaults to a natural join between the two tables.

      inherit_foreign_keys
        when inherit_condition is used and the condition contains no
        ForeignKey columns, specify the "foreign" columns of the join
        condition in this list.  else leave as None.

      order_by
        A single ``Column`` or list of ``Columns`` for which
        selection operations should use as the default ordering for
        entities.  Defaults to the OID/ROWID of the table if any, or
        the first primary key column of the table.

      non_primary
        Construct a ``Mapper`` that will define only the selection
        of instances, not their persistence.  Any number of non_primary
        mappers may be created for a particular class.

      polymorphic_on
        Used with mappers in an inheritance relationship, a ``Column``
        which will identify the class/mapper combination to be used
        with a particular row.  requires the polymorphic_identity
        value to be set for all mappers in the inheritance
        hierarchy.

      _polymorphic_map
        Used internally to propagate the full map of polymorphic
        identifiers to surrogate mappers.

      polymorphic_identity
        A value which will be stored in the Column denoted by
        polymorphic_on, corresponding to the *class identity* of
        this mapper.