unit-syntax 0.2.0__tar.gz → 0.2.2__tar.gz

{unit_syntax-0.2.0 → unit_syntax-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unit-syntax
-Version: 0.2.0
+Version: 0.2.2
 Summary: Physical unit literals for Jupyter and IPython
 Home-page: https://github.com/ahupp/unit-syntax
 Author: Adam Hupp
@@ -25,11 +25,11 @@ Description-Content-Type: text/markdown
 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.
+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.
 
-Where? `unit-syntax` currently supports Jupyter notebooks and the IPython interpreter; support for standalone scripts is planned.
+`unit-syntax` currently supports Jupyter notebooks and the IPython interpreter; maybe someday support for standalone scripts.
 
-How? A syntax transformer based on the official Python grammar turns these expression into calls to the excellent [Pint](https://pint.readthedocs.io/) units library.
+[How does it work?](#how-does-it-work)
 
 ## Getting Started
 
@@ -42,8 +42,7 @@ $ pip install unit-syntax
 To enable unit-syntax in a Jupyter/IPython session run:
 
 ```python
-import unit_syntax
-unit_syntax.enable_ipython()
+%load_ext unit_syntax
 ```
 
 Tip: In Jupyter this must be run in its own cell before any units expressions are evaluated.
@@ -60,13 +59,13 @@ Units can be applied to any "simple" expression:
 - unary operators: `-x dBm`
 - power: `x**2 meters`
 
-To apply units within a more complex expression, use parentheses:
+In expressions mixing units and binary operators, parenthesize:
 
 ```python
 one_lux = (1 lumen)/(1 meter**2)
 ```
 
-Units can be used in other places where Python allows expressions like:
+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)]`
@@ -92,26 +91,32 @@ x (newton meters)/(second*kg)
 x newton meters/(second*kg)
 ```
 
-## Why only allow units on simple expressions?
-
-The rule for applying units only to "simple" expressions rather than treating it as a typical operator is to avoid unintentional error. Imagine units were instead parsed as operator with high precedence and you wrote this reasonable looking expression:
+Using invalid units produces a syntax error at import time:
 
 ```python
-ppi = 300 pixels/inch
-y = x inches * ppi
+>>> 1 smoot
+...
+SyntaxError: 'smoot' is not defined in the unit registry
 ```
 
-`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 hypoethical concern, I hit this within 10 minutes of first trying out the idea)
+## How does it work?
 
-## Help!
+The parser is [pegen](https://we-like-parsers.github.io/pegen/), which is the same parser generator used by Python itself. The grammar is a lightly modified version the official Python grammar.
 
-If you're getting an unexpected result, try using `unit_syntax.enable_ipython(debug_transform=True)`. This will log the transformed Python code to the console.
+Syntax transformation in IPython/Jupyter uses [IPython custom input transformers](https://ipython.readthedocs.io/en/stable/config/inputtransforms.html).
 
-If you're stuck, feel free to open an issue.
+## Why only allow units on simple expressions?
 
-## How does it work?
+Imagine units were instead parsed as operator with high precedence and you wrote this reasonable looking expression:
+
+```python
+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)
 
-The parser is derived from the official Python grammar using the same parser generator ([pegen](https://github.com/we-like-parsers/pegen)) as Python itself. The transformer hooks into IPython/Jupyter using [custom input transformers](https://ipython.readthedocs.io/en/stable/config/inputtransforms.html).
+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
 
@@ -127,7 +132,7 @@ A [long discussion on the python-ideas mailing list](https://lwn.net/Articles/90
 
 To regenerate the parser:
 
-`python -m pegen grammar.txt -o unit_syntax/parser.py`
+`python -m pegen python_units.gram -o unit_syntax/parser.py`
 
 Running tests:
 
@@ -140,11 +145,10 @@ $ poetry run pytest
 
 - Test against various ipython and python versions
 - Support standalone scripts through sys.meta_path
-- Check units at parse time
 - Unit type hints, maybe checked with [@runtime_checkable](https://docs.python.org/3/library/typing.html#typing.runtime_checkable). More Pint typechecking [discussion](https://github.com/hgrecco/pint/issues/1166)
 - Expand the demo Colab notebook
 - Typography of output
 - make it work with numba
 - understand how numpy interop works
-- fail more clearly when units are used in an invalid location
+- pre-parse units
 

{unit_syntax-0.2.0 → unit_syntax-0.2.2}/README.md

@@ -6,11 +6,11 @@
 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.
+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.
 
-Where? `unit-syntax` currently supports Jupyter notebooks and the IPython interpreter; support for standalone scripts is planned.
+`unit-syntax` currently supports Jupyter notebooks and the IPython interpreter; maybe someday support for standalone scripts.
 
-How? A syntax transformer based on the official Python grammar turns these expression into calls to the excellent [Pint](https://pint.readthedocs.io/) units library.
+[How does it work?](#how-does-it-work)
 
 ## Getting Started
 
@@ -23,8 +23,7 @@ $ pip install unit-syntax
 To enable unit-syntax in a Jupyter/IPython session run:
 
 ```python
-import unit_syntax
-unit_syntax.enable_ipython()
+%load_ext unit_syntax
 ```
 
 Tip: In Jupyter this must be run in its own cell before any units expressions are evaluated.
@@ -41,13 +40,13 @@ Units can be applied to any "simple" expression:
 - unary operators: `-x dBm`
 - power: `x**2 meters`
 
-To apply units within a more complex expression, use parentheses:
+In expressions mixing units and binary operators, parenthesize:
 
 ```python
 one_lux = (1 lumen)/(1 meter**2)
 ```
 
-Units can be used in other places where Python allows expressions like:
+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)]`
@@ -73,26 +72,32 @@ x (newton meters)/(second*kg)
 x newton meters/(second*kg)
 ```
 
-## Why only allow units on simple expressions?
-
-The rule for applying units only to "simple" expressions rather than treating it as a typical operator is to avoid unintentional error. Imagine units were instead parsed as operator with high precedence and you wrote this reasonable looking expression:
+Using invalid units produces a syntax error at import time:
 
 ```python
-ppi = 300 pixels/inch
-y = x inches * ppi
+>>> 1 smoot
+...
+SyntaxError: 'smoot' is not defined in the unit registry
 ```
 
-`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 hypoethical concern, I hit this within 10 minutes of first trying out the idea)
+## How does it work?
 
-## Help!
+The parser is [pegen](https://we-like-parsers.github.io/pegen/), which is the same parser generator used by Python itself. The grammar is a lightly modified version the official Python grammar.
 
-If you're getting an unexpected result, try using `unit_syntax.enable_ipython(debug_transform=True)`. This will log the transformed Python code to the console.
+Syntax transformation in IPython/Jupyter uses [IPython custom input transformers](https://ipython.readthedocs.io/en/stable/config/inputtransforms.html).
 
-If you're stuck, feel free to open an issue.
+## Why only allow units on simple expressions?
 
-## How does it work?
+Imagine units were instead parsed as operator with high precedence and you wrote this reasonable looking expression:
+
+```python
+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)
 
-The parser is derived from the official Python grammar using the same parser generator ([pegen](https://github.com/we-like-parsers/pegen)) as Python itself. The transformer hooks into IPython/Jupyter using [custom input transformers](https://ipython.readthedocs.io/en/stable/config/inputtransforms.html).
+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
 
@@ -108,7 +113,7 @@ A [long discussion on the python-ideas mailing list](https://lwn.net/Articles/90
 
 To regenerate the parser:
 
-`python -m pegen grammar.txt -o unit_syntax/parser.py`
+`python -m pegen python_units.gram -o unit_syntax/parser.py`
 
 Running tests:
 
@@ -121,10 +126,9 @@ $ poetry run pytest
 
 - Test against various ipython and python versions
 - Support standalone scripts through sys.meta_path
-- Check units at parse time
 - Unit type hints, maybe checked with [@runtime_checkable](https://docs.python.org/3/library/typing.html#typing.runtime_checkable). More Pint typechecking [discussion](https://github.com/hgrecco/pint/issues/1166)
 - Expand the demo Colab notebook
 - Typography of output
 - make it work with numba
 - understand how numpy interop works
-- fail more clearly when units are used in an invalid location
+- pre-parse units

{unit_syntax-0.2.0 → unit_syntax-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "unit-syntax"
-version = "0.2.0"
+version = "0.2.2"
 authors = ["Adam Hupp <adam@hupp.org>"]
 packages = [{ include = "unit_syntax" }]
 readme = "README.md"

unit_syntax-0.2.2/unit_syntax/__init__.py

@@ -0,0 +1,14 @@
+import pint
+
+
+# Use the _DEFAULT_REGISTRY so we can interoperate with other pint-using libraries
+ureg = pint._DEFAULT_REGISTRY
+
+
+BOOTSTRAP = """
+import unit_syntax
+_unit_syntax_q = unit_syntax.ureg.Quantity
+"""
+
+
+from .ipython import load_ipython_extension, unload_ipython_extension

unit_syntax-0.2.2/unit_syntax/ipython.py

@@ -0,0 +1,71 @@
+from .transform import transform
+import pint
+
+
+def _add_formatters(ipython):
+    # Overide default formatters to use reduced units.  This lets us keep using the
+    # default registry for interop with other pint-using libraries, but gives more
+    # sensible output in the notebook.
+    def add_formatter(mime, display_fn_name):
+        fn = getattr(pint.Quantity, display_fn_name, None)
+        if fn is None:
+            return
+
+        def fmt_reduced(q, *args):
+            return fn(q.to_reduced_units(), *args)
+
+        formatter = ipython.display_formatter.formatters[mime]
+        formatter.for_type(pint.Quantity, fmt_reduced)
+
+    add_formatter("text/markdown", "_repr_markdown_")
+    add_formatter("text/html", "_repr_html_")
+    add_formatter("text/plain", "_repr_pretty_")
+    add_formatter("text/latex", "_repr_latex_")
+
+
+_has_init_log = False
+_debug = False
+
+
+def transform_lines(lines: list[str]) -> list[str]:
+    """IPython transforms provide a list of strings in the current cell, but to parse correctly we
+    need to parse them as a single string"""
+    return transform("".join(lines)).splitlines(keepends=True)
+
+
+def ipython_transform(lines):
+    ret = transform_lines(lines)
+
+    if _debug:
+        import logging
+
+        global _has_init_log
+        if not _has_init_log:
+            logging.basicConfig(level=logging.DEBUG, force=True)
+        _has_init_log = True
+        logging.debug("unit_syntax: %s -> %s", "\n".join(lines), "\n".join(ret))
+    return ret
+
+
+def load_ipython_extension(ipython):
+    if not hasattr(ipython, "input_transformers_post"):
+        raise ImportError("Unsupported IPython version, version >=7 is required")
+
+    ipython.input_transformers_post.append(ipython_transform)
+
+    _add_formatters(ipython)
+
+    from . import BOOTSTRAP
+
+    ipython.run_cell(BOOTSTRAP)
+
+    try:
+        import matplotlib
+
+        pint.setup_matplotlib(True)
+    except ImportError:
+        pass
+
+
+def unload_ipython_extension(ipython):
+    ipython.input_transformers_post.remove(ipython_transform)