Что нового в SQLAlchemy 0.6?¶

Импорт диалектов¶

Изменилась структура импорта диалектов. Теперь каждый диалект экспортирует свой базовый класс «диалект», а также полный набор типов SQL, поддерживаемых в данном диалекте, через sqlalchemy.dialects.<name>. Например, для импорта набора типов PG:

from sqlalchemy.dialects.postgresql import (
    INTEGER,
    BIGINT,
    SMALLINT,
    VARCHAR,
    MACADDR,
    DATE,
    BYTEA,
)

Выше, INTEGER фактически является обычным типом INTEGER из sqlalchemy.types, но диалект PG делает его доступным так же, как и те типы, которые специфичны для PG, такие как BYTEA и MACADDR.

Важная ошибка в языке выражения¶

В языке выражений есть одно довольно существенное изменение, которое может повлиять на некоторые приложения. Булевое значение булевых выражений Python, т.е. ==, != и им подобных, теперь точно оценивается относительно двух сравниваемых объектов клаузы.

Как известно, сравнение ClauseElement с любым другим объектом возвращает другой ClauseElement:

>>> from sqlalchemy.sql import column
>>> column("foo") == 5
<sqlalchemy.sql.expression._BinaryExpression object at 0x1252490>

Это сделано для того, чтобы при преобразовании выражений Python в строки получались выражения SQL:

>>> str(column("foo") == 5)
'foo = :foo_1'

Но что произойдет, если мы скажем это?

>>> if column("foo") == 5:
...     print("yes")

В предыдущих версиях SQLAlchemy возвращаемое значение _BinaryExpression представляло собой обычный объект Python, который оценивался как True. Теперь он оценивает, должно ли реальное ClauseElement иметь такое же хэш-значение, как и сравниваемое. Значение:

>>> bool(column("foo") == 5)
False
>>> bool(column("foo") == column("foo"))
False
>>> c = column("foo")
>>> bool(c == c)
True
>>>

Это означает код, подобный следующему:

if expression:
    print("the expression is:", expression)

Если expression является бинарным предложением, то оценка не производится. Поскольку указанный паттерн никогда не должен использоваться, то теперь базовый ClauseElement вызывает исключение, если вызывается в булевом контексте:

>>> bool(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
    raise TypeError("Boolean value of this clause is not defined")
TypeError: Boolean value of this clause is not defined

Код, который хочет проверить наличие выражения ClauseElement, должен вместо этого сказать:

if expression is not None:
    print("the expression is:", expression)

Следует помнить, что это относится и к объектам Table и Column.

Это изменение объясняется двумя причинами:

• Сравнения вида if c1 == c2:  <do something> фактически можно записать теперь так

• Поддержка корректного хеширования объектов ClauseElement теперь работает на альтернативных платформах, а именно на Jython. До этого момента SQLAlchemy сильно зависела от специфического поведения cPython в этом отношении (и все еще имела с ним периодические проблемы).

Более строгое поведение «исполнителе黶

В SQLAlchemy «executemany» соответствует вызову execute(), передающему коллекцию наборов связывающих параметров:

connection.execute(table.insert(), {"data": "row1"}, {"data": "row2"}, {"data": "row3"})

Когда объект Connection отправляет на компиляцию заданную конструкцию insert(), он передает компилятору ключевые имена, присутствующие в первом наборе передаваемых связок, чтобы определить построение предложения VALUES оператора. Пользователи, знакомые с этой конструкцией, знают, что дополнительные ключи, присутствующие в остальных словарях, не оказывают никакого влияния. Отличие заключается в том, что все последующие словари должны содержать как минимум каждый ключ, присутствующий в первом словаре. Это означает, что подобный вызов больше не работает:

connection.execute(
    table.insert(),
    {"timestamp": today, "data": "row1"},
    {"timestamp": today, "data": "row2"},
    {"data": "row3"},
)

Потому что в третьей строке не указан столбец „timestamp“. Предыдущие версии SQLAlchemy просто вставляли NULL для этих отсутствующих столбцов. Однако если бы столбец timestamp в приведенном выше примере содержал значение или функцию по умолчанию на языке Python, он бы не использовался. Это объясняется тем, что операция «executemany» оптимизирована для максимальной производительности при огромном количестве наборов параметров и не пытается оценить значения по умолчанию на стороне Python для этих отсутствующих ключей. Поскольку умолчания часто реализуются либо как SQL-выражения, которые встраиваются в оператор INSERT, либо как выражения на стороне сервера, которые опять же срабатывают на основе структуры строки INSERT, которая по определению не может срабатывать условно на основе каждого набора параметров, было бы непоследовательно, чтобы умолчания на стороне Python вели себя иначе, чем умолчания на стороне SQL/сервера. (Умолчания, основанные на SQL-выражениях, начиная с версии 0.5 встраиваются в строку, опять же для минимизации влияния огромного количества наборов параметров).

Поэтому SQLAlchemy 0.6 устанавливает предсказуемую последовательность, запрещая в последующих наборах параметров оставлять пустые поля. Таким образом, больше не будет молчаливого отказа от значений и функций по умолчанию на стороне Python, которым дополнительно разрешено оставаться последовательными в своем поведении по сравнению с SQL и значениями по умолчанию на стороне сервера.

UNION и другие «составные» конструкции последовательно заключаются в скобки¶

Было удалено правило, призванное помочь SQLite, согласно которому первый составной элемент внутри другого составного элемента (например, union() внутри except_()) не заключался в скобки. Это непоследовательно и приводит к неправильным результатам в PostgreSQL, где действуют правила приоритета в отношении INTERSECTION, и это, в общем-то, удивительно. При использовании сложных композитов в SQLite теперь необходимо превращать первый элемент в подзапрос (что также совместимо на PG). Новый пример приведен в учебнике по SQL-выражениям в конце раздела [https://www.sqlalchemy.org/docs/06/sqlexpression.html #unions-and-other-set-operations]. Дополнительную информацию см. в #1665 и r6690.

Утраченные/удаленные элементы схемы¶

Пакет схем также был значительно оптимизирован. Многие опции и методы, которые были устаревшими в версии 0.5, были удалены. Также были удалены другие малоизвестные аксессоры и методы.

• ключевой аргумент «owner» удален из Table. Используйте «schema» для представления любых пространств имен, которые должны быть добавлены к имени таблицы.

• Устранены устаревшие MetaData.connect() и ThreadLocalMetaData.connect() - для связывания метаданных передавайте атрибут «bind».

• Устранен устаревший метод metadata.table_iterator() (используйте sorted_tables)

• аргумент «метаданные» удаляется из DefaultGenerator и подклассов, но остается локально присутствующим в Sequence, который является самостоятельной конструкцией в DDL.

• deprecated PassiveDefault - используйте DefaultClause.

• Убрана публичная мутабельность из объектов Index и Constraint:

  • ForeignKeyConstraint.append_element()

  • Index.append_column()

  • UniqueConstraint.append_column()

  • PrimaryKeyConstraint.add()

  • PrimaryKeyConstraint.remove()

Они должны быть построены декларативно (т.е. в одной конструкции).

• Другие удаленные вещи:

  • Table.key (не знаю, для чего это нужно)

  • Column.bind (получить через column.table.bind)

  • Column.metadata (получить через column.table.metadata)

  • Column.sequence (использовать column.default)

Другие изменения в поведении¶

• UniqueConstraint, Index, PrimaryKeyConstraint принимают в качестве аргументов списки имен столбцов или объектов столбцов.

• Флаг use_alter на ForeignKey теперь является опцией быстрого доступа к операциям, которые могут быть сконструированы вручную с использованием системы событий DDL(). Побочным эффектом этого рефактора является то, что объекты ForeignKeyConstraint с флагом use_alter=True не будут выдаваться на SQLite, который не поддерживает ALTER для внешних ключей. На поведение SQLite это никак не влияет, поскольку SQLite фактически не соблюдает ограничения FOREIGN KEY.

• Table.primary_key не является назначаемым - используйте table.append_constraint(PrimaryKeyConstraint(...))

• Определение Column с ForeignKey и без типа, например Column(name, ForeignKey(sometable.c.somecol)), раньше получало тип ссылаемого столбца. Сейчас поддержка такого автоматического вывода типа является частичной и может работать не во всех случаях.

Новая архитектура¶

Система типов была полностью переработана за кулисами для достижения двух целей:

• Отделить обработку параметров привязки и значений строк результатов, что обычно является требованием DBAPI, от SQL-спецификации самого типа, что является требованием базы данных. Это соответствует общему рефактору диалекта, который отделяет поведение SQL в базе данных от DBAPI.

• Установить четкий и последовательный контракт для генерации DDL из объекта TypeEngine и для построения объектов TypeEngine на основе отражения столбцов.

Основные изменения включают:

• Полностью переработано построение типов в диалектах. Диалекты теперь определяют общедоступные типы исключительно как имена UPPERCASE, а внутренние типы реализации - с помощью идентификаторов с подчеркиванием (т.е. являются частными). Система, с помощью которой типы выражаются в SQL и DDL, перенесена в систему компилятора. Это привело к тому, что в большинстве диалектов стало гораздо меньше объектов типов. Подробный документ по этой архитектуре для авторов диалектов находится в [source:/lib/sqlalc hemy/dialects/type_migration_guidelines.txt].

• Отражение типов теперь возвращает точный тип UPPERCASE в файле types.py, или тип UPPERCASE в самом диалекте, если тип не является стандартным типом SQL. Это означает, что отражение теперь возвращает более точную информацию об отражаемых типах.

• Определяемые пользователем типы, которые являются подклассом TypeEngine и хотят предоставлять get_col_spec(), теперь должны быть подклассом UserDefinedType.

• Метод result_processor() всех классов типов теперь принимает дополнительный аргумент coltype. Это объект типа DBAPI, присоединенный к cursor.description, и его следует использовать в тех случаях, когда это необходимо для принятия более точных решений о том, какой тип вызываемого объекта обработки результатов должен быть возвращен. В идеале функции обработки результатов никогда не должны использовать isinstance(), который является дорогостоящим вызовом на этом уровне.

Родной режим Unicode¶

Поскольку все больше DBAPI поддерживают непосредственное возвращение объектов Python unicode, базовый диалект теперь при первом подключении выполняет проверку, которая устанавливает, возвращает ли DBAPI объект Python unicode для базового выбора значения VARCHAR. Если да, то тип String и все его подклассы (т.е. Text, Unicode и т.д.) будут пропускать шаг проверки/преобразования «юникода» при получении строк результатов. Это дает значительный прирост производительности для больших наборов результатов. В настоящее время известно, что «режим юникода» работает с:

• sqlite3 / pysqlite

• psycopg2 - SQLA 0.6 теперь по умолчанию использует расширение типа «UNICODE» для каждого объекта соединения psycopg2

• pg8000

• cx_oracle (мы используем выходной процессор - хорошая возможность !)

Другие типы при необходимости могут отключать обработку юникода, как, например, тип NVARCHAR при использовании с MS-SQL.

В частности, при переносе приложения, основанного на DBAPI, который ранее возвращал неюникодные строки, режим «native unicode» имеет явно иное поведение по умолчанию - столбцы, объявленные как String или VARCHAR, теперь по умолчанию возвращают юникод, тогда как раньше они возвращали строки. Это может привести к поломке кода, ожидающего неюникодных строк. Режим psycopg2 «native unicode» может быть отключен путем передачи use_native_unicode=False в create_engine().

Более общим решением для строковых столбцов, в которых явно не требуется объект unicode, является использование TypeDecorator, который преобразует unicode обратно в utf-8, или в то, что требуется:

class UTF8Encoded(TypeDecorator):
    """Unicode type which coerces to utf-8."""

    impl = sa.VARCHAR

    def process_result_value(self, value, dialect):
        if isinstance(value, unicode):
            value = value.encode("utf-8")
        return value

Обратите внимание, что флаг assert_unicode теперь устарел. SQLAlchemy позволяет используемому DBAPI и backend-базе данных обрабатывать параметры в Unicode, если они доступны, и не добавляет операционных затрат на проверку входящего типа; современные системы, такие как sqlite и PostgreSQL, в случае передачи некорректных данных выдадут ошибку кодировки на своей стороне. В тех случаях, когда SQLAlchemy необходимо перевести параметр связывания из Python Unicode в кодированную строку, или когда тип Unicode используется явно, выдается предупреждение, если объект является байтовой строкой. Это предупреждение может быть подавлено или преобразовано в исключение с помощью фильтра предупреждений Python, документированного по адресу: https://docs.python.org/library/warnings.html.

Generic Enum Type¶

Теперь у нас есть Enum в модуле types. Это строковый тип, которому задается набор «меток», ограничивающих возможные значения, присваиваемые этим меткам. По умолчанию этот тип генерирует VARCHAR, используя размер самой большой метки, и накладывает ограничение CHECK на таблицу в операторе CREATE TABLE. При использовании MySQL тип по умолчанию использует тип MySQL ENUM, а при использовании PostgreSQL тип будет генерировать определенный пользователем тип CREATE TYPE <mytype> AS ENUM. Для создания типа с использованием PostgreSQL необходимо указать в конструкторе параметр name. Тип также принимает параметр native_enum=False, который будет выдавать стратегию VARCHAR/CHECK для всех баз данных. Обратите внимание, что в настоящее время типы PostgreSQL ENUM не работают с pg8000 или zxjdbc.

Отражение возвращает диалектно-специфические типы¶

Теперь Reflection возвращает из базы данных наиболее конкретный тип. То есть, если создать таблицу с использованием String, а затем отразить ее обратно, то отраженный столбец, скорее всего, будет VARCHAR. Для диалектов, поддерживающих более конкретную форму типа, это то, что вы получите. Так, тип Text на Oracle будет иметь вид oracle.CLOB, LargeBinary может быть mysql.MEDIUMBLOB и т.д. Очевидным преимуществом здесь является то, что отражение сохраняет как можно больше информации из базы данных.

Некоторые приложения, работающие с метаданными таблиц, могут захотеть сравнивать типы в отраженных и/или неотраженных таблицах. Для этого на TypeEngine имеется полуприватный аксессор _type_affinity и связанный с ним помощник сравнения _compare_type_affinity. Этот аксессор возвращает «общий» класс types, которому соответствует тип:

>>> String(50)._compare_type_affinity(postgresql.VARCHAR(50))
True
>>> Integer()._compare_type_affinity(mysql.REAL)
False

Различные изменения в API¶

По-прежнему используется обычная система «общих» типов, т.е. String, Float, DateTime. Здесь есть несколько изменений:

• Типы больше не делают никаких предположений относительно параметров по умолчанию. В частности, Numeric, Float, а также подклассы NUMERIC, FLOAT, DECIMAL не генерируют никакой длины или масштаба, если это не указано. Сюда же по-прежнему относятся спорные типы String и VARCHAR (хотя диалект MySQL будет упреждающе поднимать вопрос о выводе VARCHAR без длины). Никакие значения по умолчанию не принимаются, и если они используются в операторе CREATE TABLE, то будет выдана ошибка, если базовая база данных не позволяет использовать не удлиненные версии этих типов.

• тип Binary переименован в LargeBinary, для BLOB/BYTEA/подобных типов. Для BINARY и VARBINARY они присутствуют непосредственно как types.BINARY, types.VARBINARY, а также в диалектах MySQL и MS-SQL.

• PickleType теперь использует == для сравнения значений при mutable=True, если к типу не указан аргумент «comparator» с функцией сравнения. Если вы собираете пользовательский объект, то вам следует реализовать метод __eq__(), чтобы сравнение по значениям было точным.

• Аргументы по умолчанию «precision» и «scale» для Numeric и Float были удалены и теперь имеют значение None. По умолчанию NUMERIC и FLOAT будут отображаться без числовых аргументов, если эти значения не указаны.

• Типы DATE, TIME и DATETIME в SQLite теперь могут принимать необязательные аргументы «storage_format» и «regexp». «storage_format» может использоваться для хранения этих типов в пользовательском строковом формате. «regexp» позволяет использовать пользовательское регулярное выражение для сопоставления строковых значений из базы данных.

• __legacy_microseconds__ на типах SQLite Time и DateTime больше не поддерживается. Вместо этого следует использовать новый аргумент «storage_format».

• Типы DateTime на SQLite теперь по умолчанию используют более строгое регулярное выражение для сопоставления строк из базы данных. Используйте новый аргумент «regexp», если вы используете данные, хранящиеся в устаревшем формате.

Новая единица измерения¶

Внутренние компоненты единицы работы, в первую очередь topological.py и unitofwork.py, были полностью переписаны и значительно упрощены. Это не должно повлиять на использование, так как все существующее поведение во время flush было сохранено в точности (или, по крайней мере, в той степени, в которой оно было реализовано в нашем тестовом наборе и в нескольких производственных средах, которые активно тестировали его). При выполнении flush() теперь используется на 20-30% меньше вызовов методов, а также должно потребляться меньше памяти. Замысел и поток исходного кода теперь достаточно легко проследить, а архитектура flush на данный момент является достаточно открытой, что создает пространство для потенциальных новых областей развития. Процесс промывки больше не зависит от рекурсии, поэтому можно выполнять промывку планов произвольного размера и сложности. Кроме того, процесс «сохранения» mapper’а, выполняющий операции INSERT и UPDATE, теперь кэширует «скомпилированную» форму этих двух операций, что позволяет значительно сократить количество вызовов при очень больших объемах прошивки.

О любых изменениях в поведении, наблюдаемых при использовании flush по сравнению с более ранними версиями 0.6 или 0.5, следует сообщать нам как можно скорее - мы проследим за тем, чтобы функциональность не была потеряна.

Изменения в query.update() и query.delete()¶

• Опция „expire“ в query.update() была переименована в „fetch“, что соответствует опции query.delete()

• По умолчанию для стратегии синхронизации query.update() и query.delete() установлено значение „evaluate“.

• стратегия „synchronize“ для update() и delete() приводит к ошибке. Неявного возврата на «fetch» не существует. Неудачная оценка основана на структуре критериев, поэтому успех/неудача детерминированы структурой кода.

relation() официально назван relationship()¶

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

Расширенная загрузка подзапросов¶

Добавлена новая разновидность ускоренной загрузки, называемая «подзапросом». Это загрузка, при которой сразу после первого SQL-запроса выполняется второй, который загружает полные коллекции для всех родительских запросов первого запроса, соединяясь с родительским запросом по возрастанию с помощью INNER JOIN. Загрузка подзапросов используется аналогично текущей загрузке joined-eager, с использованием `subqueryload()`` and ``subqueryload_all()`` options as well as the ``lazy='subquery'`` setting on ``relationship()`. Загрузка с помощью подзапросов обычно гораздо эффективнее при загрузке больших коллекций, поскольку в ней безоговорочно используется INNER JOIN, а также не происходит повторной загрузки родительских строк.

`eagerload()``, ``eagerload_all()`` is now ``joinedload()``, ``joinedload_all()`¶

Чтобы освободить место для новой функции загрузки подзапросов, существующие `eagerload()``/``eagerload_all()`` options are now superseded by ``joinedload()`` and ``joinedload_all()``. The old names will hang around for the foreseeable future just like ``relation()`.

`lazy=False|None|True|'dynamic'`` now accepts ``lazy='noload'|'joined'|'subquery'|'select'|'dynamic'`¶

В продолжение открытой темы о стратегиях загрузчиков, стандартные ключевые слова для `lazy`` option on ``relationship()`` are now ``select`` for lazy loading (via a SELECT issued on attribute access), ``joined`` for joined-eager loading, ``subquery`` for subquery-eager loading, ``noload`` for no loading should occur, and ``dynamic`` for a «dynamic» relationship. The old ``True``, ``False``, ``None` аргументы по-прежнему принимаются с тем же поведением, что и раньше.

innerjoin=True on relation, joinedload¶

Скалярам и коллекциям, загружаемым с нетерпением, теперь можно предписать использовать INNER JOIN вместо OUTER JOIN. На PostgreSQL это дает ускорение в 300-600% для некоторых запросов. Установите этот флаг для любого many-to-one, работающего с внешним ключом NOT NULL, и аналогично для любой коллекции, в которой гарантированно существуют связанные элементы.

На уровне картографа:

mapper(Child, child)
mapper(
    Parent,
    parent,
    properties={"child": relationship(Child, lazy="joined", innerjoin=True)},
)

На уровне времени запроса:

session.query(Parent).options(joinedload(Parent.child, innerjoin=True)).all()

Флаг innerjoin=True на уровне relationship() будет действовать и для любой опции joinedload(), которая не переопределяет его значение.

Усовершенствования «многие к одному¶

• Отношения «многие-к-одному» теперь вызывают ленивую загрузку в меньшем количестве случаев, в том числе в большинстве случаев не будут получать «старое» значение при замене его новым.

• отношение «многие-к-одному» к подклассу объединенной таблицы теперь использует get() для простой загрузки (известное как условие «use_get»), т.е. Related->``Sub(Base)``, без необходимости переопределения условия primaryjoin в терминах базовой таблицы. [ticket:1186]

• Указание внешнего ключа с декларативным столбцом, т.е. ForeignKey(MyRelatedClass.id), не нарушает условия «use_get» [ticket:1492]

• В relationship(), joinedload() и joinedload_all() появилась опция «innerjoin». Укажите True или False для того, чтобы определить, как будет построено нетерпеливое соединение - INNER или OUTER. По умолчанию, как всегда, используется False. Опции отображателя будут переопределять ту настройку, которая задана в relationship(). Как правило, этот параметр следует устанавливать для отношений типа «многие к одному», а не для отношений с нулевым внешним ключом, чтобы повысить производительность соединения. [ticket:1544]

• поведение объединенной ускоренной загрузки, при котором основной запрос оборачивается в подзапрос при наличии LIMIT/OFFSET, теперь делает исключение для случая, когда все ускоренные загрузки являются объединениями «многие к одному». В таких случаях нетерпеливые соединения выполняются непосредственно к родительской таблице вместе с ограничением/смещением без дополнительных затрат на подзапрос, поскольку соединение «многие к одному» не добавляет строк к результату.

  Например, в 0,5 этот запрос:

  session.query(Address).options(eagerload(Address.user)).limit(10)

  выдаст SQL типа:

  SELECT * FROM
    (SELECT * FROM addresses LIMIT 10) AS anon_1
    LEFT OUTER JOIN users AS users_1 ON users_1.id = anon_1.addresses_user_id

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

  В 0.6 эта логика более чувствительна и может определить, что все eager-загрузчики представляют собой many-to-one, и в этом случае eager-соединения не влияют на количество строк:

  SELECT * FROM addresses LEFT OUTER JOIN users AS users_1 ON users_1.id = addresses.user_id LIMIT 10

Изменяемые первичные ключи с наследованием объединенных таблиц¶

Конфигурация наследования объединенных таблиц, в которой дочерняя таблица имеет PK, являющийся внешним ключом к родительскому PK, теперь может обновляться в базах данных с поддержкой CASCADE, таких как PostgreSQL. У параметра mapper() теперь есть опция passive_updates=True, которая указывает, что этот внешний ключ обновляется автоматически. Если вы используете некаскадную базу данных, например SQLite или MySQL/MyISAM, установите этот флаг в значение False. В будущем будет сделана попытка сделать этот флаг автоматически настраиваемым в зависимости от используемого диалекта/стиля таблицы.

Кэширование мензурок¶

Новый многообещающий пример интеграции Beaker представлен в examples/beaker_caching. Это простой рецепт, который применяет кэш Beaker в механизме генерации результатов Query. Параметры кэша предоставляются через query.options(), что позволяет полностью контролировать содержимое кэша. В SQLAlchemy 0.6 метод Session.merge() был усовершенствован для поддержки этого и подобных рецептов, а также для обеспечения значительно более высокой производительности в большинстве сценариев.

Другие изменения¶

• объект «кортеж строк», возвращаемый командой Query при выборе нескольких столбцов/сущностей, теперь является picklable, а также имеет более высокую производительность.

• query.join() был переработан для обеспечения более последовательного поведения и большей гибкости (включает [ticket:1537])

• query.select_from() принимает несколько предложений для получения нескольких записей, разделенных запятыми, в предложении FROM. Это полезно при выборе из нескольких клаузул join().

• флаг «dont_load=True» для Session.merge() устарел и теперь имеет значение «load=False».

• добавлена вспомогательная функция «make_transient()», которая превращает постоянный/отсоединенный экземпляр в переходный (т.е. удаляет ключ_экземпляра и удаляет из любой сессии) [ticket:1052].

• флаг allow_null_pks в mapper() устарел и был переименован в allow_partial_pks. По умолчанию он включен. Это означает, что строка, имеющая ненулевое значение для любого из столбцов первичного ключа, будет считаться идентичностью. Необходимость в этом сценарии обычно возникает только при сопоставлении с внешним объединением. При установке значения False PK, содержащий NULL, не будет считаться первичным ключом - в частности, это означает, что строка результата будет возвращаться как None (или не будет заполнена в коллекцию), а в новой версии 0.6 также означает, что session.merge() не будет выполнять обход базы данных для такого значения PK. [ticket:1680]

• Механика «обратной ссылки» полностью объединена в более тонкую систему «back_populates» и происходит полностью внутри метода _generate_backref() в RelationProperty. Это упрощает процедуру инициализации RelationProperty и позволяет легче распространять настройки (например, из подклассов RelationProperty) в обратную ссылку. Внутренний BackRef() исчез, а backref() возвращает обычный кортеж, понятный RelationProperty.

• атрибут keys в ResultProxy теперь является методом, поэтому ссылки на него (result.keys) должны быть заменены на вызовы методов (result.keys())

• ResultProxy.last_inserted_ids теперь устарел, вместо него используйте ResultProxy.inserted_primary_key.

Утраченные/удаленные элементы ORM¶

Большинство элементов, которые были устаревшими в версии 0.5 и вызывали предупреждения об устаревании, были удалены (за некоторыми исключениями). Все элементы, которые были помечены как «ожидающие устаревания», теперь являются устаревшими и при их использовании будет выдаваться предупреждение.

• Флаг „transactional“ в функции sessionmaker() и других удален. Используйте „autocommit=True“ для указания „transactional=False“.

• Убран аргумент „polymorphic_fetch“ в функции mapper(). Загрузка может контролироваться с помощью опции „with_polymorphic“.

• Аргумент „select_table“ в функции mapper() удален. Для этой функциональности используйте „with_polymorphic=(«*», <some selectable>)“.

• Убран аргумент „proxy“ в функции synonym(). В версии 0.5 этот флаг ничего не делал, так как теперь «генерация прокси» происходит автоматически.

• Передача одного списка элементов в функции joinedload(), joinedload_all(), contains_eager(), lazyload(), defer() и undefer() вместо нескольких позиционных *args является устаревшей.

• Передача одного списка элементов в query.order_by(), query.group_by(), query.join() или query.outerjoin() вместо нескольких позиционных *args является устаревшей.

• query.iterate_instances() удаляется. Используйте query.instances().

• Query.query_from_parent() удаляется. Используйте функцию sqlalchemy.orm.with_parent() для получения «родительского» предложения, или, как вариант, query.with_parent().

• query._from_self() удален, вместо него используйте query.from_self().

• аргумент «comparator» в composite() удален. Используйте «comparator_factory».

• RelationProperty._get_join() удаляется.

• флаг „echo_uow“ на Session снят. Используйте протоколирование по имени «sqlalchemy.orm.unitofwork».

• session.clear() удаляется. используйте session.expunge_all().

• session.save(), session.update(), session.save_or_update() удалены. Используйте session.add() и session.add_all().

• флаг «objects» в session.flush() остается устаревшим.

• флаг «dont_load=True» в session.merge() устарел в пользу «load=False».

• ScopedSession.mapper остается устаревшим. См. рецепт использования по адресу https://www.sqlalchemy.org/trac/wiki/Usag eRecipes/SessionAwareMapper.

• Передача InstanceState (внутреннего объекта состояния SQLAlchemy) в attributes.init_collection() или attributes.get_history() является устаревшей. Эти функции являются публичными API и обычно ожидают обычный экземпляр объекта mapped.

• параметр „engine“ в declarative_base() удаляется. Используйте аргумент с ключевым словом „bind“.

SQLSoup¶

SQLSoup был модернизирован и обновлен с учетом общих возможностей 0.5/0.6, включая хорошо проработанную интеграцию с сессиями. Ознакомьтесь с новой документацией по адресу [https://www.sqlalc hemy.org/docs/06/reference/ext/sqlsoup.html].

Декларативный¶

DeclarativeMeta (метакласс по умолчанию для declarative_base) ранее позволял подклассам модифицировать dict_ для добавления атрибутов класса (например, столбцов). Теперь это не работает, конструктор DeclarativeMeta теперь игнорирует dict_. Вместо этого атрибуты класса должны присваиваться напрямую, например, cls.id=Column(...), или вместо подхода метаклассов следует использовать подход MixIn class.