关联代理

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 实例上初始化，以引用接收 append 操作的父 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 字典，该字典严格处理映射到字符串 keyword 的 special_key 的字符串值。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 属性，将关系表示为更简单值的集合或标量值。代理属性将模仿目标的集合类型（list、dict 或 set），或者，在 一对一 关系的情况下，一个简单的标量值。

参数:

• 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 应该使用 creator 创建 源对象。仅适用于标量属性。这与 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

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

参数:

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

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

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

类签名

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

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

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法，该方法属于 ColumnOperators

实现 == 运算符。

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

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

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法，该方法属于 ColumnOperators

实现 <= 运算符。

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

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

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法，该方法属于 ColumnOperators

实现 < 运算符。

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

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

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法，该方法属于 ColumnOperators

实现 != 运算符。

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

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

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

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

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

注意

请务必不要将较新的 ColumnOperators.all_() 方法与此方法的旧版版本混淆，即特定于 ARRAY 的 Comparator.all() 方法，后者使用不同的调用样式。

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

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

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

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

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

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

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

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的旧版版本混淆，即特定于 ARRAY 的 Comparator.any() 方法，后者使用不同的调用样式。

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

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

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

attribute 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

生成一个位与运算，通常通过 & 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

继承自 ColumnOperators.bitwise_lshift() 方法，源自 ColumnOperators

生成一个位左移运算，通常通过 << 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

继承自 ColumnOperators.bitwise_not() 方法，源自 ColumnOperators

生成一个位非运算，通常通过 ~ 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

继承自 ColumnOperators.bitwise_or() 方法，源自 ColumnOperators

生成一个位或运算，通常通过 | 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

继承自 ColumnOperators.bitwise_rshift() 方法，源自 ColumnOperators

生成一个位右移运算，通常通过 >> 运算符实现。

2.0.2 版本新增。

另请参阅

位运算符

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

继承自 ColumnOperators.bitwise_xor() 方法，源自 ColumnOperators

生成一个位异或运算，通常通过 ^ 运算符实现，PostgreSQL 中使用 #。

2.0.2 版本新增。

另请参阅

位运算符

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

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

继承自 ColumnOperators.collate() 方法，源自 ColumnOperators

生成一个针对父对象的 collate() 子句，给定排序规则字符串。

另请参阅

collate()

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

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

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

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

使用 EXISTS 生成代理的 'has' 表达式。

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

方法 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 表达式。 除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

• 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.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 表达式。 除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

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

方法 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 版本新增：添加了 “expanding” 绑定参数

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

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

  1.3 版本新增：“expanding” 绑定参数现在支持空列表

• 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.AssociationProxyInstance.info

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

继承自 ColumnOperators.is_() 方法，源自 ColumnOperators

实现 IS 操作符。

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

另请参阅

ColumnOperators.is_not()

方法 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”。

方法 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_()

方法 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() 重命名。为了向后兼容，之前的名称仍然可用。

方法 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_()

方法 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() 重命名。为了向后兼容，之前的名称仍然可用。

方法 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 表达式。 除非将 ColumnOperators.istartswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会被转义。

• 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.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 引用的 ‘local’ 类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

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

继承自 ColumnOperators.match() 方法，源自 ColumnOperators

实现数据库特定的 ‘match’ 操作符。

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

• PostgreSQL - 渲染 x @@ plainto_tsquery(y)

  在版本 2.0 中变更：现在 PostgreSQL 使用 plainto_tsquery() 而不是 to_tsquery()；为了与其他形式兼容，请参阅 全文搜索。

• MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - MySQL 特定构造，具有附加功能。

• Oracle Database - 渲染 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 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 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()

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

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

继承自 ColumnOperators.notin_() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

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

在 other 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 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.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.AssociationProxyInstance.nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nulls_last() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullsfirst() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullslast() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

method 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 – 一个字符串，将作为中缀运算符输出在此元素和传递给生成函数的表达式之间。

• precedence –

  数据库预期应用于 SQL 表达式中运算符的优先级。此整数值充当 SQL 编译器知道何时应在特定操作周围呈现显式括号的提示。当应用于具有更高优先级的另一个运算符时，较低的数字将导致表达式被括起来。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值 100 将高于或等于所有运算符，而 -100 将低于或等于所有运算符。

  另请参阅

  我正在使用 op() 生成自定义运算符，但我的括号没有正确输出 - 有关 SQLAlchemy SQL 编译器如何呈现括号的详细描述

• is_comparison –

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

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法取代；这种更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表达 “boolean” 数据类型，即 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 Database - 渲染 REGEXP_LIKE(x, y)

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

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

• 没有任何特殊实现的后端将发出运算符 “REGEXP” 或 “NOT REGEXP”。这与 SQLite 和 MySQL 等兼容。

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

参数:

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志呈现为 SQL 表达式中的文字内联值。

另请参阅

ColumnOperators.regexp_replace()

方法 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 Database、PostgreSQL、MySQL 8 或更高版本和 MariaDB 实现了正则表达式替换支持。第三方方言的支持可能有所不同。

参数:

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

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志呈现为 SQL 表达式中的文字内联值。

另请参阅

ColumnOperators.regexp_match()

属性 sqlalchemy.ext.associationproxy.AssociationProxyInstance.remote_attr

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

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

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

继承自 Operators.reverse_operate() 方法 Operators

对参数进行反向操作。

用法与 operate() 相同。

属性 sqlalchemy.ext.associationproxy.AssociationProxyInstance.scalar

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

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

方法 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 表达式。除非 ColumnOperators.startswith.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会转义。

• 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.AssociationProxyInstance.target_class: Type[Any]

此 AssociationProxyInstance 处理的中间类。

拦截的 append/set/assignment 事件将导致生成此类的新实例。

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

继承自 ColumnOperators.timetuple 属性 ColumnOperators

Hack，允许在 LHS 上比较 datetime 对象。

类 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

生成一个位与运算，通常通过 & 运算符实现。

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 表达式。 除非将 ColumnOperators.endswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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 表达式。 除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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.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 表达式。 除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

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

方法 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 版本新增：添加了 “expanding” 绑定参数

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

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

  1.3 版本新增：“expanding” 绑定参数现在支持空列表

• 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.ObjectAssociationProxyInstance.is_(other: Any) → ColumnOperators

继承自 ColumnOperators.is_() 方法，源自 ColumnOperators

实现 IS 操作符。

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

另请参阅

ColumnOperators.is_not()

方法 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”。

方法 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_()

方法 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() 重命名。为了向后兼容，之前的名称仍然可用。

方法 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_()

方法 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() 重命名。为了向后兼容，之前的名称仍然可用。

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

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

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.local_attr

继承自 AssociationProxyInstance.local_attr 属性，来自 AssociationProxyInstance

此 AssociationProxyInstance 引用的 ‘local’ 类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

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

继承自 ColumnOperators.match() 方法，源自 ColumnOperators

实现数据库特定的 ‘match’ 操作符。

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

• PostgreSQL - 渲染 x @@ plainto_tsquery(y)

  在版本 2.0 中变更：现在 PostgreSQL 使用 plainto_tsquery() 而不是 to_tsquery()；为了与其他形式兼容，请参阅 全文搜索。

• MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - MySQL 特定构造，具有附加功能。

• Oracle Database - 渲染 CONTAINS(x, y)

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

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

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

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

继承自 ColumnOperators.not_in() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

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

在 other 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

在版本 1.4 中变更：not_in() 操作符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

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

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

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

继承自 ColumnOperators.notin_() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

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

在 other 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

在版本 1.4 中变更：not_in() 操作符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

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

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

继承自 ColumnOperators.nulls_first() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nulls_last() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullsfirst() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullslast() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

方法 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，则该运算符将被视为 “比较” 运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了使 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.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()。

方法 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 Database - 渲染 REGEXP_LIKE(x, y)

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

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

• 没有任何特殊实现的后端将发出运算符 “REGEXP” 或 “NOT REGEXP”。这与 SQLite 和 MySQL 等兼容。

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

参数:

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志呈现为 SQL 表达式中的文字内联值。

另请参阅

ColumnOperators.regexp_replace()

方法 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 Database、PostgreSQL、MySQL 8 或更高版本和 MariaDB 实现了正则表达式替换支持。第三方方言的支持可能有所不同。

参数:

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

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志呈现为 SQL 表达式中的文字内联值。

另请参阅

ColumnOperators.regexp_match()

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.remote_attr

继承自 AssociationProxyInstance.remote_attr 属性，来自 AssociationProxyInstance

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

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

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

继承自 Operators.reverse_operate() 方法 Operators

对参数进行反向操作。

用法与 operate() 相同。

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.scalar

继承自 AssociationProxyInstance.scalar 属性，来自 AssociationProxyInstance

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

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

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.target_class: Type[Any]

此 AssociationProxyInstance 处理的中间类。

拦截的 append/set/assignment 事件将导致生成此类的新实例。

属性 sqlalchemy.ext.associationproxy.ObjectAssociationProxyInstance.timetuple: Literal[None] = None

继承自 ColumnOperators.timetuple 属性 ColumnOperators

Hack，允许在 LHS 上比较 datetime 对象。

类 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

类签名

class 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

生成一个位与运算，通常通过 & 运算符实现。

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 版本新增。

另请参阅

位运算符

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

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

继承自 ColumnOperators.collate() 方法，源自 ColumnOperators

生成一个针对父对象的 collate() 子句，给定排序规则字符串。

另请参阅

collate()

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

继承自 ColumnOperators.concat() 方法，源自 ColumnOperators

实现 ‘concat’ 运算符。

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

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

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

继承自 ColumnOperators.desc() 方法，源自 ColumnOperators

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

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

继承自 ColumnOperators.distinct() 方法，源自 ColumnOperators

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

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

方法 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 表达式。除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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.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 表达式。除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

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

method 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 版本新增：添加了 “expanding” 绑定参数

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

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

  1.3 版本新增：“expanding” 绑定参数现在支持空列表

• 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() 构造，或包含设置为 True 的 bindparam.expanding 标志的 bindparam() 构造。

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

继承自 ColumnOperators.is_() 方法，源自 ColumnOperators

实现 IS 操作符。

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

另请参阅

ColumnOperators.is_not()

method 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”。

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

method 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() 重命名。为了向后兼容，之前的名称仍然可用。

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

method 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() 重命名。为了向后兼容，之前的名称仍然可用。

method 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 表达式。除非将 ColumnOperators.istartswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

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

attribute sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.local_attr

继承自 AssociationProxyInstance.local_attr 属性，来自 AssociationProxyInstance

此 AssociationProxyInstance 引用的 ‘local’ 类属性。

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.remote_attr

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

继承自 ColumnOperators.match() 方法，源自 ColumnOperators

实现数据库特定的 ‘match’ 操作符。

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

• PostgreSQL - 渲染 x @@ plainto_tsquery(y)

  在版本 2.0 中变更：现在 PostgreSQL 使用 plainto_tsquery() 而不是 to_tsquery()；为了与其他形式兼容，请参阅 全文搜索。

• MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - MySQL 特定构造，具有附加功能。

• Oracle Database - 渲染 CONTAINS(x, y)

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

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

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

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

继承自 ColumnOperators.not_in() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

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

在 other 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

在版本 1.4 中变更：not_in() 操作符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

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

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

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

继承自 ColumnOperators.notin_() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

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

在 other 是空序列的情况下，编译器生成 “empty not in” 表达式。 这默认为表达式 “1 = 1”，以便在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

在版本 1.4 中变更：not_in() 操作符已从之前的版本中的 notin_() 重命名。之前的名称为了向后兼容仍然可用。

在版本 1.2 中变更：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

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

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

继承自 ColumnOperators.nulls_first() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nulls_last() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullsfirst() 方法，源自 ColumnOperators

生成针对父对象的 nulls_first() 子句。

在版本 1.4 中变更：nulls_first() 操作符已从之前的版本中的 nullsfirst() 重命名。之前的名称为了向后兼容仍然可用。

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

继承自 ColumnOperators.nullslast() 方法，源自 ColumnOperators

生成针对父对象的 nulls_last() 子句。

在版本 1.4 中变更：nulls_last() 操作符已从之前的版本中的 nullslast() 重命名。之前的名称为了向后兼容仍然可用。

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，则该运算符将被视为 “比较” 运算符，即评估为布尔值 true/false 的运算符，如 ==、> 等。提供此标志是为了使 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 Database - 渲染 REGEXP_LIKE(x, y)

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

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

• 没有任何特殊实现的后端将发出运算符 “REGEXP” 或 “NOT REGEXP”。这与 SQLite 和 MySQL 等兼容。

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

参数:

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“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 Database、PostgreSQL、MySQL 8 或更高版本和 MariaDB 实现了正则表达式替换支持。第三方方言的支持可能有所不同。

参数:

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

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

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

1.4 版本新增。

在 1.4.48 版本中更改,: 2.0.18 请注意，由于实现错误，“flags” 参数之前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法与缓存正确配合使用，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志呈现为 SQL 表达式中的文字内联值。

另请参阅

ColumnOperators.regexp_match()

attribute sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.remote_attr

继承自 AssociationProxyInstance.remote_attr 属性，来自 AssociationProxyInstance

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

另请参阅

AssociationProxyInstance.attr

AssociationProxyInstance.local_attr

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

继承自 Operators.reverse_operate() 方法 Operators

对参数进行反向操作。

用法与 operate() 相同。

attribute sqlalchemy.ext.associationproxy.ColumnAssociationProxyInstance.scalar

继承自 AssociationProxyInstance.scalar 属性，来自 AssociationProxyInstance

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

method 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 表达式。除非将 ColumnOperators.startswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。

• 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.ColumnAssociationProxyInstance.target_class: Type[Any]

此 AssociationProxyInstance 处理的中间类。

拦截的 append/set/assignment 事件将导致生成此类的新实例。

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

继承自 ColumnOperators.timetuple 属性 ColumnOperators

Hack，允许在 LHS 上比较 datetime 对象。

class sqlalchemy.ext.associationproxy.AssociationProxyExtensionType

一个枚举。

成员

ASSOCIATION_PROXY

类签名

class sqlalchemy.ext.associationproxy.AssociationProxyExtensionType (sqlalchemy.orm.base.InspectionAttrExtensionType)

attribute sqlalchemy.ext.associationproxy.AssociationProxyExtensionType.ASSOCIATION_PROXY = 'ASSOCIATION_PROXY'

指示 InspectionAttr 类型的符号，该类型为 AssociationProxy。

分配给 InspectionAttr.extension_type 属性。