openrig.naming.types module

Type definitions for the naming system.

Defines all types used internally by the naming package:

Config types (used by rules.py):

• RuleConfig: raw deserialized configuration for a single token rule.

• GlobalRules: global constraints applied to every fully-built name.

Token value types (used by manager.py):

• TokenValue: accepted raw input for a token before normalization.

• TokenData: canonical post-normalization form (always str values).

Rule protocol (used by manager.py):

• RuleValidator: Protocol that every rule type must satisfy.

Concrete rule implementations (used by rules.py, manager.py):

• RegexRule: validates a token value against a regular expression.

• ListRule: validates a token value against a fixed set of allowed values.

• CallableRule: delegates validation to an arbitrary callable.

• ConcreteRule: union of all concrete rule types.

class openrig.naming.types.RuleConfig(type: str, value: str | list[str] | None = None, sources: list[str] | None = None, module: str | None = None)

Bases: object

Raw deserialized configuration for a single token rule.

Intermediate representation populated from naming/config.json. rules.py converts each instance into a ConcreteRule.

type

Rule type: "regex", "list", "from_enums", or "callable".

Type:

str

value

Primary payload — pattern string, list of values, or dotted import path, depending on type.

Type:

str | list[str] | None

sources

Enum class names to aggregate. Only for "from_enums".

Type:

list[str] | None

module

Dotted module path where sources are defined. Only for "from_enums". Defaults to "openrig.constants".

Type:

str | None

type: str

value: str | list[str] | None = None

sources: list[str] | None = None

module: str | None = None

class openrig.naming.types.GlobalRules(max_length: int, forbidden_patterns: list[str] = <factory>, separator_rule: ~openrig.naming.types.RuleConfig | None = None)

Bases: object

Global constraints applied to every fully-built name.

max_length

Maximum allowed character length for any built name.

Type:

int

forbidden_patterns

Substrings that must not appear in any built name.

Type:

list[str]

separator_rule

Optional RuleConfig constraining valid separators.

Type:

openrig.naming.types.RuleConfig | None

max_length: int

forbidden_patterns: list[str]

separator_rule: RuleConfig | None = None

class openrig.naming.types.RuleValidator(*args, **kwargs)

Bases: Protocol

Protocol for all token-level validation rules.

Any object that implements validate and to_regex_pattern satisfies this protocol.

Example

>>> class MyRule:
...     def validate(self, value: str) -> bool:
...         return value.isalpha()
...     def to_regex_pattern(self) -> str:
...         return r"[a-zA-Z]+"

validate(value: str) → bool

Validates a normalized token value.

Parameters:

value – The normalized (post-normalization) string value to check.

Returns:

True if the value is acceptable, False otherwise.

to_regex_pattern() → str

Returns a regex pattern representing the valid values for this rule.

Used by the Manager to build the global matching regex without inspecting the rule’s internal structure.

Returns:

A regex pattern string (without anchors ^ / $).

class openrig.naming.types.RegexRule(pattern: str)

Bases: object

A rule that validates a token value against a regular expression.

pattern

The regex pattern string. Anchors ^ / $ are optional; validate always performs a full match.

Type:

str

Example

>>> rule = RegexRule(pattern=r"^[a-z][a-zA-Z0-9]*$")
>>> rule.validate("armUpper")
True
>>> rule.validate("Arm Upper")
False

pattern: str

__post_init__() → None

Validates that the pattern compiles correctly on construction.

validate(value: str) → bool

Validates the value against the compiled regex pattern.

Parameters:

value – The normalized token value.

Returns:

True if the value matches the full pattern.

to_regex_pattern() → str

Returns the raw pattern, stripping leading/trailing anchors.

Returns:

The pattern string ready for embedding in a larger regex.

class openrig.naming.types.ListRule(allowed: frozenset[str])

Bases: object

A rule that validates a token value against a fixed set of allowed values.

allowed

A frozenset of accepted string values.

Type:

frozenset[str]

Example

>>> rule = ListRule(allowed=frozenset({"l", "r", "c", "m"}))
>>> rule.validate("l")
True
>>> rule.validate("left")
False

allowed: frozenset[str]

validate(value: str) → bool

Checks membership in the allowed set.

Parameters:

value – The normalized token value.

Returns:

True if value is in the allowed set.

to_regex_pattern() → str

Returns an alternation pattern of all allowed values, sorted by length.

Sorting by length descending prevents shorter alternatives from shadowing longer ones in the regex engine.

Returns:

A non-capturing alternation group, e.g. (?:left|right|l|r).

class openrig.naming.types.CallableRule(func: object, name: str)

Bases: object

A rule that delegates validation to an arbitrary callable.

The callable must accept a single str argument and return bool. Because callable rules are opaque to the regex engine, to_regex_pattern returns a catch-all pattern; validation must be performed separately via validate.

func

The validation callable. Typed as object to avoid hashability issues; narrowed at call site.

Type:

object

name

A human-readable label used in error messages and __repr__.

Type:

str

Example

>>> rule = CallableRule(func=str.isalpha, name="alpha_only")
>>> rule.validate("arm")
True
>>> rule.validate("arm1")
False

func: object

name: str

validate(value: str) → bool

Calls the wrapped function with the value.

Parameters:

value – The normalized token value.

Returns:

True if the function returns a truthy result.

Raises:

TypeError – If the stored func is not callable.

to_regex_pattern() → str

Returns a permissive catch-all pattern.

Returns:

A catch-all pattern [^\\s]+.