Analyzing the Parsed Statement

When the parse() function is called the returned value is a tree-ish representation of the analyzed statements. The returned objects can be used by applications to retrieve further information about the parsed SQL.

Base Classes

All returned objects inherit from these base classes. The Token class represents a single token and TokenList class is a group of tokens. The latter provides methods for inspecting it’s child tokens.

class sqlparse.sql.Token(ttype, value)

Base class for all other classes in this module.

It represents a single token and has two instance attributes: value is the unchange value of the token and ttype is the type of the token.

flatten()

Resolve subgroups.

has_ancestor(other)

Returns True if other is in this tokens ancestry.

is_child_of(other)

Returns True if this token is a direct child of other.

is_group()

Returns True if this object has children.

is_whitespace()

Return True if this token is a whitespace token.

match(ttype, values, regex=False)

Checks whether the token matches the given arguments.

ttype is a token type. If this token doesn’t match the given token type. values is a list of possible values for this token. The values are OR’ed together so if only one of the values matches True is returned. Except for keyword tokens the comparison is case-sensitive. For convenience it’s ok to pass in a single string. If regex is True (default is False) the given values are treated as regular expressions.

to_unicode()

Returns a unicode representation of this object.

Deprecated since version 0.1.5: Use unicode(token) (for Python 3: str(token)) instead.

within(group_cls)

Returns True if this token is within group_cls.

Use this method for example to check if an identifier is within a function: t.within(sql.Function).

class sqlparse.sql.TokenList(tokens=None)

A group of tokens.

It has an additional instance attribute tokens which holds a list of child-tokens.

flatten()

Generator yielding ungrouped tokens.

This method is recursively called for all child tokens.

get_alias()

Returns the alias for this identifier or None.

get_name()

Returns the name of this identifier.

This is either it’s alias or it’s real name. The returned valued can be considered as the name under which the object corresponding to this identifier is known within the current statement.

get_parent_name()

Return name of the parent object if any.

A parent object is identified by the first occuring dot.

get_real_name()

Returns the real name (object name) of this identifier.

get_token_at_offset(offset)

Returns the token that is on position offset.

group_tokens(grp_cls, tokens, ignore_ws=False)

Replace tokens by an instance of grp_cls.

has_alias()

Returns True if an alias is present.

insert_after(where, token, skip_ws=True)

Inserts token after where.

insert_before(where, token)

Inserts token before where.

token_first(ignore_whitespace=True, ignore_comments=False)

Returns the first child token.

If ignore_whitespace is True (the default), whitespace tokens are ignored.

if ignore_comments is True (default: False), comments are ignored too.

token_index(token)

Return list index of token.

token_next(idx, skip_ws=True)

Returns the next token relative to idx.

If skip_ws is True (the default) whitespace tokens are ignored. None is returned if there’s no next token.

token_next_by_instance(idx, clss)

Returns the next token matching a class.

idx is where to start searching in the list of child tokens. clss is a list of classes the token should be an instance of.

If no matching token can be found None is returned.

token_next_by_type(idx, ttypes)

Returns next matching token by it’s token type.

token_next_match(idx, ttype, value, regex=False)

Returns next token where it’s match method returns True.

token_prev(idx, skip_ws=True)

Returns the previous token relative to idx.

If skip_ws is True (the default) whitespace tokens are ignored. None is returned if there’s no previous token.

tokens_between(start, end, exclude_end=False)

Return all tokens between (and including) start and end.

If exclude_end is True (default is False) the end token is included too.

SQL Representing Classes

The following classes represent distinct parts of a SQL statement.

class sqlparse.sql.Statement(tokens=None)

Represents a SQL statement.

get_type()

Returns the type of a statement.

The returned value is a string holding an upper-cased reprint of the first DML or DDL keyword. If the first token in this group isn’t a DML or DDL keyword “UNKNOWN” is returned.

Whitespaces and comments at the beginning of the statement are ignored.

class sqlparse.sql.Comment(tokens=None)

A comment.

class sqlparse.sql.Identifier(tokens=None)

Represents an identifier.

Identifiers may have aliases or typecasts.

get_array_indices()

Returns an iterator of index token lists

get_ordering()

Returns the ordering or None as uppercase string.

get_typecast()

Returns the typecast or None of this object as a string.

is_wildcard()

Return True if this identifier contains a wildcard.

class sqlparse.sql.IdentifierList(tokens=None)

A list of Identifier‘s.

get_identifiers()

Returns the identifiers.

Whitespaces and punctuations are not included in this generator.

class sqlparse.sql.Where(tokens=None)

A WHERE clause.

class sqlparse.sql.Case(tokens=None)

A CASE statement with one or more WHEN and possibly an ELSE part.

get_cases()

Returns a list of 2-tuples (condition, value).

If an ELSE exists condition is None.

class sqlparse.sql.Parenthesis(tokens=None)

Tokens between parenthesis.

class sqlparse.sql.If(tokens=None)

An ‘if’ clause with possible ‘else if’ or ‘else’ parts.

class sqlparse.sql.For(tokens=None)

A ‘FOR’ loop.

class sqlparse.sql.Assignment(tokens=None)

An assignment like ‘var := val;’

class sqlparse.sql.Comparison(tokens=None)

A comparison used for example in WHERE clauses.