Physical unit literals for Jupyter and IPython
Project description
unit-syntax
adds support for physical units to the Python language:
>>> speed = 5 meters/second
>>> (2 seconds) * speed
10 meter
Why? I often use Python as an interactive calculator for physical problems and wished it had the type safety of explicit units along with the readability of normal notation.
unit-syntax
currently supports Jupyter notebooks and the IPython interpreter; maybe someday support for standalone scripts.
Getting Started
Install the package:
$ pip install unit-syntax
To enable unit-syntax in a Jupyter/IPython session run:
%load_ext unit_syntax
Tip: In Jupyter this must be run in its own cell before any units expressions are evaluated.
Usage
An interactive notebook to play around with units
Units can be applied to any "simple" expression:
- number:
1 meter
- variables:
x parsec
,y.z watts
,area[id] meters**2
- lists and tuples:
[1., 37.] newton meters
- unary operators:
-x dBm
- power:
x**2 meters
In expressions mixing units and binary operators, parenthesize:
one_lux = (1 lumen)/(1 meter**2)
Units can be used in any place where Python allows expressions, e.g:
- function arguments:
area_of_circle(radius=1 meter)
- list comprehensions:
[x meters for x in range(10)]
Quantities can be converted to another measurement system:
>>> (88 miles / hour) furlongs / fortnight
236543.5269120001 furlong / fortnight
>>> (0 degC) degF
31.999999999999936 degree_Fahrenheit
Compound units (e.g. newtons/meter**2
) are supported and follow the usual precedence rules.
Units may not begin with parentheses (consider the possible
interpretations of x (meters)
). Parentheses are allowed anywhere else:
# parsed as a function call, will result in a runtime error
x (newton meters)/(second*kg)
# a-ok
x newton meters/(second*kg)
Using invalid units produces a syntax error at import time:
>>> 1 smoot
...
SyntaxError: 'smoot' is not defined in the unit registry
How does it work?
The parser is pegen, which is the same parser generator used by Python itself. The grammar is a lightly modified version the official Python grammar.
Syntax transformation in IPython/Jupyter uses IPython custom input transformers.
Why only allow units on simple expressions?
Imagine units were instead parsed as operator with high precedence and you wrote this reasonable looking expression:
ppi = 300 pixels/inch
y = x inches * ppi
inches * ppi
would be parsed as the unit, leading to (at best) a runtime error sometime later and at worst an incorrect calculation. This could be avoided by parenthesizing the expression (e.g. (x inches) * ppi
, but in general it's too error prone to allow free intermixing of operators and units. (Note: This is not a hypothical concern, I hit this within 10 minutes of first trying out the idea)
It's easy to detect units used when they aren't allowed (that syntax isn't valid anywhere else), but not generally possible to determine if you forgot parens or meant to write a unit.
Prior Art
The immediate inspriration of unit-syntax
is a language called Fortress from Sun Microsystems. Fortress was intended as a modern Fortran, and had first-class support for units in both the syntax and type system.
F# (an OCaml derivative from Microsoft) also has first class support for units.
The Julia package Unitful.jl
A long discussion on the python-ideas mailing list about literal units in Python.
Development
To regenerate the parser:
python -m pegen python_units.gram -o unit_syntax/parser.py
Running tests:
$ poetry install --with dev
$ poetry run pytest
Future work and open questions
- Test against various ipython and python versions
- Support standalone scripts through sys.meta_path
- Unit type hints, maybe checked with @runtime_checkable. More Pint typechecking discussion
- Expand the demo Colab notebook
- Typography of output
- make it work with numba
- understand how numpy interop works
- pre-parse units
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.
Source Distribution
Built Distribution
Hashes for unit_syntax-0.2.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fea001b05e37cfecec791591fdca6cb3b69c4d6f3008c0237a7bfb0c4f031f44 |
|
MD5 | e2a343a762899ebe818904d6105e96f9 |
|
BLAKE2b-256 | e761cedd7512166948c964d207722e2ea9feadc940250241a4a9dbc3b32e4c1f |