{"id":25188332,"url":"https://github.com/tbielawa/bitmath","last_synced_at":"2025-04-05T07:02:50.912Z","repository":{"id":14822953,"uuid":"17545616","full_name":"tbielawa/bitmath","owner":"tbielawa","description":"Python module for representing file sizes with different prefix notations","archived":false,"fork":false,"pushed_at":"2024-04-17T08:22:42.000Z","size":731,"stargazers_count":93,"open_issues_count":20,"forks_count":25,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T06:03:48.179Z","etag":null,"topics":["files","filesystem","math-library","python","python2","python3","size-calculation","sizes"],"latest_commit_sha":null,"homepage":"http://bitmath.readthedocs.org/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tbielawa.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-08T16:19:05.000Z","updated_at":"2024-11-02T19:01:21.000Z","dependencies_parsed_at":"2024-06-18T15:27:32.252Z","dependency_job_id":"f8a90efe-c5c3-4beb-9a4a-0c6cea6a87ce","html_url":"https://github.com/tbielawa/bitmath","commit_stats":{"total_commits":340,"total_committers":13,"mean_commits":"26.153846153846153","dds":0.1029411764705882,"last_synced_commit":"f72a79b616ddb7dc48ea7356514fc7739e1074a9"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbielawa%2Fbitmath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbielawa%2Fbitmath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbielawa%2Fbitmath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbielawa%2Fbitmath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tbielawa","download_url":"https://codeload.github.com/tbielawa/bitmath/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299831,"owners_count":20916190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["files","filesystem","math-library","python","python2","python3","size-calculation","sizes"],"created_at":"2025-02-09T20:19:37.768Z","updated_at":"2025-04-05T07:02:50.890Z","avatar_url":"https://github.com/tbielawa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://api.travis-ci.org/tbielawa/bitmath.png\n   :target: https://travis-ci.org/tbielawa/bitmath/\n   :align: right\n   :height: 19\n   :width: 77\n\n.. image:: https://coveralls.io/repos/tbielawa/bitmath/badge.png?branch=master\n   :target: https://coveralls.io/r/tbielawa/bitmath?branch=master\n   :align: right\n   :height: 19\n   :width: 77\n\n.. image:: https://readthedocs.org/projects/bitmath/badge/?version=latest\n   :target: http://bitmath.rtfd.org/\n   :align: right\n   :height: 19\n   :width: 77\n\n\nbitmath\n=======\n\n`bitmath \u003chttp://bitmath.readthedocs.org/en/latest/\u003e`_ simplifies many\nfacets of interacting with file sizes in various units. Originally\nfocusing on file size unit conversion, functionality now includes:\n\n* Converting between **SI** and **NIST** prefix units (``kB`` to ``GiB``)\n* Converting between units of the same type (SI to SI, or NIST to NIST)\n* Automatic human-readable prefix selection (like in `hurry.filesize \u003chttps://pypi.python.org/pypi/hurry.filesize\u003e`_)\n* Basic arithmetic operations (subtracting 42KiB from 50GiB)\n* Rich comparison operations (``1024 Bytes == 1KiB``)\n* bitwise operations (``\u003c\u003c``, ``\u003e\u003e``, ``\u0026``, ``|``, ``^``)\n* Reading a device's storage capacity (Linux/OS X support only)\n* `argparse \u003chttps://docs.python.org/2/library/argparse.html\u003e`_\n  integration as a custom type\n* `click \u003chttps://click.palletsprojects.com/\u003e`_\n  integration as a custom parameter type\n* `progressbar \u003chttps://code.google.com/p/python-progressbar/\u003e`_\n  integration as a better file transfer speed widget\n* String parsing\n* Sorting\n\n\nIn addition to the conversion and math operations, `bitmath` provides\nhuman readable representations of values which are suitable for use in\ninteractive shells as well as larger scripts and applications. The\nformat produced for these representations is customizable via the\nfunctionality included in stdlibs `string.format\n\u003chttps://docs.python.org/2/library/string.html\u003e`_.\n\nIn discussion we will refer to the NIST units primarily. I.e., instead\nof \"megabyte\" we will refer to \"mebibyte\". The former is ``10^3 =\n1,000,000`` bytes, whereas the second is ``2^20 = 1,048,576``\nbytes. When you see file sizes or transfer rates in your web browser,\nmost of the time what you're really seeing are the base-2 sizes/rates.\n\n**Don't Forget!** The source for bitmath `is available on GitHub\n\u003chttps://github.com/tbielawa/bitmath\u003e`_.\n\nAnd did we mention there's almost 200 unittests? `Check them out for\nyourself \u003chttps://github.com/tbielawa/bitmath/tree/master/tests\u003e`_.\n\nRunning the tests should be as simple as calling the ``ci-all`` target\nin the Makefile: ``make ci-all``. Please file a bug report if you run\ninto issues.\n\n\n\n\nInstallation\n============\n\nThe easiest way to install bitmath is via ``dnf`` (or ``yum``) if\nyou're on a Fedora/RHEL based distribution. bitmath is available in\nthe main Fedora repositories, as well as the `EPEL6\n\u003chttp://download.fedoraproject.org/pub/epel/6/i386/repoview/epel-release.html\u003e`_\nand `EPEL7\n\u003chttp://download.fedoraproject.org/pub/epel/7/x86_64/repoview/epel-release.html\u003e`_\nrepositories. There are now dual python2.x and python3.x releases\navailable.\n\n\n**Python 2.x**:\n\n.. code-block:: bash\n\n   $ sudo dnf install python2-bitmath\n\n**Python 3.x**:\n\n.. code-block:: bash\n\n   $ sudo dnf install python3-bitmath\n\n\n.. note::\n\n   **Upgrading**: If you have the old *python-bitmath* package\n   installed presently, you could also run ``sudo dnf update\n   python-bitmath`` instead\n\n\n**PyPi**:\n\nYou could also install bitmath from `PyPi\n\u003chttps://pypi.python.org/pypi/bitmath\u003e`_ if you like:\n\n.. code-block:: bash\n\n   $ sudo pip install bitmath\n\n.. note::\n\n   **pip** installs need pip \u003e= 1.1. To workaround this, `download\n   bitmath \u003chttps://pypi.python.org/pypi/bitmath/#downloads\u003e`_, from\n   PyPi and then ``pip install bitmath-x.y.z.tar.gz``. See `issue #57\n   \u003chttps://github.com/tbielawa/bitmath/issues/57#issuecomment-227018168\u003e`_\n   for more information.\n\n\n**PPA**:\n\nUbuntu Xenial, Wily, Vivid, Trusty, and Precise users can install\nbitmath from the `launchpad PPA\n\u003chttps://launchpad.net/~tbielawa/+archive/ubuntu/bitmath\u003e`_:\n\n.. code-block:: bash\n\n   $ sudo add-apt-repository ppa:tbielawa/bitmath\n   $ sudo apt-get update\n   $ sudo apt-get install python-bitmath\n\n\n**Source**:\n\nOr, if you want to install from source:\n\n.. code-block:: bash\n\n   $ sudo python ./setup.py install\n\nIf you want the bitmath manpage installed as well:\n\n.. code-block:: bash\n\n   $ sudo make install\n\n\nDocumentation\n=============\n\nThe main documentation lives at\n`http://bitmath.readthedocs.org/en/latest/\n\u003chttp://bitmath.readthedocs.org/en/latest/\u003e`_.\n\nTopics include:\n\n* The ``bitmath`` Module\n\n  * Utility Functions\n  * Context Managers\n  * Module Variables\n  * ``argparse`` integration\n  * ``click`` integration\n  * ``progressbar`` integration\n\n* The ``bitmath`` command-line Tool\n\n* Classes\n\n  * Initializing\n  * Available Classes\n  * Class Methods\n\n* Instances\n\n  * Instance Attributes\n  * Instance Methods\n  * Instance Properties\n  * The Formatting Mini-Language\n\n* Getting Started\n\n  * Tables of Supported Operations\n  * Basic Math\n  * Unit Conversion\n  * Rich Comparison\n  * Sorting\n\n* Real Life Examples\n\n  * Download Speeds\n  * Calculating how many files fit on a device\n  * Printing Human-Readable File Sizes in Python\n  * Calculating Linux BDP and TCP Window Scaling\n\n* Contributing to bitmath\n* Appendices\n\n  * Rules for Math\n  * On Units\n  * Who uses Bitmath\n  * Related Projects\n\n* NEWS\n\n* Copyright\n\n\nExamples\n========\n\n\nArithmetic\n----------\n\n.. code-block:: python\n\n   \u003e\u003e\u003e import bitmath\n   \u003e\u003e\u003e log_size = bitmath.kB(137.4)\n   \u003e\u003e\u003e log_zipped_size = bitmath.Byte(987)\n   \u003e\u003e\u003e print \"Compression saved %s space\" % (log_size - log_zipped_size)\n   Compression saved 136.413kB space\n   \u003e\u003e\u003e thumb_drive = bitmath.GiB(12)\n   \u003e\u003e\u003e song_size = bitmath.MiB(5)\n   \u003e\u003e\u003e songs_per_drive = thumb_drive / song_size\n   \u003e\u003e\u003e print songs_per_drive\n   2457.6\n\n\nConvert Units\n-------------\n\nFile size unit conversion:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e from bitmath import *\n   \u003e\u003e\u003e dvd_size = GiB(4.7)\n   \u003e\u003e\u003e print \"DVD Size in MiB: %s\" % dvd_size.to_MiB()\n   DVD Size in MiB: 4812.8 MiB\n\n\nSelect a human-readable unit\n----------------------------\n\n.. code-block:: python\n\n   \u003e\u003e\u003e small_number = kB(100)\n   \u003e\u003e\u003e ugly_number = small_number.to_TiB()\n\n   \u003e\u003e\u003e print ugly_number\n   9.09494701773e-08 TiB\n   \u003e\u003e\u003e print ugly_number.best_prefix()\n   97.65625 KiB\n\n\nRich Comparison\n---------------\n\n.. code-block:: python\n\n   \u003e\u003e\u003e cd_size = MiB(700)\n   \u003e\u003e\u003e cd_size \u003e dvd_size\n   False\n   \u003e\u003e\u003e cd_size \u003c dvd_size\n   True\n   \u003e\u003e\u003e MiB(1) == KiB(1024)\n   True\n   \u003e\u003e\u003e MiB(1) \u003c= KiB(1024)\n   True\n\nSorting\n-------\n\n.. code-block:: python\n\n   \u003e\u003e\u003e sizes = [KiB(7337.0), KiB(1441.0), KiB(2126.0), KiB(2178.0),\n                     KiB(2326.0), KiB(4003.0), KiB(48.0), KiB(1770.0),\n                     KiB(7892.0), KiB(4190.0)]\n\n   \u003e\u003e\u003e print sorted(sizes)\n   [KiB(48.0), KiB(1441.0), KiB(1770.0), KiB(2126.0), KiB(2178.0),\n   KiB(2326.0), KiB(4003.0), KiB(4190.0), KiB(7337.0), KiB(7892.0)]\n\n\nCustom Formatting\n-----------------\n\n* Use of the custom formatting system\n* All of the available instance properties\n\nExample:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e longer_format = \"\"\"Formatting attributes for %s\n      ...: This instances prefix unit is {unit}, which is a {system} type unit\n      ...: The unit value is {value}\n      ...: This value can be truncated to just 1 digit of precision: {value:.1f}\n      ...: In binary this looks like: {binary}\n      ...: The prefix unit is derived from a base of {base}\n      ...: Which is raised to the power {power}\n      ...: There are {bytes} bytes in this instance\n      ...: The instance is {bits} bits large\n      ...: bytes/bits without trailing decimals: {bytes:.0f}/{bits:.0f}\"\"\" % str(ugly_number)\n\n   \u003e\u003e\u003e print ugly_number.format(longer_format)\n   Formatting attributes for 5.96046447754 MiB\n   This instances prefix unit is MiB, which is a NIST type unit\n   The unit value is 5.96046447754\n   This value can be truncated to just 1 digit of precision: 6.0\n   In binary this looks like: 0b10111110101111000010000000\n   The prefix unit is derived from a base of 2\n   Which is raised to the power 20\n   There are 6250000.0 bytes in this instance\n   The instance is 50000000.0 bits large\n   bytes/bits without trailing decimals: 6250000/50000000\n\nUtility Functions\n-----------------\n\n**bitmath.getsize()**\n\n.. code-block:: python\n\n   \u003e\u003e\u003e print bitmath.getsize('python-bitmath.spec')\n   3.7060546875 KiB\n\n**bitmath.parse_string()**\n\nParse a string with standard units:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e import bitmath\n   \u003e\u003e\u003e a_dvd = bitmath.parse_string(\"4.7 GiB\")\n   \u003e\u003e\u003e print type(a_dvd)\n   \u003cclass 'bitmath.GiB'\u003e\n   \u003e\u003e\u003e print a_dvd\n   4.7 GiB\n\n**bitmath.parse_string_unsafe()**\n\nParse a string with ambiguous units:\n\n.. code-block:: python\n\n   \u003e\u003e\u003e import bitmath\n   \u003e\u003e\u003e a_gig = bitmath.parse_string_unsafe(\"1gb\")\n   \u003e\u003e\u003e print type(a_gig)\n   \u003cclass 'bitmath.GB'\u003e\n   \u003e\u003e\u003e a_gig == bitmath.GB(1)\n   True\n   \u003e\u003e\u003e bitmath.parse_string_unsafe('1gb') == bitmath.parse_string_unsafe('1g')\n   True\n\n\n**bitmath.query_device_capacity()**\n\n.. code-block:: python\n\n   \u003e\u003e\u003e import bitmath\n   \u003e\u003e\u003e with open('/dev/sda') as fp:\n   ...     root_disk = bitmath.query_device_capacity(fp)\n   ...     print root_disk.best_prefix()\n   ...\n   238.474937439 GiB\n\n**bitmath.listdir()**\n\n.. code-block:: python\n\n   \u003e\u003e\u003e for i in bitmath.listdir('./tests/', followlinks=True, relpath=True, bestprefix=True):\n   ...     print i\n   ...\n   ('tests/test_file_size.py', KiB(9.2900390625))\n   ('tests/test_basic_math.py', KiB(7.1767578125))\n   ('tests/__init__.py', KiB(1.974609375))\n   ('tests/test_bitwise_operations.py', KiB(2.6376953125))\n   ('tests/test_context_manager.py', KiB(3.7744140625))\n   ('tests/test_representation.py', KiB(5.2568359375))\n   ('tests/test_properties.py', KiB(2.03125))\n   ('tests/test_instantiating.py', KiB(3.4580078125))\n   ('tests/test_future_math.py', KiB(2.2001953125))\n   ('tests/test_best_prefix_BASE.py', KiB(2.1044921875))\n   ('tests/test_rich_comparison.py', KiB(3.9423828125))\n   ('tests/test_best_prefix_NIST.py', KiB(5.431640625))\n   ('tests/test_unique_testcase_names.sh', Byte(311.0))\n   ('tests/.coverage', KiB(3.1708984375))\n   ('tests/test_best_prefix_SI.py', KiB(5.34375))\n   ('tests/test_to_built_in_conversion.py', KiB(1.798828125))\n   ('tests/test_to_Type_conversion.py', KiB(8.0185546875))\n   ('tests/test_sorting.py', KiB(4.2197265625))\n   ('tests/listdir_symlinks/10_byte_file_link', Byte(10.0))\n   ('tests/listdir_symlinks/depth1/depth2/10_byte_file', Byte(10.0))\n   ('tests/listdir_nosymlinks/depth1/depth2/10_byte_file', Byte(10.0))\n   ('tests/listdir_nosymlinks/depth1/depth2/1024_byte_file', KiB(1.0))\n   ('tests/file_sizes/kbytes.test', KiB(1.0))\n   ('tests/file_sizes/bytes.test', Byte(38.0))\n   ('tests/listdir/10_byte_file', Byte(10.0))\n\n\nFormatting\n----------\n\n.. code-block:: python\n\n   \u003e\u003e\u003e with bitmath.format(fmt_str=\"[{value:.3f}@{unit}]\"):\n   ...     for i in bitmath.listdir('./tests/', followlinks=True, relpath=True, bestprefix=True):\n   ...         print i[1]\n   ...\n   [9.290@KiB]\n   [7.177@KiB]\n   [1.975@KiB]\n   [2.638@KiB]\n   [3.774@KiB]\n   [5.257@KiB]\n   [2.031@KiB]\n   [3.458@KiB]\n   [2.200@KiB]\n   [2.104@KiB]\n   [3.942@KiB]\n   [5.432@KiB]\n   [311.000@Byte]\n   [3.171@KiB]\n   [5.344@KiB]\n   [1.799@KiB]\n   [8.019@KiB]\n   [4.220@KiB]\n   [10.000@Byte]\n   [10.000@Byte]\n   [10.000@Byte]\n   [1.000@KiB]\n   [1.000@KiB]\n   [38.000@Byte]\n   [10.000@Byte]\n\n``argparse`` Integration\n------------------------\n\nExample script using ``bitmath.integrations.bmargparse.BitmathType`` as an\nargparser argument type:\n\n.. code-block:: python\n\n   import argparse\n   from bitmath.integrations.bmargparse import BitmathType\n   parser = argparse.ArgumentParser(\n       description=\"Arg parser with a bitmath type argument\")\n   parser.add_argument('--block-size',\n                       type=BitmathType,\n                       required=True)\n\n   results = parser.parse_args()\n   print \"Parsed in: {PARSED}; Which looks like {TOKIB} as a Kibibit\".format(\n       PARSED=results.block_size,\n       TOKIB=results.block_size.Kib)\n\nIf ran as a script the results would be similar to this:\n\n.. code-block:: bash\n\n   $ python ./bmargparse.py --block-size 100MiB\n   Parsed in: 100.0 MiB; Which looks like 819200.0 Kib as a Kibibit\n\n``click`` Integration\n---------------------\n\nExample script using ``bitmath.integrations.bmclick.BitmathType`` as an\nclick parameter type:\n\n.. code-block:: python\n\n   import click\n   from bitmath.integrations.bmclick import BitmathType\n\n   @click.command()\n   @click.argument('size', type=BitmathType())\n   def best_prefix(size):\n      click.echo(size.best_prefix())\n\nIf ran as a script the results should be similar to this:\n\n.. code-block:: bash\n\n   $ python ./bestprefix.py \"1024 KiB\"\n   1.0 MiB\n\n``progressbar`` Integration\n---------------------------\n\nUse ``bitmath.integrations.bmprogressbar.BitmathFileTransferSpeed`` as a\n``progressbar`` file transfer speed widget to monitor download speeds:\n\n.. code-block:: python\n\n   import requests\n   import progressbar\n   import bitmath\n   from bitmath.integrations.bmprogressbar import BitmathFileTransferSpeed\n\n   FETCH = 'https://www.kernel.org/pub/linux/kernel/v3.0/patch-3.16.gz'\n   widgets = ['Bitmath Progress Bar Demo: ', ' ',\n              progressbar.Bar(marker=progressbar.RotatingMarker()), ' ',\n              BitmathFileTransferSpeed()]\n\n   r = requests.get(FETCH, stream=True)\n   size = bitmath.Byte(int(r.headers['Content-Length']))\n   pbar = progressbar.ProgressBar(widgets=widgets, maxval=int(size),\n                                  term_width=80).start()\n   chunk_size = 2048\n   with open('/dev/null', 'wb') as fd:\n       for chunk in r.iter_content(chunk_size):\n           fd.write(chunk)\n           if (pbar.currval + chunk_size) \u003c pbar.maxval:\n               pbar.update(pbar.currval + chunk_size)\n   pbar.finish()\n\n\nIf ran as a script the results would be similar to this:\n\n.. code-block:: bash\n\n   $ python ./smalldl.py\n   Bitmath Progress Bar Demo:  ||||||||||||||||||||||||||||||||||||||||| 1.58 MiB/s\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbielawa%2Fbitmath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftbielawa%2Fbitmath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbielawa%2Fbitmath/lists"}