Skip to main content

bookeep keeps track of units, bounds, and immutable items.

Project description

Version_status Documentation license

What is bookkeep?

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

Installation

Get the latest version of bookkeep from https://pypi.python.org/pypi/bookkeep/

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://github.com/yoelcortes/bookkeep

Documentation

bookkeep’s documentation is available on the web:

http://bookkeep.readthedocs.io/

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'},
...                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
UnitManager: {'T': 'degC'}
>>> 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 RuntimeWarning is issued when a value is set out of bounds:

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

Nested SmartBook objects are easy to read, and can be made using the same units and bounds. A representative pandas DataFrame object can be created from the SmartBook object.

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(units=sb.units, sb1=sb1, sb2=sb2)
        {'sb1':
            {'T': 25 (degC),
             'P': 500 (Pa)},
         'sb2':
            {'T': 50 (degC),
             'Duty': 50 (kg/hr)}}

Create DataFrame object:

>>>  nsb.table()
        Units Value
sb1:
  T         K    25
  P        Pa   500
sb2:
  T         K    50
  Duty  kJ/hr    50

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: RuntimeWarning: T (-274.15 degC) is out of bounds.
 T should be within -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:

https://github.com/yoelcortes/bookkeep

Bug reports

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

https://github.com/yoelcortes/bookkeep

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.

Citation

To cite bookkeep in publications use:

Yoel Cortes-Pena (2018). bookkeep: An easy way to track quantities
https://github.com/yoelcortes/bookkeep

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.3.tar.gz (8.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page