Конфигурация и техника инкассации¶

Динамические загрузчики отношений¶

Отношение relationship(), соответствующее большой коллекции, может быть настроено так, чтобы при обращении к нему возвращался унаследованный объект Query, что позволяет фильтровать отношения по критериям. Класс - это специальный класс AppenderQuery, возвращаемый вместо коллекции при обращении к нему. Может применяться критерий фильтрации, а также ограничения и смещения, явно или через срезы массива:

class User(Base):
    __tablename__ = "user"

    posts = relationship(Post, lazy="dynamic")


jack = session.get(User, id)

# filter Jack's blog posts
posts = jack.posts.filter(Post.headline == "this is a post")

# apply array slices
posts = jack.posts[5:20]

Динамические отношения поддерживают ограниченные операции записи с помощью методов AppenderQuery.append() и AppenderQuery.remove():

oldpost = jack.posts.filter(Post.headline == "old post").one()
jack.posts.remove(oldpost)

jack.posts.append(Post("new post"))

Поскольку сторона чтения динамического отношения всегда запрашивает базу данных, изменения в базовой коллекции не будут видны до тех пор, пока данные не будут удалены. Однако, если на используемом Session включена функция «autoflush», это будет происходить автоматически каждый раз, когда коллекция собирается выполнить запрос.

Чтобы поместить динамическое отношение на обратную ссылку, используйте функцию backref() в сочетании с lazy='dynamic':

class Post(Base):
    __table__ = posts_table

    user = relationship(User, backref=backref("posts", lazy="dynamic"))

Обратите внимание, что опции eager/lazy loading не могут быть использованы в сочетании с динамическими отношениями в настоящее время.

Установки Noload, RaiseLoad¶

Отношения «noload» никогда не загружаются из базы данных, даже при обращении к ним. Оно настраивается с помощью lazy='noload':

class MyClass(Base):
    __tablename__ = "some_table"

    children = relationship(MyOtherClass, lazy="noload")

Выше, коллекция children полностью доступна для записи, и изменения в ней будут сохранены в базе данных, а также доступны для чтения локально в момент их добавления. Однако когда экземпляры MyClass только что загружены из базы данных, коллекция children остается пустой. Стратегия noload также доступна на основе опции запроса с помощью опции загрузчика noload().

В качестве альтернативы, отношение «raise»-loaded будет вызывать InvalidRequestError там, где атрибут обычно выдает ленивую загрузку:

class MyClass(Base):
    __tablename__ = "some_table"

    children = relationship(MyOtherClass, lazy="raise")

Выше, доступ к атрибутам коллекции children вызовет исключение, если она не была предварительно загружена. Это относится к доступу на чтение, но для коллекций также повлияет на доступ на запись, поскольку коллекции не могут быть изменены без предварительной загрузки. Это делается для того, чтобы убедиться, что приложение не создает неожиданных ленивых загрузок в определенном контексте. Вместо того, чтобы читать журналы SQL, чтобы определить, что все необходимые атрибуты были загружены с нетерпением, стратегия «raise» заставит незагруженные атрибуты немедленно подниматься при обращении к ним. Стратегия «raise» также доступна на основе опции запроса с помощью опции загрузчика raiseload().

Использование пассивных удалений¶

См. раздел Использование каскада внешних ключей ON DELETE с отношениями ORM для этого раздела.

Коллекции словарей¶

При использовании словаря в качестве коллекции требуется небольшая дополнительная деталь. Это связано с тем, что объекты всегда загружаются из базы данных в виде списков, и для правильного заполнения словаря необходимо иметь стратегию генерации ключей. Функция attribute_mapped_collection() является наиболее распространенным способом создания простой коллекции словарей. Она создает класс словаря, который будет применять определенный атрибут сопоставленного класса в качестве ключа. Ниже мы отображаем класс Item, содержащий словарь из Note элементов, ключом к которому служит атрибут Note.keyword:

from sqlalchemy import Column, ForeignKey, Integer, String
from sqlalchemy.orm import declarative_base, relationship
from sqlalchemy.orm.collections import attribute_mapped_collection

Base = declarative_base()


class Item(Base):
    __tablename__ = "item"
    id = Column(Integer, primary_key=True)
    notes = relationship(
        "Note",
        collection_class=attribute_mapped_collection("keyword"),
        cascade="all, delete-orphan",
    )


class Note(Base):
    __tablename__ = "note"
    id = Column(Integer, primary_key=True)
    item_id = Column(Integer, ForeignKey("item.id"), nullable=False)
    keyword = Column(String)
    text = Column(String)

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

Item.notes является словарем:

>>> item = Item()
>>> item.notes["a"] = Note("a", "atext")
>>> item.notes.items()
{'a': <__main__.Note object at 0x2eaaf0>}

attribute_mapped_collection() будет гарантировать, что атрибут .keyword каждого Note соответствует ключу в словаре. Например, при назначении на Item.notes, ключ словаря, который мы предоставляем, должен соответствовать ключу фактического объекта Note:

item = Item()
item.notes = {
    "a": Note("a", "atext"),
    "b": Note("b", "btext"),
}

Атрибут, который attribute_mapped_collection() использует в качестве ключа, вообще не нужно сопоставлять! Использование обычного Python @property позволяет использовать в качестве ключа практически любую деталь или комбинацию деталей об объекте, как показано ниже, когда мы задаем его как кортеж из Note.keyword и первых десяти букв поля Note.text:

class Item(Base):
    __tablename__ = "item"
    id = Column(Integer, primary_key=True)
    notes = relationship(
        "Note",
        collection_class=attribute_mapped_collection("note_key"),
        backref="item",
        cascade="all, delete-orphan",
    )


class Note(Base):
    __tablename__ = "note"
    id = Column(Integer, primary_key=True)
    item_id = Column(Integer, ForeignKey("item.id"), nullable=False)
    keyword = Column(String)
    text = Column(String)

    @property
    def note_key(self):
        return (self.keyword, self.text[0:10])

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

Выше мы добавили обратную ссылку Note.item. Присваивая этому обратное отношение, Note добавляется в словарь Item.notes и ключ генерируется для нас автоматически:

>>> item = Item()
>>> n1 = Note("a", "atext")
>>> n1.item = item
>>> item.notes
{('a', 'atext'): <__main__.Note object at 0x2eaaf0>}

Другие встроенные типы словарей включают column_mapped_collection(), который почти аналогичен attribute_mapped_collection(), за исключением того, что объект Column передается непосредственно:

from sqlalchemy.orm.collections import column_mapped_collection


class Item(Base):
    __tablename__ = "item"
    id = Column(Integer, primary_key=True)
    notes = relationship(
        "Note",
        collection_class=column_mapped_collection(Note.__table__.c.keyword),
        cascade="all, delete-orphan",
    )

а также mapped_collection(), которому передается любая вызываемая функция. Обратите внимание, что обычно проще использовать attribute_mapped_collection() вместе с @property, как упоминалось ранее:

from sqlalchemy.orm.collections import mapped_collection


class Item(Base):
    __tablename__ = "item"
    id = Column(Integer, primary_key=True)
    notes = relationship(
        "Note",
        collection_class=mapped_collection(lambda note: note.text[0:10]),
        cascade="all, delete-orphan",
    )

Сопоставления словарей часто комбинируются с расширением «Association Proxy» для создания упрощенных представлений словарей. Примеры смотрите в Проксирование к коллекциям на основе словарей и Доверенности объединений.

class A(Base):
    __tablename__ = "a"

    id = Column(Integer, primary_key=True)
    bs = relationship(
        "B",
        collection_class=attribute_mapped_collection("data"),
        back_populates="a",
    )


class B(Base):
    __tablename__ = "b"
    id = Column(Integer, primary_key=True)
    a_id = Column(ForeignKey("a.id"))
    data = Column(String)

    a = relationship("A", back_populates="bs")

>>> a1 = A()
>>> b1 = B(a=a1)
>>> a1.bs
{None: <test3.B object at 0x7f7b1023ef70>}

>>> b1.data = "the key"
>>> a1.bs
{None: <test3.B object at 0x7f7b1023ef70>}

>>> B(a=a1, data="the key")
<test3.B object at 0x7f7b10114280>
>>> a1.bs
{None: <test3.B object at 0x7f7b10114280>}

>>> B(data="the key", a=a1)
<test3.B object at 0x7f7b10114340>
>>> a1.bs
{'the key': <test3.B object at 0x7f7b10114340>}

from sqlalchemy import event
from sqlalchemy.orm import attributes


@event.listens_for(B.data, "set")
def set_item(obj, value, previous, initiator):
    if obj.a is not None:
        previous = None if previous == attributes.NO_VALUE else previous
        obj.a.bs[value] = obj
        obj.a.bs.pop(previous)

Аннотирование пользовательских коллекций с помощью декораторов¶

Декораторы можно использовать для обозначения отдельных методов, необходимых ORM для управления коллекциями. Используйте их, когда ваш класс не совсем соответствует обычному интерфейсу для своего типа контейнера, или когда вы хотите использовать другой метод для выполнения работы.

from sqlalchemy.orm.collections import collection


class SetLike(object):
    __emulates__ = set

    def __init__(self):
        self.data = set()

    @collection.appender
    def append(self, item):
        self.data.add(item)

    def remove(self, item):
        self.data.remove(item)

    def __iter__(self):
        return iter(self.data)

И это все, что необходимо для завершения примера. SQLAlchemy будет добавлять экземпляры с помощью метода append. remove и __iter__ являются методами по умолчанию для множеств и будут использоваться для удаления и итерации. Методы по умолчанию могут быть изменены:

from sqlalchemy.orm.collections import collection

class MyList(list):
    @collection.remover
    def zark(self, item):
        # do something special...

    @collection.iterator
    def hey_use_this_instead_for_iteration(self):
        # ...

Не требуется, чтобы коллекция была списком или набором. Классы коллекций могут быть любой формы, лишь бы они имели интерфейс append, remove и iterate, обозначенный для использования SQLAlchemy. Методы append и remove будут вызываться с сопоставленной сущностью в качестве единственного аргумента, а методы iterator вызываются без аргументов и должны возвращать итератор.

Пользовательские коллекции на основе словарей¶

Класс MappedCollection можно использовать в качестве базового класса для ваших пользовательских типов или как микс-ин для быстрого добавления поддержки коллекции dict в другие классы. Он использует ключевую функцию для делегирования функций __setitem__ и __delitem__:

from sqlalchemy.util import OrderedDict
from sqlalchemy.orm.collections import MappedCollection


class NodeMap(OrderedDict, MappedCollection):
    """Holds 'Node' objects, keyed by the 'name' attribute with insert order maintained."""

    def __init__(self, *args, **kw):
        MappedCollection.__init__(self, keyfunc=lambda node: node.name)
        OrderedDict.__init__(self, *args, **kw)

При подклассификации MappedCollection, пользовательские версии __setitem__() или __delitem__() должны быть украшены collection.internally_instrumented(), если они вызывают те же методы на MappedCollection. Это связано с тем, что методы на MappedCollection уже инструментированы - их вызов из уже инструментированного вызова может вызвать повторное или неуместное срабатывание событий, что в редких случаях приводит к повреждению внутреннего состояния:

from sqlalchemy.orm.collections import MappedCollection, collection


class MyMappedCollection(MappedCollection):
    """Use @internally_instrumented when your methods
    call down to already-instrumented methods.

    """

    @collection.internally_instrumented
    def __setitem__(self, key, value, _sa_initiator=None):
        # do something with key, value
        super(MyMappedCollection, self).__setitem__(key, value, _sa_initiator)

    @collection.internally_instrumented
    def __delitem__(self, key, _sa_initiator=None):
        # do something with key
        super(MyMappedCollection, self).__delitem__(key, _sa_initiator)

ORM понимает интерфейс dict так же, как списки и множества, и будет автоматически использовать все диктоподобные методы, если вы решите подклассифицировать dict или обеспечить диктоподобное поведение коллекции в классе с типом «утка». Однако вы должны украсить методы appender и remover - в базовом интерфейсе словаря нет совместимых методов, которые SQLAlchemy использовал бы по умолчанию. Итерация будет проходить через itervalues(), если не оформлено иначе.

Инструментарий и пользовательские типы¶

Многие пользовательские типы и существующие библиотечные классы можно использовать в качестве типа коллекции сущностей как есть, без лишних слов. Однако важно отметить, что процесс инструментации изменит тип, автоматически добавляя декораторы вокруг методов.

Декоративные элементы легки и не требуют вмешательства вне отношений, но они добавляют ненужные накладные расходы, когда срабатывают в других местах. При использовании библиотечного класса в качестве коллекции, хорошей практикой может быть использование трюка «тривиальный подкласс», чтобы ограничить декорации только вашим использованием в отношениях. Например:

class MyAwesomeList(some.great.library.AwesomeList):
    pass


# ... relationship(..., collection_class=MyAwesomeList)

ORM использует этот подход для встроенных элементов, спокойно подставляя тривиальный подкласс, когда list, set или dict используется напрямую.