NumberedLines
era_pl.NumberedLines(lines, index=None)A sequence of text lines that preserves original line numbers.
NumberedLines behaves like a read-only sequence of strings, but carries an explicit index attribute that records the original (global) line numbers for each line. This is useful when working with text extracted from external sources (e.g., PDFs, logs, or scraped documents) where line numbers are meaningful for debugging, citation, or reproducibility.
The object supports slicing and filtering while preserving original line numbers. Slicing returns a new NumberedLines object whose index reflects the corresponding subset of the original indices. The index can be reset explicitly using reset_index().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lines | str or Iterable[str] | Either a single string containing newline-separated text, or an iterable of strings. If a string is provided, it is split into lines using str.splitlines(). If an iterable of strings is provided (e.g., page-level text from a PDF), each element is split into lines and flattened. |
required |
| index | Iterable[int] | Explicit line numbers to associate with lines. If not provided, line numbers are assigned sequentially starting from zero. |
None |
Attributes
| Name | Type | Description |
|---|---|---|
| lines | list[str] | The underlying text lines. |
| index | list[int] | The original line numbers corresponding to each line. |
Notes
NumberedLinesis immutable: slicing and filtering return new objects rather than modifying the original.- The class does not perform any I/O. Display and printing are left to the caller.
- The object can be passed directly to
pd.Series()or other APIs that accept a sequence of strings.
Examples
Create from a single string:
>>> nl = NumberedLines("a\nb\nc")
>>> nl.index
[0, 1, 2]Slice while preserving original line numbers:
>>> nl[1:3].index
[1, 2]Reset indices after slicing:
>>> nl[1:3].reset_index().index
[0, 1]Methods
| Name | Description |
|---|---|
| filter | Return only lines matching regex (preserving original indices). |
| filter_out | |
| format | Return a list of strings with line numbers prefixed. |
| reset_index | Return a new NumberedLines with index reset to 0..n-1. |
| to_list | Explicit escape hatch: get the underlying list. |
filter
era_pl.NumberedLines.filter(regex)Return only lines matching regex (preserving original indices).
filter_out
era_pl.NumberedLines.filter_out(regex)format
era_pl.NumberedLines.format(pad=None)Return a list of strings with line numbers prefixed.
reset_index
era_pl.NumberedLines.reset_index()Return a new NumberedLines with index reset to 0..n-1.
to_list
era_pl.NumberedLines.to_list()Explicit escape hatch: get the underlying list.