sqlfluff.utils.reflow
: Whitespace Reflow API¶
Many rules supported by SQLFluff involve the spacing and layout of different elements, either to enforce a particular layout or just to add or remove code elements in a way sensitive to the existing layout configuration. The way this is achieved is through some centralised utilities in the sqlfluff.utils.reflow module.
This module aims to achieve several things:
Less code duplication by implementing reflow logic in only one place.
Provide a streamlined interface for rules to easily utilise reflow logic.
Given this requirement, it’s important that reflow utilities work within the existing framework for applying fixes to potentially templated code. We achieve this by returning LintFix objects which can then be returned by each rule wanting to use this logic.
Provide a consistent way of configuring layout requirements. For more details on configuration see Configuring Layout.
To support this, the module provides a ReflowSequence
class which
allows access to all of the relevant operations which can be used to
reformat sections of code, or even a whole file. Unless there is a very
good reason, all rules should use this same approach to ensure consistent
treatment of layout.
- class ReflowSequence(elements: List[ReflowBlock | ReflowPoint], root_segment: BaseSegment, reflow_config: ReflowConfig, depth_map: DepthMap, lint_results: List[LintResult] | None = None)¶
Class for keeping track of elements in a reflow operation.
This acts as the primary route into using the reflow routines. It acts in a way that plays nicely within a rule context in that it accepts segments and configuration, while allowing access to modified segments and a series of
LintFix
objects, which can be returned by the calling rule.Sequences are made up of alternating
ReflowBlock
andReflowPoint
objects (even if some points have no segments). This is validated on construction.Most operations also return
ReflowSequence
objects such that operations can be chained, and then the resultant fixes accessed at the last stage, for example:fixes = ( ReflowSequence.from_around_target( context.segment, root_segment=context.parent_stack[0], config=context.config, ) .rebreak() .get_fixes() )
- break_long_lines() ReflowSequence ¶
Rebreak any remaining long lines in a sequence.
This assumes that reindent() has already been applied.
- classmethod from_around_target(target_segment: BaseSegment, root_segment: BaseSegment, config: FluffConfig, sides: str = 'both') ReflowSequence ¶
Generate a sequence around a target.
- Parameters:
target_segment (
RawSegment
) – The segment to center around when considering the sequence to construct.root_segment (
BaseSegment
) – The relevant root segment (usually the baseFileSegment
).config (
FluffConfig
) – A config object from which to load the spacing behaviours of different segments.sides (
str
) – Limit the reflow sequence to just one side of the target. Default is two sided (“both”), but set to “before” or “after” to limit to either side.
NOTE: We don’t just expand to the first block around the target but to the first code element, which means we may swallow several comment blocks in the process.
To evaluate reflow around a specific target, we need need to generate a sequence which goes for the preceding raw to the following raw. i.e. at least: block - point - block - point - block (where the central block is the target).
- classmethod from_raw_segments(segments: Sequence[RawSegment], root_segment: BaseSegment, config: FluffConfig, depth_map: DepthMap | None = None) ReflowSequence ¶
Construct a ReflowSequence from a sequence of raw segments.
This is intended as a base constructor, which others can use. In particular, if no depth_map argument is provided, this method will generate one in a potentially inefficient way. If the calling method has access to a better way of inferring a depth map (for example because it has access to a common root segment for all the content), it should do that instead and pass it in.
- classmethod from_root(root_segment: BaseSegment, config: FluffConfig) ReflowSequence ¶
Generate a sequence from a root segment.
- Parameters:
root_segment (
BaseSegment
) – The relevant root segment (usually the baseFileSegment
).config (
FluffConfig
) – A config object from which to load the spacing behaviours of different segments.
- get_fixes() List[LintFix] ¶
Get the current fix buffer.
We’re hydrating them here directly from the LintResult objects, so for more accurate results, consider using .get_results(). This method is particularly useful when consolidating multiple results into one.
- get_raw() str ¶
Get the current raw representation.
- get_results() List[LintResult] ¶
Return the current result buffer.
- insert(insertion: RawSegment, target: RawSegment, pos: str = 'before') ReflowSequence ¶
Returns a new
ReflowSequence
with the new element inserted.Insertion is always relative to an existing element. Either before or after it as specified by pos. This generates appropriate creation
LintFix
objects to direct the linter to insert those elements.
- rebreak(rebreak_type: Literal['lines', 'keywords'] = 'lines') ReflowSequence ¶
Returns a new
ReflowSequence
corrected line breaks.This intentionally does not handle indentation, as the existing indents are assumed to be correct.
Note
Currently this only moves existing segments around line breaks (e.g. for operators and commas), but eventually this method will also handle line length considerations too.
- reindent() ReflowSequence ¶
Reindent lines within a sequence.
- replace(target: BaseSegment, edit: Sequence[BaseSegment]) ReflowSequence ¶
Returns a new
ReflowSequence
with edit elements replaced.This generates appropriate replacement
LintFix
objects to direct the linter to modify those elements.
- respace(strip_newlines: bool = False, filter: str = 'all') ReflowSequence ¶
Returns a new
ReflowSequence
with points respaced.- Parameters:
strip_newlines (
bool
) – Optionally strip newlines before respacing. This is primarily used on focused sequences to coerce objects onto a single line. This does not apply any prioritisation to which line breaks to remove and so is not a substitute for the full reindent or reflow methods.filter (
str
) – Optionally filter which reflow points to respace. Default configuration is all. Other options are line_break which only respaces points containing a newline or followed by an end_of_file marker, or inline which is the inverse of line_break. This is most useful for filtering between trailing whitespace and fixes between content on a line.
NOTE this method relies on the embodied results being correct so that we can build on them.
- without(target: RawSegment) ReflowSequence ¶
Returns a new
ReflowSequence
without the specified segment.This generates appropriate deletion
LintFix
objects to direct the linter to remove those elements.
- class ReflowPoint(segments: Tuple[RawSegment, ...])¶
Class for keeping track of editable elements in reflow.
This class, and its sibling
ReflowBlock
, should not normally be manipulated directly by rules, but instead should be manipulated usingReflowSequence
.It holds segments which can be changed during a reflow operation such as whitespace and newlines.It may also contain
Indent
andDedent
elements.It holds no configuration and is influenced by the blocks on either side, so that any operations on it usually have that configuration passed in as required.
- property class_types: Set[str]¶
Get the set of contained class types.
Parallel to BaseSegment.class_types
- get_indent() str | None ¶
Get the current indent (if there).
- get_indent_impulse() IndentStats ¶
Get the change in intended indent balance from this point.
- get_indent_segment_vals(exclude_block_indents=False) List[int] ¶
Iterate through any indent segments and extract their values.
- indent_to(desired_indent: str, after: BaseSegment | None = None, before: BaseSegment | None = None, description: str | None = None, source: str | None = None) Tuple[List[LintResult], ReflowPoint] ¶
Coerce a point to have a particular indent.
If the point currently contains no newlines, one will be introduced and any trailing whitespace will be effectively removed.
More specifically, the newline is inserted before the existing whitespace, with the new indent being a replacement for that same whitespace.
For placeholder newlines or indents we generate appropriate source fixes.
- is_all_unrendered() bool ¶
Return whether this element is all unrendered.
Returns True if contains only whitespace, indents, template loops or placeholders.
Note: * ReflowBlocks will contain the placeholders and loops * ReflowPoints will contain whitespace, indents and newlines.
- num_newlines() int ¶
Return the number of newlines in this element.
These newlines are either newline segments or contained within consumed sections of whitespace. This counts both.
- property pos_marker: PositionMarker | None¶
Get the first position marker of the element.
- property raw: str¶
Get the current raw representation.
- respace_point(prev_block: ReflowBlock | None, next_block: ReflowBlock | None, root_segment: BaseSegment, lint_results: List[LintResult], strip_newlines: bool = False, anchor_on: str = 'before') Tuple[List[LintResult], ReflowPoint] ¶
Respace a point based on given constraints.
NB: This effectively includes trailing whitespace fixes.
Deletion and edit fixes are generated immediately, but creations are paused to the end and done in bulk so as not to generate conflicts.
Note that the strip_newlines functionality exists here as a slight exception to pure respacing, but as a very simple case of positioning line breaks. The default operation of respace does not enable it, however it exists as a convenience for rules which wish to use it.
- class ReflowBlock(segments: Tuple[RawSegment, ...], spacing_before: str, spacing_after: str, line_position: str | None, depth_info: DepthInfo, stack_spacing_configs: Dict[int, str], line_position_configs: Dict[int, str], keyword_line_position: str | None, keyword_line_position_configs: Dict[int, str])¶
Class for keeping track of elements to reflow.
This class, and its sibling
ReflowPoint
, should not normally be manipulated directly by rules, but instead should be manipulated usingReflowSequence
.It holds segments to reflow and also exposes configuration regarding how they are expected to reflow around others. Typically it holds only a single element, which is usually code or a templated element. Because reflow operations control spacing, it would be very unusual for this object to be modified; as such it exposes relatively few methods.
The attributes exposed are designed to be “post configuration” i.e. they should reflect configuration appropriately.
- property class_types: Set[str]¶
Get the set of contained class types.
Parallel to BaseSegment.class_types
- depth_info: DepthInfo¶
Metadata on the depth of this segment within the parse tree which is used in inferring how and where line breaks should exist.
- classmethod from_config(segments: Tuple[RawSegment, ...], config: ReflowConfig, depth_info: DepthInfo) ReflowBlock ¶
Construct a ReflowBlock while extracting relevant configuration.
This is the primary route to construct a ReflowBlock, as is allows all of the inference of the spacing and position configuration from the segments it contains and the appropriate config objects.
- is_all_unrendered() bool ¶
Return whether this element is all unrendered.
Returns True if contains only whitespace, indents, template loops or placeholders.
Note: * ReflowBlocks will contain the placeholders and loops * ReflowPoints will contain whitespace, indents and newlines.
- keyword_line_position: str | None¶
Desired line position for this block’s keywords. See Configuring layout and spacing
- keyword_line_position_configs: Dict[int, str]¶
Desired keyword line position configurations for parent segments of the segment in this block. See Configuring layout and spacing
- line_position: str | None¶
Desired line position for this block. See Configuring layout and spacing
- line_position_configs: Dict[int, str]¶
Desired line position configurations for parent segments of the segment in this block. See Configuring layout and spacing
- num_newlines() int ¶
Return the number of newlines in this element.
These newlines are either newline segments or contained within consumed sections of whitespace. This counts both.
- property pos_marker: PositionMarker | None¶
Get the first position marker of the element.
- property raw: str¶
Get the current raw representation.
- spacing_after: str¶
Desired spacing after this block. See Configuring layout and spacing
- spacing_before: str¶
Desired spacing before this block. See Configuring layout and spacing
- stack_spacing_configs: Dict[int, str]¶
Desired spacing configurations for parent segments of the segment in this block. See Configuring layout and spacing