sciform 0.38.0__tar.gz → 0.38.1__tar.gz

{sciform-0.38.0 → sciform-0.38.1}/CHANGELOG.rst

@@ -9,8 +9,22 @@ Unreleased
 ----------
 
 * Any unreleased changes can be viewed in the latest version
-  documentation
-  `changelog <https://sciform.readthedocs.io/en/latest/project.html#changelog>`_.
+   documentation
+   `changelog <https://sciform.readthedocs.io/en/latest/project.html#changelog>`_.
+
+0.38.1 (2024-11-02)
+-------------------
+
+Added
+-----
+
+* Documented examples demonstrating the interplay between ``sciform``
+  formatting the ``decimal`` module configuration.
+  [`#183 <https://github.com/jagerber48/sciform/issues/183>`_]
+* Added an example demonstrating how users can implement a "fallback"
+  formatter for cases when users want different formatting behavior
+  applied when the uncertainty is invalid or not present.
+  [`#177 <https://github.com/jagerber48/sciform/issues/177>`_]
 
 ----
 

{sciform-0.38.0/src/sciform.egg-info → sciform-0.38.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sciform
-Version: 0.38.0
+Version: 0.38.1
 Summary: A package for formatting numbers into scientific formatted strings.
 Author-email: Justin Gerber <justin.gerber48@gmail.com>
 Project-URL: homepage, https://github.com/jagerber48/sciform

{sciform-0.38.0 → sciform-0.38.1}/docs/source/examples.rst

@@ -352,7 +352,7 @@ makes this easy.
  ['7.000(30) M' '8.000(20) M' '9.000(10) M']]
 
 Appending Units
-========================
+===============
 
 The :mod:`sciform` :ref:`SI prefix mode<exp_str_replacement>` allows
 exponent strings such as ``'e+03'`` to be replaced with their SI
@@ -416,3 +416,120 @@ At this point it would be recommended to, instead, directly calculate
 the unit, rescale the numerical inputs to :mod:`sciform` formatting, and
 append the entire unit without utilizing the :mod:`sciform` SI prefix
 mode.
+
+Interactions with the Decimal Module
+====================================
+
+Numbers passed into :mod:`sciform` are always converted into
+:class:`Decimal` instances during formatting.
+Various options exposed by the
+`Decimal module <https://docs.python.org/3/library/decimal.html>`_
+will (desirably or undesirably) modify :mod:`sciform` formatting
+behavior.
+
+>>> import decimal
+>>> from sciform import SciNum
+>>>
+>>> # We calculate 1/9 in a high precision decimal context
+>>> with decimal.localcontext() as ctx:
+...     ctx.prec = 100
+...     num = decimal.Decimal(1)/decimal.Decimal(9)
+>>> # Formatted in the default decimal context
+>>> print(format(SciNum(num), "Af"))
+0.1111111111111111111111111111
+>>>
+>>> # Formatted in a low precision decimal context
+>>> with decimal.localcontext() as ctx:
+...     ctx.prec = 5
+...     print(format(SciNum(num), "Af"))
+0.11111
+>>>
+>>> # Formatted in a high precision decimal context
+>>> with decimal.localcontext() as ctx:
+...     ctx.prec = 50
+...     print(format(SciNum(num), "Af"))
+0.11111111111111111111111111111111111111111111111111
+>>>
+>>> # Formatted in a decimal context with a different rounding rule
+>>> with decimal.localcontext() as ctx:
+...     ctx.rounding = decimal.ROUND_CEILING
+...     print(format(SciNum(num), "Af"))
+0.1111111111111111111111111112
+
+We see that the number of digits shown in the ``"all"`` round mode can
+be modified using the decimal context precision.
+We also see that the rounding mode can be adjusted away from the default
+round-to-even rounding.
+
+When working on high precision applications, recall that :class:`float`
+instances will always be converted to :class:`Decimal` instances with 17
+digits of precision or fewer.
+So, if you desire higher precision you should use :class:`Decimal`
+rather than :class:`float` inputs, otherwise you may observe undesirable
+behavior.
+See :ref:`dec_and_float`.
+
+Fallback Formatters
+===================
+
+Sometimes values and value/uncertainty pairs with various properties may
+appear together in the same context.
+It may be inappropriate to use a single formatter for all of these
+inputs.
+For example
+
+>>> from sciform import Formatter
+>>> sform = Formatter(round_mode="pdg", paren_uncertainty=True)
+>>> print(sform(123456, 0.0789))
+123456.00(8)
+>>> print(sform(123456, float("nan")))
+120000(nan)
+>>> print(sform(123456))
+120000
+
+In both the cases when the uncertainty was invalid for rounding and when
+the uncertainty wasn't present the rounding got applied to the value
+directly.
+However, it may be inappropriate to apply PDG rounding, which is usually
+used for uncertainty, to the value.
+Instead, the user may want to retain more significant figures when
+rounding is applied to the value instead of the uncertainty.
+Users can resolve this by defining two formatters and a simple helper
+function to cover these cases.
+
+>>> from math import isfinite
+>>> from sciform import Formatter
+>>>
+>>> def generate_multi_formatter(
+...     val_unc_formatter=None,
+...     val_formatter=None
+... ):
+...     if val_unc_formatter is None:
+...         val_unc_formatter = Formatter()
+...     if val_formatter is None:
+...         val_formatter = Formatter()
+...     def multi_formatter(val, unc=None):
+...         if unc is None or not isfinite(unc):
+...             return val_formatter(val, unc)
+...         else:
+...             return val_unc_formatter(val, unc)
+...     return multi_formatter
+>>>
+>>> multi_formatter = generate_multi_formatter(
+...     val_unc_formatter = Formatter(
+...         round_mode="pdg",
+...         paren_uncertainty=True,
+...     ),
+...     val_formatter=Formatter(
+...         round_mode="sig_fig",
+...         ndigits=6,
+...         paren_uncertainty=True,
+...     ),
+... )
+>>>
+>>> print(multi_formatter(123456, 0.0789))
+123456.00(8)
+>>> print(multi_formatter(123456, float("nan")))
+123456(nan)
+>>> print(multi_formatter(123456))
+123456

{sciform-0.38.0 → sciform-0.38.1/src/sciform.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sciform
-Version: 0.38.0
+Version: 0.38.1
 Summary: A package for formatting numbers into scientific formatted strings.
 Author-email: Justin Gerber <justin.gerber48@gmail.com>
 Project-URL: homepage, https://github.com/jagerber48/sciform