1Metadata-Version: 1.2
2Name: prefixed
3Version: 0.3.2
4Summary: Prefixed alternative numeric library
5Home-page: https://github.com/Rockhopper-Technologies/prefixed
6Author: Avram Lubkin
7Author-email: avylove@rockhopper.net
8Maintainer: Avram Lubkin
9Maintainer-email: avylove@rockhopper.net
10License: MPLv2.0
11Project-URL: Documentation, https://prefixed.readthedocs.io
12Description: .. start-badges
13
14        | |docs| |travis| |codecov|
15        | |pypi| |supported-versions| |supported-implementations|
16
17        .. |docs| image:: https://img.shields.io/readthedocs/prefixed.svg?style=plastic&logo=read-the-docs
18            :target: https://prefixed.readthedocs.org
19            :alt: Documentation Status
20
21        .. |travis| image:: https://img.shields.io/travis/Rockhopper-Technologies/prefixed.svg?style=plastic&logo=travis
22            :target: https://travis-ci.org/Rockhopper-Technologies/prefixed
23            :alt: Travis-CI Build Status
24
25        .. |codecov| image:: https://img.shields.io/codecov/c/github/Rockhopper-Technologies/prefixed.svg?style=plastic&logo=codecov
26            :target: https://codecov.io/gh/Rockhopper-Technologies/prefixed
27            :alt: Coverage Status
28
29        .. |pypi| image:: https://img.shields.io/pypi/v/prefixed.svg?style=plastic&logo=pypi
30            :alt: PyPI Package latest release
31            :target: https://pypi.python.org/pypi/prefixed
32
33        .. |supported-versions| image:: https://img.shields.io/pypi/pyversions/prefixed.svg?style=plastic&logo=pypi
34            :alt: Supported versions
35            :target: https://pypi.python.org/pypi/prefixed
36
37        .. |supported-implementations| image:: https://img.shields.io/pypi/implementation/prefixed.svg?style=plastic&logo=pypi
38            :alt: Supported implementations
39            :target: https://pypi.python.org/pypi/prefixed
40
41        .. end-badges
42
43
44        Overview
45        ========
46
47        Prefixed provides an alternative implementation of the built-in float_ which supports
48        formatted output with `SI (decimal)`_ and `IEC (binary)`_ prefixes.
49
50        .. code-block:: python
51
52          >>> from prefixed import Float
53
54          >>> f'{Float(3250):.2h}'
55          '3.25k'
56
57          >>> '{:.2h}s'.format(Float(.00001534))
58          '15.34μs'
59
60          >>> '{:.2j}B'.format(Float(42467328))
61          '40.50MiB'
62
63          >>> f'{Float(2048):.2J}B'
64          '2.00KB'
65
66        Because `prefixed.Float`_ inherits from the built-in float_, it behaves
67        exactly the same in most cases.
68
69        Key differences:
70
71        - When a math operation is performed with another real number type
72          (float_, int_), the result will be a `prefixed.Float`_ instance.
73
74        - Additional presentation types ``'h'``, ``'j'``, and ``'J'`` are supported for
75          f-strings and `format()`_.
76
77          +---------+----------------------------------------------------------+
78          | Type    | Meaning                                                  |
79          +=========+==========================================================+
80          | ``'h'`` | SI format. Outputs the number with closest divisible     |
81          |         | SI prefix. (k, M, G, ...)                                |
82          +---------+----------------------------------------------------------+
83          | ``'j'`` | IEC Format. Outputs the number with closest divisible    |
84          |         | IEC prefix. (Ki, Mi, Gi, ...)                            |
85          +---------+----------------------------------------------------------+
86          | ``'J'`` | Short IEC Format. Same as ``'j'`` but only a single      |
87          |         | character.   (K, M, G, ...)                              |
88          +---------+----------------------------------------------------------+
89
90        - When initializing from strings, SI and IEC prefixes are honored
91
92        .. code-block:: python
93
94            >>> Float('2k')
95            Float(2000.0)
96
97            >>> Float('2Ki')
98            Float(2048.0)
99
100        - An additional format flag '!' is available which adds a space before the prefix
101
102        .. code-block:: python
103
104          >>> f'{Float(3250):!.2h}'
105          '3.25 k'
106
107        - An additional field, margin, can be specified which lowers or raises the threshold for
108          for each prefix by the given percentage.
109          Margin is specified before precision with the syntax  ``%[-]digit+``.
110
111        .. code-block:: python
112
113            >>> f'{Float(950):.2h}'
114            '950.00'
115
116            >>> f'{Float(950):%-5.2h}'
117            '0.95k'
118
119            >>> f'{Float(1000):%5.2h}'
120            '1000.00'
121
122            >>> f'{Float(1050):%5.2h}'
123            '1.05k'
124
125
126        Supported Prefixes
127        ==================
128
129        SI (Decimal) Prefixes
130        ^^^^^^^^^^^^^^^^^^^^^
131
132        +--------+-------+----------+
133        | Prefix | Name  |   Base   |
134        +========+=======+==========+
135        |   Y    | Yotta | |10^24|  |
136        +--------+-------+----------+
137        |   Z    | Zetta | |10^21|  |
138        +--------+-------+----------+
139        |   E    | Exa   | |10^18|  |
140        +--------+-------+----------+
141        |   P    | Peta  | |10^15|  |
142        +--------+-------+----------+
143        |   T    | Tera  | |10^12|  |
144        +--------+-------+----------+
145        |   G    | Giga  | |10^9|   |
146        +--------+-------+----------+
147        |   M    | Mega  | |10^6|   |
148        +--------+-------+----------+
149        |   k    | Kilo  | |10^3|   |
150        +--------+-------+----------+
151        |   m    | Milli | |10^-3|  |
152        +--------+-------+----------+
153        |   μ    | Micro | |10^-6|  |
154        +--------+-------+----------+
155        |   n    | Nano  | |10^-9|  |
156        +--------+-------+----------+
157        |   p    | Pico  | |10^-12| |
158        +--------+-------+----------+
159        |   f    | Femto | |10^-15| |
160        +--------+-------+----------+
161        |   a    | Atto  | |10^-18| |
162        +--------+-------+----------+
163        |   z    | Zepto | |10^-21| |
164        +--------+-------+----------+
165        |   y    | Yocto | |10^-24| |
166        +--------+-------+----------+
167
168        IEC (Binary) Prefixes
169        ^^^^^^^^^^^^^^^^^^^^^
170
171        +--------+------+--------+
172        | Prefix | Name |  Base  |
173        +========+======+========+
174        |   Y    | Yobi | |2^80| |
175        +--------+------+--------+
176        |   Z    | Zebi | |2^70| |
177        +--------+------+--------+
178        |   E    | Exbi | |2^60| |
179        +--------+------+--------+
180        |   P    | Pedi | |2^50| |
181        +--------+------+--------+
182        |   T    | Tebi | |2^40| |
183        +--------+------+--------+
184        |   G    | Gibi | |2^30| |
185        +--------+------+--------+
186        |   M    | Mebi | |2^20| |
187        +--------+------+--------+
188        |   K    | Kibi | |2^10| |
189        +--------+------+--------+
190
191        .. _SI (decimal): https://en.wikipedia.org/wiki/Metric_prefix
192        .. _IEC (binary): https://en.wikipedia.org/wiki/Binary_prefix
193        .. _float: https://docs.python.org/3/library/functions.html#float
194        .. _int: https://docs.python.org/3/library/functions.html#int
195        .. _prefixed.Float: https://prefixed.readthedocs.io/en/stable/api.html#prefixed.Float
196        .. _format(): https://docs.python.org/3/library/functions.html#format
197
198        .. |10^24| replace:: 10\ :sup:`24`\
199        .. |10^21| replace:: 10\ :sup:`21`\
200        .. |10^18| replace:: 10\ :sup:`18`\
201        .. |10^15| replace:: 10\ :sup:`15`\
202        .. |10^12| replace:: 10\ :sup:`12`\
203        .. |10^9| replace:: 10\ :sup:`9`\
204        .. |10^6| replace:: 10\ :sup:`6`\
205        .. |10^3| replace:: 10\ :sup:`3`\
206        .. |10^-3| replace:: 10\ :sup:`-3`\
207        .. |10^-6| replace:: 10\ :sup:`-6`\
208        .. |10^-9| replace:: 10\ :sup:`-9`\
209        .. |10^-12| replace:: 10\ :sup:`-12`\
210        .. |10^-15| replace:: 10\ :sup:`-15`\
211        .. |10^-18| replace:: 10\ :sup:`-18`\
212        .. |10^-21| replace:: 10\ :sup:`-21`\
213        .. |10^-24| replace:: 10\ :sup:`-24`\
214
215        .. |2^80| replace:: 2\ :sup:`80`\
216        .. |2^70| replace:: 2\ :sup:`70`\
217        .. |2^60| replace:: 2\ :sup:`60`\
218        .. |2^50| replace:: 2\ :sup:`50`\
219        .. |2^40| replace:: 2\ :sup:`40`\
220        .. |2^30| replace:: 2\ :sup:`30`\
221        .. |2^20| replace:: 2\ :sup:`20`\
222        .. |2^10| replace:: 2\ :sup:`10`\
223
224Keywords: si iec prefix nist
225Platform: UNKNOWN
226Classifier: Development Status :: 4 - Beta
227Classifier: Intended Audience :: Developers
228Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
229Classifier: Operating System :: POSIX
230Classifier: Operating System :: Microsoft :: Windows
231Classifier: Programming Language :: Python
232Classifier: Programming Language :: Python :: 2.7
233Classifier: Programming Language :: Python :: 3.5
234Classifier: Programming Language :: Python :: 3.6
235Classifier: Programming Language :: Python :: 3.7
236Classifier: Programming Language :: Python :: 3.8
237Classifier: Programming Language :: Python :: Implementation :: CPython
238Classifier: Programming Language :: Python :: Implementation :: PyPy
239Classifier: Topic :: Terminals
240