bookeep keeps track of units, bounds, and immutable items.
Project description
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:
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
UnitManager: {'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 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 (-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(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 degC 25
P Pa 500
sb2:
T degC 50
Duty kJ/hr 50
SmartBook objects assume bounds are inclusive, but may be set otherwise through the inclusive argument.
Create a SmarBook object excluding bound limits, with value at lower bound limit:
>>> SmartBook(sb.units, sb.bounds, T=-273.15, inclusive={'T': (False, False)})
__main__:1: RuntimeWarning: @Operating conditions: T (-273.15 degC) is out of bounds (-273.15 to 726.85 degC).
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 (-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.
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.