extract_text_before/extract_text_after raise UnboundLocalError when the pattern is absent

[eeshsaxena]

Summary

extract_text_before() and extract_text_after() (in unstructured/cleaners/extract.py) raise an UnboundLocalError instead of a clear error when the given pattern does not occur in the text at all. The helper they call, _get_indexed_match(), tries to build a "not found" message using a loop variable that was never assigned because the loop body never ran.

Reproduction

from unstructured.cleaners.extract import extract_text_before

# "xyz" does not appear in the text, so there are zero matches
extract_text_before("hello world", "xyz")

Actual

UnboundLocalError: cannot access local variable 'i' where it is not associated with a value

Expected

Either the intended ValueError ("Result with index 0 was not found.") or a graceful no-match result. The confusing UnboundLocalError should not surface.

Root cause

In _get_indexed_match:

for i, result in enumerate(re.finditer(pattern, text)):
    if i == index:
        regex_match = result

if regex_match is None:
    raise ValueError(f"Result with index {index} was not found. The largest index was {i}.")

When re.finditer(pattern, text) yields no matches, the for loop never executes, so i is never bound. The regex_match is None branch is then taken and the f-string references {i}, which raises UnboundLocalError before the intended ValueError can be raised. This is the normal "pattern absent" path, so any caller of extract_text_before / extract_text_after with a pattern that is not present hits it.

Suggested fix

Initialize the counter before the loop so the message is well-defined on zero matches, e.g.:

i = -1
for i, result in enumerate(re.finditer(pattern, text)):
    ...
if regex_match is None:
    raise ValueError(
        f"Result with index {index} was not found."
        + (f" The largest index was {i}." if i >= 0 else " No matches were found.")
    )

Happy to send a small PR with a regression test if that helps.

[zeweihan]

Nice catch — and worth flagging that the type of failure here matters as much as the fix.

For document-extraction pipelines, extract_text_before / extract_text_after are effectively clause-anchoring primitives: you call them with a heading/keyword anchor ("Section 3.1", "WHEREAS", "IN WITNESS WHEREOF", a defined-term pattern) to slice out a clause. The "pattern absent" case isn't an edge case in that workload — it's the common case, because:

• templates vary across counterparties, so your anchor regex misses ~15-30% of the time
• OCR on scanned exhibits routinely mangles the anchor ("Section 3.1" → "Sectlon 3.l")
• redacted/amended sections drop the anchor entirely

When "anchor not found" surfaces as an UnboundLocalError, it has two downstream costs that a clean ValueError would not:

1. Batch kills. A crash on document N of 500 stops the whole run. A catchable, named exception (or a sentinel return) lets the caller route that document to fallback extraction / a manual-review queue and keep going. UnboundLocalError is the worst of both — it is catchable as an exception, but nobody writes except UnboundLocalError, so it bubbles.

2. Wrong root-cause attribution. The message claims the largest index was {i}, but i is undefined, so the message is both missing and would have been misleading if present (the largest index when there are zero matches is "none", not a number). The proposed ValueError("...was not found") is the right message.

One design thought, since this is on the cleaners/extract boundary: regulated-domain users would benefit from a third outcome distinct from "found" and "error" — an explicit no-match sentinel (e.g. return None, or raise a dedicated NoMatchFound that callers can catch separately from genuine input errors). Collapsing "anchor not present in this document" into the same exception path as "you passed bad arguments" forces callers to either swallow all errors or re-check with re.search before every call. The minimal fix (assign i = -1 before the loop, or guard the message) resolves the crash; the sentinel would resolve the ergonomics.

tl;dr minimal fix is one line (largest_index = -1 initialized pre-loop), but this boundary is a good candidate for a documented no-match contract since absent anchors are the norm, not the exception, in real document workloads.