Rules Base API

This section is for contributors writing new built-in rules or plugin rules.

SQLFluff rules are Python classes that subclass BaseRule. The linter crawls the parse tree and calls each rule's _eval() method, which returns zero or more LintResult objects. Each LintResult may carry LintFix objects describing how to auto-correct the violation.

The crawler passed to BaseRule.crawl_behaviour controls which segments _eval() is called on — see SegmentSeekerCrawler and RootOnlyCrawler.

Source: sqlfluff/core/rules/

BaseRule

The base class for a rule.

Parameters:

Parameter	Type	Default	Description
code	str		The identifier for this rule, used in inclusion or exclusion.
description	str		A human readable description of what this rule does. It will be displayed when any violations are found.
kwargs	Any

Methods

crawl

crawl(
    tree,
    dialect,
    fix,
    templated_file,
    ignore_mask,
    fname,
    config
)

Run the rule on a given tree.

Parameters:

Parameter	Type	Default	Description
tree	BaseSegment
dialect	Dialect
fix	bool
templated_file	ForwardRef('TemplatedFile') | None
ignore_mask	ForwardRef('IgnoreMask') | None
fname	str | None
config	FluffConfig

Returns:

A tuple of (vs, raw_stack, fixes, memory)

discard_unsafe_fixes

discard_unsafe_fixes(
    lint_result,
    templated_file
) → None

Remove (discard) LintResult fixes if they are "unsafe".

By removing its fixes, a LintResult will still be reported, but it will be treated as unfixable.

Parameters:

Parameter	Type	Default	Description
lint_result	LintResult
templated_file	TemplatedFile | None

Returns:

None — See return type.

filter_meta

filter_meta(
    segments,
    keep_meta=False
) → tuple[BaseSegment, ...]

Filter the segments to non-meta.

Or optionally the opposite if keep_meta is True.

Parameters:

Parameter	Type	Default	Description
segments	collections.abc.Sequence[BaseSegment]
keep_meta	bool	False

Returns:

tuple[BaseSegment, ...] — See return type.

get_config_ref

get_config_ref() → str

Return the config lookup ref for this rule.

If a name is defined, it's the name - otherwise the code.

The name is a much more understandable reference and so makes config files more readable. For backward compatibility however we also support the rule code for those without names.

Returns:

str — See return type.

get_parent_of

get_parent_of(
    segment,
    root_segment
) → BaseSegment | None

Return the segment immediately containing segment.

NB: This is recursive.

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment		The segment to look for.
root_segment	BaseSegment		Some known parent of the segment we're looking for (although likely not the direct parent in question).

Returns:

BaseSegment | None — See return type.

split_comma_separated_string

split_comma_separated_string(
    raw
) → list[str]

Converts comma separated string to List, stripping whitespace.

Parameters:

Parameter	Type	Default	Description
raw	str | list[str]

Returns:

list[str] — See return type.

LintResult

A class to hold the results of a rule evaluation.

Parameters:

Parameter	Type	Default	Description
anchor	BaseSegment | None	None	A segment which represents the position of the problem. NB: Each fix will also hold its own reference to position, so this position is mostly for alerting the user to where the problem is.
fixes	list[LintFix] | None	None	An array of any fixes which would correct this issue. If not present then it's assumed that this issue will have to manually fixed.
memory	Any | None	None	An object which stores any working memory for the rule. The memory returned in any LintResult will be passed as an input to the next segment to be crawled.
description	str | None	None	A description of the problem identified as part of this result. This will override the description of the rule as what gets reported to the user with the problem if provided.
source	str | None	None	A string identifier for what generated the result. Within larger libraries like reflow this can be useful for tracking where a result came from.

Methods

to_linting_error

to_linting_error(
    rule
) → SQLLintError | None

Convert a linting result to a :exc:SQLLintError if appropriate.

Parameters:

Parameter	Type	Default	Description
rule	BaseRule

Returns:

SQLLintError | None — See return type.

LintFix

A class to hold a potential fix to a linting violation.

Parameters:

Parameter	Type	Default	Description
edit_type	str		One of create_before, create_after, replace, delete to indicate the kind of fix this represents.
anchor	BaseSegment		A segment which represents the position that this fix should be applied at. For deletions it represents the segment to delete, for creations it implies the position to create at (with the existing element at this position to be moved after the edit), for a replace it implies the segment to be replaced.
edit	collections.abc.Iterable[BaseSegment] | None	None	For replace and create fixes, this holds the iterable of segments to create or replace at the given anchor point.
source	collections.abc.Iterable[BaseSegment] | None	None	For replace and create fixes, this holds iterable of segments that provided code. IMPORTANT: The linter uses this to prevent copying material from templated areas.

Methods

create_after

create_after(
    anchor_segment,
    edit_segments,
    source=None
) → LintFix

Create edit segments after the supplied anchor segment.

Parameters:

Parameter	Type	Default	Description
anchor_segment	BaseSegment
edit_segments	collections.abc.Iterable[BaseSegment]
source	collections.abc.Iterable[BaseSegment] | None	None

Returns:

LintFix — See return type.

create_before

create_before(
    anchor_segment,
    edit_segments,
    source=None
) → LintFix

Create edit segments before the supplied anchor segment.

Parameters:

Parameter	Type	Default	Description
anchor_segment	BaseSegment
edit_segments	collections.abc.Iterable[BaseSegment]
source	collections.abc.Iterable[BaseSegment] | None	None

Returns:

LintFix — See return type.

delete

delete(
    anchor_segment
) → LintFix

Delete supplied anchor segment.

Parameters:

Parameter	Type	Default	Description
anchor_segment	BaseSegment

Returns:

LintFix — See return type.

get_fix_slices

get_fix_slices(
    templated_file,
    within_only
) → set[RawFileSlice]

Returns slices touched by the fix.

Parameters:

Parameter	Type	Default	Description
templated_file	TemplatedFile
within_only	bool

Returns:

set[RawFileSlice] — See return type.

has_template_conflicts

has_template_conflicts(
    templated_file
) → bool

Based on the fix slices, should we discard the fix?

Parameters:

Parameter	Type	Default	Description
templated_file	TemplatedFile

Returns:

bool — See return type.

is_just_source_edit

is_just_source_edit(
    single_source_fix=False
) → bool

Return whether this a valid source only edit.

Parameters:

Parameter	Type	Default	Description
single_source_fix	bool	False	Check for a single source_fixes.

Returns:

bool — See return type.

replace

replace(
    anchor_segment,
    edit_segments,
    source=None
) → LintFix

Replace supplied anchor segment with the edit segments.

Parameters:

Parameter	Type	Default	Description
anchor_segment	BaseSegment
edit_segments	collections.abc.Iterable[BaseSegment]
source	collections.abc.Iterable[BaseSegment] | None	None

Returns:

LintFix — See return type.

to_dict

to_dict() → dict[str, Any]

Serialise this LintFix as a dict.

Returns:

dict[str, Any] — See return type.

RuleContext

Class for holding the context passed to rule eval functions.

Parameters:

Parameter	Type	Default	Description
dialect	Dialect
fix	bool
templated_file	TemplatedFile | None
path	pathlib.Path | None
config	FluffConfig
segment	BaseSegment
parent_stack	tuple[BaseSegment, ...]	()
raw_stack	tuple[RawSegment, ...]	()
memory	Any	<factory>
segment_idx	int	0

BaseCrawler

The base interface for crawler classes.

Parameters:

Parameter	Type	Default	Description
works_on_unparsable	bool	False
kwargs	Any

Methods

crawl

crawl(
    context
) → collections.abc.Iterator[RuleContext]

Yields a RuleContext for each segment the rule should process.

Parameters:

Parameter	Type	Default	Description
context	RuleContext

Returns:

collections.abc.Iterator[RuleContext] — See return type.

passes_filter

passes_filter(
    segment
) → bool

Returns true if this segment considered at all.

This method is called during crawling but also in evaluating the anchors for linting violations and their fixes to make sure we don't get issues with linting sections of queries that we can't parse.

See BaseRule._process_lint_result().

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment

Returns:

bool — See return type.

SegmentSeekerCrawler

A crawler that efficiently searches for specific segment types.

The segment type(s) are specified on creation.

Parameters:

Parameter	Type	Default	Description
types	set[str]
provide_raw_stack	bool	False
allow_recurse	bool	True
kwargs	Any

Methods

crawl

crawl(
    context
) → collections.abc.Iterator[RuleContext]

Yields a RuleContext for each segment the rule should process.

We assume that segments are yielded by their parent.

Parameters:

Parameter	Type	Default	Description
context	RuleContext

Returns:

collections.abc.Iterator[RuleContext] — See return type.

is_self_match

is_self_match(
    segment
) → bool

Does this segment match the relevant criteria.

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment

Returns:

bool — See return type.

passes_filter

passes_filter(
    segment
) → bool

Returns true if this segment considered at all.

This method is called during crawling but also in evaluating the anchors for linting violations and their fixes to make sure we don't get issues with linting sections of queries that we can't parse.

See BaseRule._process_lint_result().

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment

Returns:

bool — See return type.

RootOnlyCrawler

A crawler that doesn't crawl.

This just yields one context on the root-level (topmost) segment of the file.

Parameters:

Parameter	Type	Default	Description
works_on_unparsable	bool	False
kwargs	Any

Methods

crawl

crawl(
    context
) → collections.abc.Iterator[RuleContext]

Yields a RuleContext for each segment the rule should process.

Parameters:

Parameter	Type	Default	Description
context	RuleContext

Returns:

collections.abc.Iterator[RuleContext] — See return type.

passes_filter

passes_filter(
    segment
) → bool

Returns true if this segment considered at all.

This method is called during crawling but also in evaluating the anchors for linting violations and their fixes to make sure we don't get issues with linting sections of queries that we can't parse.

See BaseRule._process_lint_result().

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment

Returns:

bool — See return type.