API Reference#

Functions#

renorm.compile(pattern: str, *specs: NormSpec, flags: _FlagsType = 0, **named_specs: NormSpec) → Pattern#

Compile a renorm pattern by combining a raw pattern string with positional and named specifications, and return a Pattern object.

Parameters:

patternstr: The raw pattern string containing positional ({@idx}) or named ({@name}) placeholders.
*specsNormSpec[T]: Positional specifications to substitute into the pattern.
flagsre.RegexFlag, optional: Standard re module flags to apply when compiling the underlying regular expression.
**named_specsNormSpec[T]: Named specifications to substitute into the pattern.

Returns:

Pattern[T]: A compiled renorm pattern that can be used to search and normalize matches.

Regular expression objects#

class renorm.pattern.Pattern(*args: Any, **kwargs: Any)#

Bases: Generic

Compiled renorm pattern exposing a minimal API similar to re.Pattern, but returning renorm.Match objects with normalization semantics.

Instances of this class are created via renorm.compile() and cannot be instantiated directly.

property pattern: str#: The fully expanded regular expression string incorporating renorm specifications and used internally for matching.

search(text: str) → Match | None#

Scan through text looking for the first location where the pattern matches.

Parameters:

textstr: The input string to search.

Returns:

Match[T] or None: A renorm Match object if a match is found, otherwise None.

match(text: str) → Match | None#

Match the pattern against the start of text.

Parameters:

textstr: The input string to match.

Returns:

Match[T] or None: A renorm Match object if the beginning of the string matches, otherwise None.

fullmatch(text: str) → Match | None#

Match the pattern against the entire text.

Parameters:

textstr: The input string to match.

Returns:

Match[T] or None: A renorm Match object if the whole string matches, otherwise None.

Match objects#

class renorm.pattern.Match(*args: Any, **kwargs: Any)#

Bases: Generic

renorm match object exposing a minimal API similar to re.Match, but returning normalized groups according to the associated NormSpec objects.

Instances of this class are created internally by Pattern methods and cannot be instantiated directly.

groups() → tuple[str | T | None, ...]#

Return all captured groups after normalization.

Groups associated with a NormSpec are normalized using its normalize() method. Groups without an associated specification are returned as raw strings. Optional groups that did not participate in the match are returned as None.

A captured substring may be None when the corresponding capturing group did not participate in the match. This happens with optional groups. For example, in a pattern like r"(a)?(b)":

matching only "b" produces the groups (None, "b") because the optional group (a)? matched nothing.

Returns:

tuple of (str or T or None): The normalized captured groups.

Return one or more captured groups.

Behaves like re.Match.group(), but applies normalization to groups associated with specifications.

Parameters:

*idxsint: Group indices to retrieve. 0 returns the entire match.

Returns:

str | T | None or tuple of (str or T or None): A single normalized group, or a tuple of groups if multiple indices are provided.

groupdict() → Never#

groupdict is disabled because named capture groups are reserved for internal mapping between regex groups and specifications.

Data Specification objects#

renorm composable specifications that pair a regular expression pattern with a deterministic normalization strategy.

Each specification describes a precise grammar for a class of textual values and guarantees that matched substrings can be transformed into a canonical representation.

class renorm.specs.NormSpec#

Bases: ABC, Generic

Abstract specification pairing a regular expression pattern with a deterministic normalization strategy.

A NormSpec defines two things:

a regex pattern describing the acceptable textual representations of a value of type T;
a normalization function that converts a captured substring into a canonical value of type T (or None if the substring is invalid).

Subclasses must implement pattern and normalize().

abstract property pattern: str#

Regular expression pattern describing the acceptable textual representations for this specification.

Returns:

str: The regex pattern as a string.

abstractmethod normalize(group: str | None) → T | None#

Normalize a captured substring according to this specification.

A captured substring may be None when the corresponding capturing group did not participate in the match. This happens with optional groups. For example, in the pattern r"(a)?(b)":

matching only "b" produces the groups (None, "b") because the optional group (a)? matched nothing.

Parameters:

groupstr or None: The captured substring to normalize. None indicates that the capturing group did not participate in the match (e.g., optional groups that matched nothing).

Returns:

T or None: The canonical value corresponding to the substring, or None if the substring is invalid under this specification.

class renorm.specs.Num(dec: str = '.', ths: str = '')#

Bases: NormSpec[float]

Specification for plain (non-scientific) numeric literals with configurable decimal and thousands separators.

The pattern property exposes a permissive regex used only for capture: it greedily matches number-like fragments to avoid truncating malformed literals. Normalization then applies a strict pattern that enforces the instance’s numeric specification. If the captured literal does not satisfy the strict rules, normalize returns None; otherwise it returns a normalized float.

Numeric literal semantics

If ths is an empty string, the integer part must be ungrouped.
If ths is a valid character, the integer part must be grouped in 3-digit blocks from the right, using ths as the thousands separator.
If dec is an empty string, the number must not contain a fractional part.
If dec is a valid character, a fractional part is optional and must use dec.
An optional sign (+ or -) is allowed, with optional trailing whitespace (not configurable).

Attributes:

decstr: Decimal separator: '.', ',', or '' for integers only
thsstr: Thousands separator: '.', ',', "'", ' ' <space>, or '' for no grouping

property pattern: str#

Permissive regular expression used for initial capture of number-like fragments. This pattern is intentionally broad and accepts any substring that resembles a numeric literal, without enforcing strict grouping or decimal rules. Strict validation according to the specified ths and dec separators is applied later by normalize().

Returns:

str: The permissive regex pattern as a string.

normalize(group: str | None) → float | None#

Normalize a captured numeric literal according to this specification.

This method applies strict validation to a substring previously matched by pattern. If the substring satisfies the configured grouping rules (ths), decimal separator (dec), and optional sign semantics, it is converted into a canonical float. Otherwise, None is returned.

Parameters: