The text_match.py module#

Summary#

edit_distance_le_one

Return True iff Levenshtein distance between a and b is at most 1.

fuzzy_normalize

Normalize value to a canonical spelling from allowed.

sanitize_named_object_key

Return (sanitized_name, notice_or_None) for a Fluent NamedObject key.

Description#

Shared string-matching utilities for fuzzy/typo-tolerant lookup.

These helpers are used everywhere a caller has to reconcile a user-supplied identifier against a finite, authoritative set of known strings ( such as material names from the shipped Fluent database, allowed values of an enum-typed setting, NamedObject keys, dict-key schemas, and command kwargs).

Keeping the implementation in one place avoids the trap hit historically: _check_value learned to tolerate a host-provided "least-squares-cell-based" → "least-square-cell-based" typo while copy_material could not even resolve "water-vapour" → "water-vapor". Both are the same single-edit problem. Both should share the same solution.

Public API:

Module detail#

text_match.edit_distance_le_one(a: str, b: str) → bool#

Return True iff Levenshtein distance between a and b is at most 1.

Faster than computing the full distance because only the ≤ 1 verdict is needed.

Parameters:
astr

A to supply to the function.

bstr

B to supply to the function.

Returns:
bool

Boolean result produced by the function.

text_match.fuzzy_normalize(value: str, allowed: collections.abc.Iterable[str]) → str | None#

Normalize value to a canonical spelling from allowed.

It returns the canonical spelling for value if exactly one entry in allowed is within edit distance 1 (case-insensitive), else None.

Uniqueness is required so a near-spelling never silently overwrites a value when two candidates are equally plausible. The ambiguity is surfaced to the caller instead.

Parameters:
valuestr

Value to supply to the function.

allowedIterable[str]

Allowed values to supply to the function.

Returns:
str | None

String result produced by the function.

text_match.sanitize_named_object_key(name: str, *, replacement: str = '-') → tuple[str, str | None]#

Return (sanitized_name, notice_or_None) for a Fluent NamedObject key.

Fluent rejects whitespace in NamedObject instance keys (such as boundary condition names, cell-zone names, material names, and named-expression keys). Internal whitespace runs are collapsed to replacement (hyphen by default). The idiomatic Fluent separator, such as pressure-outlet-1, phase-1, cold-inlet) and leading or trailing whitespace is stripped.

The function is conservative. It ONLY rewrites whitespace. Other illegal characters (such as /, \\, :, and brackets) are rare in free-text intent and are deliberately left alone so a deterministic rewrite never corrupts a name that the user intentionally typed. Fluent surfaces those at apply time.

The function returns a two-tuple.

  • sanitized_name: Cleaned name (equal to name when no rewrite was needed).

  • notice: One-line human-readable explanation of the rewrite, or None when the input was already clean.

Non-string inputs are returned unchanged with notice=None so callers can pipe values through this helper unconditionally.

Example:

>>> sanitize_named_object_key("oil inlet")
('oil-inlet', "name 'oil inlet' contained whitespace; ...")
>>> sanitize_named_object_key("phase-1")
('phase-1', None)
Parameters:
namestr

Name of the object, module, or setting to process.

replacementstr

Replacement to supply to the function.

Returns:
tuple[str, str | None]

Collection containing the operation results.