ReadableNumber#

class readable_number.readable_number.ReadableNumber(num: Optional[Union[float, int]] = None, digit_group_size: int = 3, digit_group_delimiter: str = ',', decimal_symbol: str = '.', precision: Optional[int] = None, significant_figures_after_decimal_point: Optional[int] = None, show_decimal_part_if_integer: bool = False, use_shortform: bool = False, use_exponent_for_large_numbers: bool = False, large_number_threshold: int = 1000000, use_exponent_for_small_numbers: bool = False, small_number_threshold: float = 1e-06)[source]#

Bases: object

A class to hold a number for human-readable printing.

Showing an arbitrary number in a human-readable way is far from trivial, because real-world numbers come in various forms. This is why there are many options in this class for users to tune. That said, the default options of this class generally give a pretty good result.

Parameters:

  • num (Optional[Union[float, int]]) – A number to be printed in a readable format. If None, it means you are only initializing an “empty” object with printing options. In that case, you can use the of() method later to print the readable result.

  • digit_group_size (int) – The size of the digit group (in the integer part). For example, if 3, the number 123456789 will be printed as 123,456,789. If 0, no grouping will happen. Only non-negative integers are allowed. (Default: 3)

  • digit_group_delimiter (str) – The symbol to delimit the digit groups. For example, if it is a space, the number 1234567 will be printed as 1 234 567. (Default: “,”)

  • decimal_symbol (str) – The symbol to use as a decimal “point”. Default: “.”

  • precision (Optional[int]) – How many digits to keep in the decimal part. For example, if 3, the number -4.56789 will be printed as -4.568. If 0, the number -75.924 will be printed as “-76.” (including the dot). If None, the number will be printed in a “natural” way. For example, 3.1415926 will be printed as “3.1415926”. But if the given number has more than 15 digits after the decimal point, only the first 15 digits will be preserved due to the limit of the double-precision system.

  • significant_figures_after_decimal_point (Optional[int]) – How many significant figures to display after the decimal point. “Significant figures” and “precision” are different concepts. Please refer to https://en.wikipedia.org/wiki/Significant_figures for more details. If one of precision and significant_figures is not None, the other must be None. If both are None, the given number will be printed in a “natural” way.

  • show_decimal_part_if_integer (bool) – Whether to show the decimal part if the given number is an integer. If this is false, it overrides precision. If this is true, the number of digits to show will be determined by precision (if precision is None, 2 digits will be used as per convention). Default: False.

  • use_shortform (bool) – If true, for large numbers, use notations such as “12.5k”, “5.6M”, etc. Currently, the largest supported unit is T (trillion). Numbers whose absolute values are larger than 1,000 trillion will be printed as something like “1535663T”.

  • use_exponent_for_large_numbers (bool) – Whether to use exponential notation (such as 1.2e+05) to represent large numbers. Default: False.

  • large_number_threshold (int) – If num’s absolute value is beyond (≥) this cutoff value, we consider it a large number. Default: 1,000,000.

  • use_exponent_for_small_numbers (bool) – Whether to use exponential notation (such as 1.2e-05) to represent small numbers. Default: False.

  • small_number_threshold (float) – If num’s absolute value is blow (≤) this cutoff value, we consider it to be a small number. Default: 1 × 10⁻⁶.

Examples

>>> from readable_number import ReadableNumber
>>> str(ReadableNumber(1234.567))
>>> rn = ReadableNumber()  # alternative way to print numbers
>>> rn.of(1234.567)

Methods Summary

deepcopy()

Make a deep copy of itself

of(num)

Print the number num in a readable format.

Methods Documentation

deepcopy() → ReadableNumber[source]#

Make a deep copy of itself

of(num: Union[float, int]) → str[source]#

Print the number num in a readable format. This method is useful when you don’t want to repeatedly specify the same options when printing many numbers.

Parameters:

num (Union[float, int]) – The number to be printed

Returns:

The number in a readable format

Return type:

str

Examples

>>> from readable_number import ReadableNumber
>>> rn = ReadableNumber()
>>> rn.of(1234.567)