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

sciform/{rendered_options.py → options/finalized_options.py}

@@ -1,23 +1,23 @@
 """
 Rendered format options used in sciform backend formatting algorithm.
 
-:class:`UserOptions` are converted into :class:`RenderedOptions`
+:class:`InputOptions` are converted into :class:`FinalizedOptions`
 internally at format time.
 """
 
 from __future__ import annotations
 
-from dataclasses import asdict, dataclass
-from enum import Enum
-from pprint import pformat
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from sciform.options.validation import validate_options
+
 if TYPE_CHECKING:  # pragma: no cover
     from sciform import modes
 
 
 @dataclass(frozen=True)
-class RenderedOptions:
+class FinalizedOptions:
     """Rendered options: All options populated and using Enum instead of Literal."""
 
     exp_mode: modes.ExpModeEnum
@@ -28,7 +28,7 @@ class RenderedOptions:
     decimal_separator: modes.DecimalSeparatorEnums
     lower_separator: modes.LowerSeparatorEnums
     sign_mode: modes.SignModeEnum
-    fill_char: modes.FillCharEnum
+    left_pad_char: modes.LeftPadCharEnum
     left_pad_dec_place: int
     exp_format: modes.ExpFormatEnum
     extra_si_prefixes: dict[int, str]
@@ -36,7 +36,6 @@ class RenderedOptions:
     extra_parts_per_forms: dict[int, str]
     capitalize: bool
     superscript: bool
-    latex: bool
     nan_inf_exp: bool
     paren_uncertainty: bool
     pdg_sig_figs: bool
@@ -44,9 +43,5 @@ class RenderedOptions:
     paren_uncertainty_separators: bool
     pm_whitespace: bool
 
-    def __str__(self: RenderedOptions) -> str:
-        options_dict = asdict(self)
-        for key, value in options_dict.items():
-            if isinstance(value, Enum):
-                options_dict[key] = value.value
-        return pformat(options_dict, sort_dicts=False)
+    def __post_init__(self: FinalizedOptions) -> None:
+        validate_options(self)

sciform/{global_options.py → options/global_options.py}

@@ -1,26 +1,25 @@
 """Global Options."""
 
 from sciform import modes
-from sciform.rendered_options import RenderedOptions
+from sciform.options.populated_options import PopulatedOptions
 
-PKG_DEFAULT_OPTIONS = RenderedOptions(
-    exp_mode=modes.ExpModeEnum.FIXEDPOINT,
+PKG_DEFAULT_OPTIONS = PopulatedOptions(
+    exp_mode="fixed_point",
     exp_val=modes.AutoExpVal,
-    round_mode=modes.RoundModeEnum.SIG_FIG,
+    round_mode="sig_fig",
     ndigits=modes.AutoDigits,
-    upper_separator=modes.SeparatorEnum.NONE,
-    decimal_separator=modes.SeparatorEnum.POINT,
-    lower_separator=modes.SeparatorEnum.NONE,
-    sign_mode=modes.SignModeEnum.NEGATIVE,
-    fill_char=modes.FillCharEnum.SPACE,
+    upper_separator="",
+    decimal_separator=".",
+    lower_separator="",
+    sign_mode="-",
+    left_pad_char=" ",
     left_pad_dec_place=0,
-    exp_format=modes.ExpFormatEnum.STANDARD,
+    exp_format="standard",
     extra_si_prefixes={},
     extra_iec_prefixes={},
     extra_parts_per_forms={},
     capitalize=False,
     superscript=False,
-    latex=False,
     nan_inf_exp=False,
     paren_uncertainty=False,
     pdg_sig_figs=False,

sciform/options/input_options.py

@@ -0,0 +1,104 @@
+"""InputOptions Dataclass which stores user input."""
+
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pprint import pformat
+from typing import TYPE_CHECKING, Any, Literal
+
+from sciform.options.validation import validate_options
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sciform import modes
+
+
+@dataclass(frozen=True)
+class InputOptions:
+    """
+    Dataclass storing user input.
+
+    Stores the user input to :class:`Formatter`, so any keyword
+    arguments that can be passed into :class:`Formatter` are stored in
+    :class:`InputOptions`. Any unpopulated options retain the ``None``
+    value. At format time the :class:`InputOptions` are populated and
+    replaced by a :class:`PopulatedOptions` instance which necessarily
+    has all attributes populated with meaningful values.
+
+    :class:`InputOptions` instances should only be accessed via the
+    :class:`Formatter.input_options()` property. They should not be
+    instantiated directly.
+
+    >>> from sciform import Formatter
+    >>> formatter = Formatter(
+    ...     exp_mode="engineering",
+    ...     round_mode="sig_fig",
+    ...     ndigits=2,
+    ...     superscript=True,
+    ... )
+    >>> print(formatter.input_options.round_mode)
+    sig_fig
+    >>> print(formatter.input_options.exp_format)
+    None
+    >>> print(formatter.input_options)
+    InputOptions(
+     'exp_mode': 'engineering',
+     'round_mode': 'sig_fig',
+     'ndigits': 2,
+     'superscript': True,
+    )
+    >>> print(formatter.input_options.as_dict())
+    {'exp_mode': 'engineering', 'round_mode': 'sig_fig', 'ndigits': 2, 'superscript': True}
+    """  # noqa: E501
+
+    exp_mode: modes.ExpMode | None = None
+    exp_val: int | type(modes.AutoExpVal) | None = None
+    round_mode: modes.RoundMode | None = None
+    ndigits: int | type(modes.AutoDigits) | None = None
+    upper_separator: modes.UpperSeparators | None = None
+    decimal_separator: modes.DecimalSeparators | None = None
+    lower_separator: modes.LowerSeparators | None = None
+    sign_mode: modes.SignMode | 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
+    extra_iec_prefixes: dict[int, str] | None = None
+    extra_parts_per_forms: dict[int, str] | None = None
+    capitalize: bool | None = None
+    superscript: 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 = None
+    add_small_si_prefixes: bool = None
+    add_ppth_form: bool = None
+
+    def __post_init__(self: InputOptions) -> None:
+        validate_options(self)
+
+    def as_dict(self: InputOptions) -> dict[str, Any]:
+        """
+        Return a dict representation of the InputOptions.
+
+        This dict can be passed into :class:`Formatter` as ``**kwargs``,
+        possibly after modification. This allows for the possibility of
+        constructing new :class:`Formatter` instances based on old ones.
+        Only explicitly populated attributes are included in the
+        returned dictionary.
+        """
+        options_dict = asdict(self)
+        for key in list(options_dict.keys()):
+            if options_dict[key] is None:
+                del options_dict[key]
+        return options_dict
+
+    def __str__(self: InputOptions) -> str:
+        options_str = pformat(self.as_dict(), width=-1, sort_dicts=False)
+        options_str = options_str.lstrip("{").rstrip("}")
+        options_str = f"InputOptions(\n {options_str},\n)"
+        return options_str

sciform/options/populated_options.py

@@ -0,0 +1,136 @@
+"""InputOptions Dataclass which stores user input."""
+
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pprint import pformat
+from typing import TYPE_CHECKING, Any
+
+from sciform.options.validation import validate_options
+
+if TYPE_CHECKING:  # pragma: no cover
+    from sciform import modes
+
+
+@dataclass(frozen=True)
+class PopulatedOptions:
+    """
+    Dataclass storing fully populated formatting options.
+
+    User input options during :class:`Formatter` initialization are
+    stored in :class:`InputOptions` instances. But
+    :class:`InputOptions` instances don't necessarily have all options
+    populated as required for the formatting algorithm. At formatting
+    time the unpopulated options are populated from the global options.
+    The new resulting options object with all options populated is a
+    :class:`PopulatedOptions` instances. Note that the global options
+    are stored as a :class:`PopulatedOptions` instance.
+
+    :class:`PopulatedOptions` instances should only be accessed via the
+    :class:`Formatter.populated_options()` property. They should not be
+    instantiated directly.
+
+    >>> from sciform import Formatter
+    >>> formatter = Formatter(
+    ...     exp_mode="engineering",
+    ...     round_mode="sig_fig",
+    ...     ndigits=2,
+    ...     superscript=True,
+    ... )
+    >>> print(formatter.populated_options.round_mode)
+    sig_fig
+    >>> print(formatter.populated_options.exp_format)
+    standard
+    >>> 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.as_dict())
+    {'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}
+
+    Note that :class:`PopulatedOptions` lacks the ``add_c_prefix``,
+    ``add_small_si_prefixes`` and ``add_ppth_form`` options present
+    in :class:`InputOptions`. These options are helper functions which
+    modify the corresponding exponent replacement dictionaries.
+
+    >>> formatter = Formatter(
+    ...     exp_mode="engineering",
+    ...     exp_format="prefix",
+    ...     add_c_prefix=True,
+    ... )
+    >>> print(formatter.input_options)
+    InputOptions(
+     'exp_mode': 'engineering',
+     'exp_format': 'prefix',
+     'add_c_prefix': True,
+    )
+    >>> print(formatter.input_options.extra_si_prefixes)
+    None
+    >>> print(formatter.populated_options.extra_si_prefixes)
+    {-2: 'c'}
+
+    """  # noqa: E501
+
+    exp_mode: modes.ExpMode
+    exp_val: int | type(modes.AutoExpVal)
+    round_mode: modes.RoundMode
+    ndigits: int | type(modes.AutoDigits)
+    upper_separator: modes.UpperSeparators
+    decimal_separator: modes.DecimalSeparators
+    lower_separator: modes.LowerSeparators
+    sign_mode: modes.SignMode
+    left_pad_char: modes.LeftPadChar
+    left_pad_dec_place: int
+    exp_format: modes.ExpFormat
+    extra_si_prefixes: dict[int, str]
+    extra_iec_prefixes: dict[int, str]
+    extra_parts_per_forms: dict[int, str]
+    capitalize: bool
+    superscript: bool
+    nan_inf_exp: bool
+    paren_uncertainty: bool
+    pdg_sig_figs: bool
+    left_pad_matching: bool
+    paren_uncertainty_separators: bool
+    pm_whitespace: bool
+
+    def __post_init__(self: PopulatedOptions) -> None:
+        validate_options(self)
+
+    def as_dict(self: PopulatedOptions) -> dict[str, Any]:
+        """
+        Return a dict representation of the PopulatedOptions.
+
+        This dict can be passed into :class:`Formatter` as ``**kwargs``,
+        possibly after modification. This allows for the possibility of
+        constructing new :class:`Formatter` instances based on old ones.
+        """
+        return asdict(self)
+
+    def __str__(self: PopulatedOptions) -> str:
+        options_str = pformat(self.as_dict(), width=-1, sort_dicts=False)
+        options_str = options_str.lstrip("{").rstrip("}")
+        options_str = f"PopulatedOptions(\n {options_str},\n)"
+        return options_str

sciform/options/validation.py

@@ -0,0 +1,101 @@
+"""Options validation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, get_args
+
+from sciform import modes
+
+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 validate_options(
+    options: InputOptions | PopulatedOptions | FinalizedOptions,
+) -> None:
+    """Validate user inputs."""
+    validate_sig_fig_round_mode(options)
+    validate_exp_val(options)
+    validate_separator_options(options)
+
+
+def validate_sig_fig_round_mode(
+    options: InputOptions | PopulatedOptions | FinalizedOptions,
+) -> None:
+    r"""Validate ndigits if round_mode == "sig_fig"."""
+    if (
+        options.round_mode == "sig_fig"
+        and isinstance(options.ndigits, int)
+        and options.ndigits < 1
+    ):
+        msg = f"ndigits must be >= 1 for sig fig rounding, not {options.ndigits}."
+        raise ValueError(msg)
+
+
+def validate_exp_val(
+    options: InputOptions | PopulatedOptions | FinalizedOptions,
+) -> None:
+    """Validate exp_val."""
+    if options.exp_val is not modes.AutoExpVal and options.exp_val is not None:
+        if options.exp_mode in ["fixed_point", "percent"] and options.exp_val != 0:
+            msg = (
+                f"Exponent must must be 0, not exp_val={options.exp_val}, for "
+                f"fixed point and percent exponent modes."
+            )
+            raise ValueError(msg)
+        if (
+            options.exp_mode in ["engineering", "engineering_shifted"]
+            and options.exp_val % 3 != 0
+        ):
+            msg = (
+                f"Exponent must be a multiple of 3, not exp_val={options.exp_val}, "
+                f"for engineering exponent modes."
+            )
+            raise ValueError(msg)
+        if options.exp_mode == "binary_iec" and options.exp_val % 10 != 0:
+            msg = (
+                f"Exponent must be a multiple of 10, not "
+                f"exp_val={options.exp_val}, for binary IEC exponent mode."
+            )
+            raise ValueError(msg)
+
+
+def validate_separator_options(
+    options: InputOptions | PopulatedOptions | FinalizedOptions,
+) -> None:
+    """Validate separator user input."""
+    if options.upper_separator is not None:
+        if options.upper_separator not in get_args(modes.UpperSeparators):
+            msg = (
+                f"upper_separator must be in "
+                f"{get_args(modes.UpperSeparators)}, not "
+                f"{options.upper_separator}."
+            )
+            raise ValueError(msg)
+        if options.upper_separator == options.decimal_separator:
+            msg = (
+                f"upper_separator and decimal_separator "
+                f"({options.upper_separator}) cannot be equal."
+            )
+            raise ValueError(msg)
+
+    if options.decimal_separator is not None and (
+        options.decimal_separator not in get_args(modes.DecimalSeparators)
+    ):
+        msg = (
+            f"decimal_separator must be in "
+            f"{get_args(modes.DecimalSeparators)}, not "
+            f"{options.decimal_separator}."
+        )
+        raise ValueError(msg)
+
+    if options.lower_separator is not None and (
+        options.lower_separator not in get_args(modes.LowerSeparators)
+    ):
+        msg = (
+            f"lower_separator must be in {get_args(modes.LowerSeparators)}, "
+            f"not {options.lower_separator}."
+        )
+        raise ValueError(msg)

sciform/output_conversion.py

@@ -0,0 +1,168 @@
+"""Convert sciform outputs into latex commands."""
+from __future__ import annotations
+
+import re
+from typing import Literal, get_args
+
+ascii_exp_pattern = re.compile(
+    r"^(?P<mantissa>.*)(?P<ascii_base>[eEbB])(?P<exp>[+-]\d+)$",
+)
+ascii_base_dict = {"e": 10, "E": 10, "b": 2, "B": 2}
+
+unicode_exp_pattern = re.compile(
+    r"^(?P<mantissa>.*)×(?P<base>10|2)(?P<super_exp>[⁺⁻]?[⁰¹²³⁴⁵⁶⁷⁸⁹]+)$",
+)
+superscript_translation = str.maketrans("⁺⁻⁰¹²³⁴⁵⁶⁷⁸⁹", "+-0123456789")
+
+output_formats = Literal["latex", "html", "ascii"]
+
+
+def _make_exp_str(
+    base: int,
+    exp: int,
+    output_format: output_formats,
+    *,
+    capitalize: bool = False,
+) -> str:
+    if output_format == "latex":
+        return rf"\times{base}^{{{exp}}}"
+    if output_format == "html":
+        return f"×{base}<sup>{exp}</sup>"
+    if output_format == "ascii":
+        if base == 10:
+            exp_str = f"e{exp:+03d}"
+        elif base == 2:
+            exp_str = f"b{exp:+03d}"
+        else:
+            msg = f"base must be 10 or 2, not {base}"
+            raise ValueError(msg)
+        if capitalize:
+            exp_str = exp_str.upper()
+        return exp_str
+    msg = f"output_format must be in {get_args(output_formats)}, not {output_format}"
+    raise ValueError(msg)
+
+
+def _string_replacements(input_str: str, replacements: list[tuple[str, str]]) -> str:
+    result_str = input_str
+    for old_chars, new_chars in replacements:
+        result_str = result_str.replace(old_chars, new_chars)
+    return result_str
+
+
+def convert_sciform_format(
+    formatted_str: str,
+    output_format: output_formats,
+) -> str:
+    r"""
+    Convert sciform output to new format for different output contexts.
+
+    convert_sciform_format() is used to convert a sciform output string
+    into different formats for presentation in different contexts.
+    Currently, LaTeX, HTML, and ASCII outputs are supported.
+
+    LaTeX
+    =====
+
+    For LaTeX conversion the resulting string is a valid LaTeX command
+    bracketed in "$" symbols to indicate it is in LaTeX math
+    environment. The following transformations are applied.
+
+    * The exponent is displayed using the LaTeX math superscript
+      construction, e.g. "10^{-3}"
+    * Any strings of alphabetic characters (plus ``"μ"``) are wrapped in
+      the LaTeX math-mode text environment, e.g.
+      ``"nan"`` -> ``r"\text{nan}"`` or ``"k"`` -> ``r"\text{k}"``.
+    * The following character replacments are made:
+
+      * ``"%"`` -> ``r"\%"``
+      * ``"_"`` -> ``r"\_"``
+      * ``" "`` -> ``r"\:"``
+      * ``"±"`` -> ``r"\pm"``
+      * ``"×"`` -> ```r"\times"``
+      * ``"μ"`` -> ``r"\textmu"``
+
+    >>> from sciform.output_conversion import convert_sciform_format
+    >>> print(convert_sciform_format("(7.8900 ± 0.0001)×10²", "latex"))
+    $(7.8900\:\pm\:0.0001)\times10^{2}$
+    >>> print(convert_sciform_format("16.18033E+03", "latex"))
+    $16.18033\times10^{3}$
+
+    HTML
+    ====
+
+    In HTML mode superscripts are representing using e.g.
+    "<sup>-3</sup>".
+
+    >>> from sciform.output_conversion import convert_sciform_format
+    >>> print(convert_sciform_format("(7.8900 ± 0.0001)×10²", "html"))
+    (7.8900 ± 0.0001)×10<sup>2</sup>
+    >>> print(convert_sciform_format("16.18033E+03", "html"))
+    16.18033×10<sup>3</sup>
+
+    ASCII
+    =====
+
+    In the ASCII mode exponents are always represented as e.g. "e-03".
+    Also, "±" is replaced by "+/-" and "μ" is replaced by "u".
+
+    >>> from sciform.output_conversion import convert_sciform_format
+    >>> print(convert_sciform_format("(7.8900 ± 0.0001)×10²", "ascii"))
+    (7.8900 +/- 0.0001)e+02
+    >>> print(convert_sciform_format("16.18033E+03", "ascii"))
+    16.18033E+03
+    """
+    if match := re.match(ascii_exp_pattern, formatted_str):
+        mantissa = match.group("mantissa")
+        ascii_base = match.group("ascii_base")
+        base = ascii_base_dict[ascii_base]
+        exp = int(match.group("exp"))
+        exp_str = _make_exp_str(
+            base,
+            exp,
+            output_format,
+            capitalize=ascii_base.isupper(),
+        )
+        main_str = mantissa
+        suffix_str = exp_str
+    elif match := re.match(unicode_exp_pattern, formatted_str):
+        mantissa = match.group("mantissa")
+        base = int(match.group("base"))
+        super_exp = match.group("super_exp")
+        exp = int(super_exp.translate(superscript_translation))
+        exp_str = _make_exp_str(base, exp, output_format)
+        main_str = mantissa
+        suffix_str = exp_str
+    else:
+        main_str = formatted_str
+        suffix_str = ""
+
+    if output_format == "latex":
+        main_str = re.sub(
+            r"([a-zA-Zμ]+)",
+            r"\\text{\1}",
+            main_str,
+        )
+
+        replacements = [
+            ("%", r"\%"),
+            ("_", r"\_"),
+            (" ", r"\:"),
+            ("±", r"\pm"),
+            ("×", r"\times"),
+            ("μ", r"\textmu"),
+        ]
+        main_str = _string_replacements(main_str, replacements)
+        return f"${main_str}{suffix_str}$"
+
+    if output_format == "html":
+        return f"{main_str}{suffix_str}"
+    if output_format == "ascii":
+        replacements = [
+            ("±", "+/-"),
+            ("μ", "u"),
+        ]
+        main_str = _string_replacements(main_str, replacements)
+        return f"{main_str}{suffix_str}"
+    msg = f"output_format must be in {get_args(output_formats)}, not {output_format}"
+    raise ValueError(msg)

sciform/scinum.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from decimal import Decimal
 from typing import TYPE_CHECKING
 
-from sciform.formatting import format_num, format_val_unc
+from sciform.formatting import FormattedNumber, format_from_options
 from sciform.fsml import format_options_from_fmt_spec
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -23,13 +23,13 @@ class SciNum:
     be populated with global default settings at format time.
 
     >>> from sciform import SciNum
-    >>> snum = SciNum(12345.54321)
-    >>> print(f"{snum:!3f}")
+    >>> num = SciNum(12345.54321)
+    >>> print(f"{num:!3f}")
     12300
-    >>> print(f"{snum:+2.3R}")
+    >>> print(f"{num:+2.3R}")
     + 12.346E+03
-    >>> snum = SciNum(123456.654321, 0.0234)
-    >>> print(f"{snum:#!2r()}")
+    >>> num = SciNum(123456.654321, 0.0234)
+    >>> print(f"{num:#!2r()}")
     (0.123456654(23))e+06
     """
 
@@ -45,12 +45,13 @@ class SciNum:
         else:
             self.uncertainty = Decimal(str(uncertainty))
 
-    def __format__(self: SciNum, fmt: str) -> str:
-        user_options = format_options_from_fmt_spec(fmt)
-        rendered_options = user_options.render()
-        if self.uncertainty is not None:
-            return format_val_unc(self.value, self.uncertainty, rendered_options)
-        return format_num(self.value, rendered_options)
+    def __format__(self: SciNum, fmt: str) -> FormattedNumber:
+        input_options = format_options_from_fmt_spec(fmt)
+        return format_from_options(
+            self.value,
+            self.uncertainty,
+            input_options=input_options,
+        )
 
     def __repr__(self: SciNum) -> str:
         if self.uncertainty is not None: