Advanced API

The simple API presents only a fraction of the functionality present within the core SQLFluff library. For more advanced use cases, users can import the Linter() and FluffConfig() classes from sqlfluff.core. As of version 0.4.0 this is considered as experimental only as the internals may change without warning in any future release. If you come to rely on the internals of SQLFluff, please post an issue on GitHub to share what you're up to. This will help shape a more reliable, tidy and well documented public API for use.

Classes

Linter

The interface class to interact with the linter.

Parameters:

Parameter	Type	Default	Description
config	`fluffconfig.FluffConfig	None`	None
formatter	`FormatterInterface	None`	None
dialect	`str	None`	None
rules	`list[str]	None`	None
user_rules	`list[type[base.BaseRule]]	None`	None
exclude_rules	`list[str]	None`	None

Methods

allowed_rule_ref_map

allowed_rule_ref_map(
    reference_map,
    disable_noqa_except
) → dict[str, set[str]]

Generate a noqa rule reference map.

Parameters:

Parameter	Type	Default	Description
reference_map	dict[str, set[str]]	—
disable_noqa_except	`str	None`	—

Returns:

dict[str, set[str]] — See return type above

fix

fix(
    self,
    tree,
    config=None,
    fname=None,
    templated_file=None
) → tuple[segments.base.BaseSegment, list[SQLBaseError]]

Return the fixed tree and violations from lintfix when we're fixing.

Parameters:

Parameter	Type	Default	Description
self	—	—
tree	segments.base.BaseSegment	—
config	`fluffconfig.FluffConfig	None`	None
fname	`str	None`	None
templated_file	`ForwardRef('TemplatedFile')	None`	None

Returns:

tuple[segments.base.BaseSegment, list[SQLBaseError]] — See return type above

get_rulepack

get_rulepack(
    self,
    config=None
) → base.RulePack

Get hold of a set of rules.

Parameters:

Parameter	Type	Default	Description
self	—	—
config	`fluffconfig.FluffConfig	None`	None

Returns:

base.RulePack — See return type above

lint

lint(
    self,
    tree,
    config=None,
    fname=None,
    templated_file=None
) → list[SQLBaseError]

Return just the violations from lintfix when we're only linting.

Parameters:

Parameter	Type	Default	Description
self	—	—
tree	segments.base.BaseSegment	—
config	`fluffconfig.FluffConfig	None`	None
fname	`str	None`	None
templated_file	`ForwardRef('TemplatedFile')	None`	None

Returns:

list[SQLBaseError] — See return type above

lint_fix_parsed

lint_fix_parsed(
    tree,
    config,
    rule_pack,
    fix=False,
    fname=None,
    templated_file=None,
    formatter=None
) → tuple[segments.base.BaseSegment, list[SQLBaseError], noqa.IgnoreMask | None, list[tuple[str, str, float]]]

Lint and optionally fix a tree object.

Parameters:

Parameter	Type	Default	Description
tree	segments.base.BaseSegment	—
config	fluffconfig.FluffConfig	—
rule_pack	base.RulePack	—
fix	bool	False
fname	`str	None`	None
templated_file	`ForwardRef('TemplatedFile')	None`	None
formatter	`FormatterInterface	None`	None

Returns:

tuple[segments.base.BaseSegment, list[SQLBaseError], noqa.IgnoreMask | None, list[tuple[str, str, float]]] — See return type above

lint_parsed

lint_parsed(
    parsed,
    rule_pack,
    fix=False,
    formatter=None,
    encoding="utf8"
) → linted_file.LintedFile

Lint a ParsedString and return a LintedFile.

Parameters:

Parameter	Type	Default	Description
parsed	common.ParsedString	—
rule_pack	base.RulePack	—
fix	bool	False
formatter	`FormatterInterface	None`	None
encoding	str	"utf8"

Returns:

linted_file.LintedFile — See return type above

lint_path

lint_path(
    self,
    path,
    fix=False,
    ignore_non_existent_files=False,
    ignore_files=True,
    processes=None
) → linted_dir.LintedDir

Lint a path.

Parameters:

Parameter	Type	Default	Description
self	—	—
path	str	—
fix	bool	False
ignore_non_existent_files	bool	False
ignore_files	bool	True
processes	`int	None`	None

Returns:

linted_dir.LintedDir — See return type above

lint_paths

lint_paths(
    self,
    paths,
    fix=False,
    ignore_non_existent_files=False,
    ignore_files=True,
    processes=None,
    apply_fixes=False,
    fixed_file_suffix="",
    fix_even_unparsable=False,
    retain_files=True
) → linting_result.LintingResult

Lint an iterable of paths.

Parameters:

Parameter	Type	Default	Description
self	—	—
paths	tuple[str, ...]	—
fix	bool	False
ignore_non_existent_files	bool	False
ignore_files	bool	True
processes	`int	None`	None
apply_fixes	bool	False
fixed_file_suffix	str	""
fix_even_unparsable	bool	False
retain_files	bool	True

Returns:

linting_result.LintingResult — See return type above

lint_rendered

lint_rendered(
    rendered,
    rule_pack,
    fix=False,
    formatter=None
) → linted_file.LintedFile

Take a RenderedFile and return a LintedFile.

Parameters:

Parameter	Type	Default	Description
rendered	common.RenderedFile	—
rule_pack	base.RulePack	—
fix	bool	False
formatter	`FormatterInterface	None`	None

Returns:

linted_file.LintedFile — See return type above

lint_string

lint_string(
    self,
    in_str="",
    fname="<string input>",
    fix=False,
    config=None,
    encoding="utf8"
) → linted_file.LintedFile

Lint a string.

Parameters:

Parameter	Type	Default	Description
self	—	—
in_str	str	""
fname	str	"<string input>"
fix	bool	False
config	`fluffconfig.FluffConfig	None`	None
encoding	str	"utf8"

Returns:

linted_file.LintedFile — LintedFile: an object representing that linted file.

lint_string_wrapped

lint_string_wrapped(
    self,
    string,
    fname="<string input>",
    fix=False,
    stdin_filename=None
) → linting_result.LintingResult

Lint strings directly.

Parameters:

Parameter	Type	Default	Description
self	—	—
string	str	—
fname	str	"<string input>"
fix	bool	False
stdin_filename	`str	None`	None

Returns:

linting_result.LintingResult — See return type above

load_raw_file_and_config

load_raw_file_and_config(
    fname,
    root_config
) → tuple[str, fluffconfig.FluffConfig, str]

Load a raw file and the associated config.

Parameters:

Parameter	Type	Default	Description
fname	str	—
root_config	fluffconfig.FluffConfig	—

Returns:

tuple[str, fluffconfig.FluffConfig, str] — See return type above

parse_path

parse_path(
    self,
    path,
    parse_statistics=False
) → collections.abc.Iterator[common.ParsedString]

Parse a path of sql files.

NB: This a generator which will yield the result of each file within the path iteratively.

Parameters:

Parameter	Type	Default	Description
self	—	—
path	str	—
parse_statistics	bool	False

Returns:

collections.abc.Iterator[common.ParsedString] — See return type above

parse_rendered

parse_rendered(
    rendered,
    parse_statistics=False
) → common.ParsedString

Parse a rendered file.

Parameters:

Parameter	Type	Default	Description
rendered	common.RenderedFile	—
parse_statistics	bool	False

Returns:

common.ParsedString — See return type above

parse_string

parse_string(
    self,
    in_str,
    fname="<string>",
    config=None,
    encoding="utf-8",
    parse_statistics=False
) → common.ParsedString

Parse a string.

Parameters:

Parameter	Type	Default	Description
self	—	—
in_str	str	—
fname	str	"<string>"
config	`fluffconfig.FluffConfig	None`	None
encoding	str	"utf-8"
parse_statistics	bool	False

Returns:

common.ParsedString — See return type above

remove_templated_errors

remove_templated_errors(
    linting_errors
) → list[SQLBaseError]

Filter a list of lint errors, removing those from the templated slices.

Parameters:

Parameter	Type	Default	Description
linting_errors	list[SQLBaseError]	—

Returns:

list[SQLBaseError] — See return type above

render_file

render_file(
    self,
    fname,
    root_config
) → common.RenderedFile

Load and render a file with relevant config.

Parameters:

Parameter	Type	Default	Description
self	—	—
fname	str	—
root_config	fluffconfig.FluffConfig	—

Returns:

common.RenderedFile — See return type above

render_string

render_string(
    self,
    in_str,
    fname,
    config,
    encoding
) → common.RenderedFile

Template the file.

Parameters:

Parameter	Type	Default	Description
self	—	—
in_str	str	—
fname	str	—
config	fluffconfig.FluffConfig	—
encoding	str	—

Returns:

common.RenderedFile — See return type above

rule_tuples

rule_tuples(
    self
) → list[common.RuleTuple]

A simple pass through to access the rule tuples of the rule set.

Parameters:

Parameter	Type	Default	Description
self	—	—

Returns:

list[common.RuleTuple] — See return type above

PyLexer

The Lexer class actually does the lexing step.

Parameters:

Parameter	Type	Default	Description
config	`fluffconfig.FluffConfig	None`	None
last_resort_lexer	`lexer.StringLexer	None`	None
dialect	`str	None`	None

Methods

elements_to_segments

elements_to_segments(
    self,
    elements,
    templated_file
) → tuple[segments.raw.RawSegment, ...]

Convert a tuple of lexed elements into a tuple of segments.

Parameters:

Parameter	Type	Default	Description
self	—	—
elements	list[lexer.TemplateElement]	—
templated_file	base.TemplatedFile	—

Returns:

tuple[segments.raw.RawSegment, ...] — See return type above

lex

lex(
    self,
    raw
) → tuple[tuple[segments.base.BaseSegment, ...], list[SQLLexError]]

Take a string or TemplatedFile and return segments.

If we fail to match the whole string, then we must have found something that we cannot lex. If that happens we should package it up as unlexable and keep track of the exceptions.

Parameters:

Parameter	Type	Default	Description
self	—	—
raw	`str	base.TemplatedFile`	—

Returns:

tuple[tuple[segments.base.BaseSegment, ...], list[SQLLexError]] — See return type above

lex_match

lex_match(
    forward_string,
    lexer_matchers
) → lexer.LexMatch

Iteratively match strings using the selection of submatchers.

Parameters:

Parameter	Type	Default	Description
forward_string	str	—
lexer_matchers	list[lexer.StringLexer]	—

Returns:

lexer.LexMatch — See return type above

map_template_slices

map_template_slices(
    elements,
    template
) → list[lexer.TemplateElement]

Create a tuple of TemplateElement from a tuple of LexedElement.

This adds slices in the templated file to the original lexed elements. We'll need this to work out the position in the source file.

Parameters:

Parameter	Type	Default	Description
elements	list[lexer.LexedElement]	—
template	base.TemplatedFile	—

Returns:

list[lexer.TemplateElement] — See return type above

violations_from_segments

violations_from_segments(
    segments
) → list[SQLLexError]

Generate any lexing errors for any unlexables.

Parameters:

Parameter	Type	Default	Description
segments	tuple[segments.raw.RawSegment, ...]	—

Returns:

list[SQLLexError] — See return type above

Parser

Instantiates parsed queries from a sequence of lexed raw segments.

Parameters:

Parameter	Type	Default	Description
config	`fluffconfig.FluffConfig	None`	None
dialect	`str	None`	None

Methods

parse

parse(
    self,
    segments,
    fname=None,
    parse_statistics=False
) → ForwardRef('BaseSegment') | None

Parse a series of lexed tokens using the current dialect.

Parameters:

Parameter	Type	Default	Description
self	—	—
segments	collections.abc.Sequence['BaseSegment']	—
fname	`str	None`	None
parse_statistics	bool	False

Returns:

ForwardRef('BaseSegment') | None — See return type above