关联代理

associationproxy 用于创建跨关系的目标属性的读写视图。它本质上隐藏了两个端点之间的“中间”属性的使用，可以用于从相关对象的集合或标量关系中挑选字段，或减少使用关联对象模式的冗长。巧妙地运用，关联代理允许构建几乎任何几何形状的复杂集合和字典视图，并使用标准的、透明配置的关系模式持久化到数据库。

简化标量集合

考虑两个类之间一对多映射，User 和 Keyword。每个 User 可以拥有任意数量的 Keyword 对象，反之亦然（一对多模式在 多对多 中描述）。以下示例说明了这种模式，与之前相同，只是在 User 类中添加了一个额外的属性，名为 User.keywords

from __future__ import annotations

from typing import Final
from typing import List

from sqlalchemy import Column
from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy import Table
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
from sqlalchemy.ext.associationproxy import association_proxy
from sqlalchemy.ext.associationproxy import AssociationProxy


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))
    kw: Mapped[List[Keyword]] = relationship(secondary=lambda: user_keyword_table)

    def __init__(self, name: str):
        self.name = name

    # proxy the 'keyword' attribute from the 'kw' relationship
    keywords: AssociationProxy[List[str]] = association_proxy("kw", "keyword")


class Keyword(Base):
    __tablename__ = "keyword"
    id: Mapped[int] = mapped_column(primary_key=True)
    keyword: Mapped[str] = mapped_column(String(64))

    def __init__(self, keyword: str):
        self.keyword = keyword


user_keyword_table: Final[Table] = Table(
    "user_keyword",
    Base.metadata,
    Column("user_id", Integer, ForeignKey("user.id"), primary_key=True),
    Column("keyword_id", Integer, ForeignKey("keyword.id"), primary_key=True),
)

在上述示例中，association_proxy() 应用于 User 类，以生成 kw 关系的“视图”，该视图公开与每个 Keyword 对象关联的字符串值 .keyword。它还会在字符串添加到集合时透明地创建新的 Keyword 对象

>>> user = User("jek")
>>> user.keywords.append("cheese-inspector")
>>> user.keywords.append("snack-ninja")
>>> print(user.keywords)
['cheese-inspector', 'snack-ninja']

要了解其机制，首先回顾一下在不使用 .keywords 关联代理的情况下 User 和 Keyword 的行为。通常，读取和操作与 User 关联的“keyword”字符串集合，需要从每个集合元素遍历到 .keyword 属性，这可能很麻烦。以下示例说明了在不使用关联代理的情况下应用相同的操作序列

>>> # identical operations without using the association proxy
>>> user = User("jek")
>>> user.kw.append(Keyword("cheese-inspector"))
>>> user.kw.append(Keyword("snack-ninja"))
>>> print([keyword.keyword for keyword in user.kw])
['cheese-inspector', 'snack-ninja']

由 association_proxy() 函数生成的 AssociationProxy 对象是 Python 描述符 的实例，并且不被 Mapper 以任何方式“映射”。因此，它始终在映射类定义中内联表示，无论使用声明式映射还是命令式映射。

代理通过对底层映射属性或集合进行操作来响应操作，并且通过代理进行的更改会立即反映在映射属性中，反之亦然。底层属性仍然完全可访问。

首次访问时，关联代理会对目标集合执行自省操作，使其行为正确对应。代理是否为集合（如典型情况）或标量引用，以及集合的行为是否像集合、列表或字典等细节都会被考虑在内，以便代理的行为与底层集合或属性的行为一致。

创建新值

当关联代理拦截列表的 append() 事件（或集合的 add()、字典的 __setitem__() 或标量赋值事件）时，它会使用构造函数实例化“中间”对象的全新实例，并将给定的值作为单个参数传递。在上面的示例中，像这样的操作

user.keywords.append("cheese-inspector")

被关联代理转换为以下操作

user.kw.append(Keyword("cheese-inspector"))

此示例有效是因为我们为 Keyword 设计了构造函数，使其接受单个位置参数 keyword。对于无法使用单个参数构造函数的情况，可以使用 association_proxy.creator 参数自定义关联代理的创建行为，该参数引用一个可调用对象（即 Python 函数），该函数将根据单个参数生成一个新的对象实例。下面我们使用 lambda 来演示，这是一种典型的做法

class User(Base):
    ...

    # use Keyword(keyword=kw) on append() events
    keywords: AssociationProxy[List[str]] = association_proxy(
        "kw", "keyword", creator=lambda kw: Keyword(keyword=kw)
    )

对于基于列表或集合的集合，或者标量属性，creator 函数接受一个参数。对于基于字典的集合，它接受两个参数：“key”和“value”。下面在 代理到基于字典的集合 中展示了示例。

简化关联对象

“关联对象”模式是多对多关系的扩展形式，在 关联对象 中有描述。关联代理对于在常规使用过程中隐藏“关联对象”非常有用。

假设我们上面的 user_keyword 表包含我们想要显式映射的其他列，但在大多数情况下，我们不需要直接访问这些属性。下面，我们展示了一个新的映射，它引入了 UserKeywordAssociation 类，该类映射到我们之前展示的 user_keyword 表。此类添加了一个额外的列 special_key，这是一个我们偶尔想要访问但不是在通常情况下访问的值。我们在 User 类上创建了一个名为 keywords 的关联代理，它将桥接 User 的 user_keyword_associations 集合到每个 UserKeywordAssociation 上的 .keyword 属性。

from __future__ import annotations

from typing import List
from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.ext.associationproxy import association_proxy
from sqlalchemy.ext.associationproxy import AssociationProxy
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))

    user_keyword_associations: Mapped[List[UserKeywordAssociation]] = relationship(
        back_populates="user",
        cascade="all, delete-orphan",
    )

    # association proxy of "user_keyword_associations" collection
    # to "keyword" attribute
    keywords: AssociationProxy[List[Keyword]] = association_proxy(
        "user_keyword_associations",
        "keyword",
        creator=lambda keyword_obj: UserKeywordAssociation(keyword=keyword_obj),
    )

    def __init__(self, name: str):
        self.name = name


class UserKeywordAssociation(Base):
    __tablename__ = "user_keyword"
    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"), primary_key=True)
    keyword_id: Mapped[int] = mapped_column(ForeignKey("keyword.id"), primary_key=True)
    special_key: Mapped[Optional[str]] = mapped_column(String(50))

    user: Mapped[User] = relationship(back_populates="user_keyword_associations")

    keyword: Mapped[Keyword] = relationship()


class Keyword(Base):
    __tablename__ = "keyword"
    id: Mapped[int] = mapped_column(primary_key=True)
    keyword: Mapped[str] = mapped_column("keyword", String(64))

    def __init__(self, keyword: str):
        self.keyword = keyword

    def __repr__(self) -> str:
        return f"Keyword({self.keyword!r})"

通过以上配置，我们可以操作每个 User 对象的 .keywords 集合，每个集合都公开了一个 Keyword 对象的集合，这些对象是从底层的 UserKeywordAssociation 元素中获取的

>>> user = User("log")
>>> for kw in (Keyword("new_from_blammo"), Keyword("its_big")):
...     user.keywords.append(kw)
>>> print(user.keywords)
[Keyword('new_from_blammo'), Keyword('its_big')]

此示例与之前在 简化标量集合 中展示的示例形成对比，在该示例中，关联代理公开的是字符串集合，而不是组合对象的集合。在这种情况下，每个 .keywords.append() 操作等效于

>>> user.user_keyword_associations.append(
...     UserKeywordAssociation(keyword=Keyword("its_heavy"))
... )

关联代理创建了两个属性的 UserKeywordAssociation 对象，这两个属性都在 append() 操作的范围内被填充；.keyword 指向 Keyword 对象，而 .user 指向 User 对象。.keyword 属性首先被填充，因为关联代理响应 .append() 操作生成一个新的 UserKeywordAssociation 对象，并将给定的 Keyword 实例分配给 .keyword 属性。然后，当 UserKeywordAssociation 对象被追加到 User.user_keyword_associations 集合时，配置为 User.user_keyword_associations 的 back_populates 的 UserKeywordAssociation.user 属性将在给定的 UserKeywordAssociation 实例上初始化，以引用接收追加操作的父 User。上面的 special_key 参数保留其默认值 None。

对于我们确实想要 special_key 具有值的情况，我们显式创建 UserKeywordAssociation 对象。下面我们分配所有三个属性，其中在构造过程中分配 .user 会通过关系将新的 UserKeywordAssociation 追加到 User.user_keyword_associations 集合中

>>> UserKeywordAssociation(
...     keyword=Keyword("its_wood"), user=user, special_key="my special key"
... )

关联代理返回由所有这些操作表示的 Keyword 对象的集合

>>> print(user.keywords)
[Keyword('new_from_blammo'), Keyword('its_big'), Keyword('its_heavy'), Keyword('its_wood')]

代理到基于字典的集合

关联代理也可以代理到基于字典的集合。SQLAlchemy 映射通常使用 attribute_keyed_dict() 集合类型来创建字典集合，以及在 自定义基于字典的集合 中描述的扩展技术。

当关联代理检测到字典集合的使用时，它会调整其行为。当向字典添加新值时，关联代理会通过向创建函数传递两个参数（键和值）来实例化中间对象。与往常一样，此创建函数默认为中间类的构造函数，可以使用 creator 参数进行自定义。

下面，我们修改我们的 UserKeywordAssociation 示例，以便 User.user_keyword_associations 集合现在将使用字典进行映射，其中 UserKeywordAssociation.special_key 参数将用作字典的键。我们还将 creator 参数应用于 User.keywords 代理，以便在向字典添加新元素时适当地分配这些值

from __future__ import annotations
from typing import Dict

from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.ext.associationproxy import association_proxy
from sqlalchemy.ext.associationproxy import AssociationProxy
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
from sqlalchemy.orm.collections import attribute_keyed_dict


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))

    # user/user_keyword_associations relationship, mapping
    # user_keyword_associations with a dictionary against "special_key" as key.
    user_keyword_associations: Mapped[Dict[str, UserKeywordAssociation]] = relationship(
        back_populates="user",
        collection_class=attribute_keyed_dict("special_key"),
        cascade="all, delete-orphan",
    )
    # proxy to 'user_keyword_associations', instantiating
    # UserKeywordAssociation assigning the new key to 'special_key',
    # values to 'keyword'.
    keywords: AssociationProxy[Dict[str, Keyword]] = association_proxy(
        "user_keyword_associations",
        "keyword",
        creator=lambda k, v: UserKeywordAssociation(special_key=k, keyword=v),
    )

    def __init__(self, name: str):
        self.name = name


class UserKeywordAssociation(Base):
    __tablename__ = "user_keyword"
    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"), primary_key=True)
    keyword_id: Mapped[int] = mapped_column(ForeignKey("keyword.id"), primary_key=True)
    special_key: Mapped[str]

    user: Mapped[User] = relationship(
        back_populates="user_keyword_associations",
    )
    keyword: Mapped[Keyword] = relationship()


class Keyword(Base):
    __tablename__ = "keyword"
    id: Mapped[int] = mapped_column(primary_key=True)
    keyword: Mapped[str] = mapped_column(String(64))

    def __init__(self, keyword: str):
        self.keyword = keyword

    def __repr__(self) -> str:
        return f"Keyword({self.keyword!r})"

我们展示了 .keywords 集合是一个字典，它将 UserKeywordAssociation.special_key 值映射到 Keyword 对象

>>> user = User("log")

>>> user.keywords["sk1"] = Keyword("kw1")
>>> user.keywords["sk2"] = Keyword("kw2")

>>> print(user.keywords)
{'sk1': Keyword('kw1'), 'sk2': Keyword('kw2')}

复合关联代理

鉴于我们之前关于从关系到标量属性的代理、跨关联对象的代理和字典代理的示例，我们可以将所有三种技术结合起来，为 User 提供一个 keywords 字典，该字典严格处理 special_key 的字符串值映射到字符串 keyword。UserKeywordAssociation 和 Keyword 类完全隐藏。这是通过在 User 上构建一个关联代理来实现的，该代理引用 UserKeywordAssociation 上存在的关联代理。

from __future__ import annotations

from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.ext.associationproxy import association_proxy
from sqlalchemy.ext.associationproxy import AssociationProxy
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
from sqlalchemy.orm.collections import attribute_keyed_dict


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))

    user_keyword_associations: Mapped[Dict[str, UserKeywordAssociation]] = relationship(
        back_populates="user",
        collection_class=attribute_keyed_dict("special_key"),
        cascade="all, delete-orphan",
    )
    # the same 'user_keyword_associations'->'keyword' proxy as in
    # the basic dictionary example.
    keywords: AssociationProxy[Dict[str, str]] = association_proxy(
        "user_keyword_associations",
        "keyword",
        creator=lambda k, v: UserKeywordAssociation(special_key=k, keyword=v),
    )

    def __init__(self, name: str):
        self.name = name


class UserKeywordAssociation(Base):
    __tablename__ = "user_keyword"
    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"), primary_key=True)
    keyword_id: Mapped[int] = mapped_column(ForeignKey("keyword.id"), primary_key=True)
    special_key: Mapped[str] = mapped_column(String(64))
    user: Mapped[User] = relationship(
        back_populates="user_keyword_associations",
    )

    # the relationship to Keyword is now called
    # 'kw'
    kw: Mapped[Keyword] = relationship()

    # 'keyword' is changed to be a proxy to the
    # 'keyword' attribute of 'Keyword'
    keyword: AssociationProxy[Dict[str, str]] = association_proxy("kw", "keyword")


class Keyword(Base):
    __tablename__ = "keyword"
    id: Mapped[int] = mapped_column(primary_key=True)
    keyword: Mapped[str] = mapped_column(String(64))

    def __init__(self, keyword: str):
        self.keyword = keyword

User.keywords 现在是一个字符串到字符串的字典，其中 UserKeywordAssociation 和 Keyword 对象通过关联代理为我们透明地创建和删除。在下面的示例中，我们说明了赋值运算符的使用，它也由关联代理适当地处理，以便将字典值一次应用于集合。

>>> user = User("log")
>>> user.keywords = {"sk1": "kw1", "sk2": "kw2"}
>>> print(user.keywords)
{'sk1': 'kw1', 'sk2': 'kw2'}

>>> user.keywords["sk3"] = "kw3"
>>> del user.keywords["sk2"]
>>> print(user.keywords)
{'sk1': 'kw1', 'sk3': 'kw3'}

>>> # illustrate un-proxied usage
... print(user.user_keyword_associations["sk3"].kw)
<__main__.Keyword object at 0x12ceb90>

我们上面示例的一个注意事项是，由于 Keyword 对象是在每个字典设置操作时创建的，因此该示例无法维护 Keyword 对象在其字符串名称上的唯一性，这是这种标记场景的典型要求。对于此用例，建议使用 UniqueObject 食谱或类似的创建策略，该策略将对 Keyword 类的构造函数应用“先查找，然后创建”策略，以便如果给定名称已经存在，则返回已经存在的 Keyword。

使用关联代理进行查询

AssociationProxy 具有简单的 SQL 构造功能，这些功能在类级别上的工作方式类似于其他 ORM 映射属性，并提供基本的过滤支持，主要基于 SQL EXISTS 关键字。

注意

关联代理扩展的主要目的是允许对已加载的映射对象实例进行改进的持久性和对象访问模式。类绑定查询功能的使用有限，无法替代在使用 JOIN、急切加载选项等构建 SQL 查询时引用底层属性的需求。

对于本节，假设一个类同时包含引用列的关联代理和引用关联对象的关联代理，如下面的示例映射所示。

from __future__ import annotations
from sqlalchemy import Column, ForeignKey, Integer, String
from sqlalchemy.ext.associationproxy import association_proxy, AssociationProxy
from sqlalchemy.orm import DeclarativeBase, relationship
from sqlalchemy.orm.collections import attribute_keyed_dict
from sqlalchemy.orm.collections import Mapped


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))

    user_keyword_associations: Mapped[UserKeywordAssociation] = relationship(
        cascade="all, delete-orphan",
    )

    # object-targeted association proxy
    keywords: AssociationProxy[List[Keyword]] = association_proxy(
        "user_keyword_associations",
        "keyword",
    )

    # column-targeted association proxy
    special_keys: AssociationProxy[List[str]] = association_proxy(
        "user_keyword_associations", "special_key"
    )


class UserKeywordAssociation(Base):
    __tablename__ = "user_keyword"
    user_id: Mapped[int] = mapped_column(ForeignKey("user.id"), primary_key=True)
    keyword_id: Mapped[int] = mapped_column(ForeignKey("keyword.id"), primary_key=True)
    special_key: Mapped[str] = mapped_column(String(64))
    keyword: Mapped[Keyword] = relationship()


class Keyword(Base):
    __tablename__ = "keyword"
    id: Mapped[int] = mapped_column(primary_key=True)
    keyword: Mapped[str] = mapped_column(String(64))

生成的 SQL 采用针对 EXISTS SQL 运算符的相关子查询的形式，以便它可以在 WHERE 子句中使用，而无需对封闭查询进行额外的修改。如果关联代理的直接目标是**映射的列表达式**，则可以使用标准的列运算符，这些运算符将嵌入到子查询中。例如，一个直接的等号运算符。

>>> print(session.scalars(select(User).where(User.special_keys == "jek")))
SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE EXISTS (SELECT 1
FROM user_keyword
WHERE "user".id = user_keyword.user_id AND user_keyword.special_key = :special_key_1)

一个 LIKE 运算符。

>>> print(session.scalars(select(User).where(User.special_keys.like("%jek"))))
SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE EXISTS (SELECT 1
FROM user_keyword
WHERE "user".id = user_keyword.user_id AND user_keyword.special_key LIKE :special_key_1)

对于关联代理，其中直接目标是**关联对象或集合，或关联对象上的另一个关联代理或属性**，可以使用关系型运算符，例如 PropComparator.has() 和 PropComparator.any()。实际上，User.keywords 属性是两个关联代理链接在一起，因此当使用此代理生成 SQL 短语时，我们会得到两级 EXISTS 子查询。

>>> print(session.scalars(select(User).where(User.keywords.any(Keyword.keyword == "jek"))))
SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE EXISTS (SELECT 1
FROM user_keyword
WHERE "user".id = user_keyword.user_id AND (EXISTS (SELECT 1
FROM keyword
WHERE keyword.id = user_keyword.keyword_id AND keyword.keyword = :keyword_1)))

这不是最有效的 SQL 形式，因此虽然关联代理对于快速生成 WHERE 条件可能很方便，但应检查 SQL 结果并将其“展开”为显式 JOIN 条件以获得最佳使用效果，尤其是在将关联代理链接在一起时。

在版本 1.3 中更改： 关联代理根据目标类型提供不同的查询模式。见 AssociationProxy 现在为面向列的目标提供标准的列运算符.

级联标量删除

在版本 1.3 中新增。

给定如下映射

from __future__ import annotations
from sqlalchemy import Column, ForeignKey, Integer, String
from sqlalchemy.ext.associationproxy import association_proxy, AssociationProxy
from sqlalchemy.orm import DeclarativeBase, relationship
from sqlalchemy.orm.collections import attribute_keyed_dict
from sqlalchemy.orm.collections import Mapped


class Base(DeclarativeBase):
    pass


class A(Base):
    __tablename__ = "test_a"
    id: Mapped[int] = mapped_column(primary_key=True)
    ab: Mapped[AB] = relationship(uselist=False)
    b: AssociationProxy[B] = association_proxy(
        "ab", "b", creator=lambda b: AB(b=b), cascade_scalar_deletes=True
    )


class B(Base):
    __tablename__ = "test_b"
    id: Mapped[int] = mapped_column(primary_key=True)


class AB(Base):
    __tablename__ = "test_ab"
    a_id: Mapped[int] = mapped_column(ForeignKey(A.id), primary_key=True)
    b_id: Mapped[int] = mapped_column(ForeignKey(B.id), primary_key=True)

    b: Mapped[B] = relationship()

对 A.b 的赋值将生成一个 AB 对象。

a.b = B()

A.b 关联是标量，并且包括参数 AssociationProxy.cascade_scalar_deletes 的使用。当启用此参数时，将 A.b 设置为 None 将同时删除 A.ab。

a.b = None
assert a.ab is None

当 AssociationProxy.cascade_scalar_deletes 未设置时，上面的关联对象 a.ab 将保留在原处。

请注意，这与基于集合的关联代理的行为不同；在这种情况下，当代理集合的成员被删除时，始终会删除中间关联对象。行是否被删除取决于关系级联设置。

另请参阅

级联

标量关系

下面的示例说明了在多对一关系的多端上使用关联代理，访问标量对象的属性。

from __future__ import annotations

from typing import List

from sqlalchemy import ForeignKey
from sqlalchemy import String
from sqlalchemy.ext.associationproxy import association_proxy
from sqlalchemy.ext.associationproxy import AssociationProxy
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class Recipe(Base):
    __tablename__ = "recipe"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(64))

    steps: Mapped[List[Step]] = relationship(back_populates="recipe")
    step_descriptions: AssociationProxy[List[str]] = association_proxy(
        "steps", "description"
    )


class Step(Base):
    __tablename__ = "step"
    id: Mapped[int] = mapped_column(primary_key=True)
    description: Mapped[str]
    recipe_id: Mapped[int] = mapped_column(ForeignKey("recipe.id"))
    recipe: Mapped[Recipe] = relationship(back_populates="steps")

    recipe_name: AssociationProxy[str] = association_proxy("recipe", "name")

    def __init__(self, description: str) -> None:
        self.description = description


my_snack = Recipe(
    name="afternoon snack",
    step_descriptions=[
        "slice bread",
        "spread peanut butted",
        "eat sandwich",
    ],
)

可以使用以下方法打印 my_snack 的摘要。

>>> for i, step in enumerate(my_snack.steps, 1):
...     print(f"Step {i} of {step.recipe_name!r}: {step.description}")
Step 1 of 'afternoon snack': slice bread
Step 2 of 'afternoon snack': spread peanut butted
Step 3 of 'afternoon snack': eat sandwich

API 文档

对象名称	描述
association_proxy(target_collection, attr, *, [creator, getset_factory, proxy_factory, proxy_bulk_set, info, cascade_scalar_deletes, create_on_none_assignment, init, repr, default, default_factory, compare, kw_only, hash])	返回一个 Python 属性，该属性实现目标属性的视图，该视图引用目标成员上的属性。
AssociationProxy	一个描述符，它提供对象属性的读/写视图。
AssociationProxyExtensionType	一个枚举。
AssociationProxyInstance	一个每个类的对象，用于提供类和对象特定的结果。
ColumnAssociationProxyInstance	一个 AssociationProxyInstance，它具有数据库列作为目标。
ObjectAssociationProxyInstance	一个 AssociationProxyInstance，它具有对象作为目标。

function sqlalchemy.ext.associationproxy.association_proxy(target_collection: str, attr: str, *, creator: _CreatorProtocol | None = None, getset_factory: _GetSetFactoryProtocol | None = None, proxy_factory: _ProxyFactoryProtocol | None = None, proxy_bulk_set: _ProxyBulkSetProtocol | None = None, info: _InfoType | None = None, cascade_scalar_deletes: bool = False, create_on_none_assignment: bool = False, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: Any | None = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG) → AssociationProxy[Any]

返回一个 Python 属性，该属性实现目标属性的视图，该视图引用目标成员上的属性。

返回值是 AssociationProxy 的一个实例。

实现一个 Python 属性，表示一个关系作为一个更简单值的集合，或一个标量值。代理属性将模仿目标的集合类型（列表、字典或集合），或者，在 一对一关系的情况下，一个简单的标量值。

参数：

• target_collection – 直接目标属性的名称。该属性通常由 relationship() 映射以链接到目标集合，但也可以是一个多对一或非标量关系。

• attr – 与目标对象实例关联的实例上的属性，这些实例在目标对象实例上可用。

• creator –

  可选。

  定义当新项目添加到代理集合时的自定义行为。

  默认情况下，将新项目添加到集合将触发目标对象实例的构造，将给定项目作为位置参数传递给目标构造函数。对于此不足以处理的情况，association_proxy.creator 可以提供一个可调用对象，它将根据传递的项目以适当的方式构造对象。

  对于列表和集合导向的集合，单个参数传递给可调用对象。对于字典导向的集合，传递两个参数，分别对应于键和值。

  对于标量（即多对一，一对一）关系，也会调用 association_proxy.creator 可调用对象。如果目标关系属性的当前值为 None，则可调用对象用于构造新对象。如果已经存在对象值，则给定属性值将填充到该对象上。

  另请参阅

  创建新值

• cascade_scalar_deletes –

  当为 True 时，表示将代理值设置为 None，或通过 del 删除它，也应该删除源对象。仅适用于标量属性。通常，删除代理目标不会删除代理源，因为该对象可能还具有要保留的其他状态。

  在版本 1.3 中新增。

  另请参阅

  级联标量删除 - 完整的用法示例

• create_on_none_assignment –

  当为 True 时，表示将代理值设置为 None 应该使用创建者 **创建** 源对象（如果不存在）。仅适用于标量属性。这与 assocation_proxy.cascade_scalar_deletes 相互排斥。

  新功能：版本 2.0.18。

• init –

  特定于 声明式数据类映射，指定映射的属性是否应该作为由数据类过程生成的 __init__() 方法的一部分。

  新功能：版本 2.0.0b4。

• repr –

  特定于 声明式数据类映射，指定由此 AssociationProxy 建立的属性是否应该作为由数据类过程生成的 __repr__() 方法的一部分。

  新功能：版本 2.0.0b4。

• default_factory –

  特定于 声明式数据类映射，指定一个默认值生成函数，该函数将在作为由数据类过程生成的 __init__() 方法的一部分执行。

  新功能：版本 2.0.0b4。

• compare –

  特定于 声明式数据类映射，指示在为映射类生成 __eq__() 和 __ne__() 方法时，是否应将此字段包含在比较操作中。

  新功能：版本 2.0.0b4。

• kw_only –

  特定于 声明式数据类映射，指示在通过数据类过程生成 __init__() 方法时，是否应将此字段标记为关键字专用。

  新功能：版本 2.0.0b4。

• hash –

  特定于 声明式数据类映射，控制在为映射类生成 __hash__() 方法时，是否包含此字段。

  版本 2.0.36 中的新增功能。

• info – 可选，如果存在，将被分配给 AssociationProxy.info。

以下其他参数涉及在 AssociationProxy 对象中注入自定义行为，仅供高级使用。

参数：

• getset_factory –

  可选。代理属性访问由例程自动处理，这些例程根据此代理的 attr 参数获取和设置值。

  如果您想自定义此行为，您可以提供一个 getset_factory 可调用对象，它产生一个包含 getter 和 setter 函数的元组。该工厂使用两个参数调用，即底层集合的抽象类型和此代理实例。

• proxy_factory – 可选。要模拟的集合类型由嗅探目标集合来确定。如果您的集合类型无法通过鸭子类型确定，或者您想使用不同的集合实现，您可以提供一个工厂函数来生成这些集合。仅适用于非标量关系。

• proxy_bulk_set – 可选，与 proxy_factory 一起使用。

class sqlalchemy.ext.associationproxy.AssociationProxy

一个描述符，它提供对象属性的读/写视图。

成员

__init__(), cascade_scalar_deletes, create_on_none_assignment, creator, extension_type, for_class(), getset_factory, info, is_aliased_class, is_attribute, is_bundle, is_clause_element, is_instance, is_mapper, is_property, is_selectable, key, proxy_bulk_set, proxy_factory, target_collection, value_attr

类签名

class sqlalchemy.ext.associationproxy.AssociationProxy (sqlalchemy.orm.base.InspectionAttrInfo, sqlalchemy.orm.base.ORMDescriptor, sqlalchemy.orm._DCAttributeOptions, sqlalchemy.ext.associationproxy._AssociationProxyProtocol)

method sqlalchemy.ext.associationproxy.AssociationProxy.__init__(target_collection: str, attr: str, *, creator: _CreatorProtocol | None = None, getset_factory: _GetSetFactoryProtocol | None = None, proxy_factory: _ProxyFactoryProtocol | None = None, proxy_bulk_set: _ProxyBulkSetProtocol | None = None, info: _InfoType | None = None, cascade_scalar_deletes: bool = False, create_on_none_assignment: bool = False, attribute_options: _AttributeOptions | None = None)

构造一个新的 AssociationProxy。

AssociationProxy 对象通常使用 association_proxy() 构造函数构建。有关所有参数的说明，请参见 association_proxy() 的描述。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.cascade_scalar_deletes: bool

attribute sqlalchemy.ext.associationproxy.AssociationProxy.create_on_none_assignment: bool

attribute sqlalchemy.ext.associationproxy.AssociationProxy.creator: _CreatorProtocol | None

attribute sqlalchemy.ext.associationproxy.AssociationProxy.extension_type: InspectionAttrExtensionType = 'ASSOCIATION_PROXY'

扩展类型，如果有。默认为 NotExtension.NOT_EXTENSION

另请参阅

HybridExtensionType

AssociationProxyExtensionType

method sqlalchemy.ext.associationproxy.AssociationProxy.for_class(class_: Type[Any], obj: object | None = None) → AssociationProxyInstance[_T]

返回特定映射类的内部状态。

例如，给定一个类 User

class User(Base):
    # ...

    keywords = association_proxy('kws', 'keyword')

如果我们从 Mapper.all_orm_descriptors 中访问此 AssociationProxy，并且我们想查看此代理的由 User 映射的目标类

inspect(User).all_orm_descriptors["keywords"].for_class(User).target_class

这将返回一个特定于 User 类的 AssociationProxyInstance 实例。 AssociationProxy 对象仍然对其父类保持不可知。

参数：

• class_ – 我们正在返回其状态的类。

• obj – 可选的，如果属性引用多态目标，则需要该类的实例，例如，我们需要查看实际目标对象的类型以获取完整路径。

New in version 1.3: - AssociationProxy 不再存储特定于特定父类的任何状态；状态现在存储在每个类的 AssociationProxyInstance 对象中。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.getset_factory: _GetSetFactoryProtocol | None

attribute sqlalchemy.ext.associationproxy.AssociationProxy.info

从 InspectionAttrInfo.info 属性继承 InspectionAttrInfo

与对象关联的信息字典，允许将用户定义的数据与该 InspectionAttr 相关联。

字典在首次访问时生成。或者，它可以作为构造函数参数指定给 column_property()、relationship() 或 composite() 函数。

另请参阅

QueryableAttribute.info

SchemaItem.info

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_aliased_class = False

从 InspectionAttr.is_aliased_class 属性继承 InspectionAttr

如果此对象是 AliasedClass 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_attribute = True

如果此对象是 Python 描述符，则为 True。

这可以指代许多类型之一。通常是 QueryableAttribute，它代表 MapperProperty 处理属性事件。但也可以是扩展类型，例如 AssociationProxy 或 hybrid_property。 InspectionAttr.extension_type 将引用标识特定子类型的常量。

另请参阅

Mapper.all_orm_descriptors

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_bundle = False

从 InspectionAttr.is_bundle 属性继承 InspectionAttr

如果此对象是 Bundle 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_clause_element = False

从 InspectionAttr.is_clause_element 属性继承 InspectionAttr

如果此对象是 ClauseElement 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_instance = False

继承自 InspectionAttr.is_instance 属性 InspectionAttr

如果此对象是 InstanceState 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_mapper = False

继承自 InspectionAttr.is_mapper 属性 InspectionAttr

如果此对象是 Mapper 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_property = False

继承自 InspectionAttr.is_property 属性 InspectionAttr

如果此对象是 MapperProperty 的实例，则为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.is_selectable = False

继承自 InspectionAttr.is_selectable 属性 InspectionAttr

如果此对象是 Selectable 的实例，则返回 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxy.key: str

attribute sqlalchemy.ext.associationproxy.AssociationProxy.proxy_bulk_set: _ProxyBulkSetProtocol | None

attribute sqlalchemy.ext.associationproxy.AssociationProxy.proxy_factory: _ProxyFactoryProtocol | None

attribute sqlalchemy.ext.associationproxy.AssociationProxy.target_collection: str

attribute sqlalchemy.ext.associationproxy.AssociationProxy.value_attr: str

class sqlalchemy.ext.associationproxy.AssociationProxyInstance

一个每个类的对象，用于提供类和对象特定的结果。

当 AssociationProxy 以特定类的实例形式被调用时，它将被使用，即当它用作常规 Python 描述符时。

当将 AssociationProxy 作为普通的 Python 描述符时，AssociationProxyInstance 是实际提供信息的 对象。在正常情况下，它的存在是透明的

>>> User.keywords.scalar
False

在特殊情况下，AssociationProxy 对象被直接访问，为了获得对 AssociationProxyInstance 的显式句柄，请使用 AssociationProxy.for_class() 方法

proxy_state = inspect(User).all_orm_descriptors["keywords"].for_class(User)

# view if proxy object is scalar or not
>>> proxy_state.scalar
False

在版本 1.3 中新增。

成员

__eq__(), __le__(), __lt__(), __ne__(), all_(), any(), any_(), asc(), attr, between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(), collate(), collection_class, concat(), contains(), delete(), desc(), distinct(), endswith(), for_proxy(), get(), has(), icontains(), iendswith(), ilike(), in_(), info, is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(), like(), local_attr, match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), op(), operate(), parent, regexp_match(), regexp_replace(), remote_attr, reverse_operate(), scalar, set(), startswith(), target_class, timetuple

类签名

类 sqlalchemy.ext.associationproxy.AssociationProxyInstance (sqlalchemy.orm.base.SQLORMOperations)

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.__eq__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法 ColumnOperators

实现 == 运算符。

在列上下文中，生成子句 a = b。如果目标是 None，则生成 a IS NULL。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.__le__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法 ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.__lt__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法 ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.__ne__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法 ColumnOperators

实现 != 运算符。

在列上下文中，生成子句 a != b。如果目标是 None，则生成 a IS NOT NULL。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 all_() 子句。

有关示例，请参见 all_() 的文档。

注意

请勿将新的 ColumnOperators.all_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.all() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

使用 EXISTS 生成一个代理的“any”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 any_() 子句。

有关示例，请参见 any_() 的文档。

注意

请勿将新的 ColumnOperators.any_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.asc() → ColumnOperators

继承自 ColumnOperators.asc() 方法，该方法属于 ColumnOperators

针对父对象生成一个 asc() 子句。

属性 sqlalchemy.ext.associationproxy.AssociationProxyInstance.attr

返回一个包含 (local_attr, remote_attr) 的元组。

此属性最初旨在通过 Query.join() 方法一次性跨两个关系进行连接来方便使用，但是这使用了过时的调用方式。

若要使用 select.join() 或 Query.join() 与关联代理一起使用，当前方法是分别使用 AssociationProxyInstance.local_attr 和 AssociationProxyInstance.remote_attr 属性。

stmt = (
    select(Parent).
    join(Parent.proxied.local_attr).
    join(Parent.proxied.remote_attr)
)

将来的版本可能会试图为关联代理属性提供更简洁的连接模式。

另请参阅

AssociationProxyInstance.local_attr

AssociationProxyInstance.remote_attr

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

继承自 ColumnOperators.between() 方法，该方法属于 ColumnOperators

针对父对象生成一个 between() 子句，该子句使用给定的下限和上限范围。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_and(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_and() 方法，该方法属于 ColumnOperators

生成一个按位 AND 运算，通常使用 & 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_lshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_lshift() 方法，该方法属于 ColumnOperators

执行按位左移操作，通常使用 << 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_not() → ColumnOperators

继承自 ColumnOperators.bitwise_not() 方法 ColumnOperators

执行按位取反操作，通常使用 ~ 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_or(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_or() 方法 ColumnOperators

执行按位或运算，通常使用 | 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_rshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_rshift() 方法 ColumnOperators

执行按位右移操作，通常使用 >> 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.bitwise_xor(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_xor() 方法 ColumnOperators

执行按位异或运算，通常使用 ^ 运算符，或 PostgreSQL 中的 # 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.bool_op() 方法 Operators

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并将 Operators.op.is_comparison 标志传递为 True 的简写。使用 Operators.bool_op() 的一个主要优点是，当使用列结构时，对于 PEP 484 目的，返回表达式的“布尔”性质将存在。

另请参阅

Operators.op()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法 ColumnOperators

对父对象执行 collate() 子句，给定排序规则字符串。

另请参阅

collate()

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.collection_class: Type[Any] | None

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.concat(other: Any) → ColumnOperators

继承自 ColumnOperators.concat() 方法 ColumnOperators

实现 ‘concat’ 运算符。

在列上下文中，生成子句 a || b，或者在 MySQL 上使用 concat() 运算符。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.contains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.contains() 方法 ColumnOperators

实现 ‘contains’ 运算符。

生成一个 LIKE 表达式，用于测试与字符串值中间的匹配。

column LIKE '%' || <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.contains("foobar"))

由于运算符使用 LIKE，所以 "%" 和 "_" 等通配符字符在 <other> 表达式中存在时，也会像通配符一样起作用。对于文字字符串值，ColumnOperators.contains.autoescape 标志可以设置为 True 以对字符串值中的这些字符的出现应用转义，以便它们匹配自身而不是通配符字符。或者，ColumnOperators.contains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个普通的字符串值，但也可能是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.contains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.contains("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.contains("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.delete(obj: Any) → None

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.desc() → ColumnOperators

继承自 ColumnOperators.desc() 方法 ColumnOperators

针对父对象生成一个 desc() 子句。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.distinct() → ColumnOperators

继承自 ColumnOperators.distinct() 方法 ColumnOperators

针对父对象生成一个 distinct() 子句。

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.endswith() 的 ColumnOperators 方法

实现“endswith”操作符。

生成一个 LIKE 表达式，用于测试字符串值的末尾是否匹配。

column LIKE '%' || <other>

例如：

stmt = select(sometable).\
    where(sometable.c.column.endswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.endswith.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.endswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.endswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.endswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '^'

  该参数也可以与 ColumnOperators.endswith.autoescape 结合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

classmethod sqlalchemy.ext.associationproxy.AssociationProxyInstance.for_proxy(parent: AssociationProxy[_T], owning_class: Type[Any], parent_instance: Any) → AssociationProxyInstance[_T]

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.get(obj: Any) → _T | None | AssociationProxyInstance[_T]

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

使用 EXISTS 生成一个代理的“has”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.icontains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.icontains() 的 ColumnOperators 方法

实现 icontains 操作符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的中间部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.icontains.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.icontains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.icontains("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.icontains("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.contains()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.iendswith() 的 ColumnOperators 方法

实现 iendswith 操作符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的末尾部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式内存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于字面字符串值，ColumnOperators.iendswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符进行转义，以便它们匹配自身而不是通配符字符。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个普通字符串值，但也可能是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 在默认情况下不会转义，除非 ColumnOperators.iendswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.iendswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.iendswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  该参数也可以与 ColumnOperators.iendswith.autoescape 组合

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.ilike() 方法的 ColumnOperators

实现 ilike 操作符，例如不区分大小写的 LIKE。

在列上下文中，生成形式为以下表达式的其中一个：

lower(a) LIKE lower(other)

或者在支持 ILIKE 操作符的后端

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.ilike("foo/%bar", escape="/")

另请参阅

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.in_(other: Any) → ColumnOperators

继承自 ColumnOperators.in_() 方法的 ColumnOperators

实现 in 操作符。

在列上下文中，生成 column IN <other> 子句。

给定的参数 other 可以是

• 字面值的列表，例如：

  stmt.where(column.in_([1, 2, 3]))

  在此调用形式中，项目列表被转换为与给定列表长度相同的绑定参数集

  WHERE COL IN (?, ?, ?)

• 如果比较针对包含多个表达式的 tuple_()，则可以提供元组列表

  from sqlalchemy import tuple_
  stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 空列表，例如：

  stmt.where(column.in_([]))

  在此调用形式中，表达式渲染“空集”表达式。这些表达式针对各个后端进行调整，通常试图获得一个空的 SELECT 语句作为子查询。例如，在 SQLite 上，表达式是

  WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.4 中更改： 空 IN 表达式现在在所有情况下都使用执行时生成的 SELECT 子查询。

• 绑定参数，例如 bindparam()，如果它包含 bindparam.expanding 标志，则可以使用

  stmt.where(column.in_(bindparam('value', expanding=True)))

  在此调用形式中，表达式渲染一个特殊的非 SQL 占位符表达式，它看起来像

  WHERE COL IN ([EXPANDING_value])

  此占位符表达式在语句执行时被拦截，以转换为前面说明的绑定参数可变数量形式。如果语句以以下方式执行

  connection.execute(stmt, {"value": [1, 2, 3]})

  数据库将为每个值传递一个绑定参数

  WHERE COL IN (?, ?, ?)

  在版本 1.2 中添加： 添加了“扩展”绑定参数

  如果传递了空列表，则会渲染一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是

  WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.3 中添加： “扩展”绑定参数现在支持空列表

• select() 结构，通常是关联的标量选择

  stmt.where(
      column.in_(
          select(othertable.c.y).
          where(table.c.x == othertable.c.x)
      )
  )

  在此调用形式中，ColumnOperators.in_() 按照给定方式渲染

  WHERE COL IN (SELECT othertable.y
  FROM othertable WHERE othertable.x = table.x)

参数：

other – 字面值的列表，select() 结构，或 bindparam() 结构，其中 bindparam.expanding 标志设置为 True。

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.info

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.is_(other: Any) → ColumnOperators

继承自 ColumnOperators.is_() 方法的 ColumnOperators

实现 IS 操作符。

通常，当与 None 值进行比较时，会自动生成 IS，它解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS。

另请参阅

ColumnOperators.is_not()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.is_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_distinct_from() 方法的 ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS NOT b”。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.is_not(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.is_not_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.isnot(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.isnot_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.istartswith() 方法 ColumnOperators

实现 istartswith 运算符，例如 ColumnOperators.startswith() 的不区分大小写的版本。

生成一个 LIKE 表达式，用于测试字符串值的开头的不区分大小写的匹配

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于该运算符使用 LIKE，因此在 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，ColumnOperators.istartswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符应用转义，以便它们本身匹配，而不是作为通配符。或者，ColumnOperators.istartswith.escape 参数将建立一个给定字符作为转义字符，当目标表达式不是文字字符串时，这很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符 % 和 _ 在默认情况下不会被转义，除非 ColumnOperators.istartswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.istartswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.istartswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.istartswith.autoescape 组合使用

  somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.like() 方法 ColumnOperators

实现 like 操作符。

在列上下文中，生成表达式

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.like("foo/%bar", escape="/")

另请参阅

ColumnOperators.ilike()

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.local_attr

此 AssociationProxyInstance 引用的“本地”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.match(other: Any, **kwargs: Any) → ColumnOperators

继承自 ColumnOperators.match() 方法 ColumnOperators

实现数据库特定的“匹配”操作符。

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或操作符。示例包括

• PostgreSQL - 呈现 x @@ plainto_tsquery(y)

  在版本 2.0 中更改: plainto_tsquery() 现在用于 PostgreSQL 而不是 to_tsquery()；有关与其他形式的兼容性，请参见 全文搜索。

• MySQL - 呈现 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - 带有附加功能的 MySQL 特定构造。

• Oracle - 呈现 CONTAINS(x, y)

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将发出操作符为“MATCH”。例如，这与 SQLite 兼容。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.not_ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_ilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.not_in(other: Any) → ColumnOperators

继承自 ColumnOperators.not_in() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.not_like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_like() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.notilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.notin_(other: Any) → ColumnOperators

继承自 ColumnOperators.notin_() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.notlike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notlike() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.nulls_last() → ColumnOperators

继承自 ColumnOperators.nulls_last() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.nullsfirst() → ColumnOperators

继承自 ColumnOperators.nullsfirst() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成一个通用的运算符函数。

例如：

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可以用来明确表示位运算符。例如

somecolumn.op('&')(0xff)

是对 somecolumn 中的值进行按位与运算。

参数：

• opstring – 一个字符串，它将在 SQL 表达式中作为此元素和传递给生成函数的表达式之间的中缀运算符输出。

• precedence –

  数据库预计对 SQL 表达式中的运算符应用的优先级。这个整数值作为 SQL 编译器的提示，用于确定何时应该在特定运算符周围渲染显式括号。较小的数字将导致在应用于另一个具有更高优先级的运算符时对表达式进行括号运算。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，-100 将低于或等于所有运算符。

  另请参阅

  我在使用 op() 生成自定义运算符时，我的括号没有正确显示 - SQLAlchemy SQL 编译器如何渲染括号的详细描述

• is_comparison –

  遗留；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔真/假值，如 ==、> 等。提供此标志是为了使 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法代替；这个更简洁的运算符会自动设置此参数，还会提供正确的 PEP 484 类型支持，因为返回的对象将表示一个“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制使用此运算符生成的表达式的返回类型为该类型。默认情况下，指定 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些没有指定该参数的运算符将与左操作数具有相同的类型。

• python_impl –

  一个可选的 Python 函数，它可以像在数据库服务器上运行此运算符一样评估两个 Python 值。对于 Python 内的 SQL 表达式评估函数很有用，例如 ORM 混合属性，以及用于在多行更新或删除后匹配会话中的对象的 ORM “评估器”。

  例如：

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也将适用于非 SQL 左操作数和右操作数

  >>> expr.operator(5, 10)
  15

  新版功能在版本 2.0 中。

另请参阅

Operators.bool_op()

重新定义和创建新的运算符

在联接条件中使用自定义运算符

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

继承自 Operators.operate() 方法 Operators

对参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类中重写此方法可以对所有操作应用通用行为。例如，重写 ColumnOperators 以对左右两侧应用 func.lower()

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 操作的“另一侧”。对于大多数操作来说，它将是一个标量。

• **kwargs – 修饰符。这些可能由特殊运算符传递，例如 ColumnOperators.contains()。

属性 sqlalchemy.ext.associationproxy.AssociationProxyInstance.parent: _AssociationProxyProtocol[_T]

方法 sqlalchemy.ext.associationproxy.AssociationProxyInstance.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_match() 方法 ColumnOperators

实现特定于数据库的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的 REGEXP 类函数或运算符，但是可用的特定正则表达式语法和标志**不是后端无关的**。

示例包括

• PostgreSQL - 在被否定时呈现 x ~ y 或 x !~ y。

• Oracle - 呈现 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将以“REGEXP”或“NOT REGEXP”的形式发出运算符。例如，这与 SQLite 和 MySQL 兼容。

正则表达式支持目前已在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。SQLite 提供了部分支持。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志特定于后端。一些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_replace()

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_replace() 方法 ColumnOperators

实现特定于数据库的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析为后端提供的 REGEXP_REPLACE 类函数，该函数通常会发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志**不是后端无关的**。

正则表达式替换支持目前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• pattern – 替换字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志特定于后端。一些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_match()

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.remote_attr

此 AssociationProxyInstance 引用的“远程”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

继承自 Operators.reverse_operate() 方法 Operators

反向操作一个参数。

使用方法与 operate() 相同。

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.scalar

如果此 AssociationProxyInstance 代理本地端的标量关系，则返回 True。

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.set(obj: Any, values: _T) → None

method sqlalchemy.ext.associationproxy.AssociationProxyInstance.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.startswith() 方法 ColumnOperators

实现 startswith 运算符。

生成 LIKE 表达式，用于测试字符串值开头的匹配项。

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于操作符使用 LIKE，因此 "%" 和 "_" 这些出现在 <other> 表达式中的通配符字符也会像通配符一样工作。对于字面字符串值，ColumnOperators.startswith.autoescape 标志可以设置为 True，以便对字符串值中出现的这些字符进行转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可能是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.startswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.startswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.startswith.autoescape 组合使用。

  somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.target_class: Type[Any]

由这个 AssociationProxyInstance 处理的中介类。

拦截的追加/设置/赋值事件将导致生成该类的新的实例。

attribute sqlalchemy.ext.associationproxy.AssociationProxyInstance.timetuple: Literal[None] = None

从 ColumnOperators.timetuple 属性继承 ColumnOperators

黑客行为，允许在 LHS 上比较 datetime 对象。

class sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance

一个 AssociationProxyInstance，它具有对象作为目标。

成员

__le__(), __lt__(), all_(), any(), any_(), asc(), attr, between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), has(), icontains(), iendswith(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(), like(), local_attr, match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), op(), operate(), regexp_match(), regexp_replace(), remote_attr, reverse_operate(), scalar, startswith(), target_class, timetuple

类签名

类 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance (sqlalchemy.ext.associationproxy.AssociationProxyInstance)

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.__le__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法 ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.__lt__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法 ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 all_() 子句。

有关示例，请参见 all_() 的文档。

注意

请勿将新的 ColumnOperators.all_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.all() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

从 AssociationProxyInstance.any() 方法继承 AssociationProxyInstance

使用 EXISTS 生成一个代理的“any”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 any_() 子句。

有关示例，请参见 any_() 的文档。

注意

请勿将新的 ColumnOperators.any_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.asc() → ColumnOperators

继承自 ColumnOperators.asc() 方法，该方法属于 ColumnOperators

针对父对象生成一个 asc() 子句。

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.attr

从 AssociationProxyInstance.attr 属性继承 AssociationProxyInstance

返回一个包含 (local_attr, remote_attr) 的元组。

此属性最初旨在通过 Query.join() 方法一次性跨两个关系进行连接来方便使用，但是这使用了过时的调用方式。

若要使用 select.join() 或 Query.join() 与关联代理一起使用，当前方法是分别使用 AssociationProxyInstance.local_attr 和 AssociationProxyInstance.remote_attr 属性。

stmt = (
    select(Parent).
    join(Parent.proxied.local_attr).
    join(Parent.proxied.remote_attr)
)

将来的版本可能会试图为关联代理属性提供更简洁的连接模式。

另请参阅

AssociationProxyInstance.local_attr

AssociationProxyInstance.remote_attr

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

继承自 ColumnOperators.between() 方法，该方法属于 ColumnOperators

针对父对象生成一个 between() 子句，该子句使用给定的下限和上限范围。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_and(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_and() 方法，该方法属于 ColumnOperators

生成一个按位 AND 运算，通常使用 & 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_lshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_lshift() 方法，该方法属于 ColumnOperators

执行按位左移操作，通常使用 << 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_not() → ColumnOperators

继承自 ColumnOperators.bitwise_not() 方法 ColumnOperators

执行按位取反操作，通常使用 ~ 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_or(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_or() 方法 ColumnOperators

执行按位或运算，通常使用 | 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_rshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_rshift() 方法 ColumnOperators

执行按位右移操作，通常使用 >> 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bitwise_xor(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_xor() 方法 ColumnOperators

执行按位异或运算，通常使用 ^ 运算符，或 PostgreSQL 中的 # 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.bool_op() 方法 Operators

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并将 Operators.op.is_comparison 标志传递为 True 的简写。 使用 Operators.bool_op() 的一个关键优势是，当使用列构造时，返回表达式的“布尔”性质将存在于 PEP 484 目的。

另请参阅

Operators.op()

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法 ColumnOperators

对父对象执行 collate() 子句，给定排序规则字符串。

另请参阅

collate()

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.concat(other: Any) → ColumnOperators

继承自 ColumnOperators.concat() 方法 ColumnOperators

实现 ‘concat’ 运算符。

在列上下文中，生成子句 a || b，或者在 MySQL 上使用 concat() 运算符。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.contains(other: Any, **kw: Any) → ColumnElement[bool]

使用 EXISTS 生成一个代理的“contains”表达式。

此表达式将是使用 Comparator.any()、Comparator.has() 和/或 Comparator.contains() 的底层代理属性运算符的组合结果。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.desc() → ColumnOperators

继承自 ColumnOperators.desc() 方法 ColumnOperators

针对父对象生成一个 desc() 子句。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.distinct() → ColumnOperators

继承自 ColumnOperators.distinct() 方法 ColumnOperators

针对父对象生成一个 distinct() 子句。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.endswith() 的 ColumnOperators 方法

实现“endswith”操作符。

生成一个 LIKE 表达式，用于测试字符串值的末尾是否匹配。

column LIKE '%' || <other>

例如：

stmt = select(sometable).\
    where(sometable.c.column.endswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.endswith.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。 这通常是一个普通的字符串值，但也可以是任意的 SQL 表达式。 LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.endswith.autoescape 标志被设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.endswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.endswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '^'

  该参数也可以与 ColumnOperators.endswith.autoescape 结合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

继承自 AssociationProxyInstance.has() 方法 AssociationProxyInstance

使用 EXISTS 生成一个代理的“has”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

方法 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.icontains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.icontains() 的 ColumnOperators 方法

实现 icontains 操作符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的中间部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.icontains.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.icontains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.icontains("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.icontains("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.contains()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.iendswith() 的 ColumnOperators 方法

实现 iendswith 操作符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的末尾部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式内存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于字面字符串值，ColumnOperators.iendswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符进行转义，以便它们匹配自身而不是通配符字符。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.iendswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.iendswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.iendswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  该参数也可以与 ColumnOperators.iendswith.autoescape 组合

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.ilike() 方法的 ColumnOperators

实现 ilike 操作符，例如不区分大小写的 LIKE。

在列上下文中，生成形式为以下表达式的其中一个：

lower(a) LIKE lower(other)

或者在支持 ILIKE 操作符的后端

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.ilike("foo/%bar", escape="/")

另请参阅

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.in_(other: Any) → ColumnOperators

继承自 ColumnOperators.in_() 方法的 ColumnOperators

实现 in 操作符。

在列上下文中，生成 column IN <other> 子句。

给定的参数 other 可以是

• 字面值的列表，例如：

  stmt.where(column.in_([1, 2, 3]))

  在此调用形式中，项目列表被转换为与给定列表长度相同的绑定参数集

  WHERE COL IN (?, ?, ?)

• 如果比较针对包含多个表达式的 tuple_()，则可以提供元组列表

  from sqlalchemy import tuple_
  stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 空列表，例如：

  stmt.where(column.in_([]))

  在此调用形式中，表达式渲染“空集”表达式。这些表达式针对各个后端进行调整，通常试图获得一个空的 SELECT 语句作为子查询。例如，在 SQLite 上，表达式是

  WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.4 中更改： 空 IN 表达式现在在所有情况下都使用执行时生成的 SELECT 子查询。

• 绑定参数，例如 bindparam()，如果它包含 bindparam.expanding 标志，则可以使用

  stmt.where(column.in_(bindparam('value', expanding=True)))

  在此调用形式中，表达式渲染一个特殊的非 SQL 占位符表达式，它看起来像

  WHERE COL IN ([EXPANDING_value])

  此占位符表达式在语句执行时被拦截，以转换为前面说明的绑定参数可变数量形式。如果语句以以下方式执行

  connection.execute(stmt, {"value": [1, 2, 3]})

  数据库将为每个值传递一个绑定参数

  WHERE COL IN (?, ?, ?)

  在版本 1.2 中添加： 添加了“扩展”绑定参数

  如果传递了空列表，则会渲染一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是

  WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.3 中添加： “扩展”绑定参数现在支持空列表

• select() 结构，通常是关联的标量选择

  stmt.where(
      column.in_(
          select(othertable.c.y).
          where(table.c.x == othertable.c.x)
      )
  )

  在此调用形式中，ColumnOperators.in_() 按照给定方式渲染

  WHERE COL IN (SELECT othertable.y
  FROM othertable WHERE othertable.x = table.x)

参数：

other – 文字列表，select() 结构，或 bindparam() 结构，该结构包含设置为 True 的 bindparam.expanding 标志。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.is_(other: Any) → ColumnOperators

继承自 ColumnOperators.is_() 方法的 ColumnOperators

实现 IS 操作符。

通常，当与 None 值进行比较时，会自动生成 IS，它解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS。

另请参阅

ColumnOperators.is_not()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.is_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_distinct_from() 方法的 ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS NOT b”。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.is_not(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.is_not_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.isnot(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.isnot_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.istartswith() 方法 ColumnOperators

实现 istartswith 运算符，例如 ColumnOperators.startswith() 的不区分大小写的版本。

生成一个 LIKE 表达式，用于测试字符串值的开头的不区分大小写的匹配

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于该运算符使用 LIKE，因此在 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，ColumnOperators.istartswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符应用转义，以便它们本身匹配，而不是作为通配符。或者，ColumnOperators.istartswith.escape 参数将建立一个给定字符作为转义字符，当目标表达式不是文字字符串时，这很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.istartswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.istartswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.istartswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.istartswith.autoescape 组合使用

  somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.like() 方法 ColumnOperators

实现 like 操作符。

在列上下文中，生成表达式

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.like("foo/%bar", escape="/")

另请参阅

ColumnOperators.ilike()

attribute sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.local_attr

从 AssociationProxyInstance.local_attr 属性继承 AssociationProxyInstance

此 AssociationProxyInstance 引用的“本地”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.match(other: Any, **kwargs: Any) → ColumnOperators

继承自 ColumnOperators.match() 方法 ColumnOperators

实现数据库特定的“匹配”操作符。

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或操作符。示例包括

• PostgreSQL - 呈现 x @@ plainto_tsquery(y)

  在版本 2.0 中更改: plainto_tsquery() 现在用于 PostgreSQL 而不是 to_tsquery()；有关与其他形式的兼容性，请参见 全文搜索。

• MySQL - 呈现 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - 带有附加功能的 MySQL 特定构造。

• Oracle - 呈现 CONTAINS(x, y)

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将发出操作符为“MATCH”。例如，这与 SQLite 兼容。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.not_ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_ilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.not_in(other: Any) → ColumnOperators

继承自 ColumnOperators.not_in() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.not_like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_like() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.notilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.notin_(other: Any) → ColumnOperators

继承自 ColumnOperators.notin_() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.notlike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notlike() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.nulls_last() → ColumnOperators

继承自 ColumnOperators.nulls_last() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.nullsfirst() → ColumnOperators

继承自 ColumnOperators.nullsfirst() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成一个通用的运算符函数。

例如：

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可以用来明确表示位运算符。例如

somecolumn.op('&')(0xff)

是对 somecolumn 中的值进行按位与运算。

参数：

• opstring – 将作为此元素与传递给生成函数的表达式的中缀运算符输出的字符串。

• precedence –

  数据库预计对 SQL 表达式中的运算符应用的优先级。这个整数值作为 SQL 编译器的提示，用于确定何时应该在特定运算符周围渲染显式括号。较小的数字将导致在应用于另一个具有更高优先级的运算符时对表达式进行括号运算。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，-100 将低于或等于所有运算符。

  另请参阅

  我在使用 op() 生成自定义运算符时，我的括号没有正确显示 - SQLAlchemy SQL 编译器如何渲染括号的详细描述

• is_comparison –

  遗留；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔真/假值，如 ==、> 等。提供此标志是为了使 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数已不再使用，取而代之的是使用 Operators.bool_op() 方法；这个更简洁的运算符会自动设置这个参数，但也提供了正确的 PEP 484 类型支持，因为返回的对象将表示一个“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制此运算符生成的表达式的返回类型为该类型。默认情况下，指定了 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些没有指定的运算符将与左侧操作数的类型相同。

• python_impl –

  一个可选的 Python 函数，它可以像在数据库服务器上运行此运算符一样评估两个 Python 值。对于 Python 内的 SQL 表达式评估函数很有用，例如 ORM 混合属性，以及用于在多行更新或删除后匹配会话中的对象的 ORM “评估器”。

  例如：

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也将适用于非 SQL 左操作数和右操作数

  >>> expr.operator(5, 10)
  15

  新版功能在版本 2.0 中。

另请参阅

Operators.bool_op()

重新定义和创建新的运算符

在联接条件中使用自定义运算符

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

继承自 Operators.operate() 方法 Operators

对参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类中重写此方法可以对所有操作应用通用行为。例如，重写 ColumnOperators 以对左右两侧应用 func.lower()

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 运算的“另一方”。对于大多数运算来说，这将是一个单一的标量值。

• **kwargs – 修饰符。这些可能会被特殊运算符（如 ColumnOperators.contains()）传递。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_match() 方法 ColumnOperators

实现特定于数据库的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的 REGEXP 类函数或运算符，但是可用的特定正则表达式语法和标志**不是后端无关的**。

示例包括

• PostgreSQL - 在被否定时呈现 x ~ y 或 x !~ y。

• Oracle - 呈现 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将以“REGEXP”或“NOT REGEXP”的形式发出运算符。例如，这与 SQLite 和 MySQL 兼容。

正则表达式支持目前已在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。SQLite 提供了部分支持。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串的形式传递。这些标志是特定于后端的。某些后端，如 PostgreSQL 和 MariaDB，可以将标志作为模式的一部分指定。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_replace()

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_replace() 方法 ColumnOperators

实现特定于数据库的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析为后端提供的 REGEXP_REPLACE 类函数，该函数通常会发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志**不是后端无关的**。

正则表达式替换支持目前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• pattern – 替换字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串的形式传递。这些标志是特定于后端的。某些后端，如 PostgreSQL 和 MariaDB，可以将标志作为模式的一部分指定。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_match()

attribute sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.remote_attr

继承自 AssociationProxyInstance.remote_attr 属性 AssociationProxyInstance

此 AssociationProxyInstance 引用的“远程”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

继承自 Operators.reverse_operate() 方法 Operators

反向操作一个参数。

用法与 operate() 相同。

attribute sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.scalar

继承自 AssociationProxyInstance.scalar 属性 AssociationProxyInstance

如果此 AssociationProxyInstance 代理本地端的标量关系，则返回 True。

method sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.startswith() 方法 ColumnOperators

实现 startswith 运算符。

生成 LIKE 表达式，用于测试字符串值开头的匹配项。

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于操作符使用 LIKE，因此 "%" 和 "_" 这些出现在 <other> 表达式中的通配符字符也会像通配符一样工作。对于字面字符串值，ColumnOperators.startswith.autoescape 标志可以设置为 True，以便对字符串值中出现的这些字符进行转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是普通的字符串值，但也可以是任意的 SQL 表达式。 LIKE 通配符 % 和 _ 在默认情况下不会转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.startswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.startswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.startswith.autoescape 组合使用。

  somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.target_class: Type[Any]

由这个 AssociationProxyInstance 处理的中介类。

拦截的追加/设置/赋值事件将导致生成该类的新的实例。

attribute sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.timetuple: Literal[None] = None

从 ColumnOperators.timetuple 属性继承 ColumnOperators

黑客行为，允许在 LHS 上比较 datetime 对象。

class sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance

一个 AssociationProxyInstance，它具有数据库列作为目标。

成员

__le__(), __lt__(), __ne__(), all_(), any(), any_(), asc(), attr, between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(), bitwise_rshift(), bitwise_xor(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), has(), icontains(), iendswith(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(), like(), local_attr, match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), op(), operate(), regexp_match(), regexp_replace(), remote_attr, reverse_operate(), scalar, startswith(), target_class, timetuple

类签名

类 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance (sqlalchemy.ext.associationproxy.AssociationProxyInstance)

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.__le__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法 ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.__lt__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法 ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.__ne__(other: Any) → ColumnOperators

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法 ColumnOperators

实现 != 运算符。

在列上下文中，生成子句 a != b。如果目标是 None，则生成 a IS NOT NULL。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 all_() 子句。

有关示例，请参见 all_() 的文档。

注意

请勿将新的 ColumnOperators.all_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.all() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

从 AssociationProxyInstance.any() 方法继承 AssociationProxyInstance

使用 EXISTS 生成一个代理的“any”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法，该方法属于 ColumnOperators

针对父对象生成一个 any_() 子句。

有关示例，请参见 any_() 的文档。

注意

请勿将新的 ColumnOperators.any_() 方法与此方法的 **旧版** 混淆，即特定于 ARRAY 的 Comparator.any() 方法，它使用不同的调用方式。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.asc() → ColumnOperators

继承自 ColumnOperators.asc() 方法，该方法属于 ColumnOperators

针对父对象生成一个 asc() 子句。

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.attr

从 AssociationProxyInstance.attr 属性继承 AssociationProxyInstance

返回一个包含 (local_attr, remote_attr) 的元组。

此属性最初旨在通过 Query.join() 方法一次性跨两个关系进行连接来方便使用，但是这使用了过时的调用方式。

若要使用 select.join() 或 Query.join() 与关联代理一起使用，当前方法是分别使用 AssociationProxyInstance.local_attr 和 AssociationProxyInstance.remote_attr 属性。

stmt = (
    select(Parent).
    join(Parent.proxied.local_attr).
    join(Parent.proxied.remote_attr)
)

将来的版本可能会试图为关联代理属性提供更简洁的连接模式。

另请参阅

AssociationProxyInstance.local_attr

AssociationProxyInstance.remote_attr

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

继承自 ColumnOperators.between() 方法，该方法属于 ColumnOperators

针对父对象生成一个 between() 子句，该子句使用给定的下限和上限范围。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_and(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_and() 方法，该方法属于 ColumnOperators

生成一个按位 AND 运算，通常使用 & 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_lshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_lshift() 方法，该方法属于 ColumnOperators

执行按位左移操作，通常使用 << 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_not() → ColumnOperators

继承自 ColumnOperators.bitwise_not() 方法 ColumnOperators

执行按位取反操作，通常使用 ~ 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_or(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_or() 方法 ColumnOperators

执行按位或运算，通常使用 | 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_rshift(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_rshift() 方法 ColumnOperators

执行按位右移操作，通常使用 >> 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bitwise_xor(other: Any) → ColumnOperators

继承自 ColumnOperators.bitwise_xor() 方法 ColumnOperators

执行按位异或运算，通常使用 ^ 运算符，或 PostgreSQL 中的 # 运算符。

版本 2.0.2 中的新增功能。

另请参阅

按位运算符

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.bool_op() 方法 Operators

返回一个自定义布尔运算符。

此方法是调用 Operators.op() 并将 Operators.op.is_comparison 标志设置为 True 的简写。 使用 Operators.bool_op() 的主要优势在于，当使用列构造时，返回表达式的“布尔”性质将对 PEP 484 目的有效。

另请参阅

Operators.op()

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法 ColumnOperators

对父对象执行 collate() 子句，给定排序规则字符串。

另请参阅

collate()

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.concat(other: Any) → ColumnOperators

继承自 ColumnOperators.concat() 方法 ColumnOperators

实现 ‘concat’ 运算符。

在列上下文中，生成子句 a || b，或者在 MySQL 上使用 concat() 运算符。

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.contains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.contains() 方法 ColumnOperators

实现 ‘contains’ 运算符。

生成一个 LIKE 表达式，用于测试与字符串值中间的匹配。

column LIKE '%' || <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.contains("foobar"))

由于运算符使用 LIKE，所以 "%" 和 "_" 等通配符字符在 <other> 表达式中存在时，也会像通配符一样起作用。对于文字字符串值，ColumnOperators.contains.autoescape 标志可以设置为 True 以对字符串值中的这些字符的出现应用转义，以便它们匹配自身而不是通配符字符。或者，ColumnOperators.contains.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是文字字符串时很有用。

参数：

• other – 要比较的表达式。 通常为普通字符串值，但也可以是任意 SQL 表达式。 LIKE 通配符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.contains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.contains("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.contains("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.desc() → ColumnOperators

继承自 ColumnOperators.desc() 方法 ColumnOperators

针对父对象生成一个 desc() 子句。

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.distinct() → ColumnOperators

继承自 ColumnOperators.distinct() 方法 ColumnOperators

针对父对象生成一个 distinct() 子句。

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.endswith() 的 ColumnOperators 方法

实现“endswith”操作符。

生成一个 LIKE 表达式，用于测试字符串值的末尾是否匹配。

column LIKE '%' || <other>

例如：

stmt = select(sometable).\
    where(sometable.c.column.endswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.endswith.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。 通常为普通字符串值，但也可以是任意 SQL 表达式。 LIKE 通配符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.endswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.endswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.endswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE '%' || :param ESCAPE '^'

  该参数也可以与 ColumnOperators.endswith.autoescape 结合使用

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

继承自 AssociationProxyInstance.has() 方法 AssociationProxyInstance

使用 EXISTS 生成一个代理的“has”表达式。

此表达式将使用底层代理属性的 Comparator.any() 和/或 Comparator.has() 运算符进行组合。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.icontains(other: Any, **kw: Any) → ColumnOperators

继承自 ColumnOperators.icontains() 的 ColumnOperators 方法

实现 icontains 操作符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的中间部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于文字字符串值，ColumnOperators.icontains.autoescape 标志可以设置为 True 以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符字符。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.icontains.autoescape 标志被设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.icontains("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.icontains("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.contains.autoescape 组合使用

  somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.contains()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.iendswith() 的 ColumnOperators 方法

实现 iendswith 操作符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值的末尾部分是否不区分大小写地匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于操作符使用 LIKE，因此在 <other> 表达式内存在的通配符字符 "%" 和 "_" 也将像通配符一样工作。对于字面字符串值，ColumnOperators.iendswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符进行转义，以便它们匹配自身而不是通配符字符。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，这在目标表达式不是字面字符串时很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是一个任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.iendswith.autoescape 标志被设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.iendswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.iendswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  该参数也可以与 ColumnOperators.iendswith.autoescape 组合

  somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.ilike() 方法的 ColumnOperators

实现 ilike 操作符，例如不区分大小写的 LIKE。

在列上下文中，生成形式为以下表达式的其中一个：

lower(a) LIKE lower(other)

或者在支持 ILIKE 操作符的后端

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.ilike("foo/%bar", escape="/")

另请参阅

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.in_(other: Any) → ColumnOperators

继承自 ColumnOperators.in_() 方法的 ColumnOperators

实现 in 操作符。

在列上下文中，生成 column IN <other> 子句。

给定的参数 other 可以是

• 字面值的列表，例如：

  stmt.where(column.in_([1, 2, 3]))

  在此调用形式中，项目列表被转换为与给定列表长度相同的绑定参数集

  WHERE COL IN (?, ?, ?)

• 如果比较针对包含多个表达式的 tuple_()，则可以提供元组列表

  from sqlalchemy import tuple_
  stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 空列表，例如：

  stmt.where(column.in_([]))

  在此调用形式中，表达式渲染“空集”表达式。这些表达式针对各个后端进行调整，通常试图获得一个空的 SELECT 语句作为子查询。例如，在 SQLite 上，表达式是

  WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.4 中更改： 空 IN 表达式现在在所有情况下都使用执行时生成的 SELECT 子查询。

• 绑定参数，例如 bindparam()，如果它包含 bindparam.expanding 标志，则可以使用

  stmt.where(column.in_(bindparam('value', expanding=True)))

  在此调用形式中，表达式渲染一个特殊的非 SQL 占位符表达式，它看起来像

  WHERE COL IN ([EXPANDING_value])

  此占位符表达式在语句执行时被拦截，以转换为前面说明的绑定参数可变数量形式。如果语句以以下方式执行

  connection.execute(stmt, {"value": [1, 2, 3]})

  数据库将为每个值传递一个绑定参数

  WHERE COL IN (?, ?, ?)

  在版本 1.2 中添加： 添加了“扩展”绑定参数

  如果传递了空列表，则会渲染一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是

  WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

  在版本 1.3 中添加： “扩展”绑定参数现在支持空列表

• select() 结构，通常是关联的标量选择

  stmt.where(
      column.in_(
          select(othertable.c.y).
          where(table.c.x == othertable.c.x)
      )
  )

  在此调用形式中，ColumnOperators.in_() 按照给定方式渲染

  WHERE COL IN (SELECT othertable.y
  FROM othertable WHERE othertable.x = table.x)

参数：

other – 一个文字列表，一个 select() 结构，或一个 bindparam() 结构，该结构包含设置为 True 的 bindparam.expanding 标志。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.is_(other: Any) → ColumnOperators

继承自 ColumnOperators.is_() 方法的 ColumnOperators

实现 IS 操作符。

通常，当与 None 值进行比较时，会自动生成 IS，它解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS。

另请参阅

ColumnOperators.is_not()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.is_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_distinct_from() 方法的 ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS NOT b”。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.is_not(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.is_not_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.is_not_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.isnot(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot() 方法 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 的值比较时，IS NOT 会自动生成，该值解析为 NULL。但是，如果在某些平台上与布尔值进行比较，则可能需要显式使用 IS NOT。

在版本 1.4 中更改： 在以前的版本中，is_not() 运算符从 isnot() 重命名。以前的名称仍然可用，以保持向后兼容性。

另请参阅

ColumnOperators.is_()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.isnot_distinct_from(other: Any) → ColumnOperators

继承自 ColumnOperators.isnot_distinct_from() 方法 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现为“a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能呈现为“a IS b”。

在版本 1.4 中更改： 在以前的版本中，is_not_distinct_from() 运算符从 isnot_distinct_from() 重命名。以前的名称仍然可用，以保持向后兼容性。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.istartswith() 方法 ColumnOperators

实现 istartswith 运算符，例如 ColumnOperators.startswith() 的不区分大小写的版本。

生成一个 LIKE 表达式，用于测试字符串值的开头的不区分大小写的匹配

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于该运算符使用 LIKE，因此在 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，ColumnOperators.istartswith.autoescape 标志可以设置为 True，以对字符串值中出现的这些字符应用转义，以便它们本身匹配，而不是作为通配符。或者，ColumnOperators.istartswith.escape 参数将建立一个给定字符作为转义字符，当目标表达式不是文字字符串时，这很有用。

参数：

• other – 要比较的表达式。这通常是一个普通字符串值，但也可以是任意 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.istartswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.istartswith("foo%bar", autoescape=True)

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.istartswith("foo/%bar", escape="^")

  将呈现为

  lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.istartswith.autoescape 组合使用

  somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.startswith()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.like() 方法 ColumnOperators

实现 like 操作符。

在列上下文中，生成表达式

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 要比较的表达式

• escape –

  可选的转义字符，渲染 ESCAPE 关键字，例如：

  somecolumn.like("foo/%bar", escape="/")

另请参阅

ColumnOperators.ilike()

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.local_attr

从 AssociationProxyInstance.local_attr 属性继承 AssociationProxyInstance

此 AssociationProxyInstance 引用的“本地”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.match(other: Any, **kwargs: Any) → ColumnOperators

继承自 ColumnOperators.match() 方法 ColumnOperators

实现数据库特定的“匹配”操作符。

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或操作符。示例包括

• PostgreSQL - 呈现 x @@ plainto_tsquery(y)

  在版本 2.0 中更改: plainto_tsquery() 现在用于 PostgreSQL 而不是 to_tsquery()；有关与其他形式的兼容性，请参见 全文搜索。

• MySQL - 呈现 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - 带有附加功能的 MySQL 特定构造。

• Oracle - 呈现 CONTAINS(x, y)

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将发出操作符为“MATCH”。例如，这与 SQLite 兼容。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.not_ilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_ilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.not_in(other: Any) → ColumnOperators

继承自 ColumnOperators.not_in() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.not_like(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.not_like() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.notilike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notilike() 方法 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

在版本 1.4 中更改: not_ilike() 操作符在以前的版本中从 notilike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.notin_(other: Any) → ColumnOperators

继承自 ColumnOperators.notin_() 方法 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个“空不在”表达式。这默认为表达式“1 = 1”，以便在所有情况下产生真。可以 create_engine.empty_in_strategy 用于更改此行为。

在版本 1.4 中更改: not_in() 操作符在以前的版本中从 notin_() 重命名。以前的名字仍然可用于向后兼容。

在版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为一个空 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.notlike(other: Any, escape: str | None = None) → ColumnOperators

继承自 ColumnOperators.notlike() 方法 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

在版本 1.4 中更改: not_like() 操作符在以前的版本中从 notlike() 重命名。以前的名字仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.nulls_last() → ColumnOperators

继承自 ColumnOperators.nulls_last() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.nullsfirst() → ColumnOperators

继承自 ColumnOperators.nullsfirst() 方法 ColumnOperators

产生一个针对父对象的 nulls_first() 子句。

在版本 1.4 中变更: The nulls_first() operator is renamed from nullsfirst() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

产生一个针对父对象的 nulls_last() 子句。

在版本 1.4 中变更: The nulls_last() operator is renamed from nullslast() in previous releases. The previous name remains available for backwards compatibility.

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法 Operators

生成一个通用的运算符函数。

例如：

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数还可以用来明确表示位运算符。例如

somecolumn.op('&')(0xff)

是对 somecolumn 中的值进行按位与运算。

参数：

• opstring – 将作为此元素和传递给生成函数的表达式之间中缀运算符输出的字符串。

• precedence –

  数据库预计对 SQL 表达式中的运算符应用的优先级。这个整数值作为 SQL 编译器的提示，用于确定何时应该在特定运算符周围渲染显式括号。较小的数字将导致在应用于另一个具有更高优先级的运算符时对表达式进行括号运算。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值为 100 将高于或等于所有运算符，-100 将低于或等于所有运算符。

  另请参阅

  我在使用 op() 生成自定义运算符时，我的括号没有正确显示 - SQLAlchemy SQL 编译器如何渲染括号的详细描述

• is_comparison –

  遗留；如果为 True，则运算符将被视为“比较”运算符，即评估为布尔真/假值，如 ==、> 等。提供此标志是为了使 ORM 关系能够在使用自定义联接条件时确定运算符是比较运算符。

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法取代; 此更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表示“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制此运算符产生的表达式的返回类型为该类型。默认情况下，指定 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些没有指定该参数的运算符将与左手运算符具有相同的类型。

• python_impl –

  一个可选的 Python 函数，它可以像在数据库服务器上运行此运算符一样评估两个 Python 值。对于 Python 内的 SQL 表达式评估函数很有用，例如 ORM 混合属性，以及用于在多行更新或删除后匹配会话中的对象的 ORM “评估器”。

  例如：

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也将适用于非 SQL 左操作数和右操作数

  >>> expr.operator(5, 10)
  15

  新版功能在版本 2.0 中。

另请参阅

Operators.bool_op()

重新定义和创建新的运算符

在联接条件中使用自定义运算符

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

对参数进行操作。

这是最低级别的操作，默认情况下会引发 NotImplementedError。

在子类中重写此方法可以对所有操作应用通用行为。例如，重写 ColumnOperators 以对左右两侧应用 func.lower()

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用对象。

• *other – 运算的“另一方”。对于大多数运算来说，它将是一个单独的标量。

• **kwargs – 修饰符。这些可能由特殊运算符（例如 ColumnOperators.contains()）传递。

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_match() 方法 ColumnOperators

实现特定于数据库的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的 REGEXP 类函数或运算符，但是可用的特定正则表达式语法和标志**不是后端无关的**。

示例包括

• PostgreSQL - 在被否定时呈现 x ~ y 或 x !~ y。

• Oracle - 呈现 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将以“REGEXP”或“NOT REGEXP”的形式发出运算符。例如，这与 SQLite 和 MySQL 兼容。

正则表达式支持目前已在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。SQLite 提供了部分支持。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。一些后端（如 PostgreSQL 和 MariaDB）可以将标志作为模式的一部分指定。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_replace()

method sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

继承自 ColumnOperators.regexp_replace() 方法 ColumnOperators

实现特定于数据库的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析为后端提供的 REGEXP_REPLACE 类函数，该函数通常会发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志**不是后端无关的**。

正则表达式替换支持目前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言的支持可能会有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。

• pattern – 替换字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，以纯 Python 字符串形式传递。这些标志是特定于后端的。一些后端（如 PostgreSQL 和 MariaDB）可以将标志作为模式的一部分指定。

版本 1.4 中的新增功能。

版本 1.4.48 中的变更:, 2.0.18 请注意，由于实现错误，“flags”参数以前除了纯 Python 字符串之外，还接受 SQL 表达式对象（如列表达式）。此实现与缓存不兼容，已将其删除；“flags”参数应仅传递字符串，因为这些标志在 SQL 表达式中以文字内联值的形式呈现。

另请参阅

ColumnOperators.regexp_match()

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.remote_attr

继承自 AssociationProxyInstance.remote_attr 属性 AssociationProxyInstance

此 AssociationProxyInstance 引用的“远程”类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

继承自 Operators.reverse_operate() 方法 Operators

反向操作一个参数。

用法与 operate() 相同。

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.scalar

继承自 AssociationProxyInstance.scalar 属性 AssociationProxyInstance

如果此 AssociationProxyInstance 代理本地端的标量关系，则返回 True。

方法 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

继承自 ColumnOperators.startswith() 方法 ColumnOperators

实现 startswith 运算符。

生成 LIKE 表达式，用于测试字符串值开头的匹配项。

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于操作符使用 LIKE，因此 "%" 和 "_" 这些出现在 <other> 表达式中的通配符字符也会像通配符一样工作。对于字面字符串值，ColumnOperators.startswith.autoescape 标志可以设置为 True，以便对字符串值中出现的这些字符进行转义，使它们匹配自身，而不是作为通配符字符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这将很有用。

参数：

• other – 要比较的表达式。这通常是一个简单的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用到比较值中所有 "%"、"_" 和转义字符本身的出现，假设该值是一个文字字符串，而不是一个 SQL 表达式。

  例如，表达式

  somecolumn.startswith("foo%bar", autoescape=True)

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字呈现，以将该字符作为转义字符。然后，可以在该字符之前放置 % 和 _" 的出现，以允许它们像自身一样起作用，而不是通配符字符。

  例如，表达式

  somecolumn.startswith("foo/%bar", escape="^")

  将呈现为

  somecolumn LIKE :param || '%' ESCAPE '^'

  该参数也可以与 ColumnOperators.startswith.autoescape 组合使用。

  somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

  在上面，给定的文字参数将转换为 "foo^%bar^^bat"，然后再传递到数据库。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.target_class: Type[Any]

由这个 AssociationProxyInstance 处理的中介类。

拦截的追加/设置/赋值事件将导致生成该类的新的实例。

属性 sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.timetuple: Literal[None] = None

从 ColumnOperators.timetuple 属性继承 ColumnOperators

黑客行为，允许在 LHS 上比较 datetime 对象。

类 sqlalchemy.ext.associationproxy.AssociationProxyExtensionType

一个枚举。

成员

ASSOCIATION_PROXY

类签名

class sqlalchemy.ext.associationproxy.AssociationProxyExtensionType (sqlalchemy.orm.base.InspectionAttrExtensionType)

属性 sqlalchemy.ext.associationproxy.AssociationProxyExtensionType.ASSOCIATION_PROXY = 'ASSOCIATION_PROXY'

表示类型为 InspectionAttr 的 AssociationProxy 的符号。

被分配给 InspectionAttr.extension_type 属性。