SyncTeX API Reference¶

def parse_synctex(
    synctex_path: str,
    *,
    strip_prefix: str = "",
) -> SyncTeXData:
    """Parse a SyncTeX file (.synctex or .synctex.gz).

    Args:
        synctex_path: Path to the SyncTeX file.
        strip_prefix: Prefix to strip from input file paths.
            For Docker builds this is typically ``"/workspace/"``.

    Returns:
        Parsed SyncTeX data for use with :func:`inverse_search`.

    Raises:
        FileNotFoundError: If the file does not exist.
        ValueError: If the file cannot be parsed.
    """
    content = _read_synctex(synctex_path)
    return _parse_content(content, strip_prefix=strip_prefix)

def inverse_search(
    data: SyncTeXData,
    page: int,
    x: float,
    y: float,
) -> dict[str, str | int] | None:
    """Find the source location for a point on a PDF page.

    Args:
        data: Parsed SyncTeX data from :func:`parse_synctex`.
        page: 1-based page number.
        x: Horizontal position in PDF points (72 DPI), from the left edge.
        y: Vertical position in PDF points (72 DPI), from the top edge.

    Returns:
        A dict ``{"file": "...", "line": N}`` on success, or ``None``
        if no matching source location is found.
    """
    boxes = data.pages.get(page)
    if not boxes:
        return None

    # Convert PDF points to scaled points
    scale = data.unit * data.magnification / 1000.0
    if scale == 0:
        scale = 1.0
    target_x = int(x * _BP_TO_SP / scale) + data.x_offset
    target_y = int(y * _BP_TO_SP / scale) + data.y_offset

    best = _find_closest_hbox(boxes, target_x, target_y)
    if best is None:
        return None

    file_path = data.inputs.get(best.tag)
    if file_path is None:
        return None

    return {"file": file_path, "line": best.line}

def forward_search(
    data: SyncTeXData,
    file: str,
    line: int,
) -> dict[str, int | float] | None:
    """Find the PDF position for a source file and line number.

    Args:
        data: Parsed SyncTeX data from :func:`parse_synctex`.
        file: Source file path (relative, as stored in ``data.inputs``).
        line: 1-based line number in the source file.

    Returns:
        A dict ``{"page": N, "x": float, "y": float}`` with coordinates
        in PDF points (72 DPI) on success, or ``None`` if no matching
        position is found.
    """
    # Reverse-lookup: find all tags that map to this file
    tags = {tag for tag, path in data.inputs.items() if path == file}
    if not tags:
        return None

    scale = data.unit * data.magnification / 1000.0
    if scale == 0:
        scale = 1.0

    # Search all pages for matching hboxes
    best_box: HBox | None = None
    best_page: int = 0
    best_line_dist: int = -1

    for page_num, boxes in data.pages.items():
        for box in boxes:
            if box.tag not in tags:
                continue
            dist = abs(box.line - line)
            if best_box is None or dist < best_line_dist:
                best_box = box
                best_page = page_num
                best_line_dist = dist
                if dist == 0:
                    break  # exact match on this page
        if best_line_dist == 0:
            break  # exact match found

    if best_box is None:
        return None

    # Convert scaled points back to PDF points
    pdf_x = (best_box.x - data.x_offset) * scale / _BP_TO_SP
    pdf_y = (best_box.y - data.y_offset) * scale / _BP_TO_SP

    return {"page": best_page, "x": round(pdf_x, 2), "y": round(pdf_y, 2)}