# HG changeset patch # User sluggoster@gmail.com # Date 1270005854 25200 # Branch trunk # Node ID 55f60b3b54ed339f3085a3a361b0704669e6179e # Parent d5121c3c978a0725de4e76a3711db44589381da7 Docs. diff --git a/docs/modules/number.rst b/docs/modules/number.rst --- a/docs/modules/number.rst +++ b/docs/modules/number.rst @@ -5,13 +5,13 @@ .. currentmodule:: webhelpers.number -Functions ---------- +Calculations +------------ .. autofunction:: percent_of -.. autofunction:: format_data_size -.. autofunction:: format_byte_size -.. autofunction:: format_bit_size + +Statistics +---------- .. autofunction:: mean .. function:: average(r) @@ -22,12 +22,16 @@ .. autofunction:: standard_deviation .. autofunction:: format_number -Classes -------- - .. autoclass:: SimpleStats :members: __call__, extend .. autoclass:: Stats :members: __call__, extend, finish +Number formatting +----------------- + +.. autofunction:: format_data_size +.. autofunction:: format_byte_size +.. autofunction:: format_bit_size + diff --git a/webhelpers/number.py b/webhelpers/number.py --- a/webhelpers/number.py +++ b/webhelpers/number.py @@ -1,8 +1,10 @@ -"""Number formatting, numeric helpers, and numeric statistics""" +"""Number formatting, numeric helpers, and numeric statistics.""" import math import re +#### Calculations #### + def percent_of(part, whole): """What percent of ``whole`` is ``part``? @@ -14,104 +16,7 @@ # Use float to force true division. return float(part * 100) / whole -def format_data_size(size, unit, precision=1, binary=False, full_name=False): - """Format a number using SI units (kilo, mega, etc.) - - ``size``: The number as a float or int. - - ``unit``: The unit name in plural form. Examples: "bytes", "B". - - ``precision``: How many digits to the right of the decimal point. Default - is 1. 0 suppresses the decimal point. - - ``binary``: If false, use base-10 decimal prefixes (kilo = K = 1000). - If true, use base-2 binary prefixes (kibi = Ki = 1024). - - ``full_name``: If false (default), use the prefix abbreviation ("k" or - "Ki"). If true, use the full prefix ("kilo" or "kibi"). If false, - use abbreviation ("k" or "Ki"). - - Examples: - - >>> format_data_size(1024, "B") - '1.0 kB' - - >>> format_data_size(1024, "B", 2) - '1.02 kB' - - >>> format_data_size(1024, "B", 2, binary=True) - '1.00 KiB' - - >>> format_data_size(54000, "Wh", 0) - '54 kWh' - - >>> format_data_size(85000, "m/h", 0) - '85 km/h' - - >>> format_data_size(85000, "m/h", 0).replace("km/h", "clicks") - '85 clicks' - """ - # Contributed by Wojciech Malinowski - if full_name is None: - full_name = len(unit) > 1 - - if not binary: - base = 1000 - if full_name: - multiples = ('', 'kilo', 'mega', 'giga', 'tera', 'peta', 'exa', 'zetta', 'yotta') - else: - multiples = ('', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y') - else: - base = 1024 - if full_name: - multiples = ('', 'kibi', 'mebi', 'gibi', 'tebi', 'pebi', 'exbi', 'zebi', 'yobi') - else: - multiples = ('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi') - - m = int(math.log(size) / math.log(base)) - if m > 8: - m = 8 - - if m == 0: - precision = '%.0f' - else: - precision = '%%.%df' % precision - - size = precision % (size / math.pow(base, m)) - - return '%s %s%s' % (size.strip(), multiples[m], unit) - -def format_byte_size(size, precision=1, binary=False, full_name=False): - """Same as ``format_data_size`` but specifically for bytes. - - Examples: - - >>> format_byte_size(2048) - '2.0 kB' - - >>> format_byte_size(2048, full_name=True) - '2.0 kilobytes' - """ - if full_name: - return format_data_size(size, "bytes", precision, binary, True) - else: - return format_data_size(size, "B", precision, binary, False) - -def format_bit_size(size, precision=1, binary=False, full_name=False): - """Same as ``format_data_size`` but specifically for bytes. - - Examples: - - >>> format_bit_size(2048) - '2.0 kb' - - >>> format_bit_size(2048, full_name=True) - '2.0 kilobits' - """ - if full_name: - return format_data_size(size, "bits", precision, binary, True) - else: - return format_data_size(size, "b", precision, binary, False) +#### Statistics #### def mean(r): """Return the mean (i.e., average) of a sequence of numbers. @@ -404,6 +309,7 @@ """Finish the subclass statistics now that all data are known.""" pass +#### Number formatting #### def format_number(n, thousands=",", decimal="."): """Format a number with a thousands separator and decimal delimeter. @@ -438,6 +344,98 @@ parts[0]) return decimal.join(parts) +def format_data_size(size, unit, precision=1, binary=False, full_name=False): + """Format a number using SI units (kilo, mega, etc.). + + ``size``: The number as a float or int. + + ``unit``: The unit name in plural form. Examples: "bytes", "B". + + ``precision``: How many digits to the right of the decimal point. Default + is 1. 0 suppresses the decimal point. + + ``binary``: If false, use base-10 decimal prefixes (kilo = K = 1000). + If true, use base-2 binary prefixes (kibi = Ki = 1024). + + ``full_name``: If false (default), use the prefix abbreviation ("k" or + "Ki"). If true, use the full prefix ("kilo" or "kibi"). If false, + use abbreviation ("k" or "Ki"). + + Examples: + + >>> format_data_size(1024, "B") + '1.0 kB' + >>> format_data_size(1024, "B", 2) + '1.02 kB' + >>> format_data_size(1024, "B", 2, binary=True) + '1.00 KiB' + >>> format_data_size(54000, "Wh", 0) + '54 kWh' + >>> format_data_size(85000, "m/h", 0) + '85 km/h' + >>> format_data_size(85000, "m/h", 0).replace("km/h", "klicks") + '85 klicks' + """ + # Contributed by Wojciech Malinowski + if full_name is None: + full_name = len(unit) > 1 + + if not binary: + base = 1000 + if full_name: + multiples = ('', 'kilo', 'mega', 'giga', 'tera', 'peta', 'exa', 'zetta', 'yotta') + else: + multiples = ('', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y') + else: + base = 1024 + if full_name: + multiples = ('', 'kibi', 'mebi', 'gibi', 'tebi', 'pebi', 'exbi', 'zebi', 'yobi') + else: + multiples = ('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi') + + m = int(math.log(size) / math.log(base)) + if m > 8: + m = 8 + + if m == 0: + precision = '%.0f' + else: + precision = '%%.%df' % precision + + size = precision % (size / math.pow(base, m)) + + return '%s %s%s' % (size.strip(), multiples[m], unit) + +def format_byte_size(size, precision=1, binary=False, full_name=False): + """Same as ``format_data_size`` but specifically for bytes. + + Examples: + + >>> format_byte_size(2048) + '2.0 kB' + >>> format_byte_size(2048, full_name=True) + '2.0 kilobytes' + """ + if full_name: + return format_data_size(size, "bytes", precision, binary, True) + else: + return format_data_size(size, "B", precision, binary, False) + +def format_bit_size(size, precision=1, binary=False, full_name=False): + """Same as ``format_data_size`` but specifically for bytes. + + Examples: + + >>> format_bit_size(2048) + '2.0 kb' + >>> format_bit_size(2048, full_name=True) + '2.0 kilobits' + """ + if full_name: + return format_data_size(size, "bits", precision, binary, True) + else: + return format_data_size(size, "b", precision, binary, False) + if __name__ == "__main__": import doctest doctest.testmod()