Formatting

The formatting helpers centralize string manipulation so your tools can produce consistent slugs, human-friendly labels, and tag suggestions.

Overview 

StringOperator exposes slugification, casing helpers, and word-level transformations that bundle common rules for mushtags and filenames:

Slugification applies transliteration, delimiter normalization, and abbreviation handling to create URL-safe identifiers.
Case conversion covers camelCase, snake_case, and title-case variants plus reversals for finetuning display labels.
Word operations offer splitting, joining, and inflection helpers that respect existing abbreviations and brand-safe capitalizations.
Abbreviation expansion lets you replace short forms with full phrases or abbreviations sourced from config or code.
Tag suggestion helps derive consistent namespace/build tags from raw phrases or file paths.

Quick Start 

from buvis.pybase.formatting import StringOperator

slug = StringOperator.slugify("BUVIS-CLI Utilities")
camel = StringOperator.camelize("cli_utilities")

print(slug)   # => "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, WordLevelTools, Abbr.

static as_graphql_field_name(text: str) → str

Convert text to a GraphQL-friendly PascalCase field name.

Parameters:: text – Text to normalize.
Returns:: A PascalCase representation suitable for GraphQL schemas.

Example

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

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 humanize(text: str) → str

Make an identifier more readable for humans.

Parameters:: text – Identifier in snake_case or camelCase.
Returns:: A human-readable string with spaces and capitalization.

Example

>>> StringOperator.humanize("first_name")
'First name'

static pluralize(text: str) → str

Return the plural form of the provided text.

Parameters:: text – Word to pluralize.
Returns:: Pluralized form of the word.

Example

>>> StringOperator.pluralize("mouse")
'mice'

static prepend(text: str, prepend_text: str) → str

Prepend a prefix when the text does not already start with it.

Parameters:

text – Target text.
prepend_text – Prefix to add when missing.

Returns:

The original text if the prefix exists, otherwise the prefixed text.

Example

>>> StringOperator.prepend("bar", "pre-")
'pre-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 singularize(text: str) → str

Return the singular form of the provided text.

Parameters:: text – Word to singularize.
Returns:: Singularized form of the word.

Example

>>> StringOperator.singularize("mice")
'mouse'

static slugify(text: str) → str

Create a URL-safe slug from the given text.

Parameters:: text – Input text to convert.
Returns:: A lowercase slug with unsafe characters replaced by hyphens.

Example

>>> StringOperator.slugify("Foo Bar!")
'foo-bar'

static suggest_tags(text: str, model: str, url: str = 'http://localhost:11434') → list[str]

Suggest tags for text via ollama API.

Parameters:

text – Text to analyze for tag candidates.
model – Ollama model name (e.g. “llama3.2:3b”).
url – Ollama base URL.

Returns:

A list of suggested tag strings, or empty list on error.

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_graphql_field_name(text: str) → str

Convert a string to a GraphQL-style field name (PascalCase).

Parameters:: text – Text to convert into PascalCase.
Returns:: PascalCase string suitable for GraphQL fields.

Example

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

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 humanize(text: str) → str

Turn an identifier into a human-readable phrase.

Parameters:: text – Lowercase string or identifier to make human readable.
Returns:: Human-readable string with spaces and capitalized words.

Example

>>> StringCaseTools.humanize('some_value')
'Some value'

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.word_level_tools.WordLevelTools

Bases: object

Word-level text manipulation utilities. Static utility class for singularization and pluralization. Wraps inflection library with domain-specific exceptions.

static pluralize(text: str) → str

Pluralize text unless it matches an exception like ‘minutes’.

Parameters:: text – Word to pluralize.
Returns:: Plural form of text, or the original text when it is exempted.

Example

>>> WordLevelTools.pluralize('minutes')
'minutes'
>>> WordLevelTools.pluralize('cat')
'cats'

static singularize(text: str) → str

Singularize text unless it matches an exception like ‘minutes’.

Parameters:: text – Word to singularize.
Returns:: Singular form of text, or the original text when it is exempted.

Example

>>> WordLevelTools.singularize('minutes')
'minutes'
>>> WordLevelTools.singularize('dogs')
'dog'

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'

Formatting

Overview

Quick Start

API Reference

Helper Classes

Overview 

Quick Start 

API Reference 

Helper Classes 