Утилиты посещения и обхода¶

Модуль sqlalchemy.sql.visitors состоит из классов и функций, которые служат для общего обхода структуры выражения Core SQL. Это не похоже на модуль Python ast, поскольку представляет собой систему, с помощью которой программа может работать с каждым компонентом выражения SQL. Обычными целями являются нахождение различных элементов, таких как объекты Table или BindParameter, а также изменение состояния структуры, например, замена одних пунктов FROM другими.

Модуль sqlalchemy.sql.visitors является частью внутренних компонентов SQLAlchemy и обычно не используется при вызове кода приложения. Однако он используется в некоторых исключительных случаях, например, при построении процедур кэширования, а также при построении пользовательских SQL-выражений с помощью Custom SQL Constructs and Compilation Extension.

Интерфейс посетителя/обходчика и библиотечные функции.

class sqlalchemy.sql.visitors.ExternalTraversal¶

Базовый класс для объектов-визитеров, которые могут обходить внешние объекты с помощью функции traverse().

Прямое использование функции traverse() обычно предпочтительнее.

Members

chain(), iterate(), traverse(), visitor_iterator

Классная подпись

класс sqlalchemy.sql.visitors.ExternalTraversal (sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.sql.visitors.ExternalTraversal.chain(visitor: ExternalTraversal) → _ExtT¶

„Цепляем“ дополнительный внешний траверсаль к этому внешнему траверсалю

Прикованный посетитель будет получать все события посещения после этого.

method sqlalchemy.sql.visitors.ExternalTraversal.iterate(obj: Optional[ExternallyTraversible]) → Iterator[ExternallyTraversible]¶

Обход заданной структуры выражения, возвращая итератор всех элементов.

method sqlalchemy.sql.visitors.ExternalTraversal.traverse(obj: Optional[ExternallyTraversible]) → Optional[ExternallyTraversible]¶

Обход и посещение заданной структуры выражений.

attribute sqlalchemy.sql.visitors.ExternalTraversal.visitor_iterator¶

Итерация через этого посетителя и каждого «связанного» посетителя.

class sqlalchemy.sql.visitors.InternalTraversal¶

Определяет символы посетителей, используемые для внутреннего обхода.

Класс InternalTraversal используется двумя способами. Во-первых, он может служить суперклассом для объекта, реализующего различные методы посещения класса. Другой заключается в том, что сами символы InternalTraversal используются внутри коллекции _traverse_internals. Например, объект Case определяет _traverse_internals как

_traverse_internals = [
    ("value", InternalTraversal.dp_clauseelement),
    ("whens", InternalTraversal.dp_clauseelement_tuples),
    ("else_", InternalTraversal.dp_clauseelement),
]

Выше, класс Case указывает на свое внутреннее состояние в виде атрибутов value, whens и else_. Каждый из них ссылается на метод InternalTraversal, который указывает на тип структуры данных, к которой он относится.

Используя структуру _traverse_internals, у объектов типа InternalTraversible будут автоматически реализованы следующие методы:

• HasTraverseInternals.get_children()

• HasTraverseInternals._copy_internals()

• HasCacheKey._gen_cache_key()

Подклассы также могут реализовать эти методы напрямую, особенно для метода HasTraverseInternals._copy_internals(), когда требуются специальные шаги.

Добавлено в версии 1.4.

Members

dp_annotations_key, dp_anon_name, dp_boolean, dp_clauseelement, dp_clauseelement_list, dp_clauseelement_tuple, dp_clauseelement_tuples, dp_dialect_options, dp_dml_multi_values, dp_dml_ordered_values, dp_dml_values, dp_fromclause_canonical_column_collection, dp_fromclause_ordered_set, dp_has_cache_key, dp_has_cache_key_list, dp_has_cache_key_tuples, dp_ignore, dp_inspectable, dp_inspectable_list, dp_multi, dp_multi_list, dp_named_ddl_element, dp_operator, dp_plain_dict, dp_plain_obj, dp_prefix_sequence, dp_propagate_attrs, dp_statement_hint_list, dp_string, dp_string_clauseelement_dict, dp_string_list, dp_string_multi_dict, dp_table_hint_list, dp_type, dp_unknown_structure

Классная подпись

класс sqlalchemy.sql.visitors.InternalTraversal (enum.Enum)

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_annotations_key = 'AK'¶

Посетите элемент _annotations_cache_key.

Это словарь дополнительной информации о ClauseElement, которая изменяет его роль. Он должен быть включен при сравнении или кэшировании объектов, однако создание этого ключа относительно дорого. Перед созданием этого ключа посетителям следует сначала проверить дикту «_annotations» на не-None.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_anon_name = 'AN'¶

Посетите потенциально «анонимизированное» строковое значение.

Значение строки считается значимым для генерации ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_boolean = 'B'¶

Посетите булево значение.

Булево значение считается значимым для генерации ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement = 'CE'¶

Посетите объект ClauseElement.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_list = 'CL'¶

Посетите список объектов ClauseElement.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuple = 'CT'¶

Посетите кортеж объектов ClauseElement.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuples = 'CTS'¶

Посетите список кортежей, которые содержат ClauseElement объектов.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dialect_options = 'DO'¶

Посетите структуру диалектных опционов.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_multi_values = 'DML_MV'¶

Посетите многозначный список словарей values() объекта Insert.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_ordered_values = 'DML_OV'¶

Посетите упорядоченный кортежный список values() объекта Update.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_values = 'DML_V'¶

Посетите словарь values() объекта ValuesBase (например, Insert или Update).

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_canonical_column_collection = 'FC'¶

Посетите объект FromClause в контексте атрибута columns.

Коллекция столбцов является «канонической», то есть это изначально определенное расположение объектов ColumnClause. Сейчас это означает, что посещаемый объект является только объектом TableClause или Table.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_ordered_set = 'CO'¶

Посетите упорядоченный набор объектов FromClause.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key = 'HC'¶

Посетите объект HasCacheKey.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key_list = 'HL'¶

Посетите список объектов HasCacheKey.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key_tuples = 'HT'¶

Посетите список кортежей, которые содержат HasCacheKey объектов.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_ignore = 'IG'¶

Укажите объект, который следует полностью игнорировать.

В настоящее время это относится к кэшированию аргументов вызова функции, где некоторые аргументы не должны рассматриваться как часть ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_inspectable = 'IS'¶

Посетите инспектируемый объект, где возвращаемым значением является объект HasCacheKey.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_inspectable_list = 'IL'¶

Посетите список проверяемых объектов, которые при проверке являются объектами HasCacheKey.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_multi = 'M'¶

Посетите объект, который может быть HasCacheKey или может быть обычным хэшируемым объектом.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_multi_list = 'MT'¶

Посетите кортеж, содержащий элементы, которые могут быть HasCacheKey или могут быть обычным хэшируемым объектом.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_named_ddl_element = 'DD'¶

Посетите простой именованный элемент DDL.

Текущим объектом, используемым этим методом, является Sequence.

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

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_operator = 'O'¶

Посетите оператора.

Оператор представляет собой функцию из модуля sqlalchemy.sql.operators.

Значение оператора считается значимым для генерации ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_plain_dict = 'PD'¶

Посетите словарь со строковыми ключами.

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

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_plain_obj = 'PO'¶

Посетите обычный объект python.

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

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_prefix_sequence = 'PS'¶

Посетите последовательность, представленную HasPrefixes или HasSuffixes.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_propagate_attrs = 'PA'¶

Перейдите к дикту propagate attrs. Это жестко кодирует конкретные элементы, о которых мы сейчас заботимся.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_statement_hint_list = 'SH'¶

Посетите коллекцию _statement_hints объекта Select.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string = 'S'¶

Посетите обычное строковое значение.

Примеры включают имена таблиц и столбцов, связанные ключи параметров, специальные ключевые слова, такие как «UNION», «UNION ALL».

Значение строки считается значимым для генерации ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_clauseelement_dict = 'CD'¶

Обращение словаря строковых ключей к объектам ClauseElement.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_list = 'SL'¶

Посетите список струн.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_multi_dict = 'MD'¶

Обращение словаря строковых ключей к значениям, которые могут быть либо обычными неизменяемыми/хэшируемыми, либо объектами HasCacheKey.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_table_hint_list = 'TH'¶

Посетите коллекцию _hints объекта Select.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_type = 'T'¶

Посетите объект TypeEngine

Объект типа считается значимым для генерации ключа кэша.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_unknown_structure = 'UK'¶

Посетите неизвестную структуру.

class sqlalchemy.sql.visitors.Visitable¶

Базовый класс для посещаемых объектов.

Visitable используется для реализации функций диспетчеризации компилятора SQL. Другие формы обхода, например, для генерации ключей кэша, реализуются отдельно с помощью интерфейса HasTraverseInternals.

Изменено в версии 2.0: Класс Visitable был назван Traversible в серии 1.4; в 2.0 это имя возвращено на Visitable, каким оно было до 1.4.

Оба названия остаются импортируемыми как в версии 1.4, так и в версии 2.0.

attribute sqlalchemy.sql.visitors..sqlalchemy.sql.visitors.anon_map¶

alias of cache_anon_map

function sqlalchemy.sql.visitors.cloned_traverse(obj: Optional[ExternallyTraversible], opts: Mapping[str, Any], visitors: Mapping[str, Callable[[Any], None]]) → Optional[ExternallyTraversible]¶

Клонирует заданную структуру выражений, позволяя посетителям вносить изменения для изменяемых объектов.

Использование обхода такое же, как и в traverse(). Функции-посетители, присутствующие в словаре visitors, также могут модифицировать внутренние компоненты данной структуры по мере выполнения обхода.

Функция cloned_traverse() не предоставляет объекты, являющиеся частью интерфейса Immutable, методам посещения (сюда в первую очередь относятся объекты ColumnClause, Column, TableClause и Table). Поскольку этот обход предназначен только для того, чтобы разрешить мутацию объектов на месте, объекты Immutable пропускаются. Метод Immutable._clone() по-прежнему вызывается на каждом объекте, чтобы позволить объектам заменять себя другим объектом, основанным на клонировании их внутренних элементов (например, ColumnClause, который клонирует свой подзапрос, чтобы вернуть новый ColumnClause).

Изменено в версии 2.0: Функция cloned_traverse() опускает объекты, которые являются частью интерфейса Immutable.

Центральной функцией API, используемой функциями cloned_traverse() и replacement_traverse(), в дополнение к функции ClauseElement.get_children(), которая используется для достижения итерации, является метод ClauseElement._copy_internals(). Чтобы структура ClauseElement правильно поддерживала обход с клонированием и заменой, она должна иметь возможность передавать функцию клонирования в свои внутренние члены для создания их копий.

См.также

traverse()

replacement_traverse()

function sqlalchemy.sql.visitors.iterate(obj: Optional[ExternallyTraversible], opts: Mapping[str, Any] = {}) → Iterator[ExternallyTraversible]¶

Обход заданной структуры выражений с возвратом итератора.

Обход настроен на обход по ширине.

Центральной API-функцией, используемой функцией iterate(), является метод ClauseElement.get_children() объектов ClauseElement. Этот метод должен возвращать все объекты ClauseElement, которые связаны с определенным объектом ClauseElement. Например, структура Case будет ссылаться на ряд ColumnElement объектов в своих переменных-членах «whens» и «else_».

Параметры:

• obj – ClauseElement структура, которую необходимо пройти

• opts – словарь опций итерации. В современном использовании этот словарь обычно пуст.

function sqlalchemy.sql.visitors.replacement_traverse(obj: Optional[ExternallyTraversible], opts: Mapping[str, Any], replace: _TraverseTransformCallableType[Any]) → Optional[ExternallyTraversible]¶

Клонирует заданную структуру выражения, позволяя заменять элементы заданной функцией замены.

Эта функция очень похожа на функцию cloned_traverse(), только вместо того, чтобы передавать словарь посетителей, все элементы безусловно передаются в данную функцию replace. Функция replace может вернуть совершенно новый объект, который заменит заданный. Если она возвращает None, то объект остается на месте.

Разница в использовании cloned_traverse() и replacement_traverse() заключается в том, что в первом случае функции-посетителю передается уже клонированный объект, и функция-посетитель может манипулировать внутренним состоянием объекта. Во втором случае функция-посетитель должна только вернуть совершенно другой объект или ничего не делать.

Примером использования replacement_traverse() является замена предложения FROM внутри SQL-структуры на другое, что является обычным примером использования в ORM.

function sqlalchemy.sql.visitors.traverse(obj: Optional[ExternallyTraversible], opts: Mapping[str, Any], visitors: Mapping[str, Callable[[Any], None]]) → Optional[ExternallyTraversible]¶

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

например:

from sqlalchemy.sql import visitors

stmt = select(some_table).where(some_table.c.foo == 'bar')

def visit_bindparam(bind_param):
    print("found bound value: %s" % bind_param.value)

visitors.traverse(stmt, {}, {"bindparam": visit_bindparam})

Для итерации объектов используется функция iterate(), которая выполняет обход по ширине с использованием стека.

Параметры:

• obj – ClauseElement структура, которую необходимо пройти

• opts – словарь опций итерации. В современном использовании этот словарь обычно пуст.

• visitors – словарь функций посещения. Словарь должен иметь строки в качестве ключей, каждая из которых будет соответствовать __visit_name__ определенного вида объекта выражения SQL, и вызываемые функции в качестве значений, каждая из которых представляет функцию посещения для этого вида объекта.

function sqlalchemy.sql.visitors.traverse_using(iterator: Iterable[ExternallyTraversible], obj: Optional[ExternallyTraversible], visitors: Mapping[str, Callable[[Any], None]]) → Optional[ExternallyTraversible]¶

Посетите заданную структуру выражения, используя заданный итератор объектов.

traverse_using() обычно вызывается внутренне как результат функции traverse().

Параметры:

• iterator – итератор или последовательность, которая будет давать структуры ClauseElement; предполагается, что итератор является произведением функции iterate().

• obj – ClauseElement, который был использован в качестве цели функции iterate().

• visitors – словарь функций посещения. Подробности об этом словаре см. в traverse().

См.также

traverse()