Passa al contenuto principale

Txt agent

La classe TxtAgent è un layer di manipolazione dei file di testo semplice (.txt). Non assume alcuna struttura: l'unità di lavoro è la riga. Tutte le operazioni di lettura e modifica avvengono su una rappresentazione line-based del file, preservando i terminatori originali (\n o \r\n).

Costruttore​

TxtAgent(file_bytes: bytes | None = None, encoding: str = "utf-8")
  • file_bytes (bytes | None): il contenuto binario del file .txt. Se None, viene creato un file vuoto.
  • encoding (str): encoding del file. Default utf-8.

Metodi​

save​

Restituisce il contenuto corrente come sequenza di bytes.

save() -> bytes

get_text​

Restituisce l'intero contenuto del file come stringa.

get_text() -> str

get_lines​

Restituisce un intervallo di righe come lista di stringhe (senza i terminatori di riga).

get_lines(start: int | None = None, end: int | None = None) -> list[str]
  • start (int | None): indice di partenza (0-based, incluso). None significa dall'inizio.
  • end (int | None): indice di fine (0-based, escluso). None significa fino alla fine.
suggerimento

Il comportamento segue le convenzioni dello slicing Python: get_lines(0, 10) restituisce le prime 10 righe.

get_line​

Restituisce una singola riga come stringa (senza terminatore).

get_line(idx: int) -> str
  • idx (int): indice della riga (0-based).
warning

Solleva IndexError se l'indice è fuori range.

line_count​

Restituisce il numero di righe del file.

line_count() -> int

get_structure​

Restituisce una mappa testuale leggera del file: conteggio di righe, parole e caratteri, encoding, e anteprima delle prime/ultime righe.

get_structure(preview_len: int = 60) -> str
  • preview_len (int): numero massimo di caratteri per le anteprime.

L'output è una stringa con un formato simile a:

TEXT STRUCTURE (250 lines, 1840 words, 12503 chars, encoding=utf-8)
────────────────────────────────────────────────────────────
  [0   ] Prima riga del documento
  [1   ] Seconda riga di esempio
  [2   ] (empty)
  [3   ] Quarta riga con del contenuto
  [4   ] Quinta riga
  ... (242 more lines)
  [247 ] Penultima riga di esempio
  [248 ] Riga precedente all'ultima
  [249 ] Ultima riga del file

Per file con più di 8 righe vengono mostrate le prime 5 e le ultime 3 con un separatore .... Le righe vuote vengono marcate esplicitamente.

edit_line​

Modifica il contenuto di una singola riga preservandone il terminatore originale (\n vs \r\n).

edit_line(idx: int, content: str) -> None
  • idx (int): indice della riga (0-based).
  • content (str): nuovo contenuto della riga. Non deve includere il terminatore — viene gestito automaticamente.

add_line​

Aggiunge una nuova riga al file.

add_line(content: str, after: int | None = None) -> int
  • content (str): contenuto della nuova riga (senza terminatore).
  • after (int | None): inserisce dopo questa riga. None aggiunge in coda.

Restituisce l'indice della nuova riga.

informazioni

Il terminatore di riga viene scelto automaticamente in base allo stile dominante nel file (\r\n se presente, altrimenti \n). Se il file non termina con un newline e si appende in coda, ne viene aggiunto uno prima.

remove_lines​

Rimuove una o più righe dal file.

remove_lines(ids: list[int]) -> None
  • ids (list[int]): lista degli indici da rimuovere.
warning

Dopo la rimozione gli indici vengono ricompattati. Per rimuovere più righe in modo sicuro, passarle tutte in una singola chiamata invece di chiamate successive.

append​

Aggiunge testo in coda al file. Se il file non termina con un newline, ne viene aggiunto uno prima dell'append.

append(text: str) -> None
  • text (str): testo da appendere.

prepend​

Aggiunge testo in testa al file.

prepend(text: str) -> None
  • text (str): testo da anteporre. Se non termina con un newline, ne viene aggiunto uno automaticamente.

replace​

Sostituzione globale stringa-per-stringa nel testo del file.

replace(old: str, new: str, count: int = -1) -> int
  • old (str): stringa da cercare.
  • new (str): stringa di sostituzione.
  • count (int): numero massimo di sostituzioni. -1 significa tutte.

Restituisce il numero di sostituzioni effettuate.

Cerca una stringa o un pattern regex nel file, con contesto circostante.

search(
    query: str,
    context_chars: int = 30,
    regex: bool = False,
) -> list[dict]
  • query (str): testo da cercare (case-insensitive in modalità letterale; case-sensitive in modalità regex salvo flag espliciti).
  • context_chars (int): numero di caratteri di contesto prima e dopo il match.
  • regex (bool): se True, query viene interpretata come pattern regex.

Restituisce una lista di dizionari:

[
    {
        "line": 12,
        "col": 8,
        "snippet": "…questa è la **parola** cercata…"
    }
]
warning

In modalità regex, solleva ValueError se il pattern non è valido.

informazioni

La ricerca non richiede alcun LLM ed è eseguita direttamente sul testo.