声明式API ¶

API参考¶

sqlalchemy.ext.declarative.declarative_base(bind=None, metadata=None, mapper=None, cls=<type 'object'>, name='Base', constructor=<function __init__>, class_registry=None, metaclass=<class 'sqlalchemy.ext.declarative.api.DeclarativeMeta'>)¶

为声明性类定义构造一个基类。

新的基类将被赋予一个元类，该元类生成适当的Table对象，并根据在类中声明提供的信息以及该类的任何子类进行相应的mapper()调用类。

参数：

bind¶ – An optional Connectable, will be assigned the bind attribute on the MetaData instance. metadata¶ – An optional MetaData instance. 所有由基类的子类隐式声明的Table对象将共享此元数据。如果没有提供MetaData实例，则会创建一个MetaData实例。The MetaData instance will be available via the metadata attribute of the generated declarative base class. mapper¶ – An optional callable, defaults to mapper(). 将用于将子类映射到其表。 cls ¶ - 默认为object。一种用作生成的声明式基类的基础的类型。可能是类或类的元组。 名称 ¶ - 默认为Base。生成的类的显示名称。自定义这不是必需的，但可以提高回溯和调试的清晰度。 constructor¶ – Defaults to _declarative_constructor(), an __init__ implementation that assigns **kwargs for declared fields and relationships to an instance. 如果提供None，则不会提供__init__，并且构造会通过正常的Python语义回退到cls .__ init__。 class_registry¶ – optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of relationship() and others. 允许两个或更多声明性基类共享相同的类名称注册表以简化基础间关系。 元类 ¶ - 默认为DeclarativeMeta。元类或__metaclass__兼容的callable用作生成的声明基类的元类型。

也可以看看

as_declarative()

sqlalchemy.ext.declarative。 T0> as_declarative T1> （ T2> **千瓦 T3> ） T4> ¶ T5>

declarative_base()的类装饰器。

为发送给declarative_base()的cls参数提供语法快捷方式，允许将基类就地转换为“声明式”基础：

from sqlalchemy.ext.declarative import as_declarative

@as_declarative()
class Base(object):
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()
    id = Column(Integer, primary_key=True)

class MyMappedClass(Base):
    # ...

传递给as_declarative()的所有关键字参数都传递给declarative_base()。

0.8.3版本中的新功能

也可以看看

declarative_base()

类 T0> sqlalchemy.ext.declarative。 T1> declared_attr T2> （ T3> fget T4>，级联=假 T5> ） T6> ¶ T7>

基础：sqlalchemy.orm.base._MappedAttribute，__builtin__.property

将类级方法标记为表示映射属性或特殊声明性成员名称的定义。

@declared_attr将属性转换为可以从未被实例化的类调用的类标量属性。声明式将特别标记为@declared_attr的属性视为返回特定于映射或声明式表配置的构造。属性的名称是该属性的非动态版本的名称。

@declared_attr通常不适用于mixin，以定义要应用于该类的不同实现者的关系：

class ProvidesUser(object):
    "A mixin that adds a 'user' relationship to classes."

    @declared_attr
    def user(self):
        return relationship("User")

它也可以应用于映射类，例如为继承提供“多态”方案：

class Employee(Base):
    id = Column(Integer, primary_key=True)
    type = Column(String(50), nullable=False)

    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    @declared_attr
    def __mapper_args__(cls):
        if cls.__name__ == 'Employee':
            return {
                    "polymorphic_on":cls.type,
                    "polymorphic_identity":"Employee"
            }
        else:
            return {"polymorphic_identity":cls.__name__}

版本0.8中的更改 declared_attr可以与非ORM或扩展属性（例如用户定义的属性或association_proxy()将在课堂上课时分配给班级。

级联 T0> ¶ T1>

将declared_attr标记为级联。

这是一个特殊用途修饰符，它指示基于列或MapperProperty的声明属性应该在映射继承方案内针对每个映射的子类明确配置。

下面，MyClass和MySubClass都将建立一个独立的id Column对象：

class HasSomeAttribute(object):
    @declared_attr.cascading
    def some_id(cls):
        if has_inherited_table(cls):
            return Column(
                ForeignKey('myclass.id'), primary_key=True)
        else:
            return Column(Integer, primary_key=True)

        return Column('id', Integer, primary_key=True)

class MyClass(HasSomeAttribute, Base):
    ""
    # ...

class MySubClass(MyClass):
    ""
    # ...

The behavior of the above configuration is that MySubClass will refer to both its own id column as well as that of MyClass underneath the attribute named some_id.

也可以看看

Inheritance Configuration

Mixing in Columns in Inheritance Scenarios

sqlalchemy.ext.declarative.api。 _declarative_constructor （ self，** kwargs ） T5> ¶ T6>

一个简单的构造函数，允许从kwargs初始化。

使用kwargs中的名称和值在构造的实例上设置属性。

只有作为实例类的属性存在的键才被允许。例如，这些可以是任何映射的列或关系。

sqlalchemy.ext.declarative。 T0> has_inherited_table T1> （ T2> CLS T3> ） T4> ¶< / T5>

给定一个类，如果它继承的任何类有一个映射表，则返回True，否则返回False。

sqlalchemy.ext.declarative.synonym_for(name, map_column=False)¶

装饰者，使Python @property成为列的查询同义词。

synonym()的装饰版本。正在装饰的函数是'descriptor'，否则将它的参数传递给synonym()：

@synonym_for('col')
@property
def prop(self):
    return 'special sauce'

常规的synonym()也可以在声明性设置中直接使用，并且可以方便读/写属性：

prop = synonym('col', descriptor=property(_read_prop, _write_prop))

sqlalchemy.ext.declarative。 T0> comparable_using T1> （ T2> comparator_factory T3> ） T4> ¶< / T5>

装饰者，允许在查询标准中使用Python @property。

这是通过comparator_factory和正在装饰的函数的comparable_property()的装饰器前端：

@comparable_using(MyComparatorType)
@property
def prop(self):
    return 'special sauce'

常规的comparable_property()也可以在声明性设置中直接使用，并且可以方便读/写属性：

prop = comparable_property(MyComparatorType)

sqlalchemy.ext.declarative.instrument_declarative(cls, registry, metadata)¶

给定一个类，使用给定的注册表（声明可以是任何字典和MetaData对象）声明性地配置类。

class sqlalchemy.ext.declarative。 AbstractConcreteBase ¶

基础：sqlalchemy.ext.declarative.api.ConcreteBase

“具体”声明映射的助手类。

AbstractConcreteBase will use the polymorphic_union() function automatically, against all tables mapped as a subclass to this class. 该函数通过__declare_last__()函数调用，该函数本质上是after_configured()事件的钩子。

AbstractConcreteBase does produce a mapped class for the base class, however it is not persisted to any table; it is instead mapped directly to the “polymorphic” selectable directly and is only used for selecting. 与ConcreteBase比较，它为基类创建一个持久表。

例：

from sqlalchemy.ext.declarative import AbstractConcreteBase

class Employee(AbstractConcreteBase, Base):
    pass

class Manager(Employee):
    __tablename__ = 'manager'
    employee_id = Column(Integer, primary_key=True)
    name = Column(String(50))
    manager_data = Column(String(40))

    __mapper_args__ = {
        'polymorphic_identity':'manager',
        'concrete':True}

抽象基类通过声明以特殊方式处理；在类配置时，它的行为就像是一个声明式混合或一个__abstract__基类。一旦配置了类并且生成了映射，它就会自己映射，但是在它的所有后继之后。这是在其他SQLAlchemy系统中找不到的独特映射系统。

使用这种方法，我们可以按照我们通常在Mixin and Custom Base Classes中执行的方式指定将在映射的子类上进行的列和属性：

class Company(Base):
    __tablename__ = 'company'
    id = Column(Integer, primary_key=True)

class Employee(AbstractConcreteBase, Base):
    employee_id = Column(Integer, primary_key=True)

    @declared_attr
    def company_id(cls):
        return Column(ForeignKey('company.id'))

    @declared_attr
    def company(cls):
        return relationship("Company")

class Manager(Employee):
    __tablename__ = 'manager'

    name = Column(String(50))
    manager_data = Column(String(40))

    __mapper_args__ = {
        'polymorphic_identity':'manager',
        'concrete':True}

但是，当我们使用我们的映射时，Manager和Employee将具有可独立使用的.company属性：

session.query(Employee).filter(Employee.company.has(id=5))

在版本1.0.0中进行了更改： - AbstractConcreteBase的机制已经过修改，以支持直接在抽象基础上建立的关系，而无需任何特殊的配置步骤。

也可以看看

ConcreteBase

Concrete Table Inheritance

Using the Declarative Helper Classes

class sqlalchemy.ext.declarative。 ConcreteBase ¶

“具体”声明映射的助手类。

ConcreteBase will use the polymorphic_union() function automatically, against all tables mapped as a subclass to this class. 该函数通过__declare_last__()函数调用，该函数本质上是after_configured()事件的钩子。

ConcreteBase produces a mapped table for the class itself. 与AbstractConcreteBase比较，不是。

例：

from sqlalchemy.ext.declarative import ConcreteBase

class Employee(ConcreteBase, Base):
    __tablename__ = 'employee'
    employee_id = Column(Integer, primary_key=True)
    name = Column(String(50))
    __mapper_args__ = {
                    'polymorphic_identity':'employee',
                    'concrete':True}

class Manager(Employee):
    __tablename__ = 'manager'
    employee_id = Column(Integer, primary_key=True)
    name = Column(String(50))
    manager_data = Column(String(40))
    __mapper_args__ = {
                    'polymorphic_identity':'manager',
                    'concrete':True}

也可以看看

AbstractConcreteBase

Concrete Table Inheritance

Using the Declarative Helper Classes

class sqlalchemy.ext.declarative。 DeferredReflection ¶

基于延迟反射步骤构建映射的辅助类。

通常，通过在声明式类中使用autoload = True将Table对象设置为__table__属性，可以在声明中使用声明式命令。The caveat is that the Table must be fully reflected, or at the very least have a primary key column, at the point at which a normal declarative mapping is constructed, meaning the Engine must be available at class declaration time.

在一个特定的方法被调用后，DeferredReflection mixin将映射器的构造移动到稍后的点，该方法首先反映了迄今为止创建的所有Table对象。类可以这样定义它：

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.ext.declarative import DeferredReflection
Base = declarative_base()

class MyClass(DeferredReflection, Base):
    __tablename__ = 'mytable'

Above, MyClass is not yet mapped. 在以上述方式定义了一系列类之后，所有表都可以被映射，并且使用prepare()创建映射：

engine = create_engine("someengine://...")
DeferredReflection.prepare(engine)

DeferredReflection mixin可以应用于各个类，用作声明性基本本身的基础，或者用于自定义抽象类。使用抽象基础允许为特定准备步骤准备只有一部分类，这对于使用多个引擎的应用程序是必需的。例如，如果应用程序有两个引擎，则可以使用两个基础，并分别进行准备，例如：

class ReflectedOne(DeferredReflection, Base):
    __abstract__ = True

class ReflectedTwo(DeferredReflection, Base):
    __abstract__ = True

class MyClass(ReflectedOne):
    __tablename__ = 'mytable'

class MyOtherClass(ReflectedOne):
    __tablename__ = 'myothertable'

class YetAnotherClass(ReflectedTwo):
    __tablename__ = 'yetanothertable'

# ... etc.

以上，可以分别配置ReflectedOne和ReflectedTwo的类层次结构：

ReflectedOne.prepare(engine_one)
ReflectedTwo.prepare(engine_two)

0.8版本中的新功能

classmethod prepare(engine)¶

为所有当前的DeferredReflection子类反映所有Table对象

class MyClass(Base):
    @classmethod
    def __declare_last__(cls):
        ""
        # do something with mappings

class MyClass(Base):
    @classmethod
    def __declare_first__(cls):
        ""
        # do something before mappings are configured

class SomeAbstractBase(Base):
    __abstract__ = True

    def some_helpful_method(self):
        ""

    @declared_attr
    def __mapper_args__(cls):
        return {"helpful mapper arguments":True}

class MyMappedClass(SomeAbstractBase):
    ""

Base = declarative_base()

class DefaultBase(Base):
    __abstract__ = True
    metadata = MetaData()

class OtherBase(Base):
    __abstract__ = True
    metadata = MetaData()

DefaultBase.metadata.create_all(some_engine)
OtherBase.metadata_create_all(some_other_engine)