Edit on GitHub

sqlglot.helper

  1from __future__ import annotations
  2
  3import inspect
  4import logging
  5import re
  6import sys
  7import typing as t
  8from collections.abc import Collection
  9from contextlib import contextmanager
 10from copy import copy
 11from enum import Enum
 12from itertools import count
 13
 14if t.TYPE_CHECKING:
 15    from sqlglot import exp
 16    from sqlglot._typing import E, T
 17    from sqlglot.dialects.dialect import DialectType
 18    from sqlglot.expressions import Expression
 19
 20CAMEL_CASE_PATTERN = re.compile("(?<!^)(?=[A-Z])")
 21PYTHON_VERSION = sys.version_info[:2]
 22logger = logging.getLogger("sqlglot")
 23
 24
 25class AutoName(Enum):
 26    """This is used for creating enum classes where `auto()` is the string form of the corresponding value's name."""
 27
 28    def _generate_next_value_(name, _start, _count, _last_values):
 29        return name
 30
 31
 32def seq_get(seq: t.Sequence[T], index: int) -> t.Optional[T]:
 33    """Returns the value in `seq` at position `index`, or `None` if `index` is out of bounds."""
 34    try:
 35        return seq[index]
 36    except IndexError:
 37        return None
 38
 39
 40@t.overload
 41def ensure_list(value: t.Collection[T]) -> t.List[T]:
 42    ...
 43
 44
 45@t.overload
 46def ensure_list(value: T) -> t.List[T]:
 47    ...
 48
 49
 50def ensure_list(value):
 51    """
 52    Ensures that a value is a list, otherwise casts or wraps it into one.
 53
 54    Args:
 55        value: the value of interest.
 56
 57    Returns:
 58        The value cast as a list if it's a list or a tuple, or else the value wrapped in a list.
 59    """
 60    if value is None:
 61        return []
 62    if isinstance(value, (list, tuple)):
 63        return list(value)
 64
 65    return [value]
 66
 67
 68@t.overload
 69def ensure_collection(value: t.Collection[T]) -> t.Collection[T]:
 70    ...
 71
 72
 73@t.overload
 74def ensure_collection(value: T) -> t.Collection[T]:
 75    ...
 76
 77
 78def ensure_collection(value):
 79    """
 80    Ensures that a value is a collection (excluding `str` and `bytes`), otherwise wraps it into a list.
 81
 82    Args:
 83        value: the value of interest.
 84
 85    Returns:
 86        The value if it's a collection, or else the value wrapped in a list.
 87    """
 88    if value is None:
 89        return []
 90    return (
 91        value if isinstance(value, Collection) and not isinstance(value, (str, bytes)) else [value]
 92    )
 93
 94
 95def csv(*args: str, sep: str = ", ") -> str:
 96    """
 97    Formats any number of string arguments as CSV.
 98
 99    Args:
100        args: the string arguments to format.
101        sep: the argument separator.
102
103    Returns:
104        The arguments formatted as a CSV string.
105    """
106    return sep.join(arg for arg in args if arg)
107
108
109def subclasses(
110    module_name: str,
111    classes: t.Type | t.Tuple[t.Type, ...],
112    exclude: t.Type | t.Tuple[t.Type, ...] = (),
113) -> t.List[t.Type]:
114    """
115    Returns all subclasses for a collection of classes, possibly excluding some of them.
116
117    Args:
118        module_name: the name of the module to search for subclasses in.
119        classes: class(es) we want to find the subclasses of.
120        exclude: class(es) we want to exclude from the returned list.
121
122    Returns:
123        The target subclasses.
124    """
125    return [
126        obj
127        for _, obj in inspect.getmembers(
128            sys.modules[module_name],
129            lambda obj: inspect.isclass(obj) and issubclass(obj, classes) and obj not in exclude,
130        )
131    ]
132
133
134def apply_index_offset(
135    this: exp.Expression,
136    expressions: t.List[t.Optional[E]],
137    offset: int,
138) -> t.List[t.Optional[E]]:
139    """
140    Applies an offset to a given integer literal expression.
141
142    Args:
143        this: the target of the index
144        expressions: the expression the offset will be applied to, wrapped in a list.
145        offset: the offset that will be applied.
146
147    Returns:
148        The original expression with the offset applied to it, wrapped in a list. If the provided
149        `expressions` argument contains more than one expressions, it's returned unaffected.
150    """
151    if not offset or len(expressions) != 1:
152        return expressions
153
154    expression = expressions[0]
155
156    from sqlglot import exp
157    from sqlglot.optimizer.annotate_types import annotate_types
158    from sqlglot.optimizer.simplify import simplify
159
160    if not this.type:
161        annotate_types(this)
162
163    if t.cast(exp.DataType, this.type).this not in (
164        exp.DataType.Type.UNKNOWN,
165        exp.DataType.Type.ARRAY,
166    ):
167        return expressions
168
169    if expression:
170        if not expression.type:
171            annotate_types(expression)
172        if t.cast(exp.DataType, expression.type).this in exp.DataType.INTEGER_TYPES:
173            logger.warning("Applying array index offset (%s)", offset)
174            expression = simplify(
175                exp.Add(this=expression.copy(), expression=exp.Literal.number(offset))
176            )
177            return [expression]
178
179    return expressions
180
181
182def camel_to_snake_case(name: str) -> str:
183    """Converts `name` from camelCase to snake_case and returns the result."""
184    return CAMEL_CASE_PATTERN.sub("_", name).upper()
185
186
187def while_changing(expression: Expression, func: t.Callable[[Expression], E]) -> E:
188    """
189    Applies a transformation to a given expression until a fix point is reached.
190
191    Args:
192        expression: the expression to be transformed.
193        func: the transformation to be applied.
194
195    Returns:
196        The transformed expression.
197    """
198    while True:
199        for n, *_ in reversed(tuple(expression.walk())):
200            n._hash = hash(n)
201        start = hash(expression)
202        expression = func(expression)
203
204        for n, *_ in expression.walk():
205            n._hash = None
206        if start == hash(expression):
207            break
208    return expression
209
210
211def tsort(dag: t.Dict[T, t.Set[T]]) -> t.List[T]:
212    """
213    Sorts a given directed acyclic graph in topological order.
214
215    Args:
216        dag: the graph to be sorted.
217
218    Returns:
219        A list that contains all of the graph's nodes in topological order.
220    """
221    result = []
222
223    for node, deps in tuple(dag.items()):
224        for dep in deps:
225            if not dep in dag:
226                dag[dep] = set()
227
228    while dag:
229        current = {node for node, deps in dag.items() if not deps}
230
231        if not current:
232            raise ValueError("Cycle error")
233
234        for node in current:
235            dag.pop(node)
236
237        for deps in dag.values():
238            deps -= current
239
240        result.extend(sorted(current))  # type: ignore
241
242    return result
243
244
245def open_file(file_name: str) -> t.TextIO:
246    """Open a file that may be compressed as gzip and return it in universal newline mode."""
247    with open(file_name, "rb") as f:
248        gzipped = f.read(2) == b"\x1f\x8b"
249
250    if gzipped:
251        import gzip
252
253        return gzip.open(file_name, "rt", newline="")
254
255    return open(file_name, encoding="utf-8", newline="")
256
257
258@contextmanager
259def csv_reader(read_csv: exp.ReadCSV) -> t.Any:
260    """
261    Returns a csv reader given the expression `READ_CSV(name, ['delimiter', '|', ...])`.
262
263    Args:
264        read_csv: a `ReadCSV` function call
265
266    Yields:
267        A python csv reader.
268    """
269    args = read_csv.expressions
270    file = open_file(read_csv.name)
271
272    delimiter = ","
273    args = iter(arg.name for arg in args)
274    for k, v in zip(args, args):
275        if k == "delimiter":
276            delimiter = v
277
278    try:
279        import csv as csv_
280
281        yield csv_.reader(file, delimiter=delimiter)
282    finally:
283        file.close()
284
285
286def find_new_name(taken: t.Collection[str], base: str) -> str:
287    """
288    Searches for a new name.
289
290    Args:
291        taken: a collection of taken names.
292        base: base name to alter.
293
294    Returns:
295        The new, available name.
296    """
297    if base not in taken:
298        return base
299
300    i = 2
301    new = f"{base}_{i}"
302    while new in taken:
303        i += 1
304        new = f"{base}_{i}"
305
306    return new
307
308
309def name_sequence(prefix: str) -> t.Callable[[], str]:
310    """Returns a name generator given a prefix (e.g. a0, a1, a2, ... if the prefix is "a")."""
311    sequence = count()
312    return lambda: f"{prefix}{next(sequence)}"
313
314
315def object_to_dict(obj: t.Any, **kwargs) -> t.Dict:
316    """Returns a dictionary created from an object's attributes."""
317    return {
318        **{k: v.copy() if hasattr(v, "copy") else copy(v) for k, v in vars(obj).items()},
319        **kwargs,
320    }
321
322
323def split_num_words(
324    value: str, sep: str, min_num_words: int, fill_from_start: bool = True
325) -> t.List[t.Optional[str]]:
326    """
327    Perform a split on a value and return N words as a result with `None` used for words that don't exist.
328
329    Args:
330        value: the value to be split.
331        sep: the value to use to split on.
332        min_num_words: the minimum number of words that are going to be in the result.
333        fill_from_start: indicates that if `None` values should be inserted at the start or end of the list.
334
335    Examples:
336        >>> split_num_words("db.table", ".", 3)
337        [None, 'db', 'table']
338        >>> split_num_words("db.table", ".", 3, fill_from_start=False)
339        ['db', 'table', None]
340        >>> split_num_words("db.table", ".", 1)
341        ['db', 'table']
342
343    Returns:
344        The list of words returned by `split`, possibly augmented by a number of `None` values.
345    """
346    words = value.split(sep)
347    if fill_from_start:
348        return [None] * (min_num_words - len(words)) + words
349    return words + [None] * (min_num_words - len(words))
350
351
352def is_iterable(value: t.Any) -> bool:
353    """
354    Checks if the value is an iterable, excluding the types `str` and `bytes`.
355
356    Examples:
357        >>> is_iterable([1,2])
358        True
359        >>> is_iterable("test")
360        False
361
362    Args:
363        value: the value to check if it is an iterable.
364
365    Returns:
366        A `bool` value indicating if it is an iterable.
367    """
368    return hasattr(value, "__iter__") and not isinstance(value, (str, bytes))
369
370
371def flatten(values: t.Iterable[t.Iterable[t.Any] | t.Any]) -> t.Iterator[t.Any]:
372    """
373    Flattens an iterable that can contain both iterable and non-iterable elements. Objects of
374    type `str` and `bytes` are not regarded as iterables.
375
376    Examples:
377        >>> list(flatten([[1, 2], 3, {4}, (5, "bla")]))
378        [1, 2, 3, 4, 5, 'bla']
379        >>> list(flatten([1, 2, 3]))
380        [1, 2, 3]
381
382    Args:
383        values: the value to be flattened.
384
385    Yields:
386        Non-iterable elements in `values`.
387    """
388    for value in values:
389        if is_iterable(value):
390            yield from flatten(value)
391        else:
392            yield value
393
394
395def dict_depth(d: t.Dict) -> int:
396    """
397    Get the nesting depth of a dictionary.
398
399    For example:
400        >>> dict_depth(None)
401        0
402        >>> dict_depth({})
403        1
404        >>> dict_depth({"a": "b"})
405        1
406        >>> dict_depth({"a": {}})
407        2
408        >>> dict_depth({"a": {"b": {}}})
409        3
410
411    Args:
412        d (dict): dictionary
413
414    Returns:
415        int: depth
416    """
417    try:
418        return 1 + dict_depth(next(iter(d.values())))
419    except AttributeError:
420        # d doesn't have attribute "values"
421        return 0
422    except StopIteration:
423        # d.values() returns an empty sequence
424        return 1
425
426
427def first(it: t.Iterable[T]) -> T:
428    """Returns the first element from an iterable.
429
430    Useful for sets.
431    """
432    return next(i for i in it)
433
434
435def case_sensitive(text: str, dialect: DialectType) -> bool:
436    """Checks if text contains any case sensitive characters depending on dialect."""
437    from sqlglot.dialects.dialect import RESOLVES_IDENTIFIERS_AS_UPPERCASE
438
439    unsafe = str.islower if dialect in RESOLVES_IDENTIFIERS_AS_UPPERCASE else str.isupper
440    return any(unsafe(char) for char in text)
441
442
443def should_identify(text: str, identify: str | bool, dialect: DialectType = None) -> bool:
444    """Checks if text should be identified given an identify option.
445
446    Args:
447        text: the text to check.
448        identify:
449            "always" or `True`: always returns true.
450            "safe": true if there is no uppercase or lowercase character in `text`, depending on `dialect`.
451        dialect: the dialect to use in order to decide whether a text should be identified.
452
453    Returns:
454        Whether or not a string should be identified.
455    """
456    if identify is True or identify == "always":
457        return True
458    if identify == "safe":
459        return not case_sensitive(text, dialect)
460    return False
class AutoName(enum.Enum):
26class AutoName(Enum):
27    """This is used for creating enum classes where `auto()` is the string form of the corresponding value's name."""
28
29    def _generate_next_value_(name, _start, _count, _last_values):
30        return name

This is used for creating enum classes where auto() is the string form of the corresponding value's name.

Inherited Members
enum.Enum
name
value
def seq_get(seq: Sequence[~T], index: int) -> Optional[~T]:
33def seq_get(seq: t.Sequence[T], index: int) -> t.Optional[T]:
34    """Returns the value in `seq` at position `index`, or `None` if `index` is out of bounds."""
35    try:
36        return seq[index]
37    except IndexError:
38        return None

Returns the value in seq at position index, or None if index is out of bounds.

def ensure_list(value):
51def ensure_list(value):
52    """
53    Ensures that a value is a list, otherwise casts or wraps it into one.
54
55    Args:
56        value: the value of interest.
57
58    Returns:
59        The value cast as a list if it's a list or a tuple, or else the value wrapped in a list.
60    """
61    if value is None:
62        return []
63    if isinstance(value, (list, tuple)):
64        return list(value)
65
66    return [value]

Ensures that a value is a list, otherwise casts or wraps it into one.

Arguments:
  • value: the value of interest.
Returns:

The value cast as a list if it's a list or a tuple, or else the value wrapped in a list.

def ensure_collection(value):
79def ensure_collection(value):
80    """
81    Ensures that a value is a collection (excluding `str` and `bytes`), otherwise wraps it into a list.
82
83    Args:
84        value: the value of interest.
85
86    Returns:
87        The value if it's a collection, or else the value wrapped in a list.
88    """
89    if value is None:
90        return []
91    return (
92        value if isinstance(value, Collection) and not isinstance(value, (str, bytes)) else [value]
93    )

Ensures that a value is a collection (excluding str and bytes), otherwise wraps it into a list.

Arguments:
  • value: the value of interest.
Returns:

The value if it's a collection, or else the value wrapped in a list.

def csv(*args: str, sep: str = ', ') -> str:
 96def csv(*args: str, sep: str = ", ") -> str:
 97    """
 98    Formats any number of string arguments as CSV.
 99
100    Args:
101        args: the string arguments to format.
102        sep: the argument separator.
103
104    Returns:
105        The arguments formatted as a CSV string.
106    """
107    return sep.join(arg for arg in args if arg)

Formats any number of string arguments as CSV.

Arguments:
  • args: the string arguments to format.
  • sep: the argument separator.
Returns:

The arguments formatted as a CSV string.

def subclasses( module_name: str, classes: Union[Type, Tuple[Type, ...]], exclude: Union[Type, Tuple[Type, ...]] = ()) -> List[Type]:
110def subclasses(
111    module_name: str,
112    classes: t.Type | t.Tuple[t.Type, ...],
113    exclude: t.Type | t.Tuple[t.Type, ...] = (),
114) -> t.List[t.Type]:
115    """
116    Returns all subclasses for a collection of classes, possibly excluding some of them.
117
118    Args:
119        module_name: the name of the module to search for subclasses in.
120        classes: class(es) we want to find the subclasses of.
121        exclude: class(es) we want to exclude from the returned list.
122
123    Returns:
124        The target subclasses.
125    """
126    return [
127        obj
128        for _, obj in inspect.getmembers(
129            sys.modules[module_name],
130            lambda obj: inspect.isclass(obj) and issubclass(obj, classes) and obj not in exclude,
131        )
132    ]

Returns all subclasses for a collection of classes, possibly excluding some of them.

Arguments:
  • module_name: the name of the module to search for subclasses in.
  • classes: class(es) we want to find the subclasses of.
  • exclude: class(es) we want to exclude from the returned list.
Returns:

The target subclasses.

def apply_index_offset( this: sqlglot.expressions.Expression, expressions: List[Optional[~E]], offset: int) -> List[Optional[~E]]:
135def apply_index_offset(
136    this: exp.Expression,
137    expressions: t.List[t.Optional[E]],
138    offset: int,
139) -> t.List[t.Optional[E]]:
140    """
141    Applies an offset to a given integer literal expression.
142
143    Args:
144        this: the target of the index
145        expressions: the expression the offset will be applied to, wrapped in a list.
146        offset: the offset that will be applied.
147
148    Returns:
149        The original expression with the offset applied to it, wrapped in a list. If the provided
150        `expressions` argument contains more than one expressions, it's returned unaffected.
151    """
152    if not offset or len(expressions) != 1:
153        return expressions
154
155    expression = expressions[0]
156
157    from sqlglot import exp
158    from sqlglot.optimizer.annotate_types import annotate_types
159    from sqlglot.optimizer.simplify import simplify
160
161    if not this.type:
162        annotate_types(this)
163
164    if t.cast(exp.DataType, this.type).this not in (
165        exp.DataType.Type.UNKNOWN,
166        exp.DataType.Type.ARRAY,
167    ):
168        return expressions
169
170    if expression:
171        if not expression.type:
172            annotate_types(expression)
173        if t.cast(exp.DataType, expression.type).this in exp.DataType.INTEGER_TYPES:
174            logger.warning("Applying array index offset (%s)", offset)
175            expression = simplify(
176                exp.Add(this=expression.copy(), expression=exp.Literal.number(offset))
177            )
178            return [expression]
179
180    return expressions

Applies an offset to a given integer literal expression.

Arguments:
  • this: the target of the index
  • expressions: the expression the offset will be applied to, wrapped in a list.
  • offset: the offset that will be applied.
Returns:

The original expression with the offset applied to it, wrapped in a list. If the provided expressions argument contains more than one expressions, it's returned unaffected.

def camel_to_snake_case(name: str) -> str:
183def camel_to_snake_case(name: str) -> str:
184    """Converts `name` from camelCase to snake_case and returns the result."""
185    return CAMEL_CASE_PATTERN.sub("_", name).upper()

Converts name from camelCase to snake_case and returns the result.

def while_changing( expression: sqlglot.expressions.Expression, func: Callable[[sqlglot.expressions.Expression], ~E]) -> ~E:
188def while_changing(expression: Expression, func: t.Callable[[Expression], E]) -> E:
189    """
190    Applies a transformation to a given expression until a fix point is reached.
191
192    Args:
193        expression: the expression to be transformed.
194        func: the transformation to be applied.
195
196    Returns:
197        The transformed expression.
198    """
199    while True:
200        for n, *_ in reversed(tuple(expression.walk())):
201            n._hash = hash(n)
202        start = hash(expression)
203        expression = func(expression)
204
205        for n, *_ in expression.walk():
206            n._hash = None
207        if start == hash(expression):
208            break
209    return expression

Applies a transformation to a given expression until a fix point is reached.

Arguments:
  • expression: the expression to be transformed.
  • func: the transformation to be applied.
Returns:

The transformed expression.

def tsort(dag: Dict[~T, Set[~T]]) -> List[~T]:
212def tsort(dag: t.Dict[T, t.Set[T]]) -> t.List[T]:
213    """
214    Sorts a given directed acyclic graph in topological order.
215
216    Args:
217        dag: the graph to be sorted.
218
219    Returns:
220        A list that contains all of the graph's nodes in topological order.
221    """
222    result = []
223
224    for node, deps in tuple(dag.items()):
225        for dep in deps:
226            if not dep in dag:
227                dag[dep] = set()
228
229    while dag:
230        current = {node for node, deps in dag.items() if not deps}
231
232        if not current:
233            raise ValueError("Cycle error")
234
235        for node in current:
236            dag.pop(node)
237
238        for deps in dag.values():
239            deps -= current
240
241        result.extend(sorted(current))  # type: ignore
242
243    return result

Sorts a given directed acyclic graph in topological order.

Arguments:
  • dag: the graph to be sorted.
Returns:

A list that contains all of the graph's nodes in topological order.

def open_file(file_name: str) -> <class 'TextIO'>:
246def open_file(file_name: str) -> t.TextIO:
247    """Open a file that may be compressed as gzip and return it in universal newline mode."""
248    with open(file_name, "rb") as f:
249        gzipped = f.read(2) == b"\x1f\x8b"
250
251    if gzipped:
252        import gzip
253
254        return gzip.open(file_name, "rt", newline="")
255
256    return open(file_name, encoding="utf-8", newline="")

Open a file that may be compressed as gzip and return it in universal newline mode.

@contextmanager
def csv_reader(read_csv: sqlglot.expressions.ReadCSV) -> Any:
259@contextmanager
260def csv_reader(read_csv: exp.ReadCSV) -> t.Any:
261    """
262    Returns a csv reader given the expression `READ_CSV(name, ['delimiter', '|', ...])`.
263
264    Args:
265        read_csv: a `ReadCSV` function call
266
267    Yields:
268        A python csv reader.
269    """
270    args = read_csv.expressions
271    file = open_file(read_csv.name)
272
273    delimiter = ","
274    args = iter(arg.name for arg in args)
275    for k, v in zip(args, args):
276        if k == "delimiter":
277            delimiter = v
278
279    try:
280        import csv as csv_
281
282        yield csv_.reader(file, delimiter=delimiter)
283    finally:
284        file.close()

Returns a csv reader given the expression READ_CSV(name, ['delimiter', '|', ...]).

Arguments:
  • read_csv: a ReadCSV function call
Yields:

A python csv reader.

def find_new_name(taken: Collection[str], base: str) -> str:
287def find_new_name(taken: t.Collection[str], base: str) -> str:
288    """
289    Searches for a new name.
290
291    Args:
292        taken: a collection of taken names.
293        base: base name to alter.
294
295    Returns:
296        The new, available name.
297    """
298    if base not in taken:
299        return base
300
301    i = 2
302    new = f"{base}_{i}"
303    while new in taken:
304        i += 1
305        new = f"{base}_{i}"
306
307    return new

Searches for a new name.

Arguments:
  • taken: a collection of taken names.
  • base: base name to alter.
Returns:

The new, available name.

def name_sequence(prefix: str) -> Callable[[], str]:
310def name_sequence(prefix: str) -> t.Callable[[], str]:
311    """Returns a name generator given a prefix (e.g. a0, a1, a2, ... if the prefix is "a")."""
312    sequence = count()
313    return lambda: f"{prefix}{next(sequence)}"

Returns a name generator given a prefix (e.g. a0, a1, a2, ... if the prefix is "a").

def object_to_dict(obj: Any, **kwargs) -> Dict:
316def object_to_dict(obj: t.Any, **kwargs) -> t.Dict:
317    """Returns a dictionary created from an object's attributes."""
318    return {
319        **{k: v.copy() if hasattr(v, "copy") else copy(v) for k, v in vars(obj).items()},
320        **kwargs,
321    }

Returns a dictionary created from an object's attributes.

def split_num_words( value: str, sep: str, min_num_words: int, fill_from_start: bool = True) -> List[Optional[str]]:
324def split_num_words(
325    value: str, sep: str, min_num_words: int, fill_from_start: bool = True
326) -> t.List[t.Optional[str]]:
327    """
328    Perform a split on a value and return N words as a result with `None` used for words that don't exist.
329
330    Args:
331        value: the value to be split.
332        sep: the value to use to split on.
333        min_num_words: the minimum number of words that are going to be in the result.
334        fill_from_start: indicates that if `None` values should be inserted at the start or end of the list.
335
336    Examples:
337        >>> split_num_words("db.table", ".", 3)
338        [None, 'db', 'table']
339        >>> split_num_words("db.table", ".", 3, fill_from_start=False)
340        ['db', 'table', None]
341        >>> split_num_words("db.table", ".", 1)
342        ['db', 'table']
343
344    Returns:
345        The list of words returned by `split`, possibly augmented by a number of `None` values.
346    """
347    words = value.split(sep)
348    if fill_from_start:
349        return [None] * (min_num_words - len(words)) + words
350    return words + [None] * (min_num_words - len(words))

Perform a split on a value and return N words as a result with None used for words that don't exist.

Arguments:
  • value: the value to be split.
  • sep: the value to use to split on.
  • min_num_words: the minimum number of words that are going to be in the result.
  • fill_from_start: indicates that if None values should be inserted at the start or end of the list.
Examples:
>>> split_num_words("db.table", ".", 3)
[None, 'db', 'table']
>>> split_num_words("db.table", ".", 3, fill_from_start=False)
['db', 'table', None]
>>> split_num_words("db.table", ".", 1)
['db', 'table']
Returns:

The list of words returned by split, possibly augmented by a number of None values.

def is_iterable(value: Any) -> bool:
353def is_iterable(value: t.Any) -> bool:
354    """
355    Checks if the value is an iterable, excluding the types `str` and `bytes`.
356
357    Examples:
358        >>> is_iterable([1,2])
359        True
360        >>> is_iterable("test")
361        False
362
363    Args:
364        value: the value to check if it is an iterable.
365
366    Returns:
367        A `bool` value indicating if it is an iterable.
368    """
369    return hasattr(value, "__iter__") and not isinstance(value, (str, bytes))

Checks if the value is an iterable, excluding the types str and bytes.

Examples:
>>> is_iterable([1,2])
True
>>> is_iterable("test")
False
Arguments:
  • value: the value to check if it is an iterable.
Returns:

A bool value indicating if it is an iterable.

def flatten(values: Iterable[Union[Iterable[Any], Any]]) -> Iterator[Any]:
372def flatten(values: t.Iterable[t.Iterable[t.Any] | t.Any]) -> t.Iterator[t.Any]:
373    """
374    Flattens an iterable that can contain both iterable and non-iterable elements. Objects of
375    type `str` and `bytes` are not regarded as iterables.
376
377    Examples:
378        >>> list(flatten([[1, 2], 3, {4}, (5, "bla")]))
379        [1, 2, 3, 4, 5, 'bla']
380        >>> list(flatten([1, 2, 3]))
381        [1, 2, 3]
382
383    Args:
384        values: the value to be flattened.
385
386    Yields:
387        Non-iterable elements in `values`.
388    """
389    for value in values:
390        if is_iterable(value):
391            yield from flatten(value)
392        else:
393            yield value

Flattens an iterable that can contain both iterable and non-iterable elements. Objects of type str and bytes are not regarded as iterables.

Examples:
>>> list(flatten([[1, 2], 3, {4}, (5, "bla")]))
[1, 2, 3, 4, 5, 'bla']
>>> list(flatten([1, 2, 3]))
[1, 2, 3]
Arguments:
  • values: the value to be flattened.
Yields:

Non-iterable elements in values.

def dict_depth(d: Dict) -> int:
396def dict_depth(d: t.Dict) -> int:
397    """
398    Get the nesting depth of a dictionary.
399
400    For example:
401        >>> dict_depth(None)
402        0
403        >>> dict_depth({})
404        1
405        >>> dict_depth({"a": "b"})
406        1
407        >>> dict_depth({"a": {}})
408        2
409        >>> dict_depth({"a": {"b": {}}})
410        3
411
412    Args:
413        d (dict): dictionary
414
415    Returns:
416        int: depth
417    """
418    try:
419        return 1 + dict_depth(next(iter(d.values())))
420    except AttributeError:
421        # d doesn't have attribute "values"
422        return 0
423    except StopIteration:
424        # d.values() returns an empty sequence
425        return 1

Get the nesting depth of a dictionary.

For example:
>>> dict_depth(None)
0
>>> dict_depth({})
1
>>> dict_depth({"a": "b"})
1
>>> dict_depth({"a": {}})
2
>>> dict_depth({"a": {"b": {}}})
3
Arguments:
  • d (dict): dictionary
Returns:

int: depth

def first(it: Iterable[~T]) -> ~T:
428def first(it: t.Iterable[T]) -> T:
429    """Returns the first element from an iterable.
430
431    Useful for sets.
432    """
433    return next(i for i in it)

Returns the first element from an iterable.

Useful for sets.

def case_sensitive( text: str, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType]) -> bool:
436def case_sensitive(text: str, dialect: DialectType) -> bool:
437    """Checks if text contains any case sensitive characters depending on dialect."""
438    from sqlglot.dialects.dialect import RESOLVES_IDENTIFIERS_AS_UPPERCASE
439
440    unsafe = str.islower if dialect in RESOLVES_IDENTIFIERS_AS_UPPERCASE else str.isupper
441    return any(unsafe(char) for char in text)

Checks if text contains any case sensitive characters depending on dialect.

def should_identify( text: str, identify: str | bool, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None) -> bool:
444def should_identify(text: str, identify: str | bool, dialect: DialectType = None) -> bool:
445    """Checks if text should be identified given an identify option.
446
447    Args:
448        text: the text to check.
449        identify:
450            "always" or `True`: always returns true.
451            "safe": true if there is no uppercase or lowercase character in `text`, depending on `dialect`.
452        dialect: the dialect to use in order to decide whether a text should be identified.
453
454    Returns:
455        Whether or not a string should be identified.
456    """
457    if identify is True or identify == "always":
458        return True
459    if identify == "safe":
460        return not case_sensitive(text, dialect)
461    return False

Checks if text should be identified given an identify option.

Arguments:
  • text: the text to check.
  • identify: "always" or True: always returns true. "safe": true if there is no uppercase or lowercase character in text, depending on dialect.
  • dialect: the dialect to use in order to decide whether a text should be identified.
Returns:

Whether or not a string should be identified.