# `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` and `ReflowPoint` 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 base `FileSegment`).

      - 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 base `FileSegment`).

      - 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.

    Note

    This method is currently excluded from test coverage because it is not actively used by any rule. It was previously utilized by rule AL01, but that rule now uses an alternative implementation. The method is retained for potential future reuse or reference.

  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.

    Note

    This method is currently excluded from test coverage because it is not actively used by any rule. It was previously utilized by rule AL01, but that rule now uses an alternative implementation. The method is retained for potential future reuse or reference.

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 using `ReflowSequence`.

  It holds segments which can be changed during a reflow operation such as whitespace and newlines.It may also contain `Indent` and `Dedent` 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], keyword_line_position_exclusions: str | list[str] | None, keyword_line_position_exclusions_configs: dict[int, str | list[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 using `ReflowSequence`.

  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

  keyword_line_position_exclusions: str | list[str] | None

    Parent segments which this block’s keyword line positioning should not apply. See Configuring layout and spacing

  keyword_line_position_exclusions_configs: dict[int, str | list[str]]

    Configurations for parent segments which this block’s keyword line positioning should not apply. 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