Skip to content

humanfriendly

Copied from the main module of the humanfriendly package.

format_size(num_bytes, keep_width=False, binary=False)

Format a byte count as a human readable file size.

:param num_bytes: The size to format in bytes (an integer). :param keep_width: :data:True if trailing zeros should not be stripped, :data:False if they can be stripped. :param binary: :data:True to use binary multiples of bytes (base-2), :data:False to use decimal multiples of bytes (base-10). :returns: The corresponding human readable file size (a string).

This function knows how to format sizes in bytes, kilobytes, megabytes, gigabytes, terabytes and petabytes. Some examples:

from humanfriendly import format_size format_size(0) '0 bytes' format_size(1) '1 byte' format_size(5) '5 bytes' format_size(1000) '1 KB' format_size(1024, binary=True) '1 KiB' format_size(1000 ** 3 * 4) '4 GB'

Source code in speechain/utilbox/humanfriendly.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def format_size(num_bytes, keep_width=False, binary=False):
    """Format a byte count as a human readable file size.

    :param num_bytes: The size to format in bytes (an integer).
    :param keep_width: :data:`True` if trailing zeros should not be stripped,
                       :data:`False` if they can be stripped.
    :param binary: :data:`True` to use binary multiples of bytes (base-2),
                   :data:`False` to use decimal multiples of bytes (base-10).
    :returns: The corresponding human readable file size (a string).

    This function knows how to format sizes in bytes, kilobytes, megabytes,
    gigabytes, terabytes and petabytes. Some examples:

    >>> from humanfriendly import format_size
    >>> format_size(0)
    '0 bytes'
    >>> format_size(1)
    '1 byte'
    >>> format_size(5)
    '5 bytes'
    > format_size(1000)
    '1 KB'
    > format_size(1024, binary=True)
    '1 KiB'
    >>> format_size(1000 ** 3 * 4)
    '4 GB'
    """
    for unit in reversed(disk_size_units):
        if num_bytes >= unit.binary.divider and binary:
            number = round_number(
                float(num_bytes) / unit.binary.divider, keep_width=keep_width
            )
            return pluralize(number, unit.binary.symbol, unit.binary.symbol)
        elif num_bytes >= unit.decimal.divider and not binary:
            number = round_number(
                float(num_bytes) / unit.decimal.divider, keep_width=keep_width
            )
            return pluralize(number, unit.decimal.symbol, unit.decimal.symbol)
    return pluralize(num_bytes, "byte")

pluralize(count, singular, plural=None)

Combine a count with the singular or plural form of a word.

:param count: The count (a number). :param singular: The singular form of the word (a string). :param plural: The plural form of the word (a string or :data:None). :returns: The count and singular or plural word concatenated (a string).

See :func:pluralize_raw() for the logic underneath :func:pluralize().

Source code in speechain/utilbox/humanfriendly.py 
 97
 98
 99
100
101
102
103
104
105
106
107
def pluralize(count, singular, plural=None):
    """Combine a count with the singular or plural form of a word.

    :param count: The count (a number).
    :param singular: The singular form of the word (a string).
    :param plural: The plural form of the word (a string or :data:`None`).
    :returns: The count and singular or plural word concatenated (a string).

    See :func:`pluralize_raw()` for the logic underneath :func:`pluralize()`.
    """
    return "%s %s" % (count, pluralize_raw(count, singular, plural))

pluralize_raw(count, singular, plural=None)

Select the singular or plural form of a word based on a count.

:param count: The count (a number). :param singular: The singular form of the word (a string). :param plural: The plural form of the word (a string or :data:None). :returns: The singular or plural form of the word (a string).

When the given count is exactly 1.0 the singular form of the word is selected, in all other cases the plural form of the word is selected.

If the plural form of the word is not provided it is obtained by concatenating the singular form of the word with the letter "s". Of course this will not always be correct, which is why you have the option to specify both forms.

Source code in speechain/utilbox/humanfriendly.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def pluralize_raw(count, singular, plural=None):
    """Select the singular or plural form of a word based on a count.

    :param count: The count (a number).
    :param singular: The singular form of the word (a string).
    :param plural: The plural form of the word (a string or :data:`None`).
    :returns: The singular or plural form of the word (a string).

    When the given count is exactly 1.0 the singular form of the word is
    selected, in all other cases the plural form of the word is selected.

    If the plural form of the word is not provided it is obtained by
    concatenating the singular form of the word with the letter "s". Of course
    this will not always be correct, which is why you have the option to
    specify both forms.
    """
    if not plural:
        plural = singular + "s"
    return singular if float(count) == 1.0 else plural

round_number(count, keep_width=False)

Round a floating point number to two decimal places in a human friendly format.

:param count: The number to format. :param keep_width: :data:True if trailing zeros should not be stripped, :data:False if they can be stripped. :returns: The formatted number as a string. If no decimal places are required to represent the number, they will be omitted.

The main purpose of this function is to be used by functions like :func:format_length(), :func:format_size() and :func:format_timespan().

Here are some examples:

from humanfriendly import round_number round_number(1) '1' round_number(math.pi) '3.14' round_number(5.001) '5'

Source code in speechain/utilbox/humanfriendly.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def round_number(count, keep_width=False):
    """Round a floating point number to two decimal places in a human friendly format.

    :param count: The number to format.
    :param keep_width: :data:`True` if trailing zeros should not be stripped,
                       :data:`False` if they can be stripped.
    :returns: The formatted number as a string. If no decimal places are
              required to represent the number, they will be omitted.

    The main purpose of this function is to be used by functions like
    :func:`format_length()`, :func:`format_size()` and
    :func:`format_timespan()`.

    Here are some examples:

    >>> from humanfriendly import round_number
    >>> round_number(1)
    '1'
    >>> round_number(math.pi)
    '3.14'
    >>> round_number(5.001)
    '5'
    """
    text = "%.2f" % float(count)
    if not keep_width:
        text = re.sub("0+$", "", text)
        text = re.sub(r"\.$", "", text)
    return text