utils: Regex and Registration Utilities#

Helpers shared by the parser, renderer, and postprocessor: composable pattern builders (multi_rgx(), define_rgx(), regex_dict()), the escape-aware NO_ESC lookbehind, match unpacking via parse_match(), registration-name inference (name_function()), and the DirectiveKind taxonomy of MyST directive names.

NOTE: multi_rgx() and regex_dict() deliberately stay local byte-for-byte copies of my.ut rather than aliases: any module-level my import runs the full my-basis package init (pydantic, srsly, numpy), and this module loads inside mdformat’s plugin scan on the CLI cold path (see TestPerformance.test_format_cold_start). The characterization tests keep the copies in behavioral lockstep with basis.

Regex and Registration Utilities.

Helpers shared by the parser, renderer, and postprocessor: composable pattern builders (multi_rgx(), define_rgx(), regex_dict()), the escape-aware NO_ESC lookbehind, match unpacking via parse_match(), registration-name inference (name_function()), and the DirectiveKind taxonomy of MyST directive names.

NOTE: multi_rgx() and regex_dict() deliberately stay local byte-for-byte copies of my.ut rather than aliases: any module-level my import runs the full my-basis package init (pydantic, srsly, numpy), and this module loads inside mdformat’s plugin scan on the CLI cold path (see TestPerformance.test_format_cold_start). The characterization tests keep the copies in behavioral lockstep with basis.

myform.utils.multi_rgx(*expressions: str | list[str], branching: bool = False, sep: str = ' ?', pre: str = '', suf: str = '') → str#

Combine expression clauses into a single alternating group that matches any of them.

Parameters:

  • *expressions – Regex patterns to be combined.

  • branching – If True, use a branching group (resets group names between branches).

  • sep – Separator for joining list patterns (default: ' ?').

  • pre – Prefix to add before combined pattern (default: empty).

  • suf – Suffix to add after combined pattern (default: empty).

Returns:

Combined regex pattern in group format (?|...) or (?:...).

myform.utils.define_rgx(**kwargs: str) → str#

Define a regex pattern with named capture groups.

Parameters:

**kwargs – A map from group names to raw, unwrapped expressions.

Returns:

A (?(DEFINE)...) expression ready to be concatenated to an expression using the groups.

myform.utils.regex_dict(expressions: ~collections.abc.Mapping[str, str | P | ~_regex.Pattern] | None = None, compile_function: ~collections.abc.Callable[[P], ~_regex.Pattern] = <function compile>, **kwargs: str | P | ~_regex.Pattern) → dict[str, Pattern]#

Compile the expression strings in the given dictionary, mapping names to Patterns.

Parameters:

  • expressions – A mapping of string names to regular expressions (compiled or otherwise).

  • compile_function – Function to compile patterns (default: re.compile).

  • **kwargs – Additional named patterns to include.

Returns:

The expressions mapping with all values now compiled.

myform.utils.is_plane_safe_href(value: str) → bool#

Return whether value is a Plane href that cannot activate an unsupported scheme.

myform.utils.name_function(name: str, fn: LambdaType, pre: str) → str#

Validate or infer the name of a registered method.

Parameters:

  • name – Explicit name to use for registration.

  • fn – Function being registered.

  • pre – Expected prefix for the function name if name is not provided.

Returns:

The name to use for registration.

myform.utils.parse_match(match: Match) → dict[str, str]#

Parse the given regex match into a dictionary of groups.

class myform.utils.DirectiveKind(*values)#

Kinds of MyST directives.

classmethod read(name: str) → DirectiveKind#

Determine the kind of the given directive name.