document performance characteristics

This commit is contained in:
2026-08-27 10:31:29 +02:00
parent 62a4fce866
commit 591bd86235

View File

@@ -51,8 +51,9 @@ would depend on configuration file ordering.
**Ties keep their original file order.** The sort keys only on the count, and **Ties keep their original file order.** The sort keys only on the count, and
Python's sort is stable. Python's sort is stable.
**Unchanged lines are still printed.** Dropping non-matching lines would **Unchanged lines are still printed.** Dropping lines that matched nothing
silently lose content, so they print last with a count of zero. would silently lose content, so every line is printed; those with no
replacements sort last.
**Only the line terminator is stripped.** `\n` and `\r\n` both; every other **Only the line terminator is stripped.** `\n` and `\r\n` both; every other
character stays replaceable. The format has no quoting, so the trailing space in character stays replaceable. The format has no quoting, so the trailing space in
@@ -61,22 +62,31 @@ character stays replaceable. The format has no quoting, so the trailing space in
## Performance characteristics ## Performance characteristics
`replace_line` tries every pair at each position, so cost grows with both the `replace_line` tries every pair at each position, so cost grows with both the
line length and the number of pairs. On a fixed 20,000-line input of line length and the number of pairs. Two alternatives, measured on the same
40-character lines, against two alternatives producing identical output: 20,000-line input of 40-character lines and producing identical output:
| Pairs | this implementation | `re` alternation | prefix tree | | Pairs | this implementation | regex alternation | prefix tree |
| ----: | ------------------: | ---------------: | ----------: | | ----: | ------------------: | ----------------: | ----------: |
| 3 | 0.27s | 0.011s | 0.067s | | 3 | 1x | 1x | 1x |
| 100 | 6.13s | 0.011s | 0.073s | | 100 | 20x | 1.2x | 1.1x |
| 1000 | 58.80s | 0.011s | 0.067s | | 1000 | 207x | 1.1x | 1.1x |
The regex is a constant-factor win, running the scan in C; the prefix tree is Median of repeated runs, relative to each column's own three-pair baseline, so
the algorithmic one, taking the pair count out of the complexity entirely. The the figures do not depend on the machine. The three-pair run takes about a
explicit loop is kept because at the sizes described here the difference is not quarter of a second. Neither alternative is quite flat, because the larger
observable, and the loop keeps the longest-match rule visible in the code. configurations in this benchmark also use longer keys, which cost slightly more
to match.
The regex is only equivalent because `prepare_pairs` already orders patterns The regex alternation joins every `value1` into one pattern (`a|bb|c`) that
longest first: Python's `re` is leftmost-first, not leftmost-longest. Python's `re` module scans in C: a constant-factor win, the same work done
faster. The prefix tree is the algorithmic one, taking the pair count out of the
complexity rather than making each step cheaper. The explicit loop is kept
because at the sizes described here the difference is not observable, and it
keeps the longest-match rule visible in the code.
The alternation is only equivalent because `prepare_pairs` orders the patterns
longest first: `re` is leftmost-first rather than leftmost-longest, so `b|bb`
would otherwise match `b` against the input `bb`.
Memory is proportional to the input size, since every line is held before Memory is proportional to the input size, since every line is held before
sorting. sorting.
@@ -84,12 +94,13 @@ sorting.
## Error handling ## Error handling
The configuration file is validated while loading: a line without `=`, and a The configuration file is validated while loading: a line without `=`, and a
line whose value1 is empty, are both rejected reporting the offending line line whose `value1` is empty, are both rejected, reporting the offending line
number. An empty value1 would match at every position without consuming number. An empty `value1` would match at every position without consuming
anything, which is why it is refused rather than ignored. Missing files, anything, which is why it is refused rather than ignored.
unreadable files, and input that is not valid UTF-8 are reported as messages on
stderr rather than tracebacks, and exit with status 1. Status 2 is reserved by Missing files, unreadable files, and input that is not valid UTF-8 are reported
`argparse` for command line misuse. as messages on stderr rather than tracebacks, and exit with status 1. Status 2
is reserved by `argparse` for command line misuse.
## Tests ## Tests
@@ -99,8 +110,9 @@ pytest
``` ```
- `tests/unit/` covers configuration parsing and the replacement algorithm, - `tests/unit/` covers configuration parsing and the replacement algorithm,
including the overlapping-pattern and empty-input edge cases, plus a line by including the overlapping-pattern case, empty input, and the rejection of an
line check of the worked example in `test_sample_data.py`. empty `value1`, plus a line by line check of the worked example in
`test_sample_data.py`.
- `tests/integration/test_cli.py` invokes `main.py` as a subprocess to cover - `tests/integration/test_cli.py` invokes `main.py` as a subprocess to cover
what unit tests cannot: argument handling, exit status, stderr messages, and what unit tests cannot: argument handling, exit status, stderr messages, and
the sort order as actually printed. the sort order as actually printed.