achevrot / impunity

A Python library to check physical units

impunity is a Python library consisting of a single decorator function designed to ensure consistency of physical quantities. Compared to other libraries (pint, etc.), it has a minimal overhead on performance because physical units are only manipulated through static analysis and disappear at runtime.

impunity is based on Python “flexible variable and function annotations” (PEP 593) and checks consistency between variables and arguments of functions. If physical units are consistent, impunity rewrites the code by automatically applying conversions in the code of the function.

impunity is compatible with regular type annotations, and functions decorated with impunity remain compatible with other static analysis tools and type checkers like mypy.

In most situations, impunity will only perform minimal sanity checks on your code at import time and not edit anything.

Installation

impunity is available on pip (and soon conda):

pip install impunity

For development purposes, clone the repository and use poetry:

git clone --depth=1 https://github.com/achevrot/impunity
cd impunity
poetry install

Usage

Full documentation available at website

• The most simple usage consists of using units placed as annotations: code is checked and rewritten if need be.

  from impunity import impunity
  
  def speed(distance: "m", time: "s") -> "m/s":
      return distance / time
  
  @impunity
  def regular_conversion():
      altitudes: "ft" = np.arange(0, 1000, 100)
      duration: "mn" = 100
      result = speed(altitudes, duration)
      print(result)  # results in m/s
  
      result_imperial: "ft/mn" = speed(altitudes, duration)
      print(result_imperial)  # results in ft/mn
  
  if __name__ == "__main__":
      regular_conversion()

• The check fails if units are inconsistent:

  @impunity
  def inconsistent_units():
      temperatures: "K" = np.arange(0, 100, 10)
      duration: "s" = 6000
      return speed(temperatures, duration)
  
  # Warning: "K" is not compatible with "m"

• Only check for consistency, do not attempt to rewrite the code:

  @impunity(rewrite=False)  # only check for consistency
  def regular_conversion():
      pass
  
  @impunity(rewrite="output.log")  # check code output in an external file
  def regular_conversion():
      pass

Compatibility with type checkers

Types can be used with the Annotated keyword, which carries

from typing import Annotation
import numpy.types as npt

feet_array = Annotated[npt.ndarray[np.float64], "ft"]
altitudes: feet_array = np.arange(0, 1000, 100)

impunity is implemented and typed with Annotated keywords.

Tests

Tests are supported by the unittest package.

Because AST manipulation can be tricky, continuous integration is ensured by Github Actions for:

• Linux, MacOS and Windows;
• all versions of Python since 3.8

Why impunity?

We were searching for a pun with physical units. Things converged on im-pun-unit-y.

impunity's Issues

NameError: name '_call_reprcompare' is not defined when several asserts in test

This is probably due to the fun.code.co_consts not being properly reconstructed due to pytest decorators.
Might be an issue with other methods overhead.

problems with list warnings

In some cases, lists shouldn't raise warnings:

a1: Annotated(list[float], "m")   # should raise a warning
a2: Annotated(list[float], "m") = []  # should raise a warning
a3 = []  # should not raise a warning

x: "m"
a4 = [x]  # should raise a warning

y: "ft"
y, *_ = a4  # does not convert units

Annotated Assignment when the value of the node is iterable

alt_m1: "m" = 1000
alt_m2: "m" = 1000
alt_m3: "m" = 1000
l: "m" = [alt_m1, alt_m2, alt_m3]
self.assertEqual(l[0], 1000)
l2: "ft" = [alt_m1, alt_m2, alt_m3]
self.assertAlmostEqual(l2[0], 3280.84, delta=1e-2)

First test is fine but second one fails : can't multiply sequence by non-int of type 'float'

Would need to change the Annotated Assign node visitor implementation to do so.

impunified functions fail if some (sometimes irrelevant) annotations are missing

from impunity import impunity
from typing_extensions import Annotated


@impunity
def above_sea_level(a: Annotated[float, "m"]):
    return a > 0

Raises a KeyError: 'return'

add ignore argument to impunity decorator

@impunity(ignore_warnings=True)
def fun():
	a: "m" = 1
   x = [a]
	return x

arguments for parsing only class attributes

@impunity(methods=False)
class M:
	distance: "m"
   time: pd.Timestamp
	duration: "s"

	def toto(self):
		pass  # not inspected

	@impunity
	def tata(self):
		pass  # inspected