Fetching contributors…
Cannot retrieve contributors at this time
1047 lines (775 sloc) 36.8 KB

The bitmath Module


This section describes utility functions included in the :py:mod:`bitmath` module.






Context Managers

This section describes all of the context managers provided by the bitmath class.


For a bit of background, a context manager (specifically, the with statement) is a feature of the Python language which is commonly used to:

  • Decorate, or wrap, an arbitrary block of code. I.e., effect a certain condition onto a specific body of code
  • Automatically open and close an object which is used in a specific context. I.e., handle set-up and tear-down of objects in the place they are used.


Module Variables

This section describes the module-level variables. Some of which are constants and are used for reference. Some of which effect output or behavior.


Modifying these variables will change the default representation indefinitely. Use the :py:func:`bitmath.format` context manager to limit changes to a specific block of code.

3rd Party Module Integrations

This section describes the various ways in which :py:mod:`bitmath` can be integrated with other 3rd pary modules.

To see a full demo of the :mod:`argparse` and :mod:`progressbar` integrations, as well as a comprehensive demonstrations of the full capabilities of the bitmath library, see :ref:`Creating Download Progress Bars <real_life_examples_download_progress_bars>` in the Real Life Examples section.


The argparse module (part of stdlib) is used to parse command line arguments. By default, parsed options and arguments are turned into strings. However, one useful feature :py:mod:`argparse` provides is the ability to specify what datatype any given argument or option should be interpreted as.


The progressbar module is typically used to display the progress of a long running task, such as a file transfer operation. The module provides widgets for custom formatting how exactly the 'progress' is displayed. Some examples include: overall percentage complete, estimated time until completion, and an ASCII progress bar which fills as the operation continues.

While :mod:`progressbar` already includes a widget suitable for displaying file transfer rates, this widget does not support customizing its presentation, and is limited to only prefix units from the SI system.

The :class:`BitmathFileTransferSpeed` class is a more functional replacement for the upstream FileTransferSpeed widget.

While both widgets are able to calculate average transfer rates over a period of time, the :class:`BitmathFileTransferSpeed` widget adds new support for NIST prefix units (the upstream widget only supports SI prefix units).

In addition to NIST unit support, :class:`BitmathFileTransferSpeed` enables the user to have full control over the look and feel of the displayed rates.

param system:Default: :py:data:`bitmath.NIST`. The preferred system of units for the printed rate.
type system:One of :py:data:`bitmath.NIST` or :py:data:`bitmath.SI`
param string format:a formatting mini-language compat formatting string. Default {value:.2f} {unit}/s (e.g., 13.37 GiB/s)


See :ref:`instance attributes <instances_attributes>` for a list of available formatting items. See the section on :ref:`formatting bitmath instances <instances_format>` for more information on this topic.

Use :class:`BitmathFileTransferSpeed` exactly like the upstream FileTransferSpeed widget (example copied and modified from the progressbar project page):

If this was ran from a script we would see output similar to the following:

Something: 100% ||||||||||||||||||||||||||||||||||| Time: 0:00:01 9.27 MiB/s

If we wanted behavior identical to :class:`FileTransferSpeed` we would set the system parameter to :py:data:`bitmath.SI` (line 5 below):

If this was ran from a script we would see output similar to the following:

Something: 100% ||||||||||||||||||||||||||||||||||| Time: 0:00:01 9.80 MB/s

Note how the only difference is in the displayed unit. The former example produced a rate with a unit of MiB (a NIST unit) whereas the latter examples unit is MB (an SI unit).

As noted previously, :class:`BitmathFileTransferSpeed` allows for full control over the formatting of the calculated rate of transfer.

For example, if we wished to see the rate printed using more verbose language and plauralized units, we could do exactly that by constructing our widget in the following way:

BitmathFileTransferSpeed(format="{value:.2f} {unit_plural} per second")

And if this were run from a script like the previous examples:

Something: 100% ||||||||||||||||||||||||||||||||||| Time: 0:00:01 9.41 MiBs per second