Welcome to si-prefix’s documentation!

si_prefix

Functions for formatting numbers according to SI standards.

Example usage:

from si_prefix import si_format

print si_format(.5)
# 500.0 m  (default precision is 1)

print si_format(.01331, precision=2)
# 13.31 m

print si_format(1331, precision=2)
# 1.33 k

print si_format(1331, precision=0)
# 1 k

Changelog

  • 1.0: use unicode strings and use µ (i.e., \N{MICRO SIGN}) to denote micro (not u).
    • Note: switching to unicode strings is an API-breaking change and may break code expecting a ``str`` return type.
    • See issue #4 for more details.
  • 0.5: change license to 3-clause BSD
  • 0.4.1: add space before unit prefix
  • 0.4: add Python 3 support, si_parse function
  • 0.2: bug fixes
  • 0.1: initial release

Credits

Written by Christian Fobel christian@fobel.net

Ported from C version written by Jukka “Yucca” Korpela

Contributors

Python 3 support: olehermanse

License

This project is licensed under the terms of the BSD 3-clause license


API

si_prefix.CRE_SI_NUMBER = <_sre.SRE_Pattern object at 0x2fe76c0>

Changed in version 1.0: Use unicode string for SI unit to support micro (i.e., µ) character.

See also

Issue #4.

si_prefix.SI_PREFIX_UNITS = u'yzafpn\xb5m kMGTPEZY'

Changed in version 1.0: Define as unicode string and use µ (i.e., \N{MICRO SIGN}, \x0b5) to denote micro (not u).

See also

Issue #4.

Forum post discussing unicode using µ as an example.

The International System of Units (SI) report from the Bureau International des Poids et Mesures

si_prefix.prefix(expof10)[source]
Parameters:expof10 – Exponent of a power of 10 associated with a SI unit character.
Returns:One of the characters in “yzafpnum kMGTPEZY”.
Return type:str
si_prefix.si_format(value, precision=1, format_str=u'{value} {prefix}', exp_format_str=u'{value}e{expof10}')[source]

Format value to string with SI prefix, using the specified precision.

Parameters:
  • value (int, float) – Input value.
  • precision (int) – Number of digits after decimal place to include.
  • format_str (str or unicode) – Format string where {prefix} and {value} represent the SI prefix and the value (scaled according to the prefix), respectively. The default format matches the SI prefix style format.
  • exp_str (str or unicode) – Format string where {expof10} and {value} represent the exponent of 10 and the value (scaled according to the exponent of 10), respectively. This format is used if the absolute exponent of 10 value is greater than 24.
Returns:

value formatted according to the SI prefix style.

Return type:

unicode

Examples

For example, with precision=2:

1e-27 --> 1.00e-27
1.764e-24 --> 1.76 y
7.4088e-23 --> 74.09 y
3.1117e-21 --> 3.11 z
1.30691e-19 --> 130.69 z
5.48903e-18 --> 5.49 a
2.30539e-16 --> 230.54 a
9.68265e-15 --> 9.68 f
4.06671e-13 --> 406.67 f
1.70802e-11 --> 17.08 p
7.17368e-10 --> 717.37 p
3.01295e-08 --> 30.13 n
1.26544e-06 --> 1.27 u
5.31484e-05 --> 53.15 u
0.00223223 --> 2.23 m
0.0937537 --> 93.75 m
3.93766 --> 3.94
165.382 --> 165.38
6946.03 --> 6.95 k
291733 --> 291.73 k
1.22528e+07 --> 12.25 M
5.14617e+08 --> 514.62 M
2.16139e+10 --> 21.61 G
9.07785e+11 --> 907.78 G
3.8127e+13 --> 38.13 T
1.60133e+15 --> 1.60 P
6.7256e+16 --> 67.26 P
2.82475e+18 --> 2.82 E
1.1864e+20 --> 118.64 E
4.98286e+21 --> 4.98 Z
2.0928e+23 --> 209.28 Z
8.78977e+24 --> 8.79 Y
3.6917e+26 --> 369.17 Y
1.55051e+28 --> 15.51e+27
6.51216e+29 --> 651.22e+27

Changed in version 1.0: Use unicode string for format_str and SI value format string to support micro (i.e., µ) characte, and change return type to unicode string.

See also

Issue #4.

si_prefix.si_parse(value)[source]

Parse a value expressed using SI prefix units to a floating point number.

Parameters:value (str or unicode) – Value expressed using SI prefix units (as returned by si_format() function).

Changed in version 1.0: Use unicode string for SI unit to support micro (i.e., µ) character.

See also

Issue #4.

si_prefix.si_prefix_expof10(si_unit)[source]
Parameters:si_unit (str) – SI unit character, i.e., one of “yzafpnµm kMGTPEZY”.
Returns:Exponent of the power of ten associated with si_unit, e.g., 3 for si_unit=k and -6 for si_unit=µ.
Return type:int
si_prefix.si_prefix_scale(si_unit)[source]
Parameters:si_unit (str) – SI unit character, i.e., one of “yzafpnµm kMGTPEZY”.
Returns:Multiple associated with si_unit, e.g., 1000 for si_unit=k.
Return type:int
si_prefix.split(value, precision=1)[source]

Split value into value and “exponent-of-10”, where “exponent-of-10” is a multiple of 3. This corresponds to SI prefixes.

Returns tuple, where the second value is the “exponent-of-10” and the first value is value divided by the “exponent-of-10”.

Parameters:
  • value (int, float) – Input value.
  • precision (int) – Number of digits after decimal place to include.
Returns:

The second value is the “exponent-of-10” and the first value is value divided by the “exponent-of-10”.

Return type:

tuple

Examples

si_prefix.split(0.04781)   ->  (47.8, -3)
si_prefix.split(4781.123)  ->  (4.8, 3)

See si_format() for more examples.

Indices and tables