fastlines 0.0.0

Fast line match extraction for LLM context pre-staging.

fastlines

fastlines pre-stages line-level references from a directory so humans or LLMs can work from stable, local context instead of repeated file reads.

• Standard library only
• File discovery by glob or regex
• Line matching by regex, literal text, or fuzzy similarity
• Hard blocklist for binary extensions (e.g. png, xls) even if explicitly requested
• Outputs JSON for retention plus a Markdown context document for prompt usage

Install

pip install fastlines

Quickstart

CLI

Scan SQL files for exact import matches and emit JSON + context outputs:

fastlines C:\path\to\repo --include-glob "*.sql" --line-regex "\\bimport\\b" \
  --output-json results.json --output-context context.md

Case-insensitive literal match across multiple file globs:

fastlines C:\path\to\repo --include-glob "*.sql,*.py" --line-text "some_text" --ignore-case

Regex file selection plus exclusions:

fastlines C:\path\to\repo --include-regex "\\.sql$" --exclude-glob "*_test.sql" --line-text "some_text"

Fuzzy matching (ratio 0-1, higher is stricter):

fastlines C:\path\to\repo --line-fuzzy "some_text" --fuzzy-threshold 0.85

Allow a default-skipped extension (e.g. a text-based PDF):

fastlines C:\path\to\repo --include-glob "*.pdf" --line-text "some_text" --allow-ext ".pdf"

Python

from fastlines import LineMatcher, scan_directory, write_context_document, write_json_results

matcher = LineMatcher(regex=r"\bimport\b", ignore_case=True)
result = scan_directory(
    "C:/path/to/repo",
    line_matcher=matcher,
    include_globs=["*.py"],
)
write_json_results(result.matches, "results.json")
write_context_document(result.matches, "context.md")

CLI reference

fastlines ROOT \
  [--include-glob PATTERN] [--include-regex REGEX] \
  [--exclude-glob PATTERN] [--exclude-regex REGEX] \
  [--skip-dir NAME] [--allow-dir NAME] [--allow-ext EXT] [--no-default-skip] \
  (--line-regex REGEX | --line-text TEXT | --line-fuzzy TEXT) \
  [--ignore-case] [--fuzzy-threshold 0.8] \
  [--max-line-length N] [--max-matches-per-file N] \
  [--output-json FILE] [--output-context FILE]

Documentation (bundled)

The package ships with offline documentation that is accessible after install:

python -m fastlines.docs --list
python -m fastlines.docs --show CLI
python -m fastlines.docs --show EXAMPLES
python -m fastlines.docs --show PERFORMANCE
python -m fastlines.docs --show LIMITATIONS
python -m fastlines.docs --show CHANGELOG
python -m fastlines.docs --show SECURITY
python -m fastlines.docs --show TROUBLESHOOTING
python -m fastlines.docs --write-dir .\\fastlines-docs

Python API (core objects)

LineMatcher

LineMatcher(
    regex: str | None = None,
    text: str | None = None,
    fuzzy: str | None = None,
    ignore_case: bool = False,
    fuzzy_threshold: float = 0.8,
)

Result models

LineMatch(number: int, content: str)
FileMatch(source_file: str, file_lines: int, lines: list[LineMatch])
ScanResult(matches: list[FileMatch], stats: ScanStats)

ScanStats(
    files_considered: int = 0,
    files_scanned: int = 0,
    files_matched: int = 0,
    lines_matched: int = 0,
    files_skipped_blocked_ext: int = 0,
    files_skipped_default_ext: int = 0,
    files_skipped_binary: int = 0,
    files_skipped_unreadable: int = 0,
)

Scanning + output

scan_directory(
    root: str | Path,
    *,
    line_matcher: LineMatcher,
    include_globs: Sequence[str] | None = None,
    include_regexes: Sequence[str] | None = None,
    exclude_globs: Sequence[str] | None = None,
    exclude_regexes: Sequence[str] | None = None,
    skip_dirs: Sequence[str] | None = None,
    allow_dirs: Sequence[str] | None = None,
    allow_exts: Sequence[str] | None = None,
    use_default_skip: bool = True,
    max_line_length: int | None = None,
    max_matches_per_file: int | None = None,
) -> ScanResult

write_json_results(matches: Sequence[FileMatch], path: str | Path) -> None
write_context_document(matches: Sequence[FileMatch], path: str | Path) -> None

Output formats

JSON output (list of file matches):

[
  {
    "source_file": "C:/path/to/repo/query.sql",
    "file_lines": 120,
    "lines": [
      {"number": 12, "content": "-- some_text here"}
    ]
  }
]

Context output:

# File References
## C:/path/to/repo/query.sql
012 | -- some_text here

file_lines is the total line count of the source file and is used to pad line numbers in the context output.

Notes

• Files are skipped if the extension is on the blocklist or the file appears to be binary.
• By default, fastlines skips common build/cache folders (e.g. .git, .venv) plus .ipynb/.pdf. Use --allow-dir/--allow-ext (or --allow-dirs/--allow-exts) to opt back in for specific defaults, or --no-default-skip to include them all.
• --allow-ext does not override the blocklist (e.g. .png, .xls are always blocked).
• LineMatcher(text=...) is a substring match; use LineMatcher(regex=r"\bword\b") for exact word boundaries.
• Line numbering is 1-based and paths are always absolute.