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

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

Примечание

модуль sqlalchemy.sql.visitors является внутренним API и не является полностью публичным. Он может быть изменен и, кроме того, может функционировать не так, как ожидается, для шаблонов использования, которые не рассматриваются в рамках внутренних механизмов SQLAlchemy.

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

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

Object Name Description

anon_map

alias of cache_anon_map

cloned_traverse(obj, opts, visitors)

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

ExternalTraversal

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

InternalTraversal

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

iterate(obj[, opts])

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

replacement_traverse(obj, opts, replace)

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

traverse(obj, opts, visitors)

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

traverse_using(iterator, obj, visitors)

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

Visitable

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

class sqlalchemy.sql.visitors.ExternalTraversal

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

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

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

класс 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.

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

класс 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 правильно поддерживала обход с клонированием и заменой, она должна иметь возможность передавать функцию клонирования в свои внутренние члены для создания их копий.

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_».

Параметры:
  • objClauseElement структура, которую необходимо пройти

  • 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(), которая выполняет обход по ширине с использованием стека.

Параметры:
  • objClauseElement структура, которую необходимо пройти

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

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

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

См.также

traverse()

Вернуться на верх