Source code for hbutils.string.plural

"""
Overview:
    Useful utilities for pluralize your words.
"""
import warnings
from functools import lru_cache
from typing import Optional

try:
    import inflect
except ImportError:
    from ..system import pip_install

    pip_install(['inflect>=5.2.0'], silent=True)
    import inflect

__all__ = ['plural_form', 'plural_word', 'singular_form']


@lru_cache()
def _default_engine():
    return inflect.engine()


[docs]def plural_form(word: str, engine: Optional[inflect.engine] = None) -> str: """ Overview: Get the pluralized form of the given ``word``. Arguments: - word (:obj:`str`): The given word to be pluralized. - engine (:obj:`Optional[inflect.engine]`): Engine to be used, \ default is ``None`` which means just use the default one. Returns: - pluralized (:obj:`str`): Pluralized word. Examples:: >>> from hbutils.string import plural_form >>> plural_form('it') 'they' >>> plural_form('word') 'words' >>> plural_form('woman') 'women' """ engine = engine or _default_engine() return engine.plural(word)
[docs]def singular_form(word: str, engine: Optional[inflect.engine] = None) -> str: """ Overview: Get the singular form of the given ``word``. Arguments: - word (:obj:`str`): The given word to be singularized. - engine (:obj:`Optional[inflect.engine]`): Engine to be used, \ default is ``None`` which means just use the default one. Returns: - single (:obj:`str`): Singular form of word. Examples:: >>> from hbutils.string import singular_form >>> singular_form('they') 'it' >>> singular_form('them') 'it' >>> singular_form('it') 'it' >>> singular_form('women') 'woman' >>> singular_form('words') 'word' >>> singular_form('themselves') 'itself' """ engine = engine or _default_engine() result = engine.singular_noun(word) if not result: # already a singular form return word else: return result
[docs]def plural_word(count: int, word: str, num_text: bool = False, num_threshold: Optional[int] = None, engine: Optional[inflect.engine] = None) -> str: """ Overview: Get plural form of the whole word, with the number before the word. Arguments: - count (:obj:`int`): Count of the word, should be a non-negative integer. - word (:obj:`str`): Word to be pluralized. - num_text (:obj:`bool`): Show the number as text format or not, \ default is ``False`` which means just use the arabic number for all the cases. - num_threshold (:obj:`Optional[int]`): Threshold value when the number is shown as text, \ default is ``None`` which means just use english text format for all the cases. - engine (:obj:`Optional[inflect.engine]`): Engine to be used, \ default is ``None`` which means just use the default one. Returns: - plural_word (:obj:`str`): Pluralized word, with the number. Examples:: >>> from hbutils.string import plural_word >>> plural_word(0, 'word') '0 words' >>> plural_word(1, 'word') '1 word' >>> plural_word(2, 'word') '2 words' >>> plural_word(20, 'word') '20 words' >>> plural_word(233, 'word') '233 words' >>> plural_word(20, 'word', num_text=True) 'twenty words' >>> plural_word(233, 'word', num_text=True) 'two hundred and thirty-three words' >>> plural_word(20, 'word', num_text=True, num_threshold=99) 'twenty words' >>> plural_word(233, 'word', num_text=True, num_threshold=99) '233 words' """ engine = engine or _default_engine() if num_text: number = engine.number_to_words(count, threshold=num_threshold) else: if num_threshold is not None: warnings.warn(UserWarning('Text-formatted number is not enabled, ' 'so the num_threshold argument will be ignored.'), stacklevel=2) number = str(count) single_word = singular_form(word, engine) final_word = engine.plural(single_word, count) return f'{number} {final_word}'