版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

声明式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实例。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一个类型,用作生成的声明基类的基础。可能是类或类的元组。
  • tt> name - 默认为Base生成的类的显示名称。自定义这不是必需的,但可以提高回溯和调试的清晰度。
  • constructor – Defaults to _declarative_constructor(), an __init__ implementation that assigns **kwargs for declared fields and relationships to an instance. 如果提供None,则不会提供__init__,并且构造将通过正常的Python语义返回到cl.s .__ 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. 允许两个或多个声明式基类共享相同的类名称注册表以简化基础间关系。
  • metaclass – Defaults to DeclarativeMeta. 元类或__metaclass__兼容的可调用来作为生成的声明基类的元类型。

也可以看看

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()

class sqlalchemy.ext.declarative.declared_attr(fget, cascading=False)

基础: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.

sqlalchemy.ext.declarative.api._declarative_constructor(self, **kwargs)

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

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

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

sqlalchemy.ext.declarative。 T0> has_inherited_table T1> ( T2> CLS T3> ) T4>

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

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

装饰者,使一个Python @property作为一个列的查询同义词。

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>

装饰者,允许在查询标准中使用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}

抽象基类是以特殊的方式通过声明来处理的;在类配置的时候,它的行为就像一个声明性的mixin或一个__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}

然而,当我们使用我们的映射时,ManagerEmployee将具有可独立使用的.company属性:

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

在版本1.0.0中改变: - AbstractConcreteBase的机制已经被重写,以支持直接在抽象基础上建立的关系,而没有任何特殊的配置步骤。

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}
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.

上面,可以分别配置ReflectedOneReflectedTwo的类层次结构:

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

0.8版本中的新功能

classmethod prepare(engine)

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

特别指令

__declare_last__()

The __declare_last__() hook allows definition of a class level function that is automatically called by the MapperEvents.after_configured() event, which occurs after mappings are assumed to be completed and the ‘configure’ step has finished:

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

New in version 0.7.3.

__declare_first__()

__declare_last__(),但通过MapperEvents.before_configured()事件在映射器配置开始时调用:

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

版本0.9.3中新增。

__abstract__

__abstract__ causes declarative to skip the production of a table or mapper for the class entirely. 一个类可以像mixin(见Mixin and Custom Base Classes)一样添加到层次结构中,允许子类只从特殊类扩展:

class SomeAbstractBase(Base):
    __abstract__ = True

    def some_helpful_method(self):
        ""

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

class MyMappedClass(SomeAbstractBase):
    ""

__abstract__的一个可能用途是对不同的基础使用不同的MetaData

Base = declarative_base()

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

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

以上,从DefaultBase继承的类将使用一个MetaData作为表的注册表,那些从OtherBase继承的类将使用不同的表。表格本身可以在不同的数据库中创建:

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

New in version 0.7.3.