Skip to content

Rockhopper-Technologies/prefixed

Repository files navigation

Documentation Status GitHub Actions Status Coverage Status
PyPI Package latest release Supported versions Supported implementations

Overview

Prefixed provides an alternative implementation of the built-in float which supports formatted output with SI (decimal) and IEC (binary) prefixes.

>>> from prefixed import Float

>>> f'{Float(3250):.2h}'
'3.25k'

>>> '{:.2h}s'.format(Float(.00001534))
'15.34μs'

>>> '{:.2k}B'.format(Float(42467328))
'40.50MiB'

>>> f'{Float(2048):.2m}B'
'2.00KB'

Because prefixed.Float inherits from the built-in float, it behaves exactly the same in most cases.

When a math operation is performed with another real number type (float, int), the result will be a prefixed.Float instance.

Presentation Types

Additional presentation types 'h', 'H', 'k', 'K', 'm', and 'M' are supported for f-strings and format().

Type Meaning
'h' SI format. Outputs the number with closest divisible SI prefix. (k, M, G, ...)
'H' Same as 'h' with precision indicating significant digits.
'k' IEC Format. Outputs the number with closest divisible IEC prefix. (Ki, Mi, Gi, ...)
'K' Same as 'k' with precision indicating significant digits.
'm' Short IEC Format. Same as 'k' but only a single character. (K, M, G, ...)
'M' Same as 'm' with precision indicating significant digits.
   
'j' Alias for 'k' - DEPRECATED
'J' Alias for 'm' - DEPRECATED

String Initialization

When initializing from strings, SI and IEC prefixes are honored

>>> Float('2k')
Float(2000.0)

>>> Float('2Ki')
Float(2048.0)

Additional Flags

An additional format flag '!' is available which adds a space before the prefix

>>> f'{Float(3250):!.2h}'
'3.25 k'

Significant Digits

When the 'H', 'K, or 'M' presentation types are used, precision is treated as the number of significant digits to include. Standard rounding will occur for the final digit.

>>> f'{Float(1246):.3h}'
'1.246k'

>>> f'{Float(1246):.3H}'
'1.25k'

By default, trailing zeros are removed.

>>> f'{Float(1000):.3H}'
'1k'

To preserve trailing zeros, include the '#' flag.

>>> f'{Float(1000):#.3H}'
'1.00k'

Adjustable Thresholds

An additional field, margin, can be specified which lowers or raises the threshold for for each prefix by the given percentage. Margin is specified before precision with the syntax %[-]digit+.

>>> f'{Float(950):.2h}'
'950.00'

>>> f'{Float(950):%-5.2h}'
'0.95k'

>>> f'{Float(1000):%5.2h}'
'1000.00'

>>> f'{Float(1050):%5.2h}'
'1.05k'

Supported Prefixes

SI (Decimal) Prefixes

Prefix Name Base
Q Quetta 1030
R Ronna 1027
Y Yotta 1024
Z Zetta 1021
E Exa 1018
P Peta 1015
T Tera 1012
G Giga 109
M Mega 106
k Kilo 103
m Milli 10-3
μ Micro 10-6
n Nano 10-9
p Pico 10-12
f Femto 10-15
a Atto 10-18
z Zepto 10-21
y Yocto 10-24
r Ronto 10-27
q Quecto 10-30

Note

Prefixed uses the lowercase Greek letter mu ('μ'), U+03BC, to represent the Micro prefix, but will accept input using the Micro sign ('µ'), U+00B5. This complies with the preference defined in Unicode Technical Report #25 section 2.5.

IEC (Binary) Prefixes

Prefix Name Base
Y Yobi 280
Z Zebi 270
E Exbi 260
P Pedi 250
T Tebi 240
G Gibi 230
M Mebi 220
K Kibi 210