https://github.com/ofek/binary

Easily convert between binary and SI units (kibibyte, kilobyte, etc.).
https://github.com/ofek/binary

binary-prefix conversion library python si-units units-of-measurement

Last synced: about 1 year ago
JSON representation

Easily convert between binary and SI units (kibibyte, kilobyte, etc.).

• Host: GitHub
• URL: https://github.com/ofek/binary
• Owner: ofek
• License: apache-2.0
• Created: 2018-01-21T04:44:27.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2024-12-05T16:09:48.000Z (over 1 year ago)
• Last Synced: 2025-04-09T20:04:37.888Z (about 1 year ago)
• Topics: binary-prefix, conversion, library, python, si-units, units-of-measurement
• Language: Python
• Homepage:
• Size: 36.1 KB
• Stars: 10
• Watchers: 2
• Forks: 4
• Open Issues: 1
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

          
binary

======

.. image:: https://img.shields.io/pypi/v/binary.svg?style=flat-square

    :target: https://pypi.org/project/binary

    :alt: Latest PyPI version

.. image:: https://github.com/ofek/binary/workflows/test/badge.svg

    :target: https://github.com/ofek/binary/actions/workflows/test.yml

    :alt: GitHub Actions

.. image:: https://img.shields.io/codecov/c/github/ofek/binary/master.svg?style=flat-square

    :target: https://codecov.io/gh/ofek/binary

    :alt: Codecov

.. image:: https://img.shields.io/pypi/pyversions/binary.svg?style=flat-square

    :target: https://pypi.org/project/binary

    :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/l/binary.svg?style=flat-square

    :target: https://choosealicense.com/licenses

    :alt: License

-----

``binary`` provides a bug-free and easy way to convert between and within

binary (`IEC`_) and decimal (`SI`_) units.

.. contents:: **Table of Contents**

    :backlinks: none

Installation

------------

``binary`` is distributed on `PyPI `_ as a universal

wheel and is available on Linux/macOS and Windows and supports

Python 2.7/3.5+ and PyPy.

.. code-block:: bash

    $ pip install binary

Examples

--------

Let's import what we need:

.. code-block:: python

    >>> from binary import BinaryUnits, DecimalUnits, convert_units

**Basic conversion:**

.. code-block:: python

    >>> convert_units(1536, BinaryUnits.KB, BinaryUnits.MB)

    (1.5, 'MiB')

**How much actual storage your new hard drive has:**

.. code-block:: python

    >>> convert_units(4, DecimalUnits.TB, BinaryUnits.TB)

    (3.637978807091713, 'TiB')

**Human readable:**

.. code-block:: python

    >>> amount, unit = convert_units(kubernetes_ingest_bytes_per_second)

    >>> 'Incoming traffic: {:.2f} {}/s'.format(amount, unit)

    'Incoming traffic: 24.77 GiB/s'

Usage

-----

Just a single function!

``convert_units(n, unit=BYTE, to=None, si=False, exact=False)``

Converts between and within binary and decimal units. If no ``unit``

is specified, ``n`` is assumed to already be in bytes. If no ``to`` is

specified, ``n`` will be converted to the highest unit possible. If

no ``unit`` nor ``to`` is specified, the output will be binary units

unless ``si`` is ``True``. If ``exact`` is ``True``. the calculations

will use ``decimal.Decimal``.

| Binary units conform to IEC standards, see:

| ``_

| ``_

| ``_ (paywalled)

|

| Decimal units conform to SI standards, see:

| ``_

|

* Parameters

  - **n** (``int`` or ``float``) - The number of ``unit``\ s.

  - **unit** - The unit ``n`` represents. See `types`_.

  - **to** - The unit to convert to. See `types`_.

  - **si** (``bool``) - Assume SI units when no ``unit`` nor ``to`` is specified.

  - **exact** (``bool``) - Use ``decimal.Decimal`` for calculations.

Types

^^^^^

Although the string representations for binary units end in ``iB``,

the attributes do not for ease of use.

+--------------+-------+-----------+

| Type         | Short | Long      |

+==============+=======+===========+

| BinaryUnits  | B     | BYTE      |

+--------------+-------+-----------+

| BinaryUnits  | KB    | KIBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | MB    | MEBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | GB    | GIBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | TB    | TEBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | PB    | PEBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | EB    | EXBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | ZB    | ZEBIBYTE  |

+--------------+-------+-----------+

| BinaryUnits  | YB    | YOBIBYTE  |

+--------------+-------+-----------+

| DecimalUnits | B     | BYTE      |

+--------------+-------+-----------+

| DecimalUnits | KB    | KILOBYTE  |

+--------------+-------+-----------+

| DecimalUnits | MB    | MEGABYTE  |

+--------------+-------+-----------+

| DecimalUnits | GB    | GIGABYTE  |

+--------------+-------+-----------+

| DecimalUnits | TB    | TERABYTE  |

+--------------+-------+-----------+

| DecimalUnits | PB    | PETABYTE  |

+--------------+-------+-----------+

| DecimalUnits | EB    | EXABYTE   |

+--------------+-------+-----------+

| DecimalUnits | ZB    | ZETTABYTE |

+--------------+-------+-----------+

| DecimalUnits | YB    | YOTTABYTE |

+--------------+-------+-----------+

License

-------

``binary`` is distributed under the terms of both

- `MIT License `_

- `Apache License, Version 2.0 `_

at your option.

Changelog

---------

Important changes are emphasized.

1.0.1

^^^^^

- Fix syntax warning on newer versions of Python

1.0.0

^^^^^

- Initial release

.. _IEC: https://en.wikipedia.org/wiki/Binary_prefix

.. _SI: https://en.wikipedia.org/wiki/International_System_of_Units