sciform 0.32.3__py3-none-any.whl → 0.34.0__py3-none-any.whl

sciform/__init__.py

@@ -1,22 +1,30 @@
 """``sciform`` is used to convert python numbers into scientific formatted strings."""
 
 from sciform.formatter import Formatter
+from sciform.formatting import FormattedNumber
 from sciform.global_configuration import (
-    GlobalDefaultsContext,
-    print_global_defaults,
-    reset_global_defaults,
-    set_global_defaults,
+    GlobalOptionsContext,
+    get_default_global_options,
+    get_global_options,
+    reset_global_options,
+    set_global_options,
 )
 from sciform.modes import AutoDigits, AutoExpVal
+from sciform.options.input_options import InputOptions
+from sciform.options.populated_options import PopulatedOptions
 from sciform.scinum import SciNum
 
 __all__ = [
     "Formatter",
-    "GlobalDefaultsContext",
-    "print_global_defaults",
-    "reset_global_defaults",
-    "set_global_defaults",
+    "FormattedNumber",
+    "GlobalOptionsContext",
+    "get_default_global_options",
+    "get_global_options",
+    "reset_global_options",
+    "set_global_options",
     "AutoDigits",
     "AutoExpVal",
     "SciNum",
+    "InputOptions",
+    "PopulatedOptions",
 ]

sciform/format_utils.py

@@ -10,7 +10,6 @@ from typing import Literal, Union, cast
 from sciform.modes import (
     AutoDigits,
     AutoExpVal,
-    ExpDriver,
     ExpFormatEnum,
     ExpModeEnum,
     RoundModeEnum,
@@ -155,7 +154,7 @@ def get_standard_exp_str(base: int, exp_val: int, *, capitalize: bool = False) -
 
 
 def get_superscript_exp_str(base: int, exp_val: int) -> str:
-    """Get superscript (e.g. '×10⁺²') exponent string."""  # noqa: RUF002
+    """Get superscript (e.g. '×10⁺²') exponent string."""
     sup_trans = str.maketrans("+-0123456789", "⁺⁻⁰¹²³⁴⁵⁶⁷⁸⁹")
     exp_val_str = f"{exp_val}".translate(sup_trans)
     return f"×{base}{exp_val_str}"
@@ -198,8 +197,6 @@ def get_exp_str(  # noqa: PLR0913
     extra_iec_prefixes: dict[int, str],
     extra_parts_per_forms: dict[int, str],
     capitalize: bool,
-    latex: bool,
-    latex_trim_whitespace: bool,
     superscript: bool,
 ) -> str:
     """Get formatting exponent string."""
@@ -225,43 +222,14 @@ def get_exp_str(  # noqa: PLR0913
         if exp_val in text_exp_dict and text_exp_dict[exp_val] is not None:
             exp_str = f" {text_exp_dict[exp_val]}"
             exp_str = exp_str.rstrip(" ")
-            if latex:
-                if latex_trim_whitespace:
-                    exp_str = exp_str.lstrip(" ")
-                exp_str = rf"\text{{{exp_str}}}"
             return exp_str
 
-    if latex:
-        return rf"\times {base}^{{{exp_val:+}}}"
     if superscript:
         return get_superscript_exp_str(base, exp_val)
 
     return get_standard_exp_str(base, exp_val, capitalize=capitalize)
 
 
-def parse_standard_exp_str(exp_str: str) -> tuple[int, int]:
-    """Extract base and exponent value from standard exponent string."""
-    match = re.match(
-        r"""
-         ^
-         (?P<exp_symbol>[eEbB])
-         (?P<exp_val>[+-]\d+)
-         $
-         """,
-        exp_str,
-        re.VERBOSE,
-    )
-
-    exp_symbol = match.group("exp_symbol")
-    symbol_to_base_dict = {"e": 10, "b": 2}
-    base = symbol_to_base_dict[exp_symbol.lower()]
-
-    exp_val_str = match.group("exp_val")
-    exp_val = int(exp_val_str)
-
-    return base, exp_val
-
-
 def get_sign_str(num: Decimal, sign_mode: SignModeEnum) -> str:
     """Get the format sign string."""
     if num < 0:
@@ -338,11 +306,11 @@ def get_round_digit(
     return round_digit
 
 
-def get_fill_str(fill_char: str, top_digit: int, top_padded_digit: int) -> str:
-    """Get the string filling from top_digit place to top_padded_digit place."""
+def get_pad_str(left_pad_char: str, top_digit: int, top_padded_digit: int) -> str:
+    """Get the string padding from top_digit place to top_padded_digit place."""
     if top_padded_digit > top_digit:
         pad_len = top_padded_digit - max(top_digit, 0)
-        pad_str = fill_char * pad_len
+        pad_str = left_pad_char * pad_len
     else:
         pad_str = ""
     return pad_str
@@ -353,7 +321,7 @@ def format_num_by_top_bottom_dig(
     target_top_digit: int,
     target_bottom_digit: int,
     sign_mode: SignModeEnum,
-    fill_char: str,
+    left_pad_char: str,
 ) -> str:
     """Format a number according to specified top and bottom digit places."""
     print_prec = max(0, -target_bottom_digit)
@@ -362,26 +330,8 @@ def format_num_by_top_bottom_dig(
     sign_str = get_sign_str(num, sign_mode)
 
     num_top_digit = get_top_digit(num)
-    fill_str = get_fill_str(fill_char, num_top_digit, target_top_digit)
-    return f"{sign_str}{fill_str}{abs_mantissa_str}"
-
-
-def latex_translate(input_str: str) -> str:
-    """Translate elements of a string for Latex compatibility."""
-    result_str = input_str
-    replacements = (
-        ("(", r"\left("),
-        (")", r"\right)"),
-        ("%", r"\%"),
-        ("_", r"\_"),
-        ("nan", r"\text{nan}"),
-        ("NAN", r"\text{NAN}"),
-        ("inf", r"\text{inf}"),
-        ("INF", r"\text{INF}"),
-    )
-    for old_chars, new_chars in replacements:
-        result_str = result_str.replace(old_chars, new_chars)
-    return result_str
+    pad_str = get_pad_str(left_pad_char, num_top_digit, target_top_digit)
+    return f"{sign_str}{pad_str}{abs_mantissa_str}"
 
 
 def round_val_unc(
@@ -420,24 +370,17 @@ def get_val_unc_exp(
     unc: Decimal,
     exp_mode: ExpModeEnum,
     input_exp: int,
-) -> tuple[int, ExpDriver]:
+) -> int:
     """Get exponent for value/uncertainty formatting."""
     if val.is_finite() and unc.is_finite():
         if abs(val) >= unc:
-            exp_driver_type = ExpDriver.VAL
+            exp_driver_val = val
         else:
-            exp_driver_type = ExpDriver.UNC
+            exp_driver_val = unc
     elif val.is_finite():
-        exp_driver_type = ExpDriver.VAL
-    else:
-        exp_driver_type = ExpDriver.UNC
-
-    if exp_driver_type is ExpDriver.VAL:
         exp_driver_val = val
-    elif exp_driver_type is ExpDriver.UNC:
+    else:
         exp_driver_val = unc
-    else:  # pragma: no cover
-        raise ValueError
 
     _, exp_val, _ = get_mantissa_exp_base(
         exp_driver_val,
@@ -445,7 +388,7 @@ def get_val_unc_exp(
         input_exp=input_exp,
     )
 
-    return exp_val, exp_driver_type
+    return exp_val
 
 
 def get_val_unc_top_digit(
@@ -469,11 +412,10 @@ def get_val_unc_top_digit(
     return new_top_digit
 
 
-def get_val_unc_mantissa_exp_strs(
+def get_val_unc_mantissa_strs(
     val_mantissa_exp_str: str,
     unc_mantissa_exp_str: str,
-    exp_driver_type: ExpDriver,
-) -> tuple[str, str, str]:
+) -> tuple[str, str]:
     """Break val/unc mantissa/exp strings into mantissa strings and an exp string."""
     # Optional parentheses needed to handle (nan)e+00 case
     mantissa_exp_pattern = re.compile(
@@ -485,15 +427,7 @@ def get_val_unc_mantissa_exp_strs(
     unc_match = mantissa_exp_pattern.match(unc_mantissa_exp_str)
     unc_mantissa_str = unc_match.group("mantissa_str")
 
-    if exp_driver_type is ExpDriver.VAL:
-        exp_str = val_match.group("exp_str")
-    elif exp_driver_type is ExpDriver.UNC:
-        exp_str = unc_match.group("exp_str")
-    else:
-        msg = f"Invalid exp_driver_type: {exp_driver_type}."
-        raise ValueError(msg)
-
-    return val_mantissa_str, unc_mantissa_str, exp_str
+    return val_mantissa_str, unc_mantissa_str
 
 
 def construct_val_unc_str(  # noqa: PLR0913
@@ -504,13 +438,12 @@ def construct_val_unc_str(  # noqa: PLR0913
     decimal_separator: SeparatorEnum,
     *,
     paren_uncertainty: bool,
-    latex: bool,
     pm_whitespace: bool,
     paren_uncertainty_separators: bool,
 ) -> str:
     """Construct the value/uncertainty part of the formatted string."""
     if not paren_uncertainty:
-        pm_symb = r"\pm" if latex else "±"
+        pm_symb = "±"
         if pm_whitespace:
             pm_symb = f" {pm_symb} "
         val_unc_str = f"{val_mantissa_str}{pm_symb}{unc_mantissa_str}"
@@ -555,7 +488,6 @@ def construct_val_unc_exp_str(  # noqa: PLR0913
     extra_iec_prefixes: dict[int, str | None],
     extra_parts_per_forms: dict[int, str | None],
     capitalize: bool,
-    latex: bool,
     superscript: bool,
     paren_uncertainty: bool,
 ) -> str:
@@ -565,22 +497,22 @@ def construct_val_unc_exp_str(  # noqa: PLR0913
         exp_mode=exp_mode,
         exp_format=exp_format,
         capitalize=capitalize,
-        latex=latex,
-        latex_trim_whitespace=True,
         superscript=superscript,
         extra_si_prefixes=extra_si_prefixes,
         extra_iec_prefixes=extra_iec_prefixes,
         extra_parts_per_forms=extra_parts_per_forms,
     )
 
-    """
-    "1234(12)" val_unc_str along with exp_str "k" will be formatted as
-    "1234(12) k whereas 1234(12) with exp_str "e+03" will be
-    formatted as (1234(12))e+03.
-    "1234 ± 12" will be formatted with parentheses as "(1234 ± 12) k" or
-    "(1234 ± 12)e+03"
-    """
-    if paren_uncertainty and not re.match(r"^[eEbB][+-]\d+$", exp_str):
+    if exp_str == "":
+        val_unc_exp_str = f"{val_unc_str}{exp_str}"
+    elif paren_uncertainty and not re.match(r"^[eEbB][+-]\d+$", exp_str):
+        """
+        "1234(12)" val_unc_str along with exp_str "k" will be formatted as
+        "1234(12) k whereas 1234(12) with exp_str "e+03" will be
+        formatted as (1234(12))e+03.
+        "1234 ± 12" will be formatted with parentheses as "(1234 ± 12) k" or
+        "(1234 ± 12)e+03"
+        """
         val_unc_exp_str = f"{val_unc_str}{exp_str}"
     else:
         val_unc_exp_str = f"({val_unc_str}){exp_str}"

sciform/formatter.py

@@ -2,41 +2,132 @@
 
 from __future__ import annotations
 
-from decimal import Decimal
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
-from sciform.formatting import format_num, format_val_unc
-from sciform.user_options import UserOptions
+from sciform.formatting import format_from_options
+from sciform.options.conversion import populate_options
+from sciform.options.input_options import InputOptions
 
 if TYPE_CHECKING:  # pragma: no cover
     from sciform import modes
     from sciform.format_utils import Number
+    from sciform.formatting import FormattedNumber
+    from sciform.options.populated_options import PopulatedOptions
 
 
 class Formatter:
-    """
-    Class to format numbers and pairs of numbers into strings.
+    r"""
+    Class to format value and value/uncertainty pairs.
 
-    :class:`Formatter` is used to convert numbers and pairs of numbers
-    into formatted strings according to a variety of formatting options.
-    See :ref:`formatting_options` for more details on the available
-    options. Any options which are unpopulated (have the value ``None``)
-    will be populated at format time by the corresponding values in the
-    globally configured default options. See :ref:`global_config` for
-    details about how to view and modify the global default options.
+    :class:`Formatter` is used to convert value and value/uncertainty
+    pairs into formatted strings according to a variety of formatting
+    options. See :ref:`formatting_options` for more details on the
+    available options. Any options which are not populated (not passed
+    in or passed in the ``None`` value) will be populated at format time
+    by the corresponding values in the globally configured default
+    options. See :ref:`global_config` for details about how to view and
+    modify the global options. The user supplied options cannot be
+    updated after the :class:`Formatter` is constructed.
+
+    After initialization, the :class:`Formatter` is used by passing in
+    a value into the :class:`Formatter`.
 
     >>> from sciform import Formatter
-    >>> sform = Formatter(exp_mode="engineering", round_mode="sig_fig", ndigits=4)
-    >>> print(sform(12345.678))
+    >>> formatter = Formatter(exp_mode="engineering", round_mode="sig_fig", ndigits=4)
+    >>> print(formatter(12345.678))
     12.35e+03
 
-    The Formatter can be called with two aguments for value/uncertainty
-    formatting
+    A value/uncertainty pair can also be passed into the
+    :class:`Formatter`.
+
+    >>> formatter = Formatter(
+    ...     exp_mode="engineering",
+    ...     round_mode="sig_fig",
+    ...     ndigits=2,
+    ...     superscript=True,
+    ... )
+    >>> formatted = formatter(12345.678, 3.4)
+    >>> print(formatted)
+    (12.3457 ± 0.0034)×10³
+
+    The returned object behaves like a ``str``, but is, in fact, a
+    :class:`FormattedNumber` instance. The :class:`FormattedNumber` is
+    a subclass of ``str`` but provides methods for post-conversion into
+    LaTeX, HTML, and ASCII formats.
+
+    >>> print(formatted.as_latex())
+    $(12.3457\:\pm\:0.0034)\times10^{3}$
+    >>> print(formatted.as_html())
+    (12.3457 ± 0.0034)×10<sup>3</sup>
+    >>> print(formatted.as_ascii())
+    (12.3457 +/- 0.0034)e+03
+
+    The formatting options input by the user can be checked by
+    inspecting the :attr:`input_options` property
+
+    >>> print(formatter.input_options)
+    InputOptions(
+     'exp_mode': 'engineering',
+     'round_mode': 'sig_fig',
+     'ndigits': 2,
+     'superscript': True,
+    )
+
+    Only explicitly populated options appear in the string printout.
+    However, populated and unpopulated parameters can be inspected by
+    direct attribute access. Unpopulated parameters are ``None``-valued.
+
+    >>> print(formatter.input_options.round_mode)
+    sig_fig
+    >>> print(formatter.input_options.exp_format)
+    None
+
+    The :meth:`InputOptions.as_dict` method returns a dictionary of
+    input options that can be passed back into a :class:`Formatter`
+    constructor as ``**kwargs``, possibly after modification. Only
+    explicitly populated options are included in this dictionary.
+
+    >>> print(formatter.input_options.as_dict())
+    {'exp_mode': 'engineering', 'round_mode': 'sig_fig', 'ndigits': 2, 'superscript': True}
+
+    Likewise, the result of populating the options with the global
+    options can be previewed by inspecting the :attr:`populated_options`
+    property.
 
-    >>> sform = Formatter(exp_mode="engineering", round_mode="sig_fig", ndigits=2)
-    >>> print(sform(12345.678, 3.4))
-    (12.3457 ± 0.0034)e+03
-    """
+    >>> print(formatter.populated_options)
+    PopulatedOptions(
+     'exp_mode': 'engineering',
+     'exp_val': AutoExpVal,
+     'round_mode': 'sig_fig',
+     'ndigits': 2,
+     'upper_separator': '',
+     'decimal_separator': '.',
+     'lower_separator': '',
+     'sign_mode': '-',
+     'left_pad_char': ' ',
+     'left_pad_dec_place': 0,
+     'exp_format': 'standard',
+     'extra_si_prefixes': {},
+     'extra_iec_prefixes': {},
+     'extra_parts_per_forms': {},
+     'capitalize': False,
+     'superscript': True,
+     'nan_inf_exp': False,
+     'paren_uncertainty': False,
+     'pdg_sig_figs': False,
+     'left_pad_matching': False,
+     'paren_uncertainty_separators': True,
+     'pm_whitespace': True,
+    )
+    >>> print(formatter.populated_options.exp_format)
+    standard
+
+    The :class:`PopulatedOptions` class also provides a
+    :class:`PopulatedOptions.as_dict` method which can be used to
+    construct ``**kwargs`` to pass into new :class:`Formatter`
+    instances.
+
+    """  # noqa: E501
 
     def __init__(  # noqa: PLR0913
         self: Formatter,
@@ -49,7 +140,7 @@ class Formatter:
         decimal_separator: modes.DecimalSeparators | None = None,
         lower_separator: modes.LowerSeparators | None = None,
         sign_mode: modes.SignMode | None = None,
-        fill_char: modes.FillChar | None = None,
+        left_pad_char: modes.LeftPadChar | Literal[0] | None = None,
         left_pad_dec_place: int | None = None,
         exp_format: modes.ExpFormat | None = None,
         extra_si_prefixes: dict[int, str] | None = None,
@@ -57,18 +148,17 @@ class Formatter:
         extra_parts_per_forms: dict[int, str] | None = None,
         capitalize: bool | None = None,
         superscript: bool | None = None,
-        latex: bool | None = None,
         nan_inf_exp: bool | None = None,
         paren_uncertainty: bool | None = None,
         pdg_sig_figs: bool | None = None,
         left_pad_matching: bool | None = None,
         paren_uncertainty_separators: bool | None = None,
         pm_whitespace: bool | None = None,
-        add_c_prefix: bool = False,
-        add_small_si_prefixes: bool = False,
-        add_ppth_form: bool = False,
+        add_c_prefix: bool | None = None,
+        add_small_si_prefixes: bool | None = None,
+        add_ppth_form: bool | None = None,
     ) -> None:
-        r"""
+        """
         Create a new ``Formatter``.
 
         The following checks are performed when creating a new
@@ -119,8 +209,9 @@ class Formatter:
         :type lower_separator: ``Literal['', ' ', '_'] | None``
         :param sign_mode: Indicate sign symbol behavior.
         :type sign_mode: ``Literal['-', '+', ' '] | None``
-        :param fill_char: Indicate whether to fill with zeros or spaces.
-        :type fill_char: ``Literal[' ', '0'] | None``
+        :param left_pad_char: Indicate whether to pad with zeros or
+          spaces.
+        :type left_pad_char: ``Literal[' ', '0', 0] | None``
         :param left_pad_dec_place: Positive ``int`` indicating the
           decimal place to which the string will be left padded before
           the sign symbol. 0 corresponds to the ones place, 1
@@ -151,10 +242,6 @@ class Formatter:
           should be converted into superscript notation. E.g.
           ``'1.23e+02'`` is converted to ``'1.23×10²'``
         :type superscript: ``bool | None``
-        :param latex: Flag indicating if the resulting string should be
-          converted into a latex parseable code, e.g.
-          ``'\\left(1.23 \\pm 0.01\\right)\\times 10^{2}'``.
-        :type latex: ``bool | None``
         :param nan_inf_exp: Flag indicating whether non-finite numbers
           such as ``float('nan')`` or ``float('inf')`` should be
           formatted with exponent symbols when exponent modes including
@@ -182,18 +269,19 @@ class Formatter:
           whitespace surrounding the ``'±'`` symbols when formatting.
           E.g. ``123.4±2.3`` compared to ``123.4 ± 2.3``.
         :type pm_whitespace: ``bool | None``
-        :param add_c_prefix: (default ``False``) If ``True``, adds
-          ``{-2: 'c'}`` to ``extra_si_prefixes``.
-        :type add_c_prefix: ``bool``
-        :param add_small_si_prefixes: (default ``False``) If ``True``, adds
+        :param add_c_prefix: (default ``None`` is like ``False``) If
+          ``True``, adds ``{-2: 'c'}`` to ``extra_si_prefixes``.
+        :type add_c_prefix: ``bool | None``
+        :param add_small_si_prefixes: (default ``None`` is like
+          ``False``) If ``True``, adds
           ``{-2: 'c', -1: 'd', +1: 'da', +2: 'h'}`` to
           ``extra_si_prefixes``.
-        :type add_small_si_prefixes: ``bool``
-        :param add_ppth_form: (default ``False``) if ``True``, adds
-          ``{-3: 'ppth'}`` to ``extra_parts_per_forms``.
-        :type add_ppth_form: ``bool``
-        """  # noqa: RUF002
-        self._user_options = UserOptions(
+        :type add_small_si_prefixes: ``bool | None``
+        :param add_ppth_form: (default ``None`` is like ``False``) if
+          ``True``, adds ``{-3: 'ppth'}`` to ``extra_parts_per_forms``.
+        :type add_ppth_form: ``bool | None``
+        """
+        self._input_options = InputOptions(
             exp_mode=exp_mode,
             exp_val=exp_val,
             round_mode=round_mode,
@@ -202,7 +290,7 @@ class Formatter:
             decimal_separator=decimal_separator,
             lower_separator=lower_separator,
             sign_mode=sign_mode,
-            fill_char=fill_char,
+            left_pad_char=left_pad_char,
             left_pad_dec_place=left_pad_dec_place,
             exp_format=exp_format,
             extra_si_prefixes=extra_si_prefixes,
@@ -210,7 +298,6 @@ class Formatter:
             extra_parts_per_forms=extra_parts_per_forms,
             capitalize=capitalize,
             superscript=superscript,
-            latex=latex,
             nan_inf_exp=nan_inf_exp,
             paren_uncertainty=paren_uncertainty,
             pdg_sig_figs=pdg_sig_figs,
@@ -222,12 +309,28 @@ class Formatter:
             add_ppth_form=add_ppth_form,
         )
 
+    @property
+    def input_options(self: Formatter) -> InputOptions:
+        """Return user input options as :class:`InputOptions` instance."""
+        return self._input_options
+
+    @property
+    def populated_options(self: Formatter) -> PopulatedOptions:
+        """
+        Return fully populated options as :class:`PopulatedOptions` instance.
+
+        :attr:`populated_options` is re-calculated from
+        :attr:`input_options` and the global options each time it is
+        accessed so that it always reflects the current global options.
+        """
+        return populate_options(self.input_options)
+
     def __call__(
         self: Formatter,
         value: Number,
         uncertainty: Number | None = None,
         /,
-    ) -> str:
+    ) -> FormattedNumber:
         """
         Format a value or value/uncertainty pair.
 
@@ -236,13 +339,8 @@ class Formatter:
         :param uncertainty: Optional uncertainty to be formatted.
         :type uncertainty: ``Decimal | float | int | str | None``
         """
-        rendered_options = self._user_options.render()
-        if uncertainty is None:
-            output = format_num(Decimal(str(value)), rendered_options)
-        else:
-            output = format_val_unc(
-                Decimal(str(value)),
-                Decimal(str(uncertainty)),
-                rendered_options,
-            )
-        return output
+        return format_from_options(
+            value,
+            uncertainty,
+            input_options=self.input_options,
+        )