Skip to main content

keep track of units and measurement bounds.

Project description

Version_status Documentation license

What is bookkeep?

bookkeep is a python package for keeping track of units of measure and measurment bounds. The package mainly features the SmartBook, a dictionary subclass that incorporates pint Quantity objects for managing units of measure.


Get the latest version of bookkeep from

If you have an installation of Python with pip, simple install it with:

$ pip install bookkeep

To get the git version, run:

$ git clone git://


bookkeep’s documentation is available on the web:

Getting started

SmartBook objects are dictionaries that provide an easy way to keep track of units of measure and enforce bounds.

Create a SmartBook object with units, bounds, a source description, and arguments to initialize the dictionary:

>>> sb = SmartBook(units={'T': 'K', 'Duty': 'kJ/hr'},
...                bounds={'T': (0, 1000)},
...                source='Operating conditions',
...                T=350)
>>> sb
{'T': 350 (K)}

The units attribute becomes a UnitManager object with a reference to all dictionaries (clients) it controls. These include the SmartBook and its bounds.

>>> sb.units
{'T': 'degC',
 'Duty': 'kJ/hr'}
>>> sb.units.clients
[{'T': 350 (K)}, {'T': (0, 1000)}]

Change units:

>>> sb.units['T'] = 'degC'
>>> sb
{'T': 76.85 (degC)}
>>> sb.bounds
{'T': array([ -273.15, 726.85])}

Add items:

>>> sb['P'] = 101325
>>> sb
{'T': 76.85 (degC),
 'P': 101325}

Add units:

>>> sb.units['P'] = 'Pa'
>>> sb
{'T': 76.85 (degC),
 'P': 101325 (Pa)}

A BookkeepWarning is issued when a value is set out of bounds:

>>> sb['T'] = -300
__main__:1: BookkeepWarning: @Operating conditions: T (-300 degC) is out of bounds (-273.15 to 726.85 degC).

Nested SmartBook objects are easy to read, and can be made using the same units and bounds.

Create new SmartBook objects:

>>> sb1 = SmartBook(sb.units, sb.bounds,
...                 T=25, P=500)
>>> sb2 = SmartBook(sb.units, sb.bounds,
...                 T=50, Duty=50)
>>> sb1
{'T': 25 (degC),
 'P': 500 (Pa)}
>>> sb2
{'T': 50 (degC),
 'Duty': 50 (kJ/hr)})

Create nested SmartBook:

>>> nsb = SmartBook(sb1=sb1, sb2=sb2)
    {'T': 25 (degC),
     'P': 500 (Pa)},
    {'T': 50 (degC),
     'Duty': 50 (kg/hr)}}

Pint Quantity objects are also compatible, so long as the corresponding Quantity class is set as the Quantity attribute.

Set a Quantity object:

>>> Q_ = SmartBook.Quantity
>>> sb1.bounds['T'] = Q_((0, 1000), 'K')
>>> sb1['T'] = Q_(100, 'K')
>>> sb1
{'T': -173.15 degC,
 'P': 500 (Pa)}

Setting a Quantity object out of bounds will issue a warning:

>>> sb1['T'] = Q_(-1, 'K')
 __main__:1: BookkeepWarning: T (-274.15 degC) is out of bounds (-273.15 to 726.85 degC).

Trying to set a Quantity object with wrong dimensions will raise an error:

>>> Q_ = SmartBook.Quantity
>>> sb1['T'] = Q_(100, 'meter')
DimensionalityError: Cannot convert from 'meter' ([length]) to 'degC' ([temperature])

Latest source code

The latest development version of bookeep’s sources can be obtained at:

Bug reports

To report bugs, please use the bookkeep’s Bug Tracker at:

License information

See LICENSE.txt for information on the terms & conditions for usage of this software, and a DISCLAIMER OF ALL WARRANTIES.

Although not required by the bookkeep license, if it is convenient for you, please cite bookkeep if used in your work. Please also consider contributing any changes you make back, and benefit the community.


To cite bookkeep in publications use:

Yoel Cortes-Pena (2018). bookkeep: An easy way to track quantities

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bookkeep-0.5.7.tar.gz (8.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page