openrig.naming.utils module

String manipulation utilities for the OpenRig naming system.

Provides validators, getters, converters, and incrementers for building and transforming name strings used throughout the rigging pipeline.

Categories:

Validators: is_string, is_digit, is_camel_case, etc. Getters: get_digits, get_version, get_namespace, etc. Converters: to_camel_case, to_snake_case, to_kebab_case, etc. Incrementers: increment_digit, increment_character, etc. Decrementers: decrement_digit, decrement_character, etc.

openrig.naming.utils.is_string(text: object) → bool

Validates whether a variable is a string.

Parameters:

text – The value to validate.

Returns:

True if text is a str instance, False otherwise.

openrig.naming.utils.is_digit(value: object) → bool

Validates whether a variable is a number.

Parameters:

value – The value to validate.

Returns:

True if value is an int or float instance, False otherwise.

openrig.naming.utils.is_camel_case(text: str) → bool

Validates if a text is in camelCase style.

Parameters:

text – Text to validate.

Returns:

True if the text is in camelCase style, False otherwise.

openrig.naming.utils.is_pascal_case(text: str) → bool

Validates if a text is in PascalCase style.

Parameters:

text – String to validate.

Returns:

True if the text is in PascalCase style, False otherwise.

openrig.naming.utils.is_snake_case(text: str) → bool

Validates if a text is in snake_case style.

Parameters:

text – String to validate.

Returns:

True if the text is in snake_case style, False otherwise.

openrig.naming.utils.is_kebab_case(text: str) → bool

Validates if a text is in kebab-case style.

Parameters:

text – String to validate.

Returns:

True if the text is in kebab-case style, False otherwise.

openrig.naming.utils.is_character_in(text: str, character: str = '_') → bool

Validates if a character is in a text.

Parameters:

• text – Text to look for.

• character – Character to validate. Defaults to ‘_’.

Returns:

True if the character is in the text, False otherwise.

openrig.naming.utils.get_case_style(text: str) → str

Determines the naming style of a given text.

Parameters:

text – The text to determine style.

Returns:

“camelCase”, “PascalCase”, “snake_case”, “kebab-case”, or “unknown”.

Return type:

The naming style of the text. Possible values are

openrig.naming.utils.get_digits(text: str) → list[str]

Gets digits inside a text.

Parameters:

text – Text to extract digits.

Returns:

List of string digits from the original text.

openrig.naming.utils.get_digit_by_index(text: str, index: int = 0) → str | None

Gets the digit inside a text at a specific index.

Parameters:

• text – Text to extract digits.

• index – Index of the digit to extract. Defaults to 0.

Returns:

Digit from the original text.

openrig.naming.utils.get_first_digit(text: str) → str | None

Gets the first digit inside a text.

Parameters:

text – Text to extract digits.

Returns:

First digit from the original string.

openrig.naming.utils.get_last_digit(text: str) → str | None

Gets the last digit inside a string.

Parameters:

text – Text to extract digits.

Returns:

Last digit from the original text.

openrig.naming.utils.get_digits_between_brackets(text: str) → list[str]

Gets all digits between brackets inside a text.

Parameters:

text – The text to extract digits from.

Returns:

List of strings representing the numeric digits found between square brackets.

openrig.naming.utils.get_data_between_underscores(text: str) → list[str]

Gets all data between underscores inside a text.

Parameters:

text – The text to extract data from.

Returns:

List of strings representing the data found between underscores.

openrig.naming.utils.get_version(text: str) → int | None

Extracts the version number from a text (e.g., ‘v001’ -> 1).

Parameters:

text – Text to extract version from.

Returns:

The version number as an integer, or None if not found.

openrig.naming.utils.get_namespace(text: str, separator: str = ':') → str

Extracts the namespace prefix from a string.

Parameters:

• text – The string to process (e.g., ‘namespace:item’).

• separator – The separator character. Defaults to ‘:’.

Returns:

The namespace string, or empty string if none.

openrig.naming.utils.replace_spaces(text: str, replacement: str) → str

Replaces spaces in the given text with a specified character.

Parameters:

• text – The input text.

• replacement – Specified character to replace with.

Returns:

The input text with spaces replaced by the given replacement.

openrig.naming.utils.normalize_text(text: str) → str

Normalizes text by replacing non-alphanumeric characters with spaces.

Parameters:

text – Text to normalize.

Returns:

Normalized text.

openrig.naming.utils.to_upper(text: str) → str

Converts a text to uppercase.

Parameters:

text – Text to convert.

Returns:

Uppercase text.

openrig.naming.utils.to_lower(text: str) → str

Converts a text to lowercase.

Parameters:

text – Text to convert.

Returns:

Lowercase text.

openrig.naming.utils.to_camel_case(text: str, remove_digits: bool = False) → str

Converts a text to camelCase.

Parameters:

• text – Text to convert to camelCase.

• remove_digits – Remove digits from the text. Defaults to False.

Returns:

camelCase string.

openrig.naming.utils.to_pascal_case(text: str, remove_digits: bool = False) → str

Converts a text to PascalCase.

Parameters:

• text – Text to convert to PascalCase.

• remove_digits – Remove digits from the text. Defaults to False.

Returns:

PascalCase string.

openrig.naming.utils.to_snake_case(text: str, remove_digits: bool = False) → str

Converts a text to snake_case.

Parameters:

• text – Text to convert to snake_case.

• remove_digits – Remove digits from the text. Defaults to False.

Returns:

snake_case string.

openrig.naming.utils.to_kebab_case(text: str, remove_digits: bool = False) → str

Converts a text to kebab-case.

Parameters:

• text – Text to convert to kebab-case.

• remove_digits – Remove digits from the text. Defaults to False.

Returns:

kebab-case string.

openrig.naming.utils.value_to_str(value: float | int) → str

Converts a numeric value to a filesystem-safe string in MxDx format.

The M prefix indicates a negative value; the decimal point is replaced by d (e.g. -1.5 → "M1d5", 2.0 → "2d0").

Parameters:

value – The numeric value to encode.

Returns:

The encoded string representation.

openrig.naming.utils.str_to_value(text: str) → float

Converts a formatted MxDx string back into a numeric value.

Reverses the encoding applied by value_to_str: strips the M sign prefix and replaces d with a decimal point.

Parameters:

text – Formatted text to convert into a digit.

Returns:

The corresponding numerical value.

openrig.naming.utils.strip_digits(text: str) → str

Removes digits from a text.

Parameters:

text – Text to remove digits from.

Returns:

Text without digits.

openrig.naming.utils.split_text(text: str) → list[str]

Splits text into individual words.

Handles camelCase, PascalCase, and delimiters like _ and -.

Parameters:

text – The text to split.

Returns:

A list of words.

openrig.naming.utils.join_tokens(tokens: Iterable[str | None], separator: str = '_') → str

Joins a sequence of tokens, filtering out None or empty strings.

Parameters:

• tokens – A sequence of tokens (strings or None).

• separator – The separator to use. Defaults to ‘_’.

Returns:

The joined string.

openrig.naming.utils.capitalize_first(text: str) → str

Capitalizes the first letter of a text.

Parameters:

text – Text to capitalize.

Returns:

Text with the first letter capitalized.

openrig.naming.utils.remove_prefix(text: str, prefix: str) → str

Removes a prefix from a text.

Parameters:

• text – Text to remove prefix from.

• prefix – Prefix to remove.

Returns:

Text without prefix.

openrig.naming.utils.remove_suffix(text: str, suffix: str) → str

Removes a suffix from a text.

Parameters:

• text – Text to remove suffix from.

• suffix – Suffix to remove.

Returns:

Text without suffix.

openrig.naming.utils.clean_txt(text: str, replace_with: str = '_') → str

Cleans a string by replacing illegal characters.

Ensures the result does not start with a digit by prepending replace_with if necessary.

Parameters:

• text – Text to clean.

• replace_with – Character to replace illegal characters with. Defaults to ‘_’.

Returns:

Cleaned text.

openrig.naming.utils.strip_namespace(text: str, separator: str = ':') → str

Removes the namespace prefix from a string.

Parameters:

• text – The string to process.

• separator – The separator character. Defaults to ‘:’.

Returns:

The string without the namespace prefix.

openrig.naming.utils.get_base_name(text: str, separator: str = '|') → str

Returns the last component of a path-like string.

Parameters:

• text – The path string (e.g. ‘path/to/item’).

• separator – The path separator. Defaults to ‘|’.

Returns:

The base name (leaf node).

openrig.naming.utils.truncate(text: str, max_length: int, ellipsis: str = '...') → str

Truncates a string to a maximum length.

Parameters:

• text – The text to truncate.

• max_length – The maximum length including the ellipsis.

• ellipsis – The string to append to truncated text. Defaults to “…”.

Returns:

The truncated string.

openrig.naming.utils.split_name_number(text: str) → tuple[str, str | None]

Splits a string into its name and trailing number components.

Parameters:

text – The text to split (e.g., ‘arm01’).

Returns:

A tuple containing the name and the number string (or None).

openrig.naming.utils.get_unique_name(name: str, existing_names: Iterable[str]) → str

Returns a unique name by incrementing the digit if it exists in the list.

Parameters:

• name – The desired name.

• existing_names – Iterable of names that already exist.

Returns:

A unique name.

openrig.naming.utils.increment_character(text: str) → str

Increments a letter sequence in a manner similar to Excel column naming.

• Works for both uppercase and lowercase sequences

• Handles cases like ‘ZZ’ → ‘AAA’ and ‘zz’ → ‘aaa’

Parameters:

text – A text containing only letters (‘A’-‘Z’ or ‘a’-‘z’).

Returns:

The incremented letter sequence.

openrig.naming.utils.increment_digit(text: str, pads: int | None = None) → str

Increments the last digit in a text.

Parameters:

• text – Text to increment.

• pads – Number of digits for padding. If None, uses existing padding or defaults to 2.

Returns:

Text with the last digit incremented, or a digit appended if none existed.

openrig.naming.utils.replace_padding(text: str, padding: int = 2) → str

Replaces the padding of the last number in the text.

Parameters:

• text – Text to modify.

• padding – New padding size. Defaults to 2.

Returns:

Text with updated padding.

openrig.naming.utils.add_suffix(text: str, suffix: str, separator: str = '_') → str

Adds a suffix to a text using a separator.

Parameters:

• text – Text to add the suffix to.

• suffix – The suffix to add.

• separator – The separator to use. Defaults to ‘_’.

Returns:

Text with the suffix added.

openrig.naming.utils.add_prefix(text: str, prefix: str, separator: str = '_') → str

Adds a prefix to a text using a separator.

Parameters:

• text – Text to add the prefix to.

• prefix – The prefix to add.

• separator – The separator to use. Defaults to ‘_’.

Returns:

Text with the prefix added.

openrig.naming.utils.add_text(text: str, text_to_add: str = '') → str

Adds a text to another text in PascalCase.

Parameters:

• text – The text to add to.

• text_to_add – The text to add. Defaults to ‘’.

Returns:

The text with the text_to_add added.

openrig.naming.utils.swap_substrings(text: str, mapping: dict[str, str] | None = None) → str

Swaps substrings in a text based on a mapping dictionary.

Performs a simultaneous replacement of all keys found in the mapping. This prevents double-swapping (e.g. L->R then R->L) and ensures robustness.

Parameters:

• text – The text to process.

• mapping – Dictionary mapping substrings (e.g., {‘_L_’: ‘_R_’}). If None, defaults to a standard side mapping (L/R, Left/Right).

Returns:

The text with substrings swapped if matches are found.

openrig.naming.utils.decrement_character(text: str) → str

Decrements a letter sequence in a manner similar to Excel column naming.

• Works for both uppercase and lowercase sequences

• Handles cases like ‘AAA’ → ‘ZZ’ and ‘aaa’ → ‘zz’

Parameters:

text – A text containing only letters (‘A’-‘Z’ or ‘a’-‘z’).

Returns:

The decremented letter sequence.

openrig.naming.utils.decrement_digit(text: str, remove_if_one: bool = True) → str

Decrements the last digit in a text.

Parameters:

• text – Text to decrement.

• remove_if_one – If True, removes the digit if it becomes 0 or 1. Defaults to True.

Returns:

Text with the decremented digit, or the original text if no digit is found.