TextDocument

Document model for reading and manipulating text documents.

Position

Position dataclass

Position(line: int, character: int)

Represents a line and character position in a document.

is_before

is_before(other: Position) -> bool

Check if this position is before another position.

Source code in vscode_sockpuppet/document.py

def is_before(self, other: "Position") -> bool:
    """Check if this position is before another position."""
    if self.line < other.line:
        return True
    if self.line == other.line and self.character < other.character:
        return True
    return False

is_before_or_equal

is_before_or_equal(other: Position) -> bool

Check if this position is before or equal to another.

Source code in vscode_sockpuppet/document.py

def is_before_or_equal(self, other: "Position") -> bool:
    """Check if this position is before or equal to another."""
    return self.is_before(other) or self.is_equal(other)

is_after

is_after(other: Position) -> bool

Check if this position is after another position.

Source code in vscode_sockpuppet/document.py

def is_after(self, other: "Position") -> bool:
    """Check if this position is after another position."""
    return not self.is_before_or_equal(other)

is_after_or_equal

is_after_or_equal(other: Position) -> bool

Check if this position is after or equal to another.

Source code in vscode_sockpuppet/document.py

def is_after_or_equal(self, other: "Position") -> bool:
    """Check if this position is after or equal to another."""
    return not self.is_before(other)

is_equal

is_equal(other: Position) -> bool

Check if this position is equal to another position.

Source code in vscode_sockpuppet/document.py

def is_equal(self, other: "Position") -> bool:
    """Check if this position is equal to another position."""
    return self.line == other.line and self.character == other.character

compare_to

compare_to(other: Position) -> int

Compare this position to another.

Returns:

Type	Description
int	Negative if this < other, 0 if equal, positive if this > other

Source code in vscode_sockpuppet/document.py

def compare_to(self, other: "Position") -> int:
    """
    Compare this position to another.

    Returns:
        Negative if this < other, 0 if equal, positive if this > other
    """
    if self.line < other.line:
        return -1
    if self.line > other.line:
        return 1
    return self.character - other.character

translate

translate(line_delta: int = 0, character_delta: int = 0) -> Position

Create a new position relative to this position.

Parameters:

Name	Type	Description	Default
line_delta	int	Delta for line value (default 0)	0
character_delta	int	Delta for character value (default 0)	0

Returns:

Type	Description
Position	New Position object

Source code in vscode_sockpuppet/document.py

def translate(self, line_delta: int = 0, character_delta: int = 0) -> "Position":
    """
    Create a new position relative to this position.

    Args:
        line_delta: Delta for line value (default 0)
        character_delta: Delta for character value (default 0)

    Returns:
        New Position object
    """
    return Position(
        line=self.line + line_delta,
        character=self.character + character_delta,
    )

with_line

with_line(line: int) -> Position

Create a new position with a different line number.

Source code in vscode_sockpuppet/document.py

def with_line(self, line: int) -> "Position":
    """Create a new position with a different line number."""
    return Position(line=line, character=self.character)

with_character

with_character(character: int) -> Position

Create a new position with a different character.

Source code in vscode_sockpuppet/document.py

def with_character(self, character: int) -> "Position":
    """Create a new position with a different character."""
    return Position(line=self.line, character=character)

Range

Range dataclass

Range(start: Position, end: Position)

Represents a range in a document with start and end positions.

is_empty property

is_empty: bool

Check if this range is empty (start == end).

is_single_line property

is_single_line: bool

Check if this range is on a single line.

contains

contains(position_or_range: Position | Range) -> bool

Check if a position or range is contained in this range.

Parameters:

Name	Type	Description	Default
position_or_range	Position | Range	Position or Range to check	required

Returns:

Type	Description
bool	True if contained within this range

Source code in vscode_sockpuppet/document.py

def contains(self, position_or_range: "Position | Range") -> bool:
    """
    Check if a position or range is contained in this range.

    Args:
        position_or_range: Position or Range to check

    Returns:
        True if contained within this range
    """
    if isinstance(position_or_range, Position):
        pos = position_or_range
        return self.start.is_before_or_equal(pos) and self.end.is_after_or_equal(pos)
    else:
        other_range = position_or_range
        return self.start.is_before_or_equal(other_range.start) and self.end.is_after_or_equal(
            other_range.end
        )

is_equal

is_equal(other: Range) -> bool

Check if this range is equal to another range.

Source code in vscode_sockpuppet/document.py

def is_equal(self, other: "Range") -> bool:
    """Check if this range is equal to another range."""
    return self.start.is_equal(other.start) and self.end.is_equal(other.end)

intersection

intersection(other: Range) -> Optional[Range]

Compute the intersection of two ranges.

Parameters:

Name	Type	Description	Default
other	Range	Another range	required

Returns:

Type	Description
Optional[Range]	The intersection range, or None if no intersection

Source code in vscode_sockpuppet/document.py

def intersection(self, other: "Range") -> Optional["Range"]:
    """
    Compute the intersection of two ranges.

    Args:
        other: Another range

    Returns:
        The intersection range, or None if no intersection
    """
    # Find the later start and earlier end
    start = self.start if self.start.is_after(other.start) else other.start
    end = self.end if self.end.is_before(other.end) else other.end

    # Check if valid intersection
    if start.is_after(end):
        return None
    return Range(start=start, end=end)

union

union(other: Range) -> Range

Compute the union of two ranges.

Parameters:

Name	Type	Description	Default
other	Range	Another range	required

Returns:

Type	Description
Range	Range spanning both ranges

Source code in vscode_sockpuppet/document.py

def union(self, other: "Range") -> "Range":
    """
    Compute the union of two ranges.

    Args:
        other: Another range

    Returns:
        Range spanning both ranges
    """
    start = self.start if self.start.is_before(other.start) else other.start
    end = self.end if self.end.is_after(other.end) else other.end
    return Range(start=start, end=end)

with_start

with_start(start: Position) -> Range

Create a new range with a different start position.

Source code in vscode_sockpuppet/document.py

def with_start(self, start: Position) -> "Range":
    """Create a new range with a different start position."""
    return Range(start=start, end=self.end)

with_end

with_end(end: Position) -> Range

Create a new range with a different end position.

Source code in vscode_sockpuppet/document.py

def with_end(self, end: Position) -> "Range":
    """Create a new range with a different end position."""
    return Range(start=self.start, end=end)

TextLine

TextLine

TextLine(line_number: int, text: str, is_empty_or_whitespace: bool, first_non_whitespace_char_index: int, range_obj: Range, range_including_line_break: Range)

Represents a line of text in a document.

Source code in vscode_sockpuppet/document.py

def __init__(
    self,
    line_number: int,
    text: str,
    is_empty_or_whitespace: bool,
    first_non_whitespace_char_index: int,
    range_obj: Range,
    range_including_line_break: Range,
):
    self.line_number = line_number
    self.text = text
    self.is_empty_or_whitespace = is_empty_or_whitespace
    self.first_non_whitespace_character_index = first_non_whitespace_char_index
    self.range = range_obj
    self.range_including_line_break = range_including_line_break

TextDocument

TextDocument

TextDocument(client: VSCodeClient, data: dict)

Represents a text document in VS Code. Mirrors the VS Code TextDocument API.

Source code in vscode_sockpuppet/document.py

def __init__(self, client: "VSCodeClient", data: dict):
    self._client = client
    self._uri = data["uri"]
    self._file_name = data["fileName"]
    self._is_untitled = data["isUntitled"]
    self._language_id = data["languageId"]
    self._version = data["version"]
    self._is_dirty = data["isDirty"]
    self._is_closed = data["isClosed"]
    self._eol = data["eol"]
    self._line_count = data["lineCount"]
    self._encoding = data["encoding"]

uri property

uri: str

The URI of this document.

file_name property

file_name: str

The file system path of this document.

is_untitled property

is_untitled: bool

True if the document is not saved.

language_id property

language_id: str

The language identifier (e.g., 'python', 'typescript').

version property

version: int

The version number (incremented on each change).

is_dirty property

is_dirty: bool

True if there are unsaved changes.

is_closed property

is_closed: bool

True if the document has been closed.

eol property

eol: str

End-of-line sequence ('\n' or '\r\n').

line_count property

line_count: int

The number of lines in this document.

encoding property

encoding: str

The file encoding that will be used when the document is saved.

Common values include: 'utf8', 'utf8bom', 'utf16le', 'utf16be', 'windows1252', 'iso88591', etc.

save

save() -> bool

Save the document.

Returns:

Type	Description
bool	True if saved successfully

Source code in vscode_sockpuppet/document.py

def save(self) -> bool:
    """
    Save the document.

    Returns:
        True if saved successfully
    """
    result = self._client._send_request("document.save", {"uri": self._uri})
    if result.get("success"):
        self._is_dirty = False
        self._version = result.get("version", self._version)
    return result.get("success", False)

line_at

line_at(line_or_position: int | Position) -> TextLine

Get a text line by line number or position.

Parameters:

Name	Type	Description	Default
line_or_position	int | Position	Line number (0-based) or Position	required

Returns:

Type	Description
TextLine	TextLine object

Source code in vscode_sockpuppet/document.py

def line_at(self, line_or_position: int | Position) -> TextLine:
    """
    Get a text line by line number or position.

    Args:
        line_or_position: Line number (0-based) or Position

    Returns:
        TextLine object
    """
    if isinstance(line_or_position, Position):
        line_num = line_or_position.line
    else:
        line_num = line_or_position

    result = self._client._send_request(
        "document.lineAt", {"uri": self._uri, "line": line_num}
    )
    return TextLine.from_dict(result)

offset_at

offset_at(position: Position) -> int

Get the document offset for a position.

Parameters:

Name	Type	Description	Default
position	Position	The position	required

Returns:

Type	Description
int	The character offset

Source code in vscode_sockpuppet/document.py

def offset_at(self, position: Position) -> int:
    """
    Get the document offset for a position.

    Args:
        position: The position

    Returns:
        The character offset
    """
    return self._client._send_request(
        "document.offsetAt",
        {"uri": self._uri, "position": position.to_dict()},
    )

position_at

position_at(offset: int) -> Position

Get the position for a document offset.

Parameters:

Name	Type	Description	Default
offset	int	The character offset	required

Returns:

Type	Description
Position	Position object

Source code in vscode_sockpuppet/document.py

def position_at(self, offset: int) -> Position:
    """
    Get the position for a document offset.

    Args:
        offset: The character offset

    Returns:
        Position object
    """
    result = self._client._send_request(
        "document.positionAt", {"uri": self._uri, "offset": offset}
    )
    return Position.from_dict(result)

get_text

get_text(range: Optional[Range] = None) -> str

Get text from the document.

Parameters:

Name	Type	Description	Default
range	Optional[Range]	Optional range to get text from (entire document if None)	None

Returns:

Type	Description
str	The text content

Source code in vscode_sockpuppet/document.py

def get_text(self, range: Optional[Range] = None) -> str:
    """
    Get text from the document.

    Args:
        range: Optional range to get text from (entire document if None)

    Returns:
        The text content
    """
    params = {"uri": self._uri}
    if range:
        params["range"] = range.to_dict()

    return self._client._send_request("document.getText", params)

get_word_range_at_position

get_word_range_at_position(position: Position, regex: Optional[str] = None) -> Optional[Range]

Get the word range at a position.

Parameters:

Name	Type	Description	Default
position	Position	The position	required
regex	Optional[str]	Optional regex pattern for word boundaries	None

Returns:

Type	Description
Optional[Range]	Range of the word, or None if no word at position

Source code in vscode_sockpuppet/document.py

def get_word_range_at_position(
    self, position: Position, regex: Optional[str] = None
) -> Optional[Range]:
    """
    Get the word range at a position.

    Args:
        position: The position
        regex: Optional regex pattern for word boundaries

    Returns:
        Range of the word, or None if no word at position
    """
    params = {"uri": self._uri, "position": position.to_dict()}
    if regex:
        params["regex"] = regex

    result = self._client._send_request("document.getWordRangeAtPosition", params)
    return Range.from_dict(result) if result else None

validate_range

validate_range(range: Range) -> Range

Ensure a range is valid for this document.

Parameters:

Name	Type	Description	Default
range	Range	The range to validate	required

Returns:

Type	Description
Range	Validated range

Source code in vscode_sockpuppet/document.py

def validate_range(self, range: Range) -> Range:
    """
    Ensure a range is valid for this document.

    Args:
        range: The range to validate

    Returns:
        Validated range
    """
    result = self._client._send_request(
        "document.validateRange",
        {"uri": self._uri, "range": range.to_dict()},
    )
    return Range.from_dict(result)

validate_position

validate_position(position: Position) -> Position

Ensure a position is valid for this document.

Parameters:

Name	Type	Description	Default
position	Position	The position to validate	required

Returns:

Type	Description
Position	Validated position

Source code in vscode_sockpuppet/document.py

def validate_position(self, position: Position) -> Position:
    """
    Ensure a position is valid for this document.

    Args:
        position: The position to validate

    Returns:
        Validated position
    """
    result = self._client._send_request(
        "document.validatePosition",
        {"uri": self._uri, "position": position.to_dict()},
    )
    return Position.from_dict(result)