Speed, distance and time calculations around quantities of digital information.

$ pip install nibble

The following snippet provides an example of Nibble's ability to format and manipulate quantities of information, durations and speeds. For explanations of what's going on, see each class's section below.

from nibble import Information, Duration, Speed


information = Information(123, Information.GIBIBITS)
print('{0}'.format(information))               # '15.38 GiB'
print('{0:GB}'.format(information))            # '16.51GB'
print('{0: GB}'.format(information))           # '16.51 GB'
print('{0:,.2f| Mb}'.format(information))      # '132,070.24 Mb'

speed = Speed(Information(20, Information.MEGABITS), Duration.SECOND)
print('{0}'.format(speed))                     # '2.38 MiB/s'
print('{0:Mb}'.format(speed))                  # '20Mb/s'
print('{0: Gb/w}'.format(speed))               # '12,096 Gb/w'
print(Speed.TEN_GIGABIT / 10
      == Speed.HUNDRED_MEGABIT * 10
      == Speed.GIGABIT)                        # True
print('{0: dB/y}'.format(Speed.TEN_GIGABIT))   # '39.42 PB/y'
print('{0:.2f| bB/mo}'.format(Speed.GIGABIT))  # '298.77 TiB/mo'

Nibble represents all quantities of information in terms of the smallest unit: bits. The syntax for formatting Information objects is:

[number format|][ ][unit symbol or category]

• [number format|] is a valid floating point format specification followed by a pipe symbol so it can be distinguished from the rest of the format string
• [ ] is an optional blank space separating the number from the unit symbol
• [unit symbol or category] is either a single unit to represent the information in, e.g. Gb, or a category of units (see below), in which case Nibble will choose the most appropriate one

The default format specification is '.2f| bB'.

At the lower end, Nibble supports bits, nibbles (of course) and bytes. Larger units fall into one of four categories. They are either binary or decimal (they can be expressed as 2ⁿ or 10ⁿ respectively), or bit or byte based:

It is a common misconception that there are 1024 bytes in a kilobyte. If you'd like to work in multiples of 1024, use the -ibibyte units instead.

Nibble supports all of the above units with prefixes from Ki- to Yi-. For the full list, consult the _SYMBOLS dict in the Information class.

In addition to representing a quantity of information in a specific unit, nibble can determine the most appropriate one to use from a range. These ranges are called categories, and correspond to rows in the table above.

The first letter of the category refers to the base, b and d for binary and decimal respectively. The second letter refers to the suffix, b and B for bit and byte respectively. Therefore, to format an amount of information in the bits, kilobits, megabits, gigabits etc., use '{0:db}'.format(...).

The only remaining ambiguity is how Nibble determines the best unit to use in each category. It simply chooses the largest unit where the amount of information to represent is >=1 of that unit, falling back on the smallest unit where that's not possible (e.g. representing less than 1 byte in bB or dB). For example, 1 GiB would be shown in GiB. One bit less would be shown in MiB.

The following class constants are provided for common quantities of information:

This class is Nibble's equivalent of datetime.timedelta(). Why re-implement? Because that only goes down to microsecond precision, and lacks months and years. To make working with this class as easy as possible, a from_timedelta() method and timedelta property are provided - however bear in mind these will lose precision by virtue of working at a coarser level of granularity.

The syntax for formatting Duration objects is:

[number format|][ ][unit symbol]

• [number format|] is a valid floating point format specification followed by a pipe symbol so it can be distinguished from the rest of the format string
• [ ] is an optional blank space separating the number from the unit symbol
• [unit symbol] is a time unit to represent the duration in (see below)

By default, durations will be shown in the largest unit where the time period is greater or equal to 1 of that unit. For example, 1 minute would be shown as 1 m. One nanosecond less would be shown as 60.00s.

The following class constants are provided for common durations:

Speeds can be created using the standard constructor, or by calling .in_duration()` with aDurationon anInformationobject. The syntax for formattingSpeedobjects is: :: [number format|][ ][unit symbol or category][/time unit] -[number format bB/s'. Shortcuts ~~~~~~~~~ The following class constants are provided for common speeds: +---------------------+--------------+ | Constant | Equivalent | +=====================+==============+ |ZERO| 0 b/s | +---------------------+--------------+ |TEN_MEGABIT| 10 Mb/s | +---------------------+--------------+ |HUNDRED_MEGABIT| 100 Mb/s | +---------------------+--------------+ |GIGABIT| 1 Gb/s | +---------------------+--------------+ |TEN_GIGABIT| 10 Gb/s | +---------------------+--------------+ |FORTY_GIGABIT| 40 Gb/s | +---------------------+--------------+ |HUNDRED_GIGABIT| 100 Gb/s | +---------------------+--------------+ |E0/DS0| 64 Kb/s | +---------------------+--------------+ |E1| 2.048 Mb/s | +---------------------+--------------+ |E2| 8.448 Mb/s | +---------------------+--------------+ |E3| 34.368 Mb/s | +---------------------+--------------+ |E4| 139.264 Mb/s | +---------------------+--------------+ |E5| 565.148 Mb/s | +---------------------+--------------+ |T1/DS1| 1.544 Mb/s | +---------------------+--------------+ |T1C/DS1C| 3.152 Mb/s | +---------------------+--------------+ |T2/DS2| 6.312 Mb/s | +---------------------+--------------+ |T3/DS3| 44.736 Mb/s | +---------------------+--------------+ |T4/DS4| 274.176 Mb/s | +---------------------+--------------+ |T5/DS5`` | 400.352 Mb/s | +---------------------+--------------+

A library like this is useless if not correct, which is why I've invested so much time in test coverage. If you find an incorrect result, please create a new issue with the input as well as expected and actual output.