debian._deb822_repro.locatable module

class debian._deb822_repro.locatable.Locatable

Bases: object

property parent_element: Deb822Element | None

position_in_file() → Position

The start position of this token/element in this file

This is an expensive operation and in many cases have to traverse the entire file structure to answer the query. Consider whether you can maintain the parent’s position and then use position_in_parent() combined with child_position.relative_to(parent_position)

position_in_parent() → Position

The start position of this token/element inside its parent

This is operation is generally linear to the number of “parts” (elements/tokens) inside the parent.

range_in_parent() → Range

The range of this token/element inside its parent

This is operation is generally linear to the number of “parts” (elements/tokens) inside the parent.

size() → Range

Describe the objects size as a continuous range

class debian._deb822_repro.locatable.Position(line_position: int, cursor_position: int)

Bases: object

Describes a “cursor” position inside a file

It consists of a line position (0-based line number) and a cursor position. This is modelled after the “Position” in Language Server Protocol (LSP).

cursor_position: int

Describes a cursor position (“between two characters”) or a character offset.

When this value is 0, the position is at the start of a line. When it is 1, then the position is between the first and the second character (etc.).

property line_number: int

The line number as human would count it

line_position: int

Describes the line position as a 0-based line number

See line_number if you want a human-readable line number

relative_to(new_base: Position) → Position

Offsets the position relative to another position

This is useful to avoid the position_in_file() method by caching where the parents position and then for its children you use range_in_parent() plus relative_to() to rebase the range.

>>> parent: Locatable = ...                   
>>> children: Iterable[Locatable] = ...       
>>> # This will expensive
>>> parent_pos = parent.position_in_file()     
>>> for child in children:                    
...    child_pos = child.position_in_parent()
...    # Avoid a position_in_file() for each child
...    child_pos_in_file = child_pos.relative_to(parent_pos)
...    ...  # Use the child_pos_in_file for something

Parameters:

new_base – The position that should have been the origin rather than (0, 0).

Returns:

The range offset relative to the base position.

class debian._deb822_repro.locatable.Range(start_pos: Position, end_pos: Position)

Bases: object

Describes a range inside a file

This can be useful to describe things like “from line 4, cursor position 2 to line 7 to cursor position 10”. When describing a full line including the newline, use line N, cursor position 0 to line N+1. cursor position 0.

It is also used to denote the size of objects (in that case, the start position is set to START_POSITION as a convention if the precise location is not specified).

This is modelled after the “Range” in Language Server Protocol (LSP).

as_size() → Range

Reduces the range to a “size”

The returned range will always have its start position to (0, 0) and its end position shifted accordingly if it was not already based at (0, 0).

The original range is not mutated and, if it is already at (0, 0), the method will just return it as-is.

classmethod between(a: Position, b: Position) → Self

Computes the range between two positions

Unlike the constructor, this will always create a “positive” range. That is, the “earliest” position will always be the start position regardless of the order they were passed to between. When using the Range constructor, you have freedom to do “inverse” ranges in case that is ever useful

property end_cursor_position: int

Describes the end cursor position

When this value is 0, the position is at the start of a line. When it is 1, then the position is between the first and the second character (etc.).

property end_line_number: int

The end line number as human would count it

property end_line_position: int

Describes the end line position as a 0-based line number

See end_line_number if you want a human-readable line number

end_pos: Position

classmethod from_position_and_size(base: Position, size: Range) → Self

Compute a range from a position and the size of another range

This provides you with a range starting at the base position that has the same effective span as the size parameter.

Parameters:

• base – The desired starting position

• size – A range, which will be used as a size (that is, it will be reduced to a size via the as_size() method) for the resulting range

Returns:

A range at the provided base position that has the size of the provided range.

classmethod from_position_and_sizes(base: Position, sizes: Iterable[Range]) → Self

Compute a range from a position and the size of number of ranges

Parameters:

• base – The desired starting position

• sizes – All the ranges that combined makes up the size of the desired position. Note that order can affect the end result. Particularly the end character offset gets reset every time a size spans a line.

Returns:

A range at the provided base position that has the size of the provided range.

property line_count: int

The number of lines (newlines) spanned by this range.

Will be zero when the range fits inside one line.

relative_to(new_base: Position) → Range

Offsets the range relative to another position

This is useful to avoid the position_in_file() method by caching where the parents position and then for its children you use range_in_parent() plus relative_to() to rebase the range.

>>> parent: Locatable = ...                   
>>> children: Iterable[Locatable] = ...       
>>> # This will expensive
>>> parent_pos = parent.position_in_file()     
>>> for child in children:                    
...    child_range = child.range_in_parent()
...    # Avoid a position_in_file() for each child
...    child_range_in_file = child_range.relative_to(parent_pos)
...    ...  # Use the child_range_in_file for something

Parameters:

new_base – The position that should have been the origin rather than (0, 0).

Returns:

The range offset relative to the base position.

property start_cursor_position: int

Describes the starting cursor position

When this value is 0, the position is at the start of a line. When it is 1, then the position is between the first and the second character (etc.).

property start_line_number: int

The start line number as human would count it

property start_line_position: int

Describes the start line position as a 0-based line number

See start_line_number if you want a human-readable line number

start_pos: Position