sciform 0.33.0__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/formatter.py

@@ -2,42 +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.output_conversion import convert_sciform_format
-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}
 
-    >>> sform = Formatter(exp_mode="engineering", round_mode="sig_fig", ndigits=2)
-    >>> print(sform(12345.678, 3.4))
-    (12.3457 ± 0.0034)e+03
-    """
+    Likewise, the result of populating the options with the global
+    options can be previewed by inspecting the :attr:`populated_options`
+    property.
+
+    >>> 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,
@@ -50,7 +140,7 @@ class Formatter:
         decimal_separator: modes.DecimalSeparators | None = None,
         lower_separator: modes.LowerSeparators | None = None,
         sign_mode: modes.SignMode | None = None,
-        left_pad_char: modes.LeftPadChar | 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,
@@ -64,11 +154,11 @@ class Formatter:
         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
@@ -121,7 +211,7 @@ class Formatter:
         :type sign_mode: ``Literal['-', '+', ' '] | None``
         :param left_pad_char: Indicate whether to pad with zeros or
           spaces.
-        :type left_pad_char: ``Literal[' ', '0'] | None``
+        :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
@@ -179,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``
+        :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._user_options = UserOptions(
+        self._input_options = InputOptions(
             exp_mode=exp_mode,
             exp_val=exp_val,
             round_mode=round_mode,
@@ -218,6 +309,22 @@ 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,
@@ -232,56 +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 FormattedNumber(output)
-
-
-class FormattedNumber(str):
-    """
-    Representation (typically string) of a formatted number.
-
-    The ``FormattedNumber`` class is returned by ``sciform`` formatting
-    methods. In most cases it behaves like a regular python string, but
-    it provides the possibility for post-converting the string to
-    various other formats such as latex or html. This allows the
-    formatted number to be displayed in a range of contexts other than
-    e.g. text terminals.
-
-    """
-
-    __slots__ = ()
-
-    def as_str(self: FormattedNumber) -> str:
-        """Return the string representation of the formatted number."""
-        return self.__str__()
-
-    def as_ascii(self: FormattedNumber) -> str:
-        """Return the ascii representation of the formatted number."""
-        return convert_sciform_format(self, "ascii")
-
-    def as_html(self: FormattedNumber) -> str:
-        """Return the html representation of the formatted number."""
-        return convert_sciform_format(self, "html")
-
-    def as_latex(self: FormattedNumber, *, strip_math_mode: bool = False) -> str:
-        """Return the latex representation of the formatted number."""
-        latex_repr = convert_sciform_format(self, "latex")
-        if strip_math_mode:
-            latex_repr = latex_repr.strip("$")
-        return latex_repr
-
-    def _repr_html_(self: FormattedNumber) -> str:
-        """Hook for HTML display."""  # noqa: D401
-        return self.as_html()
-
-    def _repr_latex_(self: FormattedNumber) -> str:
-        """Hook for LaTeX display."""  # noqa: D401
-        return self.as_latex()
+        return format_from_options(
+            value,
+            uncertainty,
+            input_options=self.input_options,
+        )

sciform/formatting.py

@@ -1,11 +1,15 @@
 """Main formatting functions."""
+from __future__ import annotations
 
 from dataclasses import replace
 from decimal import Decimal
-from typing import cast
+from typing import TYPE_CHECKING, cast
 from warnings import warn
 
+from typing_extensions import Self
+
 from sciform.format_utils import (
+    Number,
     construct_val_unc_exp_str,
     construct_val_unc_str,
     format_num_by_top_bottom_dig,
@@ -25,10 +29,35 @@ from sciform.modes import (
     RoundModeEnum,
     SignModeEnum,
 )
-from sciform.rendered_options import RenderedOptions
+from sciform.options.conversion import finalize_populated_options, populate_options
+from sciform.output_conversion import convert_sciform_format
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sciform.options.finalized_options import FinalizedOptions
+    from sciform.options.input_options import InputOptions
+    from sciform.options.populated_options import PopulatedOptions
+
+
+def format_from_options(
+    value: Number,
+    uncertainty: Number | None = None,
+    /,
+    input_options: InputOptions | None = None,
+) -> FormattedNumber:
+    """Finalize options and select value of value/uncertainty formatter."""
+    populated_options = populate_options(input_options)
+    finalized_options = finalize_populated_options(populated_options)
+    value = Decimal(str(value))
+
+    if uncertainty is not None:
+        uncertainty = Decimal(str(uncertainty))
+        formatted_str = format_val_unc(value, uncertainty, finalized_options)
+    else:
+        formatted_str = format_num(value, finalized_options)
+    return FormattedNumber(formatted_str, populated_options)
 
 
-def format_non_finite(num: Decimal, options: RenderedOptions) -> str:
+def format_non_finite(num: Decimal, options: FinalizedOptions) -> str:
     """Format non-finite numbers."""
     if num.is_nan():
         num_str = "nan"
@@ -73,7 +102,7 @@ def format_non_finite(num: Decimal, options: RenderedOptions) -> str:
     return result
 
 
-def format_num(num: Decimal, options: RenderedOptions) -> str:
+def format_num(num: Decimal, options: FinalizedOptions) -> str:
     """Format a single number according to input options."""
     if not num.is_finite():
         return format_non_finite(num, options)
@@ -145,7 +174,7 @@ def format_num(num: Decimal, options: RenderedOptions) -> str:
     return result
 
 
-def format_val_unc(val: Decimal, unc: Decimal, options: RenderedOptions) -> str:
+def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str:
     """Format value/uncertainty pair according to input options."""
     exp_mode = options.exp_mode
 
@@ -289,3 +318,61 @@ def format_val_unc(val: Decimal, unc: Decimal, options: RenderedOptions) -> str:
         val_unc_exp_str = f"({val_unc_exp_str})%"
 
     return val_unc_exp_str
+
+
+class FormattedNumber(str):
+    """
+    Representation of a formatted value of value/uncertainty pair.
+
+    The :class:`FormattedNumber` class is returned by ``sciform``
+    formatting methods. In most cases it behaves like a regular python
+    string, but it provides functionality for post-converting the string
+    to various other formats such as latex or html. This allows the
+    formatted number to be displayed in a range of contexts other than
+    e.g. text terminals.
+
+    The :class:`FormattedNumber` class should never be instantiated
+    directly.
+    """
+
+    __slots__ = {
+        "populated_options": "Record of the :class:`PopulatedOptions` used to "
+        "generate the :class:`FormattedNumber`.",
+    }
+
+    def __new__(
+        cls: type[Self],
+        formatted_str: str,
+        populated_options: PopulatedOptions,
+    ) -> Self:
+        """Get a new string."""
+        obj = super().__new__(cls, formatted_str)
+        obj.populated_options = populated_options
+        return obj
+
+    def as_str(self: FormattedNumber) -> str:
+        """Return the string representation of the formatted number."""
+        return self.__str__()
+
+    def as_ascii(self: FormattedNumber) -> str:
+        """Return the ascii representation of the formatted number."""
+        return convert_sciform_format(self, "ascii")
+
+    def as_html(self: FormattedNumber) -> str:
+        """Return the html representation of the formatted number."""
+        return convert_sciform_format(self, "html")
+
+    def as_latex(self: FormattedNumber, *, strip_math_mode: bool = False) -> str:
+        """Return the latex representation of the formatted number."""
+        latex_repr = convert_sciform_format(self, "latex")
+        if strip_math_mode:
+            latex_repr = latex_repr.strip("$")
+        return latex_repr
+
+    def _repr_html_(self: FormattedNumber) -> str:
+        """Hook for HTML display."""  # noqa: D401
+        return self.as_html()
+
+    def _repr_latex_(self: FormattedNumber) -> str:
+        """Hook for LaTeX display."""  # noqa: D401
+        return self.as_latex()

sciform/fsml.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 
-from sciform.user_options import UserOptions
+from sciform.options.input_options import InputOptions
 
 pattern = re.compile(
     r"""^
@@ -51,8 +51,8 @@ def parse_exp_mode(
     return exp_mode, capitalize
 
 
-def format_options_from_fmt_spec(fmt_spec: str) -> UserOptions:
-    """Resolve UserOptions form format specification string."""
+def format_options_from_fmt_spec(fmt_spec: str) -> InputOptions:
+    """Resolve InputOptions from format specification string."""
     match = pattern.match(fmt_spec)
     if match is None:
         msg = f"Invalid format specifier: '{fmt_spec}'"
@@ -101,7 +101,7 @@ def format_options_from_fmt_spec(fmt_spec: str) -> UserOptions:
     else:
         paren_uncertainty = None
 
-    return UserOptions(
+    return InputOptions(
         left_pad_char=left_pad_char,
         sign_mode=sign_mode,
         left_pad_dec_place=left_pad_dec_place,

sciform/global_configuration.py

@@ -4,21 +4,28 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from sciform import global_options, modes
-from sciform.user_options import UserOptions
+from sciform.options import global_options
+from sciform.options.conversion import populate_options
+from sciform.options.input_options import InputOptions
 
 if TYPE_CHECKING:  # pragma: no cover
     from types import TracebackType
 
-    from sciform.rendered_options import RenderedOptions
+    from sciform import modes
+    from sciform.options.populated_options import PopulatedOptions
 
 
-def print_global_defaults() -> None:
-    """Print current global default formatting options as a dictionary."""
-    print(str(global_options.GLOBAL_DEFAULT_OPTIONS))  # noqa: T201
+def get_default_global_options() -> PopulatedOptions:
+    """Return the package default global options."""
+    return global_options.PKG_DEFAULT_OPTIONS
 
 
-def set_global_defaults(  # noqa: PLR0913
+def get_global_options() -> PopulatedOptions:
+    """Return the current global options."""
+    return global_options.GLOBAL_DEFAULT_OPTIONS
+
+
+def set_global_options(  # noqa: PLR0913
     *,
     exp_mode: modes.ExpMode | None = None,
     exp_val: int | type(modes.AutoExpVal) | None = None,
@@ -47,11 +54,11 @@ def set_global_defaults(  # noqa: PLR0913
     add_ppth_form: bool = False,
 ) -> None:
     """
-    Configure global default format options.
+    Configure the global options.
 
     Accepts the same keyword arguments as :class:`Formatter`.
     """
-    user_options = UserOptions(
+    input_options = InputOptions(
         exp_mode=exp_mode,
         exp_val=exp_val,
         round_mode=round_mode,
@@ -78,30 +85,30 @@ def set_global_defaults(  # noqa: PLR0913
         add_small_si_prefixes=add_small_si_prefixes,
         add_ppth_form=add_ppth_form,
     )
-    set_global_defaults_rendered(user_options.render())
+    set_global_options_populated(populate_options(input_options))
 
 
-def set_global_defaults_rendered(rendered_options: RenderedOptions) -> None:
-    """Directly set global defaults to input RenderedOptions."""
-    global_options.GLOBAL_DEFAULT_OPTIONS = rendered_options
+def set_global_options_populated(populated_options: PopulatedOptions) -> None:
+    """Directly set global options to input :class:`PopulatedOptions`."""
+    global_options.GLOBAL_DEFAULT_OPTIONS = populated_options
 
 
-def reset_global_defaults() -> None:
-    """Reset global default options to :mod:`sciform` package defaults."""
+def reset_global_options() -> None:
+    """Reset global options to :mod:`sciform` package defaults."""
     global_options.GLOBAL_DEFAULT_OPTIONS = global_options.PKG_DEFAULT_OPTIONS
 
 
-class GlobalDefaultsContext:
+class GlobalOptionsContext:
     """
-    Temporarily update global default options.
+    Temporarily update global options.
 
-    New settings are applied when the context is entered and original
-    global settings are re-applied when the context is exited. Accepts
-    the same keyword arguments as :class:`Formatter`.
+    New global options are applied when the context is entered and the
+    original global settings are re-applied when the context is exited.
+    Accepts the same keyword arguments as :class:`Formatter`.
     """
 
     def __init__(  # noqa: PLR0913
-        self: GlobalDefaultsContext,
+        self: GlobalOptionsContext,
         *,
         exp_mode: modes.ExpMode | None = None,
         exp_val: int | type(modes.AutoExpVal) | None = None,
@@ -129,7 +136,7 @@ class GlobalDefaultsContext:
         add_small_si_prefixes: bool = False,
         add_ppth_form: bool = False,
     ) -> None:
-        user_options = UserOptions(
+        input_options = InputOptions(
             exp_mode=exp_mode,
             exp_val=exp_val,
             round_mode=round_mode,
@@ -156,19 +163,19 @@ class GlobalDefaultsContext:
             add_small_si_prefixes=add_small_si_prefixes,
             add_ppth_form=add_ppth_form,
         )
-        self.rendered_options = user_options.render()
+        self.populated_options = populate_options(input_options)
         self.initial_global_defaults = None
 
-    def __enter__(self: GlobalDefaultsContext) -> None:
+    def __enter__(self: GlobalOptionsContext) -> None:
         """Enter the context."""
-        self.initial_global_defaults = global_options.GLOBAL_DEFAULT_OPTIONS
-        set_global_defaults_rendered(self.rendered_options)
+        self.initial_global_defaults = get_global_options()
+        set_global_options_populated(self.populated_options)
 
     def __exit__(
-        self: GlobalDefaultsContext,
+        self: GlobalOptionsContext,
         exc_type: type[BaseException] | None,
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
         """Exit the context."""
-        set_global_defaults_rendered(self.initial_global_defaults)
+        set_global_options_populated(self.initial_global_defaults)

sciform/options/__init__.py

@@ -0,0 +1 @@
+"""Code pertaining to sciform options handling."""