earwax.utils module

Provides various utility functions used by Earwax.

earwax.utils.english_list(items: List[str], empty: str = 'Nothing', sep: str = ', ', and_: str = 'and ') → str

Given a list of strings, returns a string representing them as a list.

For example:

english_list([]) == 'Nothing'
english_list(['bananas']) == 'bananas'
english_list(['apples', 'bananas']) == 'apples, and bananas'
english_list(
    ['apples', 'bananas', 'oranges']
) == 'apples, bananas, and oranges'
english_list(['tea', 'coffee'], and_='or ') == 'tea, or coffee'
Parameters:
  • items – The items to turn into a string.
  • empty – The string to return if items is empty.
  • sep – The string to separate list items with.
  • and – The string to show before the last item in the list.
earwax.utils.format_timedelta(td: datetime.timedelta, *args, **kwargs) → str

Given a timedelta td, return it as a human readable time.

For example:

td = timedelta(days=400, hours=2, seconds=3)
format_timedelta(
    td
) == '1 year, 1 month, 4 days, 2 hours, and 3 seconds'

Note: It is assumed that a month always contains 31 days.

Parameters:
  • td – The time delta to work with.
  • args – The extra positional arguments to pass to english_list().
  • kwargs – The extra keyword arguments to pass onto english_list().
earwax.utils.nearest_square(n: int, allow_higher: bool = False) → int

Given a number n, find the nearest square number.

If allow_higher evaluates to True, return the first square higher than n. Otherwise, return the last square below n.

For example:

nearest_square(5) == 2  # 2 * 2 == 4
nearest_square(24, allow_higher=True) == 5  # 5 * 5 == 25
nearest_square(16) == 4
nearest_square(16, allow_higher=True) == 4
Parameters:n – The number whose nearest square should be returned.
earwax.utils.pluralise(n: int, single: str, multiple: Optional[str] = None) → str

If n == 1, return single. Otherwise return multiple.

If multiple is None, it will become single + 's'.

For example:

pluralise(1, 'axe') == 'axe'
pluralise(2, 'axe') == 'axes'
pluralise(1, 'person', multiple='people') == 'person'
pluralise(2, 'person', multiple='people') == 'people'
pluralise(0, 'person', multiple='people') == 'people'
Parameters:
  • n – The number of items we are dealing with.
  • single – The name of the thing when there is only 1.
  • multiple – The name of things when there are numbers other than 1.
earwax.utils.random_file(path: pathlib.Path) → pathlib.Path

Call recursively until a file is reached.

Parameters:path – The path to start with.