FormattedNumber and post Latex and HTML conversion (#134)

CHANGELOG.rst

@@ -11,14 +11,40 @@ Unreleased
 Added
 ^^^^^
 
+* Added the ``FormattedNumber`` class.
+  This class is a subclass of ``str`` and is now returned by the
+  ``Formatter`` instead of ``str``.
+  The ``FormattedNumber`` class allows post-conversion to ASCII, HTML,
+  and LaTeX formats.
+  [`#114 <https://github.com/jagerber48/sciform/issues/114>`_]
 * Added separate flags for code coverage reports for each python
   version.
 
 Changed
 ^^^^^^^
 
+* In addition to removing the ``latex`` option from the ``Formatter`` in
+  favor of the introduction of the ``FormattedNumber`` class, the
+  LaTeX conversion algorithm has been slightly modified.
+
+    * Left and right parentheses are no longer converted to ``"\left("``
+      and ``"\right)"`` due to introducing strange spacing issues.
+      See
+      `Spacing around \\left and \\right <https://tex.stackexchange.com/questions/2607/spacing-around-left-and-right>`_.
+    * Previously spaces within the ``sciform`` output were handled
+      inconsistently and occasionally required confusing extra handling.
+      Now any spaces in the input string are directly and explicitly
+      converted into math mode medium spaces: ``"\:"``.
+    * ``"μ"`` is now included in the math mode ``\text{}`` environment
+      and converted to ``"\textmu"``.
+
 * **[BREAKING]** Renamed ``fill_char`` to ``left_pad_char``.
   [`#126 <https://github.com/jagerber48/sciform/issues/126>`_]
+* Slimmed down ``[dev]`` optional dependencies and created
+  ``[examples]`` optional dependencies.
+  The former includes development tools, while the latter includes
+  the heavy-weight requirements needed to run all the examples,
+  including, e.g. ``jupyter``, ``scipy``, etc.
 
 Fixed
 ^^^^^
@@ -28,6 +54,16 @@ Fixed
   parentheses, e.g. ``"(1.2 ± 0.1)"``.
   [`#130 <https://github.com/jagerber48/sciform/issues/130>`_]
 
+Removed
+^^^^^^^
+
+* **[BREAKING]** Removed the ``latex`` option in favor of the
+  introduction of the ``FormattedNumber.as_latex()`` method.
+  This removal simplifies the formatting algorithm by separating LaTeX
+  formatting from other tasks like exponent string resolution.
+  The ``latex`` option also introduced a potential confusion with the
+  ``superscript`` option, which had no effect when ``latex=True``.
+
 ----
 
 0.32.3 (2024-01-11)

docs/source/api.rst

@@ -32,3 +32,10 @@ Global Configuration
 .. autofunction:: reset_global_defaults()
 
 .. autoclass:: GlobalDefaultsContext()
+
+Output Conversion
+=================
+
+.. autoclass:: sciform.formatter.FormattedNumber
+   :members:
+   :private-members:

docs/source/conf.py

@@ -40,6 +40,8 @@
 todo_include_todos = True
 todo_emit_warnings = True
 
+autodoc_member_order = "bysource"
+
 # For wrapping of text in tables
 html_css_files = [
     "css/custom.css",

docs/source/options.rst

@@ -72,13 +72,13 @@ mantissa ``m`` satisfies ``1 <= m < 10``.
 >>> print(sform(123.456, 0.001))
 (1.23456 ± 0.00001)e+02
 
-Note that, for all exponent modes, the exponent integer is always
-displayed with a sign symbol (+ or -) and is left padded with a zero so
-that it is at least two digits wide.
-There are no options to modify this behavior for standard exponent
-display.
-The :ref:`superscript` or :ref:`latex_format` options can be used as
-alternatives.
+By default the exponent is expressed using ASCII characters, e.g.
+``e+02``.
+The sign symbol is always included and the exponent value is left padded
+so that it is at least two digits wide.
+These behaviors for ASCII exponents cannot be modified.
+However the :ref:`superscript` mode can be used to represent the
+exponent using Unicode superscript characters.
 
 .. _engineering:
 
@@ -567,46 +567,6 @@ superscript notation as opposed to e.g. ``e+02`` notation.
 >>> print(sform(789))
 7.89×10²
 
-.. _latex_format:
-
-Latex Format
-============
-
-The ``latex`` option can be chosen to convert strings into latex
-parseable codes.
-
->>> sform = Formatter(
-...     exp_mode="scientific",
-...     exp_val=-1,
-...     upper_separator="_",
-...     latex=True,
-... )
->>> print(sform(12345))
-123\_450\times 10^{-1}
->>> sform = Formatter(
-...     exp_mode="percent",
-...     lower_separator="_",
-...     latex=True,
-... )
->>> print(sform(0.12345678, 0.00000255))
-\left(12.345\_678 \pm 0.000\_255\right)\%
-
-The latex format makes the following changes:
-
-* Convert standard exponent strings such as ``'e+02'`` into latex
-  superscript strings like ``'\times 10^{+2}``
-* Replace ``'('`` and ``')'`` by latex size-aware delimiters
-  ``'\left('`` and ``'\right)'``.
-* Replace ``'±'`` by ``'\pm'``
-* Replace ``'_'`` by ``'\_'``
-* Replace ``'%'`` by ``'\%'``
-* Exponent replacements such as ``'M'``, ``'Ki'``, or ``'ppb'`` and
-  non-finite numbers such as ``'nan'``, ``'NAN'``, ``'inf'``, and
-  ``'INF'`` are wrapped in ``'\text{}'``.
-
-Note that use of ``latex`` renders the use of the ``superscript``
-option meaningless.
-
 Include Exponent on nan and inf
 ===============================
 

docs/source/usage.rst

@@ -138,7 +138,6 @@ package default settings):
  'extra_parts_per_forms': {},
  'capitalize': False,
  'superscript': False,
- 'latex': False,
  'nan_inf_exp': False,
  'paren_uncertainty': False,
  'pdg_sig_figs': False,
@@ -176,7 +175,6 @@ unchanged.
  'extra_parts_per_forms': {},
  'capitalize': False,
  'superscript': False,
- 'latex': False,
  'nan_inf_exp': False,
  'paren_uncertainty': False,
  'pdg_sig_figs': False,
@@ -218,6 +216,106 @@ If the user wishes to configure these options, but also use the
 :ref:`FSML <fsml>`, then they must do so by modifying the global default
 settings.
 
+.. _output_conversion:
+
+Output Conversion
+=================
+
+Typically the output of the :class:`Formatter` is used as a regular
+python string.
+However, the :class:`Formatter` actually returns a
+:class:`FormattedNumber <formatter.FormattedNumber>` instance.
+The :class:`FormattedNumber <formatter.FormattedNumber>` class
+subclasses ``str`` and in many cases is used like a normal python
+string.
+However, the :class:`FormattedNumber <formatter.FormattedNumber>` class
+exposes methods to convert the standard string representation into
+LaTex, HTML, or ASCII representations.
+The LaTeX and HTML representations may be useful when :mod:`sciform`
+outputs are being used in contexts outside of e.g. text terminals such
+as `Matplotlib <https://matplotlib.org/>`_ plots,
+`Jupyter <https://jupyter.org/>`_ notebooks, or
+`Quarto <https://quarto.org/>`_ documents which support richer display
+functionality than Unicode text.
+The ASCII representation may be useful if :mod:`sciform` outputs are
+being used in contexts in which only ASCII, and not Unicode, text is
+supported or preferred.
+
+These conversions can be accessed via the
+:meth:`as_latex() <formatter.FormattedNumber.as_latex>`,
+:meth:`as_html() <formatter.FormattedNumber.as_html>`, and
+:meth:`as_ascii() <formatter.FormattedNumber.as_ascii>` methods on the
+:class:`FormattedNumber <formatter.FormattedNumber>` class.
+
+>>> sform = Formatter(
+...     exp_mode="scientific",
+...     exp_val=-1,
+...     upper_separator="_",
+...     superscript=True,
+... )
+>>> formatted_str = sform(12345)
+>>> print(f"{formatted_str} -> {formatted_str.as_latex()}")
+123_450×10⁻¹ -> $123\_450\times10^{-1}$
+>>> print(f"{formatted_str} -> {formatted_str.as_html()}")
+123_450×10⁻¹ -> 123_450×10<sup>-1</sup>
+>>> print(f"{formatted_str} -> {formatted_str.as_ascii()}")
+123_450×10⁻¹ -> 123_450e-01
+
+>>> sform = Formatter(
+...     exp_mode="percent",
+...     lower_separator="_",
+... )
+>>> formatted_str = sform(0.12345678, 0.00000255)
+>>> print(f"{formatted_str} -> {formatted_str.as_latex()}")
+(12.345_678 ± 0.000_255)% -> $(12.345\_678\:\pm\:0.000\_255)\%$
+>>> print(f"{formatted_str} -> {formatted_str.as_html()}")
+(12.345_678 ± 0.000_255)% -> (12.345_678 ± 0.000_255)%
+>>> print(f"{formatted_str} -> {formatted_str.as_ascii()}")
+(12.345_678 ± 0.000_255)% -> (12.345_678 +/- 0.000_255)%
+
+>>> sform = Formatter(
+...     exp_mode="engineering",
+...     exp_format="prefix",
+...     ndigits=4
+... )
+>>> formatted_str = sform(314.159e-6, 2.71828e-6)
+>>> print(f"{formatted_str} -> {formatted_str.as_latex()}")
+(314.159 ± 2.718) μ -> $(314.159\:\pm\:2.718)\:\text{\textmu}$
+>>> print(f"{formatted_str} -> {formatted_str.as_html()}")
+(314.159 ± 2.718) μ -> (314.159 ± 2.718) μ
+>>> print(f"{formatted_str} -> {formatted_str.as_ascii()}")
+(314.159 ± 2.718) μ -> (314.159 +/- 2.718) u
+
+The LaTeX enclosing ``"$"`` math environment symbols can be optionally
+stripped:
+
+>>> sform = Formatter(
+...     exp_mode="engineering",
+...     exp_format="prefix",
+...     ndigits=4
+... )
+>>> formatted_str = sform(314.159e-6, 2.71828e-6)
+>>> print(f"{formatted_str} -> {formatted_str.as_latex(strip_math_mode=False)}")
+(314.159 ± 2.718) μ -> $(314.159\:\pm\:2.718)\:\text{\textmu}$
+>>> print(f"{formatted_str} -> {formatted_str.as_latex(strip_math_mode=True)}")
+(314.159 ± 2.718) μ -> (314.159\:\pm\:2.718)\:\text{\textmu}
+
+In addition to exposing
+:meth:`as_latex() <formatter.FormattedNumber.as_latex>` and
+:meth:`as_html() <formatter.FormattedNumber.as_html>`,
+the :class:`FormattedNumber <formatter.FormattedNumber>` class defines
+the aliases
+:meth:`_repr_latex_() <formatter.FormattedNumber._repr_latex_>` and
+:meth:`_repr_html_() <formatter.FormattedNumber._repr_html_>`.
+The
+`IPython display functions <https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#functions>`_
+looks for these methods, and, if available, will use them to display
+prettier representations of the class than the Unicode ``__repr__``
+representation.
+
+.. image:: ../../examples/outputs/jupyter_output.png
+  :width: 400
+
 .. _dec_and_float:
 
 Note on Decimals and Floats

examples/jupyter_output_example.ipynb

@@ -0,0 +1,50 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec4427f1-623b-4cd5-a077-63d5204cc7b0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from sciform import Formatter\n",
+    "from IPython.display import display_latex, display_html\n",
+    "\n",
+    "sform = Formatter(exp_mode=\"scientific\", superscript=True)\n",
+    "val = sform(123456, 789)\n",
+    "\n",
+    "print('String:')\n",
+    "print(val)\n",
+    "print('\\nASCII:')\n",
+    "print(val.as_ascii())\n",
+    "print('\\nLatex:')\n",
+    "display_latex(val)\n",
+    "print('\\nHTML:')\n",
+    "display_html(val)\n",
+    "print('\\nDefault Display (HTML)')\n",
+    "display(val)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -35,16 +35,23 @@ dev = [
     "sphinx-rtd-theme",
     "sphinx-toolbox",
     "numpy",
+]
+examples = [
+    "numpy",
     "scipy",
     "matplotlib",
     "tabulate",
+    "jupyter",
 ]
 
 [tool.setuptools.dynamic]
 readme = {file = "README.rst"}
 
 [tool.setuptools_scm]
 
+[tool.ruff]
+allowed-confusables = ["×"]
+
 [tool.ruff.lint]
 select = ['ALL']
 ignore = [
@@ -57,8 +64,12 @@ ignore = [
     'TD002',
     'TD003',
     'FIX002',
+    'RET504',
 ]
 
+[tool.ruff.format]
+docstring-code-format = true
+
 [tool.ruff.per-file-ignores]
 "tests/*.py" = ["D", "ANN", "PT"]
 "examples/*.py" = ["D"]