Automap

定义 sqlalchemy.ext.declarative 系统的扩展，该系统自动从数据库模式生成映射类和关系，通常但不一定是通过反射。

希望 AutomapBase 系统为著名的 SQLSoup 也试图解决的问题提供快速且现代化的解决方案，即从现有数据库动态生成快速而基本的对象模型。通过严格在映射器配置级别解决问题，并与现有的声明式类技术完全集成，AutomapBase 旨在为快速自动生成特设映射的问题提供良好集成的方案。

提示

Automap 扩展面向“零声明”方法，其中可以从数据库模式动态生成完整的 ORM 模型，包括类和预先命名的关系。对于仍然希望使用显式类声明（包括显式关系定义）以及表反射的应用程序，DeferredReflection 类（在 使用 DeferredReflection 中描述）是更好的选择。

基本用法

最简单的用法是将现有数据库反射到新模型中。我们创建一个新的 AutomapBase 类，方式类似于我们创建声明式基类的方式，使用 automap_base()。然后，我们在生成的基类上调用 AutomapBase.prepare()，要求它反射模式并生成映射

from sqlalchemy.ext.automap import automap_base
from sqlalchemy.orm import Session
from sqlalchemy import create_engine

Base = automap_base()

# engine, suppose it has two tables 'user' and 'address' set up
engine = create_engine("sqlite:///mydatabase.db")

# reflect the tables
Base.prepare(autoload_with=engine)

# mapped classes are now created with names by default
# matching that of the table name.
User = Base.classes.user
Address = Base.classes.address

session = Session(engine)

# rudimentary relationships are produced
session.add(Address(email_address="foo@bar.com", user=User(name="foo")))
session.commit()

# collection-based relationships are by default named
# "<classname>_collection"
u1 = session.query(User).first()
print(u1.address_collection)

在上面，调用 AutomapBase.prepare() 时传递 AutomapBase.prepare.reflect 参数指示将在该声明式基类的 MetaData 集合上调用 MetaData.reflect() 方法；然后，MetaData 中的每个 可行的 Table 将自动生成一个新的映射类。ForeignKeyConstraint 对象（将各个表链接在一起）将用于在类之间生成新的双向 relationship() 对象。类和关系遵循默认的命名方案，我们可以自定义该方案。此时，我们由相关的 User 和 Address 类组成的基本映射已准备好以传统方式使用。

注意

通过 可行，我们指的是要映射的表必须指定主键。此外，如果表被检测为两个其他表之间的纯关联表，则它将不会被直接映射，而是将被配置为两个引用表映射之间的多对多表。

从现有 MetaData 生成映射

我们可以将预先声明的 MetaData 对象传递给 automap_base()。可以使用任何方式构造此对象，包括以编程方式、从序列化文件或通过使用 MetaData.reflect() 反射自身。下面我们说明了反射和显式表声明的组合

from sqlalchemy import create_engine, MetaData, Table, Column, ForeignKey
from sqlalchemy.ext.automap import automap_base

engine = create_engine("sqlite:///mydatabase.db")

# produce our own MetaData object
metadata = MetaData()

# we can reflect it ourselves from a database, using options
# such as 'only' to limit what tables we look at...
metadata.reflect(engine, only=["user", "address"])

# ... or just define our own Table objects with it (or combine both)
Table(
    "user_order",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("user_id", ForeignKey("user.id")),
)

# we can then produce a set of mappings from this MetaData.
Base = automap_base(metadata=metadata)

# calling prepare() just sets up mapped classes and relationships.
Base.prepare()

# mapped classes are ready
User = Base.classes.user
Address = Base.classes.address
Order = Base.classes.user_order

从多个模式生成映射

当与反射一起使用时，AutomapBase.prepare() 方法最多可以一次反射来自一个模式的表，使用 AutomapBase.prepare.schema 参数指示要从中反射的模式的名称。为了使用来自多个模式的表填充 AutomapBase，可以多次调用 AutomapBase.prepare()，每次都将不同的名称传递给 AutomapBase.prepare.schema 参数。AutomapBase.prepare() 方法保留已映射的 Table 对象的内部列表，并且仅为自上次运行 AutomapBase.prepare() 以来新的 Table 对象添加新映射

e = create_engine("postgresql://scott:tiger@localhost/test")

Base.metadata.create_all(e)

Base = automap_base()

Base.prepare(e)
Base.prepare(e, schema="test_schema")
Base.prepare(e, schema="test_schema_2")

2.0 版本新增: AutomapBase.prepare() 方法可以调用任意次数；每次运行只会映射新添加的表。在之前的 1.4 及更早版本中，多次调用会导致错误，因为它会尝试重新映射已映射的类。直接调用 MetaData.reflect() 的先前解决方法仍然可用。

跨多个模式自动映射同名表

对于多个模式可能具有同名表并因此会生成同名类的常见情况，可以通过使用 AutomapBase.prepare.classname_for_table 钩子在每个模式的基础上应用不同的类名，或者通过使用 AutomapBase.prepare.modulename_for_table 钩子来解决冲突，该钩子允许通过更改同名类的有效 __module__ 属性来消除歧义。在下面的示例中，此钩子用于为所有类创建一个 __module__ 属性，其形式为 mymodule.<schemaname>，其中模式名称 default 用于表示没有模式的情况

e = create_engine("postgresql://scott:tiger@localhost/test")

Base.metadata.create_all(e)


def module_name_for_table(cls, tablename, table):
    if table.schema is not None:
        return f"mymodule.{table.schema}"
    else:
        return f"mymodule.default"


Base = automap_base()

Base.prepare(e, modulename_for_table=module_name_for_table)
Base.prepare(
    e, schema="test_schema", modulename_for_table=module_name_for_table
)
Base.prepare(
    e, schema="test_schema_2", modulename_for_table=module_name_for_table
)

同名类被组织成一个层次结构集合，可在 AutomapBase.by_module 中找到。此集合使用特定包/模块的点分隔名称遍历到所需的类名。

注意

当使用 AutomapBase.prepare.modulename_for_table 钩子返回一个新的 __module__ 且不为 None 时，该类 不会 放入 AutomapBase.classes 集合中；只有未给出显式模块名称的类才会被放在这里，因为该集合无法单独表示同名类。

在上面的示例中，如果数据库在默认模式、test_schema 模式和 test_schema_2 模式这三个模式中都包含一个名为 accounts 的表，则将有三个单独的类可用，分别是

Base.by_module.mymodule.default.accounts
Base.by_module.mymodule.test_schema.accounts
Base.by_module.mymodule.test_schema_2.accounts

为所有 AutomapBase 类生成的默认模块命名空间是 sqlalchemy.ext.automap。如果未使用 AutomapBase.prepare.modulename_for_table 钩子，则 AutomapBase.by_module 的内容将完全位于 sqlalchemy.ext.automap 命名空间内（例如，MyBase.by_module.sqlalchemy.ext.automap.<classname>），其中将包含与 AutomapBase.classes 中看到的相同系列类。因此，通常只有在存在显式 __module__ 约定才需要使用 AutomapBase.by_module。

显式指定类

提示

如果显式类预计在应用程序中突出显示，请考虑改用 DeferredReflection。

automap 扩展允许以类似于 DeferredReflection 类的方式显式定义类。从 AutomapBase 扩展的类的行为类似于常规声明式类，但在构造后不会立即映射，而是在我们调用 AutomapBase.prepare() 时映射。AutomapBase.prepare() 方法将根据我们使用的表名来使用我们建立的类。如果我们的模式包含表 user 和 address，我们可以定义要使用的一个或两个类

from sqlalchemy.ext.automap import automap_base
from sqlalchemy import create_engine

# automap base
Base = automap_base()


# pre-declare User for the 'user' table
class User(Base):
    __tablename__ = "user"

    # override schema elements like Columns
    user_name = Column("name", String)

    # override relationships too, if desired.
    # we must use the same name that automap would use for the
    # relationship, and also must refer to the class name that automap will
    # generate for "address"
    address_collection = relationship("address", collection_class=set)


# reflect
engine = create_engine("sqlite:///mydatabase.db")
Base.prepare(autoload_with=engine)

# we still have Address generated from the tablename "address",
# but User is the same as Base.classes.User now

Address = Base.classes.address

u1 = session.query(User).first()
print(u1.address_collection)

# the backref is still there:
a1 = session.query(Address).first()
print(a1.user)

上面，更复杂的一个细节是我们说明了覆盖 automap 本应创建的 relationship() 对象之一。为此，我们需要确保名称与 automap 通常生成的名称匹配，即关系名称为 User.address_collection，并且从 automap 的角度来看，引用的类名称为 address，即使我们在使用此类时将其称为 Address。

覆盖命名方案

automap 的任务是根据模式生成映射类和关系名称，这意味着它在如何确定这些名称方面有决策点。这三个决策点是使用可以传递给 AutomapBase.prepare() 方法的函数提供的，并且被称为 classname_for_table()、name_for_scalar_relationship() 和 name_for_collection_relationship()。可以提供任何或所有这些函数，如下例所示，我们在其中使用“驼峰式”方案作为类名，并使用 Inflect 包作为集合名称的“复数器”

import re
import inflect


def camelize_classname(base, tablename, table):
    "Produce a 'camelized' class name, e.g."
    "'words_and_underscores' -> 'WordsAndUnderscores'"

    return str(
        tablename[0].upper()
        + re.sub(
            r"_([a-z])",
            lambda m: m.group(1).upper(),
            tablename[1:],
        )
    )


_pluralizer = inflect.engine()


def pluralize_collection(base, local_cls, referred_cls, constraint):
    "Produce an 'uncamelized', 'pluralized' class name, e.g."
    "'SomeTerm' -> 'some_terms'"

    referred_name = referred_cls.__name__
    uncamelized = re.sub(
        r"[A-Z]",
        lambda m: "_%s" % m.group(0).lower(),
        referred_name,
    )[1:]
    pluralized = _pluralizer.plural(uncamelized)
    return pluralized


from sqlalchemy.ext.automap import automap_base

Base = automap_base()

engine = create_engine("sqlite:///mydatabase.db")

Base.prepare(
    autoload_with=engine,
    classname_for_table=camelize_classname,
    name_for_collection_relationship=pluralize_collection,
)

从上面的映射中，我们现在将拥有类 User 和 Address，其中从 User 到 Address 的集合称为 User.addresses

User, Address = Base.classes.User, Base.classes.Address

u1 = User(addresses=[Address(email="foo@bar.com")])

关系检测

automap 完成的大部分工作是基于外键生成 relationship() 结构。一对多和多对一关系的工作机制如下

1. 检查给定 Table（已知映射到特定类）的 ForeignKeyConstraint 对象。

2. 从每个 ForeignKeyConstraint 中，远程 Table 对象与要映射到的类（如果有）匹配，否则跳过。

3. 由于我们正在检查的 ForeignKeyConstraint 对应于来自直接映射类的引用，因此关系将被设置为指向被引用类的多对一关系；将在被引用类上创建相应的指向此类的一对多反向引用。

4. 如果属于 ForeignKeyConstraint 的任何列不可为空（例如 nullable=False），则将向要传递给关系或反向引用的关键字参数添加 relationship.cascade 关键字参数 all, delete-orphan。如果 ForeignKeyConstraint 报告 ForeignKeyConstraint.ondelete 对于非空列设置为 CASCADE，或者对于可为空列设置为 SET NULL，则在关系关键字参数集中将 relationship.passive_deletes 标志设置为 True。请注意，并非所有后端都支持 ON DELETE 的反射。

5. 关系的名称使用 AutomapBase.prepare.name_for_scalar_relationship 和 AutomapBase.prepare.name_for_collection_relationship 可调用函数确定。重要的是要注意，默认关系命名从 实际类名 派生名称。如果您通过声明为特定类指定了显式名称，或者指定了备用类命名方案，则关系名称将从该名称派生。

6. 检查类中是否存在与这些名称匹配的现有映射属性。如果在一侧检测到一个，但在另一侧没有检测到，AutomapBase 会尝试在缺失的一侧创建关系，然后使用 relationship.back_populates 参数以便将新关系指向另一侧。

7. 在通常情况下，任何一侧都没有关系，AutomapBase.prepare() 会在“多对一”侧生成 relationship()，并使用 relationship.backref 参数将其与另一侧匹配。

8. relationship() 和可选的 backref() 的生成被移交给 AutomapBase.prepare.generate_relationship 函数，最终用户可以提供该函数以增强传递给 relationship() 或 backref() 的参数，或者使用这些函数的自定义实现。

自定义关系参数

AutomapBase.prepare.generate_relationship 钩子可用于向关系添加参数。对于大多数情况，我们可以使用现有的 generate_relationship() 函数返回对象，并在使用我们自己的参数增强给定的关键字字典之后。

下面是如何将 relationship.cascade 和 relationship.passive_deletes 选项发送到所有一对多关系的示例

from sqlalchemy.ext.automap import generate_relationship
from sqlalchemy.orm import interfaces


def _gen_relationship(
    base, direction, return_fn, attrname, local_cls, referred_cls, **kw
):
    if direction is interfaces.ONETOMANY:
        kw["cascade"] = "all, delete-orphan"
        kw["passive_deletes"] = True
    # make use of the built-in function to actually return
    # the result.
    return generate_relationship(
        base, direction, return_fn, attrname, local_cls, referred_cls, **kw
    )


from sqlalchemy.ext.automap import automap_base
from sqlalchemy import create_engine

# automap base
Base = automap_base()

engine = create_engine("sqlite:///mydatabase.db")
Base.prepare(autoload_with=engine, generate_relationship=_gen_relationship)

多对多关系

automap 将生成多对多关系，例如，包含 secondary 参数的关系。生成这些关系的过程如下

1. 在将任何映射类分配给给定 Table 之前，检查其 ForeignKeyConstraint 对象。

2. 如果表包含两个且仅包含两个 ForeignKeyConstraint 对象，并且此表中的所有列都是这两个 ForeignKeyConstraint 对象的成员，则该表被假定为“二级”表，并且 不会直接映射。

3. 将 Table 引用的两个（或一个，对于自引用）外部表与将要映射到的类（如果有）匹配。

4. 如果找到两侧的映射类，则在两个类之间创建多对多双向 relationship() / backref() 对。

5. 多对多的覆盖逻辑与一对多/多对一的覆盖逻辑相同；调用 generate_relationship() 函数来生成结构，并且将维护现有属性。

与继承的关系

automap 不会在两个处于继承关系中的类之间生成任何关系。也就是说，对于以下给出的两个类

class Employee(Base):
    __tablename__ = "employee"
    id = Column(Integer, primary_key=True)
    type = Column(String(50))
    __mapper_args__ = {
        "polymorphic_identity": "employee",
        "polymorphic_on": type,
    }


class Engineer(Employee):
    __tablename__ = "engineer"
    id = Column(Integer, ForeignKey("employee.id"), primary_key=True)
    __mapper_args__ = {
        "polymorphic_identity": "engineer",
    }

从 Engineer 到 Employee 的外键不用于关系，而是用于在两个类之间建立连接继承。

请注意，这意味着 automap 将不会为从子类链接到超类的外键生成 任何 关系。如果映射也具有从子类到超类的实际关系，则需要显式声明这些关系。在下面，由于我们有两个单独的从 Engineer 到 Employee 的外键，我们需要设置我们想要的关系以及 inherit_condition，因为这些不是 SQLAlchemy 可以猜测的东西

class Employee(Base):
    __tablename__ = "employee"
    id = Column(Integer, primary_key=True)
    type = Column(String(50))

    __mapper_args__ = {
        "polymorphic_identity": "employee",
        "polymorphic_on": type,
    }


class Engineer(Employee):
    __tablename__ = "engineer"
    id = Column(Integer, ForeignKey("employee.id"), primary_key=True)
    favorite_employee_id = Column(Integer, ForeignKey("employee.id"))

    favorite_employee = relationship(
        Employee, foreign_keys=favorite_employee_id
    )

    __mapper_args__ = {
        "polymorphic_identity": "engineer",
        "inherit_condition": id == Employee.id,
    }

处理简单的命名冲突

在映射期间发生命名冲突的情况下，根据需要覆盖 classname_for_table()、name_for_scalar_relationship() 和 name_for_collection_relationship() 中的任何一个。例如，如果 automap 尝试将多对一关系命名为与现有列相同，则可以有条件地选择备用约定。给定一个模式

CREATE TABLE table_a (
    id INTEGER PRIMARY KEY
);

CREATE TABLE table_b (
    id INTEGER PRIMARY KEY,
    table_a INTEGER,
    FOREIGN KEY(table_a) REFERENCES table_a(id)
);

上面的模式将首先自动映射 table_a 表作为名为 table_a 的类；然后它将在 table_b 的类上自动映射一个关系，该关系与此相关类具有相同的名称，例如 table_a。此关系名称与映射列 table_b.table_a 冲突，并且将在映射时发出错误。

我们可以通过使用下划线来解决此冲突

def name_for_scalar_relationship(
    base, local_cls, referred_cls, constraint
):
    name = referred_cls.__name__.lower()
    local_table = local_cls.__table__
    if name in local_table.columns:
        newname = name + "_"
        warnings.warn(
            "Already detected name %s present.  using %s" % (name, newname)
        )
        return newname
    return name


Base.prepare(
    autoload_with=engine,
    name_for_scalar_relationship=name_for_scalar_relationship,
)

或者，我们可以更改列侧的名称。可以使用显式命名声明式映射列中描述的技术修改已映射的列，方法是将列显式分配给新名称

Base = automap_base()


class TableB(Base):
    __tablename__ = "table_b"
    _table_a = Column("table_a", ForeignKey("table_a.id"))


Base.prepare(autoload_with=engine)

将 Automap 与显式声明一起使用

如前所述，automap 不依赖于反射，并且可以使用 MetaData 集合中的任何 Table 对象集合。 由此可见，automap 也可以用于生成缺失的关系，前提是有一个其他完整的模型，该模型完全定义了表元数据

from sqlalchemy.ext.automap import automap_base
from sqlalchemy import Column, Integer, String, ForeignKey

Base = automap_base()


class User(Base):
    __tablename__ = "user"

    id = Column(Integer, primary_key=True)
    name = Column(String)


class Address(Base):
    __tablename__ = "address"

    id = Column(Integer, primary_key=True)
    email = Column(String)
    user_id = Column(ForeignKey("user.id"))


# produce relationships
Base.prepare()

# mapping is complete, with "address_collection" and
# "user" relationships
a1 = Address(email="u1")
a2 = Address(email="u2")
u1 = User(address_collection=[a1, a2])
assert a1.user is u1

上面，给定基本完整的 User 和 Address 映射，我们在 Address.user_id 上定义的 ForeignKey 允许在映射的类上生成双向关系对 Address.user 和 User.address_collection。

请注意，当子类化 AutomapBase 时，AutomapBase.prepare() 方法是必需的； 如果不调用，我们声明的类将处于未映射状态。

拦截列定义

MetaData 和 Table 对象支持事件钩子 DDLEvents.column_reflect()，该钩子可用于在构造 Column 对象之前，拦截关于数据库列的反射信息。 例如，如果我们想使用诸如 "attr_<columnname>" 之类的命名约定来映射列，则可以应用该事件，如下所示

@event.listens_for(Base.metadata, "column_reflect")
def column_reflect(inspector, table, column_info):
    # set column.key = "attr_<lower_case_name>"
    column_info["key"] = "attr_%s" % column_info["name"].lower()


# run reflection
Base.prepare(autoload_with=engine)

1.4.0b2 版本新增: DDLEvents.column_reflect() 事件可以应用于 MetaData 对象。

另请参阅

DDLEvents.column_reflect()

自动化反射表的列命名方案 - 在 ORM 映射文档中

API 参考

对象名称	描述
automap_base([declarative_base], **kw)	生成声明式 automap 基类。
AutomapBase	“automap” 模式的基类。
classname_for_table(base, tablename, table)	返回应该使用的类名，给定表的名称。
generate_relationship(base, direction, return_fn, attrname, ..., **kw)	代表两个映射的类生成 relationship() 或 backref()。
name_for_collection_relationship(base, local_cls, referred_cls, constraint)	返回应该用于从一个类引用到另一个类的属性名称，用于集合引用。
name_for_scalar_relationship(base, local_cls, referred_cls, constraint)	返回应该用于从一个类引用到另一个类的属性名称，用于标量对象引用。

function sqlalchemy.ext.automap.automap_base(declarative_base: Type[Any] | None = None, **kw: Any) → Any

生成声明式 automap 基类。

此函数生成一个新的基类，它是 AutomapBase 类以及由 declarative_base() 生成的声明式基类的产物。

除了 declarative_base 之外的所有参数都是关键字参数，这些参数直接传递给 declarative_base() 函数。

参数:

• declarative_base – 由 declarative_base() 生成的现有类。 传递此参数后，该函数不再调用 declarative_base() 本身，并且所有其他关键字参数都将被忽略。

• **kw – 关键字参数将传递给 declarative_base()。

class sqlalchemy.ext.automap.AutomapBase

“automap” 模式的基类。

AutomapBase 类可以与由 declarative_base() 函数生成的“声明式基类”进行比较。 实际上，AutomapBase 类始终与实际的声明式基类一起用作 mixin。

新的可子类化的 AutomapBase 通常使用 automap_base() 函数实例化。

成员

by_module, classes, metadata, prepare()

另请参阅

Automap

attribute sqlalchemy.ext.automap.AutomapBase.by_module: ClassVar[ByModuleProperties]

Properties 的一个实例，其中包含以点分隔的模块名称链接到类的分层结构。

此集合是 AutomapBase.classes 集合的替代方案，当使用 AutomapBase.prepare.modulename_for_table 参数时，此集合非常有用，该参数将对生成的类应用不同的 __module__ 属性。

automap 生成的类的默认 __module__ 是 sqlalchemy.ext.automap； 要使用 AutomapBase.by_module 访问此命名空间，如下所示

User = Base.by_module.sqlalchemy.ext.automap.User

如果一个类的 __module__ 为 mymodule.account，则访问此命名空间，如下所示

MyClass = Base.by_module.mymodule.account.MyClass

2.0 版本新增。

另请参阅

从多个模式生成映射

attribute sqlalchemy.ext.automap.AutomapBase.classes: ClassVar[Properties[Type[Any]]]

Properties 的一个实例，其中包含类。

此对象的行为很像表上的 .c 集合。 类以其给定的名称存在，例如

Base = automap_base()
Base.prepare(autoload_with=some_engine)

User, Address = Base.classes.User, Base.classes.Address

对于与 Properties 的方法名称（例如 items()）重叠的类名，也支持 getitem 形式

Item = Base.classes["items"]

attribute sqlalchemy.ext.automap.AutomapBase.metadata: ClassVar[MetaData]

引用将用于新 Table 对象的 MetaData 集合。

另请参阅

访问表和元数据

classmethod sqlalchemy.ext.automap.AutomapBase.prepare(autoload_with: Engine | None = None, engine: Any | None = None, reflect: bool = False, schema: str | None = None, classname_for_table: PythonNameForTableType | None = None, modulename_for_table: PythonNameForTableType | None = None, collection_class: Any | None = None, name_for_scalar_relationship: NameForScalarRelationshipType | None = None, name_for_collection_relationship: NameForCollectionRelationshipType | None = None, generate_relationship: GenerateRelationshipType | None = None, reflection_options: Dict[_KT, _VT] | immutabledict[_KT, _VT] = {}) → None

从 MetaData 中提取映射的类和关系，并执行映射。

有关完整文档和示例，请参见 基本用法。

参数:

• autoload_with – 用于执行模式反射的 Engine 或 Connection； 指定后，将在该方法的范围内调用 MetaData.reflect() 方法。

• engine –

  旧版；使用 AutomapBase.autoload_with。 用于指示 Engine 或 Connection，如果 AutomapBase.reflect 为 True，则使用该 Engine 或 Connection 来反射表。

  在 1.4 版本中已弃用: AutomapBase.prepare.engine 参数已弃用，将在以后的版本中删除。 请使用 AutomapBase.prepare.autoload_with 参数。

• reflect –

  旧版；使用 AutomapBase.autoload_with。 指示应调用 MetaData.reflect()。

  在 1.4 版本中已弃用: AutomapBase.prepare.reflect 参数已弃用，将在以后的版本中删除。 当传递 AutomapBase.prepare.autoload_with 时，将启用反射。

• classname_for_table – 可调用函数，该函数将用于生成新的类名，给定表名。 默认为 classname_for_table()。

• modulename_for_table –

  可调用函数，该函数将用于为内部生成的类生成有效的 __module__，以允许在单个 automap 基类中存在多个同名类，这些类将位于不同的“模块”中。

  默认为 None，这将指示不会显式设置 __module__； Python 运行时将对这些类使用值 sqlalchemy.ext.automap。

  当将 __module__ 分配给生成的类时，可以使用 AutomapBase.by_module 集合根据以点分隔的模块名称访问它们。 使用此钩子分配了显式 __module_ 的类不会放入 AutomapBase.classes 集合中，而只会放入 AutomapBase.by_module 中。

  2.0 版本新增。

  另请参阅

  从多个模式生成映射

• name_for_scalar_relationship – 可调用函数，该函数将用于为标量关系生成关系名称。 默认为 name_for_scalar_relationship()。

• name_for_collection_relationship – 可调用函数，该函数将用于为面向集合的关系生成关系名称。 默认为 name_for_collection_relationship()。

• generate_relationship – 可调用函数，该函数将用于实际生成 relationship() 和 backref() 构造。 默认为 generate_relationship()。

• collection_class – Python 集合类，当创建表示集合的新 relationship() 对象时将使用该类。 默认为 list。

• schema –

  使用 AutomapBase.prepare.autoload_with 参数反射表时要反射的模式名称。 该名称将传递给 MetaData.reflect.schema 的 MetaData.reflect() 参数。 省略时，将使用数据库连接使用的默认模式。

  注意

  AutomapBase.prepare.schema 参数支持一次反射单个模式。 为了包含来自多个模式的表，请多次调用 AutomapBase.prepare()。

  有关多模式 automap 的概述，包括使用其他命名约定来解决表名冲突，请参见 从多个模式生成映射 部分。

  2.0 版本新增: AutomapBase.prepare() 支持直接多次调用，并跟踪已处理的表以避免第二次处理它们。

• reflection_options –

  如果存在，则此选项字典将传递给 MetaData.reflect()，以提供常规的特定于反射的选项，例如 only 和/或特定于方言的选项，例如 oracle_resolve_synonyms。

  1.4 版本新增。

function sqlalchemy.ext.automap.classname_for_table(base: Type[Any], tablename: str, table: Table) → str

返回应该使用的类名，给定表的名称。

默认实现是

return str(tablename)

可以使用 AutomapBase.prepare.classname_for_table 参数指定备用实现。

参数:

• base – 执行 prepare 的 AutomapBase 类。

• tablename – Table 的字符串名称。

• table – Table 对象本身。

返回:

字符串类名。

注意

在 Python 2 中，用于类名的字符串必须是非 Unicode 对象，例如 str() 对象。 Table 的 .name 属性通常是 Python unicode 子类，因此在考虑任何非 ASCII 字符后，应将 str() 函数应用于此名称。

function sqlalchemy.ext.automap.name_for_scalar_relationship(base: Type[Any], local_cls: Type[Any], referred_cls: Type[Any], constraint: ForeignKeyConstraint) → str

返回应该用于从一个类引用到另一个类的属性名称，用于标量对象引用。

默认实现是

return referred_cls.__name__.lower()

可以使用 AutomapBase.prepare.name_for_scalar_relationship 参数指定备用实现。

参数:

• base – 进行 prepare 操作的 AutomapBase 类。

• local_cls – 本地侧要映射的类。

• referred_cls – 引用侧要映射的类。

• constraint – 正在被检查以生成此关系的 ForeignKeyConstraint。

function sqlalchemy.ext.automap.name_for_collection_relationship(base: Type[Any], local_cls: Type[Any], referred_cls: Type[Any], constraint: ForeignKeyConstraint) → str

返回应该用于从一个类引用到另一个类的属性名称，用于集合引用。

默认实现是

return referred_cls.__name__.lower() + "_collection"

可以使用 AutomapBase.prepare.name_for_collection_relationship 参数指定备用实现。

参数:

• base – 进行 prepare 操作的 AutomapBase 类。

• local_cls – 本地侧要映射的类。

• referred_cls – 引用侧要映射的类。

• constraint – 正在被检查以生成此关系的 ForeignKeyConstraint。

function sqlalchemy.ext.automap.generate_relationship(base: Type[Any], direction: RelationshipDirection, return_fn: Callable[..., Relationship[Any]] | Callable[..., ORMBackrefArgument], attrname: str, local_cls: Type[Any], referred_cls: Type[Any], **kw: Any) → Relationship[Any] | ORMBackrefArgument

代表两个映射的类生成 relationship() 或 backref()。

可以使用 AutomapBase.prepare.generate_relationship 参数指定此函数的备用实现。

此函数的默认实现如下所示

if return_fn is backref:
    return return_fn(attrname, **kw)
elif return_fn is relationship:
    return return_fn(referred_cls, **kw)
else:
    raise TypeError("Unknown relationship function: %s" % return_fn)

参数:

• base – 进行 prepare 操作的 AutomapBase 类。

• direction – 指示关系的“方向”；这将是 ONETOMANY、 MANYTOONE、 MANYTOMANY 之一。

• return_fn – 默认用于创建关系的函数。这将是 relationship() 或 backref()。 backref() 函数的结果将在第二步中用于生成新的 relationship()，因此，如果正在使用自定义关系函数，则用户定义的实现正确区分这两个函数至关重要。

• attrname – 此关系要分配到的属性名称。如果 generate_relationship.return_fn 的值是 backref() 函数，则此名称是分配给反向引用的名称。

• local_cls – 此关系或反向引用将本地存在的“本地”类。

• referred_cls – 关系或反向引用所引用的“引用”类。

• **kw – 所有其他关键字参数都传递给该函数。

返回:

一个 relationship() 或 backref() 构造，由 generate_relationship.return_fn 参数决定。