Утилиты посещения и обхода¶
Модуль 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 |
---|---|
alias of |
|
cloned_traverse(obj, opts, visitors) |
Клонирует заданную структуру выражений, позволяя посетителям вносить изменения для изменяемых объектов. |
Базовый класс для объектов-визитеров, которые могут обходить внешние объекты с помощью функции |
|
Определяет символы посетителей, используемые для внутреннего обхода. |
|
iterate(obj[, opts]) |
Обход заданной структуры выражений с возвратом итератора. |
replacement_traverse(obj, opts, replace) |
Клонирует заданную структуру выражения, позволяя заменять элементы заданной функцией замены. |
traverse(obj, opts, visitors) |
Обход и посещение заданной структуры выражения с использованием итератора по умолчанию. |
traverse_using(iterator, obj, visitors) |
Посетите заданную структуру выражения, используя заданный итератор объектов. |
Базовый класс для посещаемых объектов. |
- class sqlalchemy.sql.visitors.ExternalTraversal¶
Базовый класс для объектов-визитеров, которые могут обходить внешние объекты с помощью функции
traverse()
.Прямое использование функции
traverse()
обычно предпочтительнее.Members
Классная подпись
класс
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¶ Итерация через этого посетителя и каждого «связанного» посетителя.
-
method
- 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
.
-
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_».- Параметры:
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()
.
См.также