hbutils.string.inflection

Overview:

Useful utilities for word inflections.

This module provides a comprehensive set of functions for manipulating English words, including pluralization, singularization, case conversion, and string formatting utilities. It handles various irregular forms and special cases in English grammar.

camelize

hbutils.string.inflection.camelize(string: str, uppercase_first_letter: bool = True) → str[source]

Convert strings to CamelCase.

This function converts underscore-separated strings to CamelCase format. It can produce either UpperCamelCase or lowerCamelCase depending on the uppercase_first_letter parameter.

Parameters:

string (str) – Original string to convert.
uppercase_first_letter (bool) – If set to True, camelize() converts strings to UpperCamelCase. If set to False, camelize() produces lowerCamelCase. Defaults to True.

Returns:

The camelized string.

Return type:

str

Examples::

>>> camelize("device_type")
'DeviceType'
>>> camelize("device_type", False)
'deviceType'

Note

camelize() can be thought of as a inverse of underscore(), although there are some cases where that does not hold:

>>> camelize(underscore("IOError"))
'IoError'

dasherize

hbutils.string.inflection.dasherize(word: str) → str[source]

Replace underscores with dashes in the string.

This function converts underscore-separated strings to dash-separated strings, commonly used in URL slugs and CSS class names.

Parameters:: word (str) – Original word to dasherize.
Returns:: The dasherized string.
Return type:: str

Example::

>>> dasherize("puni_puni")
'puni-puni'

humanize

hbutils.string.inflection.humanize(word: str) → str[source]

Capitalize the first word and turn underscores into spaces and strip a trailing "_id", if any.

Like titleize(), this is meant for creating pretty output. This function is useful for converting database column names or variable names into human-readable strings.

Parameters:: word (str) – Original word to humanize.
Returns:: The humanized string.
Return type:: str

Examples::

>>> humanize("employee_salary")
'Employee salary'
>>> humanize("author_id")
'Author'

ordinal

hbutils.string.inflection.ordinal(number: int) → str[source]

Return the suffix that should be added to a number to denote the position in an ordered sequence such as 1st, 2nd, 3rd, 4th.

This function returns only the suffix (st, nd, rd, th), not the complete ordinal number. Use ordinalize() for the complete ordinal string.

Parameters:: number (int) – Int format number.
Returns:: The ordinal suffix for the number.
Return type:: str

Examples::

>>> ordinal(1)
'st'
>>> ordinal(2)
'nd'
>>> ordinal(1002)
'nd'
>>> ordinal(1003)
'rd'
>>> ordinal(-11)
'th'
>>> ordinal(-1021)
'st'

ordinalize

hbutils.string.inflection.ordinalize(number: int) → str[source]

Turn a number into an ordinal string used to denote the position in an ordered sequence such as 1st, 2nd, 3rd, 4th.

This function combines the number with its ordinal suffix to create a complete ordinal string.

Parameters:: number (int) – Int format number.
Returns:: The complete ordinal string.
Return type:: str

Examples::

>>> ordinalize(1)
'1st'
>>> ordinalize(2)
'2nd'
>>> ordinalize(1002)
'1002nd'
>>> ordinalize(1003)
'1003rd'
>>> ordinalize(-11)
'-11th'
>>> ordinalize(-1021)
'-1021st'

parameterize

hbutils.string.inflection.parameterize(string: str, separator: str = '-') → str[source]

Replace special characters in a string so that it may be used as part of a ‘pretty’ URL.

This function converts a string into a URL-friendly format by removing or replacing special characters, converting to lowercase, and using a separator for spaces. It’s commonly used for creating URL slugs.

Parameters:

string (str) – Original string to parameterize.
separator (str) – Separator of parameter words. Defaults to '-'.

Returns:

The parameterized string.

Return type:

str

Example::

>>> parameterize(u"Donald E. Knuth")
'donald-e-knuth'

pluralize

hbutils.string.inflection.pluralize(word: str) → str[source]

Return the plural form of a word.

This function converts singular English words to their plural forms, handling both regular and irregular pluralization rules. It preserves the case of the original word and handles uncountable nouns.

Parameters:: word (str) – Original word to pluralize.
Returns:: The plural form of the word.
Return type:: str

Examples::

>>> pluralize("posts")
'posts'
>>> pluralize("octopus")
'octopi'
>>> pluralize("sheep")
'sheep'
>>> pluralize("CamelOctopus")
'CamelOctopi'

singularize

hbutils.string.inflection.singularize(word: str) → str[source]

Return the singular form of a word, the reverse of pluralize().

This function converts plural English words to their singular forms, handling both regular and irregular singularization rules. It preserves the case of the original word and handles uncountable nouns.

Parameters:: word (str) – Original word to singularize.
Returns:: The singular form of the word.
Return type:: str

Examples::

>>> singularize("posts")
'post'
>>> singularize("octopi")
'octopus'
>>> singularize("sheep")
'sheep'
>>> singularize("word")
'word'
>>> singularize("CamelOctopi")
'CamelOctopus'

tableize

hbutils.string.inflection.tableize(word: str) → str[source]

Create the name of a table like Rails does for models to table names.

This method uses the pluralize() method on the last word in the string after converting it to underscore format. It’s commonly used in ORM frameworks to generate database table names from model class names.

Parameters:: word (str) – Original word to tableize.
Returns:: The tableized string.
Return type:: str

Examples::

>>> tableize('RawScaledScorer')
'raw_scaled_scorers'
>>> tableize('egg_and_ham')
'egg_and_hams'
>>> tableize('fancyCategory')
'fancy_categories'

titleize

hbutils.string.inflection.titleize(word: str) → str[source]

Capitalize all the words and replace some characters in the string to create a nicer looking title.

titleize() is meant for creating pretty output. It converts strings to title case, capitalizing the first letter of each word and replacing underscores and hyphens with spaces.

Parameters:: word (str) – Original word to titleize.
Returns:: The titleized string.
Return type:: str

Examples::

>>> titleize("man from the boondocks")
'Man From The Boondocks'
>>> titleize("x-men: the last stand")
'X Men: The Last Stand'
>>> titleize("TheManWithoutAPast")
'The Man Without A Past'
>>> titleize("raiders_of_the_lost_ark")
'Raiders Of The Lost Ark'

transliterate

hbutils.string.inflection.transliterate(string: str) → str[source]

Replace non-ASCII characters with an ASCII approximation.

If no approximation exists, the non-ASCII character is ignored. The string must be unicode. This is useful for creating URL-safe strings from text containing accented characters or other non-ASCII symbols.

Parameters:: string (str) – Original string to transliterate.
Returns:: The transliterated ASCII string.
Return type:: str

Examples::

>>> transliterate('älämölö')
'alamolo'
>>> transliterate('Ærøskøbing')
'rskbing'

underscore

hbutils.string.inflection.underscore(word: str) → str[source]

Make an underscored, lowercase form from the expression in the string.

This function converts CamelCase strings to underscore_separated strings. It’s commonly used for converting class names to file names or database column names.

Parameters:: word (str) – Original word to underscore.
Returns:: The underscored string.
Return type:: str

Example::

>>> underscore("DeviceType")
'device_type'

Note

As a rule of thumb you can think of underscore() as the inverse of camelize(), though there are cases where that does not hold:

>>> camelize(underscore("IOError"))
'IoError'