Formatting

The formatting helpers centralize string manipulation so your tools can produce consistent field names and human-friendly labels.

Overview

StringOperator exposes casing helpers and abbreviation handling that bundle common rules for note fields and titles:

• Case conversion covers camelCase and snake_case plus note-field (kebab-case) normalization for display labels and metadata keys.

• Abbreviation expansion lets you replace short forms with full phrases or abbreviations sourced from config or code.

• Whitespace helpers collapse and shorten text for compact display.

Quick Start

from buvis.pybase.formatting import StringOperator

field = StringOperator.as_note_field_name("BUVIS CLI Utilities")
camel = StringOperator.camelize("cli_utilities")

print(field)  # => "buvis-cli-utilities"
print(camel)  # => "CliUtilities"

API Reference

class buvis.pybase.formatting.StringOperator

Bases: object

Facade class providing unified string manipulation operations.

All methods are static. Delegates to StringCaseTools and Abbr.

static as_note_field_name(text: str) → str

Convert text to a lowercase, hyphen-delimited note field name.

Parameters:

text – Text to normalize.

Returns:

A lowercase string with hyphen separators.

Example

>>> StringOperator.as_note_field_name("Note Title")
'note-title'

static camelize(text: str) → str

Convert text to CamelCase.

Parameters:

text – Text to convert.

Returns:

A CamelCase string.

Example

>>> StringOperator.camelize("first_name")
'FirstName'

static collapse(text: str) → str

Collapse whitespace and strip the ends of the text.

Parameters:

text – Raw text that may contain repeated whitespace.

Returns:

The text with internal whitespace collapsed and trimmed.

Example

>>> StringOperator.collapse("  foo   bar ")
'foo bar'

static replace_abbreviations(text: str = '', abbreviations: list[dict[str, str | None] | str] | None = None, level: int = 0) → str

Replace abbreviations within the text using configured levels.

Parameters:

• text – Text containing abbreviations to replace.

• abbreviations – Mapping of abbreviations to expanded text.

• level – Expansion level (0=case fix, 4=long text plus abbreviation).

Returns:

The text with abbreviations expanded according to the level.

Example

>>> StringOperator.replace_abbreviations(
...     "Send an API request",
...     [{"API": "Application Programming Interface<<Application Programming Interface>>"}],
...     level=2,
... )
'Send an Application Programming Interface (API) request'

static shorten(text: str, limit: int, suffix_length: int) → str

Truncate text while preserving a suffix and inserting ellipsis.

Parameters:

• text – Text to truncate.

• limit – Maximum length of the returned string.

• suffix_length – Number of characters to keep from the end after ellipsis.

Returns:

A shortened string with an ellipsis if truncation occurred.

Example

>>> StringOperator.shorten("short", 10, 2)
'short'

static underscore(text: str) → str

Convert text to snake_case.

Parameters:

text – String to convert.

Returns:

A snake_case version of the text.

Example

>>> StringOperator.underscore("FirstName")
'first_name'

Helper Classes

class buvis.pybase.formatting.string_operator.string_case_tools.StringCaseTools

Bases: object

String case conversion utilities.

Static utility class for converting strings between naming conventions. Wraps the inflection library with BUVIS-specific field naming conventions.

static as_note_field_name(text: str) → str

Make a string safe for note field names (kebab-case).

Parameters:

text – Text to convert into a note field identifier.

Returns:

Kebab-case representation of the input text.

Example

>>> StringCaseTools.as_note_field_name('SomeValue')
'some-value'

static camelize(text: str) → str

Convert a string into CamelCase, respecting hyphen separators.

Parameters:

text – Text containing hyphens or underscores.

Returns:

CamelCase representation of the input text.

Example

>>> StringCaseTools.camelize('some-name')
'SomeName'

static underscore(text: str) → str

Convert a string into snake_case.

Parameters:

text – Text to convert.

Returns:

Snake_case version of the input text.

Example

>>> StringCaseTools.underscore('SomeValue')
'some_value'

class buvis.pybase.formatting.string_operator.abbr.Abbr

Bases: object

Abbreviation replacement utility.

Provides static methods for expanding abbreviations in text with configurable expansion levels.

static replace_abbreviations(text: str = '', abbreviations: list[dict[str, str | None] | str] | None = None, level: int = 0) → str

Expand abbreviations found in the provided text.

Parameters:

• text – The text to process.

• abbreviations – A list of dictionaries that map abbreviations to expansion strings, where an expansion can include an optional long form delimited by << and >> (e.g. {"API": "App<<Application Programming Interface>>"}).

• level – Determines how much of the expansion to use (0=fix case, 1=short, 2=short+(abbr), 3=long, 4=long+(abbr)).

Returns:

A string where each abbreviation is replaced according to level.

Example:

>>> Abbr.replace_abbreviations("Use the API", [{"API": "App"}], 1)
'Use the App'