binary

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

https://github.com/ofek/binary

Keywords

Keywords from Contributors

Repository

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

README.rst

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/actions/workflows/test.yml/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/badge/license-MIT%20OR%20Apache--2.0-9400d3.svg
    :target: https://spdx.org/licenses/
    :alt: License

.. image:: https://img.shields.io/github/sponsors/ofek?logo=GitHub%20Sponsors&style=social
    :target: https://github.com/sponsors/ofek
    :alt: GitHub sponsors

-----

``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
------------

.. 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.2
^^^^^

- Perform floor division when explicitly converting to bytes
- Support negative values

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

Owner

GitHub Events

Committers

Last synced: 9 months ago

Issues and Pull Requests

Last synced: 9 months ago

Packages