sciform 0.36.0__py3-none-any.whl → 0.38.0__py3-none-any.whl

sciform/formatting/number_formatting.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from dataclasses import replace
 from decimal import Decimal
 from typing import TYPE_CHECKING, cast
-from warnings import warn
 
 from sciform.api.formatted_number import FormattedNumber
 from sciform.format_utils.exponents import get_exp_str, get_val_unc_exp
@@ -25,9 +24,9 @@ from sciform.format_utils.rounding import get_round_dec_place, round_val_unc
 from sciform.formatting.parser import parse_val_unc_from_input
 from sciform.options.conversion import finalize_populated_options, populate_options
 from sciform.options.option_types import (
-    AutoExpVal,
     ExpFormatEnum,
     ExpModeEnum,
+    ExpValEnum,
     RoundModeEnum,
     SignModeEnum,
 )
@@ -79,7 +78,7 @@ def format_non_finite(num: Decimal, options: FinalizedOptions) -> str:
         exp_mode = options.exp_mode
 
         exp_val = options.exp_val
-        if options.exp_val is AutoExpVal:
+        if options.exp_val is ExpValEnum.AUTO:
             exp_val = 0
 
         exp_str = get_exp_str(
@@ -180,7 +179,7 @@ def format_num(num: Decimal, options: FinalizedOptions) -> str:
     return result
 
 
-def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str:
+def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str:  # noqa: PLR0915
     """Format value/uncertainty pair according to input options."""
     exp_mode = options.exp_mode
 
@@ -190,13 +189,6 @@ def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str
         )
         raise NotImplementedError(msg)
 
-    if options.round_mode is RoundModeEnum.DEC_PLACE:
-        msg = (
-            "Precision round mode not available for value/uncertainty formatting. "
-            "Rounding is always applied as significant figures for the uncertainty."
-        )
-        warn(msg, stacklevel=2)
-
     unc = abs(unc)
     if exp_mode is ExpModeEnum.PERCENT:
         val *= 100
@@ -210,31 +202,72 @@ def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str
         """
         exp_mode = ExpModeEnum.FIXEDPOINT
 
-    """
-    We round twice in case the first rounding changes the digits place
-    to which we need to round. E.g. rounding 999.999 ± 123.456 to two
-    significant figures will lead to 1000.000 ± 0120.000 on the first
-    pass, but we must re-round to get 1000.000 ± 0100.000.
-    """
-    val_rounded, unc_rounded, _ = round_val_unc(
-        val,
-        unc,
-        options.ndigits,
-        use_pdg_sig_figs=options.pdg_sig_figs,
-    )
-    val_rounded, unc_rounded, round_digit = round_val_unc(
-        val_rounded,
-        unc_rounded,
-        options.ndigits,
-        use_pdg_sig_figs=options.pdg_sig_figs,
-    )
+    if options.round_mode is RoundModeEnum.DEC_PLACE:
+        """
+        We calculate the exponent twice in case rounding the mantissa changes the
+        required exponent. For example, 0.0999 ± 0.0999 displayed in scientific notation
+        would be (9.99 ± 9.99)e-02 but rounded to zero digits-past-the-decimal gives
+        (10 ± 10)e-02, so we need to recalculate the exponent to get (1 ± 1)e-01.
+        """
+        exp_val = get_val_unc_exp(
+            val,
+            unc,
+            options.exp_mode,
+            options.exp_val,
+        )
+        val_mantissa = val * Decimal(10) ** (-Decimal(exp_val))
+        unc_mantissa = unc * Decimal(10) ** (-Decimal(exp_val))
+        val_mantissa_rounded, unc_mantissa_rounded, _ = round_val_unc(
+            val_mantissa,
+            unc_mantissa,
+            options.round_mode,
+            options.ndigits,
+        )
+        val_rounded = val_mantissa_rounded * Decimal(10) ** Decimal(exp_val)
+        unc_rounded = unc_mantissa_rounded * Decimal(10) ** Decimal(exp_val)
+        exp_val = get_val_unc_exp(
+            val_rounded,
+            unc_rounded,
+            options.exp_mode,
+            options.exp_val,
+        )
+        """
+        ndigits that will be used for separate digits-past-the-decimal rounding for the
+        value and uncertainty.
+        """
+        ndigits = options.ndigits
+    else:
+        """
+        We round twice in case the first rounding changes the digits place to which we
+        need to round. E.g. rounding 0.0999 ± 0.0999 to one significant figure would
+        naively result in rounding to the -2 place, leaving us with 0.10 ± 0.10. But the
+        -2 place actually corresponds to two significant figures, so we re-round to the
+        -1 place to get 0.1 ± 0.1.
+        """
+        val_rounded, unc_rounded, _ = round_val_unc(
+            val,
+            unc,
+            options.round_mode,
+            options.ndigits,
+        )
+        val_rounded, unc_rounded, round_digit = round_val_unc(
+            val_rounded,
+            unc_rounded,
+            options.round_mode,
+            options.ndigits,
+        )
 
-    exp_val = get_val_unc_exp(
-        val_rounded,
-        unc_rounded,
-        options.exp_mode,
-        options.exp_val,
-    )
+        exp_val = get_val_unc_exp(
+            val_rounded,
+            unc_rounded,
+            options.exp_mode,
+            options.exp_val,
+        )
+        """
+        ndigits that will be used for separate digits-past-the-decimal rounding for the
+        value and uncertainty.
+        """
+        ndigits = -round_digit + exp_val
 
     val_mantissa, _, _ = get_mantissa_exp_base(
         val_rounded,
@@ -254,8 +287,6 @@ def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str
         left_pad_matching=options.left_pad_matching,
     )
 
-    ndigits = -round_digit + exp_val
-
     """
     We will format the val and unc mantissas
        * using decimal place rounding mode with the ndigits calculated
@@ -294,8 +325,6 @@ def format_val_unc(val: Decimal, unc: Decimal, options: FinalizedOptions) -> str
     val_unc_str = construct_val_unc_str(
         val_mantissa_str=val_mantissa_str,
         unc_mantissa_str=unc_mantissa_str,
-        val_mantissa=val_mantissa,
-        unc_mantissa=unc_mantissa,
         decimal_separator=options.decimal_separator,
         paren_uncertainty=options.paren_uncertainty,
         pm_whitespace=options.pm_whitespace,

sciform/options/conversion.py

@@ -90,6 +90,7 @@ def populate_options(input_options: InputOptions) -> PopulatedOptions:
 
 key_to_enum_dict = {
     "exp_mode": option_types.ExpModeEnum,
+    "exp_val": option_types.ExpValEnum,
     "round_mode": option_types.RoundModeEnum,
     "upper_separator": option_types.SeparatorEnum,
     "decimal_separator": option_types.SeparatorEnum,
@@ -104,7 +105,7 @@ def finalize_populated_options(populated_options: PopulatedOptions) -> Finalized
     """Convert PopulatedOptions into FinalizedOptions with enum values."""
     kwargs = populated_options.as_dict()
     for key, value in kwargs.items():
-        if key in key_to_enum_dict:
+        if key in key_to_enum_dict and isinstance(value, str):
             enum = key_to_enum_dict[key]
             kwargs[key] = option_types.mode_str_to_enum(value, enum)
     return FinalizedOptions(**kwargs)

sciform/options/finalized_options.py

@@ -10,8 +10,6 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from sciform.options.validation import validate_options
-
 if TYPE_CHECKING:  # pragma: no cover
     from sciform.options import option_types
 
@@ -21,9 +19,9 @@ class FinalizedOptions:
     """Rendered options: All options populated and using Enum instead of Literal."""
 
     exp_mode: option_types.ExpModeEnum
-    exp_val: int | type(option_types.AutoExpVal)
+    exp_val: int | option_types.ExpValEnum
     round_mode: option_types.RoundModeEnum
-    ndigits: int | type(option_types.AutoDigits)
+    ndigits: int
     upper_separator: option_types.UpperSeparatorEnums
     decimal_separator: option_types.DecimalSeparatorEnums
     lower_separator: option_types.LowerSeparatorEnums
@@ -38,10 +36,6 @@ class FinalizedOptions:
     superscript: bool
     nan_inf_exp: bool
     paren_uncertainty: bool
-    pdg_sig_figs: bool
     left_pad_matching: bool
     paren_uncertainty_trim: bool
     pm_whitespace: bool
-
-    def __post_init__(self: FinalizedOptions) -> None:
-        validate_options(self, none_allowed=False)

sciform/options/global_options.py

@@ -1,13 +1,12 @@
 """Global Options."""
 
-from sciform.options import option_types
 from sciform.options.populated_options import PopulatedOptions
 
 PKG_DEFAULT_OPTIONS = PopulatedOptions(
     exp_mode="fixed_point",
-    exp_val=option_types.AutoExpVal,
-    round_mode="sig_fig",
-    ndigits=option_types.AutoDigits,
+    exp_val="auto",
+    round_mode="all",
+    ndigits=2,
     upper_separator="",
     decimal_separator=".",
     lower_separator="",
@@ -22,7 +21,6 @@ PKG_DEFAULT_OPTIONS = PopulatedOptions(
     superscript=False,
     nan_inf_exp=False,
     paren_uncertainty=False,
-    pdg_sig_figs=False,
     left_pad_matching=False,
     paren_uncertainty_trim=True,
     pm_whitespace=True,

sciform/options/input_options.py

@@ -51,9 +51,9 @@ class InputOptions:
     """  # noqa: E501
 
     exp_mode: option_types.ExpMode | None = None
-    exp_val: int | type(option_types.AutoExpVal) | None = None
+    exp_val: int | option_types.ExpVal | None = None
     round_mode: option_types.RoundMode | None = None
-    ndigits: int | type(option_types.AutoDigits) | None = None
+    ndigits: int | None = None
     upper_separator: option_types.UpperSeparators | None = None
     decimal_separator: option_types.DecimalSeparators | None = None
     lower_separator: option_types.LowerSeparators | None = None
@@ -68,7 +68,6 @@ class InputOptions:
     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_trim: bool | None = None
     pm_whitespace: bool | None = None

sciform/options/option_types.py

@@ -5,51 +5,6 @@ from __future__ import annotations
 from enum import Enum
 from typing import Literal, TypeVar
 
-
-class SentinelMeta(type):
-    """Sentinel metaclass, __repr__ returns class name."""
-
-    def __repr__(cls: SentinelMeta) -> str:
-        return cls.__name__
-
-
-class AutoExpVal(metaclass=SentinelMeta):
-    """
-    Flag for auto-exponent calculation mode.
-
-      * For scientific exponent mode the base-10 exponent is selected so
-        that the mantissa ``m`` satisfies ``1 <= m < 10``.
-      * For engineering exponent mode the base-10 exponent is chosen so
-        that it is an integer multiple of 3 and the mantissa ``m``
-        satisfies ``1 <= m < 1000``.
-      * For shifted engineering exponent mode the base-10 exponent is
-        chosen so that it is an integer multiple of 3 and the mantissa
-        ``m`` satisfies ``0.1 <= m < 100``.
-      * For binary exponent mode the base-2 exponent is chosen so that
-        the mantissa ``m`` satisfies ``1 <= m < 2``.
-      * For binary IEC exponent mode the base-2 exponent is chosen so
-        that the mantissa ``m`` satisfies ``1 <= m < 1024 = 2**10``.
-    """
-
-
-class AutoDigits(metaclass=SentinelMeta):
-    """
-    Flag for auto ndigits calculation mode.
-
-    In both sig fig and ndigits round modes this auto ndigits
-    option chooses the ndigits so that the least significant digit of
-    the input number will be displayed.
-    For example the number 123.456789 would be displayed with either 9
-    significant figures or 6 digits past the decimal point so that in
-    either case all digits are shown.
-
-    When used with sig fig rounding and in combination with the
-    ``pdg_sig_figs`` option, the number of significant figures will be
-    chosen to be one or two in accordance with the Particle Data Group
-    algorithm.
-    """
-
-
 LeftPadChar = Literal[" ", "0"]
 
 
@@ -101,7 +56,7 @@ LowerSeparatorEnums = Literal[
 ]
 
 
-RoundMode = Literal["sig_fig", "dec_place"]
+RoundMode = Literal["sig_fig", "dec_place", "all", "pdg"]
 
 
 class RoundModeEnum(str, Enum):
@@ -109,6 +64,8 @@ class RoundModeEnum(str, Enum):
 
     SIG_FIG = "sig_fig"
     DEC_PLACE = "dec_place"
+    ALL = "all"
+    PDG = "pdg"
 
 
 ExpMode = Literal[
@@ -145,6 +102,15 @@ class ExpFormatEnum(str, Enum):
     PARTS_PER = "parts_per"
 
 
+ExpVal = Literal["auto"]
+
+
+class ExpValEnum(str, Enum):
+    """Exponent value Enum."""
+
+    AUTO = "auto"
+
+
 T = TypeVar("T", bound=Enum)
 
 

sciform/options/populated_options.py

@@ -44,7 +44,7 @@ class PopulatedOptions:
     >>> print(formatter.populated_options)
     PopulatedOptions(
      'exp_mode': 'engineering',
-     'exp_val': AutoExpVal,
+     'exp_val': 'auto',
      'round_mode': 'sig_fig',
      'ndigits': 2,
      'upper_separator': '',
@@ -61,13 +61,12 @@ class PopulatedOptions:
      'superscript': True,
      'nan_inf_exp': False,
      'paren_uncertainty': False,
-     'pdg_sig_figs': False,
      'left_pad_matching': False,
      'paren_uncertainty_trim': 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_trim': True, 'pm_whitespace': True}
+    {'exp_mode': 'engineering', 'exp_val': 'auto', '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, 'left_pad_matching': False, 'paren_uncertainty_trim': True, 'pm_whitespace': True}
 
     Note that :class:`PopulatedOptions` lacks the ``add_c_prefix``,
     ``add_small_si_prefixes`` and ``add_ppth_form`` options present
@@ -93,9 +92,9 @@ class PopulatedOptions:
     """  # noqa: E501
 
     exp_mode: option_types.ExpMode
-    exp_val: int | type(option_types.AutoExpVal)
+    exp_val: int | option_types.ExpVal
     round_mode: option_types.RoundMode
-    ndigits: int | type(option_types.AutoDigits)
+    ndigits: int
     upper_separator: option_types.UpperSeparators
     decimal_separator: option_types.DecimalSeparators
     lower_separator: option_types.LowerSeparators
@@ -110,7 +109,6 @@ class PopulatedOptions:
     superscript: bool
     nan_inf_exp: bool
     paren_uncertainty: bool
-    pdg_sig_figs: bool
     left_pad_matching: bool
     paren_uncertainty_trim: bool
     pm_whitespace: bool

sciform/options/validation.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 
 def validate_options(
-    options: InputOptions | PopulatedOptions | FinalizedOptions,
+    options: InputOptions | PopulatedOptions,
     *,
     none_allowed: bool,
 ) -> None:
@@ -31,59 +31,49 @@ allowed_round_modes = get_args(option_types.RoundMode)
 
 
 def validate_rounding(
-    options: InputOptions | PopulatedOptions | FinalizedOptions,
+    options: InputOptions | PopulatedOptions,
     *,
     none_allowed: bool,
 ) -> None:
     r"""Validate ndigits if round_mode == "sig_fig"."""
-    if (
-        not (none_allowed and options.round_mode is None)
-        and options.round_mode not in allowed_round_modes
-    ):
-        msg = f"round_mode must be in {allowed_round_modes}, not {options.round_mode}."
-        raise ValueError(msg)
-
-    if not (none_allowed and options.ndigits is None) and not isinstance(
-        options.ndigits,
-        (int, type(option_types.AutoDigits)),
-    ):
-        msg = f'ndigits must be an "int" or "AutoDigits", not {options.ndigits}.'
+    if none_allowed and options.ndigits is None:
+        pass
+    elif not isinstance(options.ndigits, int):
+        msg = f"ndigits must be an int, not {options.ndigits}."
         raise TypeError(msg)
 
-    if (
-        not (none_allowed and options.round_mode is None)
-        and 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)
+    if none_allowed and options.round_mode is None:
+        pass
+    else:
+        if options.round_mode not in allowed_round_modes:
+            msg = (
+                f"round_mode must be in {allowed_round_modes}, not "
+                f"{options.round_mode}."
+            )
+            raise ValueError(msg)
+        if options.round_mode == "sig_fig" and options.ndigits < 1:
+            msg = f"ndigits must be >= 1 for sig fig rounding, not {options.ndigits}."
+            raise ValueError(msg)
 
 
 allowed_exp_modes = get_args(option_types.ExpMode)
-allowed_exp_val_types = (int, type(option_types.AutoExpVal), type(None))
 allowed_exp_formats = get_args(option_types.ExpFormat)
 
 
-def validate_exp_options(
+def validate_exp_val(
     options: InputOptions | PopulatedOptions | FinalizedOptions,
     *,
     none_allowed: bool,
 ) -> None:
-    """Validate exponent options."""
-    if (
-        not (none_allowed and options.exp_mode is None)
-        and options.exp_mode not in allowed_exp_modes
-    ):
-        msg = f"exp_mode must be in {allowed_exp_modes}, not {options.exp_mode}."
-        raise ValueError(msg)
-
-    if not (none_allowed and options.exp_val is None):
-        if not isinstance(options.exp_val, allowed_exp_val_types):
-            msg = f"exp_val must be an int, AutoExpVal, or None, not {options.exp_val}."
+    """Validate exponent value."""
+    if none_allowed and options.exp_val is None:
+        pass
+    else:
+        if not isinstance(options.exp_val, int) and options.exp_val != "auto":
+            msg = f"exp_val must be an int, 'auto', or None, not {options.exp_val}."
             raise TypeError(msg)
 
-        if options.exp_val is not option_types.AutoExpVal:
+        if options.exp_val != "auto":
             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 "
@@ -106,10 +96,24 @@ def validate_exp_options(
                 )
                 raise ValueError(msg)
 
-    if (
-        not (none_allowed and options.exp_format is None)
-        and options.exp_format not in allowed_exp_formats
-    ):
+
+def validate_exp_options(
+    options: InputOptions | PopulatedOptions | FinalizedOptions,
+    *,
+    none_allowed: bool,
+) -> None:
+    """Validate exponent options."""
+    if none_allowed and options.exp_mode is None:
+        pass
+    elif options.exp_mode not in allowed_exp_modes:
+        msg = f"exp_mode must be in {allowed_exp_modes}, not {options.exp_mode}."
+        raise ValueError(msg)
+
+    validate_exp_val(options, none_allowed=none_allowed)
+
+    if none_allowed and options.exp_format is None:
+        pass
+    elif options.exp_format not in allowed_exp_formats:
         msg = (
             f"{options.exp_format} must be in {allowed_exp_formats}, not "
             f"{options.exp_format}."
@@ -126,10 +130,9 @@ def validate_sign_mode(
     none_allowed: bool,
 ) -> None:
     r"""Validate ndigits if round_mode == "sig_fig"."""
-    if (
-        not (none_allowed and options.sign_mode is None)
-        and options.sign_mode not in allowed_sign_modes
-    ):
+    if none_allowed and options.sign_mode is None:
+        pass
+    elif options.sign_mode not in allowed_sign_modes:
         msg = f"sign_mode must be in {allowed_sign_modes}, not {options.sign_mode}."
         raise ValueError(msg)
 
@@ -140,7 +143,9 @@ def validate_separator_options(
     none_allowed: bool,
 ) -> None:
     """Validate separator user input."""
-    if not (none_allowed and options.upper_separator is None):
+    if none_allowed and options.upper_separator is None:
+        pass
+    else:
         if options.upper_separator not in get_args(option_types.UpperSeparators):
             msg = (
                 f"upper_separator must be in "
@@ -155,9 +160,9 @@ def validate_separator_options(
             )
             raise ValueError(msg)
 
-    if not (none_allowed and options.decimal_separator is None) and (
-        options.decimal_separator not in get_args(option_types.DecimalSeparators)
-    ):
+    if none_allowed and options.decimal_separator is None:
+        pass
+    elif options.decimal_separator not in get_args(option_types.DecimalSeparators):
         msg = (
             f"decimal_separator must be in "
             f"{get_args(option_types.DecimalSeparators)}, not "
@@ -165,9 +170,9 @@ def validate_separator_options(
         )
         raise ValueError(msg)
 
-    if not (none_allowed and options.lower_separator is None) and (
-        options.lower_separator not in get_args(option_types.LowerSeparators)
-    ):
+    if none_allowed and options.lower_separator is None:
+        pass
+    elif options.lower_separator not in get_args(option_types.LowerSeparators):
         msg = (
             f"lower_separator must be in {get_args(option_types.LowerSeparators)}, "
             f"not {options.lower_separator}."
@@ -188,7 +193,9 @@ def validate_extra_translations(
     ]
 
     for translation_dict in translations_dicts:
-        if not (none_allowed and translation_dict is None):
+        if none_allowed and translation_dict is None:
+            pass
+        else:
             for key, value in translation_dict.items():
                 if not isinstance(key, int):
                     msg = f'Translation dictionary keys must be integers, not "{key}".'
@@ -208,16 +215,19 @@ def validate_left_pad_options(
     none_allowed: bool,
 ) -> None:
     """Validate left padding options."""
-    dec_place_msg = (
-        f"left_pad_dec_place must an an int >= 0, not {options.left_pad_dec_place}."
-    )
-    if not (none_allowed and options.left_pad_dec_place is None):
+    if none_allowed and options.left_pad_dec_place is None:
+        pass
+    else:
+        dec_place_msg = (
+            f"left_pad_dec_place must an an int >= 0, not {options.left_pad_dec_place}."
+        )
         if not isinstance(options.left_pad_dec_place, int):
             raise TypeError(dec_place_msg)
         if options.left_pad_dec_place < 0:
             raise ValueError(dec_place_msg)
-    if not (
-        none_allowed and options.left_pad_char is None
-    ) and options.left_pad_char not in [0, "0", " "]:
+
+    if none_allowed and options.left_pad_char is None:
+        pass
+    elif options.left_pad_char not in [0, "0", " "]:
         msg = f'left_pad_char must be in [" ", "0", 0], not {options.left_pad_char}.'
         raise ValueError(msg)