sciform 0.33.0__tar.gz → 0.34.0__tar.gz

{sciform-0.33.0 → sciform-0.34.0}/CHANGELOG.rst

@@ -12,6 +12,76 @@ Unreleased
 
 ----
 
+0.34.0 (2024-02-04)
+-------------------
+
+Added
+^^^^^
+
+* The ``Formatter`` now exposes the ``input_options`` and
+  ``populated_options`` attributes.
+  The ``input_options`` attribute holds an ``InputOptions`` object which
+  stores a record of the input options passed into the ``Formatter``.
+  The ``populated_options`` attribute returns a ``PopulatedOptions``
+  object which shows the complete set of populated options which will be
+  used for formatting after merging with the global options.
+  Note that the ``populated_options`` attribute is re-calculated each
+  time it is access so that it reflects the current global options.
+  Both the ``InputOptions`` and ``PopulatedOptions`` objects can be used
+  to provide string representations of the options, or provide
+  programmatic access to the options via either attribute access or the
+  ``as_dict()`` methods.
+  [`#110 <https://github.com/jagerber48/sciform/issues/110>`_]
+* The ``PopulatedOptions`` used during formatting of a given
+  ``FormattedNumber`` instance are stored on that instance for future
+  reference.
+* Added ``get_default_global_options()``.
+* Now integer ``0`` can be passed into ``left_pad_char`` to get the same
+  behavior as string ``"0"``.
+* Added tests for docstrings.
+
+Changed
+^^^^^^^
+
+* **[BREAKING]** Renamed functions for configuring global options:
+
+  * ``set_global_defaults()`` -> ``set_global_options()``
+  * ``reset_global_defaults()`` -> ``reset_global_options()``
+  * ``GlobalDefaultsContext()`` -> ``GlobalOptionsContext()``
+
+* Refactored backend options handling code.
+  Previously, ``UserOptions`` were rendered into ``RenderedOptions``.
+  During rendering the global options were appropriately merged in and
+  some string literal options were replaced with enums for internal use.
+  These two classes were private.
+  Now there are ``InputOptions`` (which try to faithfully record user
+  input), ``PopulatedOptions`` (which capture the result of merging
+  the global options into the input options, but still using
+  user-friendly string representations of all options), and
+  ``FinalizedOptions`` (which use the internal enum representations of
+  certain options).
+  The ``InputOptions`` and ``PopulatedOptions`` are now public while the
+  ``FinalizedOptions`` is still private to shield the enum
+  representations from the users.
+  This sizable refactor was precipitated by the publicizing of the
+  options.
+  [`#110 <https://github.com/jagerber48/sciform/issues/110>`_]
+
+Removed
+^^^^^^^
+
+* **[BREAKING]** Removed ``print_global_defaults()`` in favor of
+  ``get_global_defaults()`` which now returns a ``PopulatedOptions``
+  object which can be printed by the user if desired.
+
+Fixed
+^^^^^
+
+* Fixed a bug where ``SciNum`` formatting resulted in ``str`` objects
+  instead of ``FormattedNumber`` objects.
+
+----
+
 0.33.0 (2024-01-31)
 -------------------
 
@@ -65,8 +135,6 @@ Changed
       Hopefully this can be replaced when ``ruff`` provides
       functionality for formatting ``.rst`` files.
 
-
-
 Fixed
 ^^^^^
 

{sciform-0.33.0 → sciform-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sciform
-Version: 0.33.0
+Version: 0.34.0
 Summary: A package for formatting numbers into scientific formatted strings.
 Author-email: Justin Gerber <justin.gerber48@gmail.com>
 Project-URL: homepage, https://github.com/jagerber48/sciform
@@ -132,18 +132,22 @@ You can view the on-going review
 Usage
 =====
 
+Here we provide a few key usage examples.
+For many more details see
+`Usage <https://sciform.readthedocs.io/en/stable/usage.html>`_.
+
 ``sciform`` provides a wide variety of formatting options which can be
 controlled when constructing ``Formatter`` objects which are then used
 to format numbers into strings according to the selected options.
 
 >>> from sciform import Formatter
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
 ... )
->>> print(sform(51413.14159265359))
+>>> print(formatter(51413.14159265359))
 51 413.141 593
->>> sform = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
->>> print(sform(123456.78))
+>>> formatter = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
+>>> print(formatter(123456.78))
 123.5e+03
 
 Users can also format numbers by constructing ``SciNum`` objects and
@@ -162,11 +166,11 @@ to format pairs of numbers as value/uncertainty pairs.
 This can be done by passing two numbers into a ``Formatter`` call or by
 using the ``SciNum`` object.
 
->>> sform = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
->>> print(sform(123456.654321, 0.00345))
+>>> formatter = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
+>>> print(formatter(123456.654321, 0.00345))
 123 456.654 3 ± 0.003 4
->>> sform = Formatter(ndigits=4, exp_mode="engineering")
->>> print(sform(123456.654321, 0.00345))
+>>> formatter = Formatter(ndigits=4, exp_mode="engineering")
+>>> print(formatter(123456.654321, 0.00345))
 (123.456654321 ± 0.000003450)e+03
 
 >>> num = SciNum(123456.654321, 0.00345)

{sciform-0.33.0 → sciform-0.34.0}/README.rst

@@ -97,18 +97,22 @@ You can view the on-going review
 Usage
 =====
 
+Here we provide a few key usage examples.
+For many more details see
+`Usage <https://sciform.readthedocs.io/en/stable/usage.html>`_.
+
 ``sciform`` provides a wide variety of formatting options which can be
 controlled when constructing ``Formatter`` objects which are then used
 to format numbers into strings according to the selected options.
 
 >>> from sciform import Formatter
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
 ... )
->>> print(sform(51413.14159265359))
+>>> print(formatter(51413.14159265359))
 51 413.141 593
->>> sform = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
->>> print(sform(123456.78))
+>>> formatter = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
+>>> print(formatter(123456.78))
 123.5e+03
 
 Users can also format numbers by constructing ``SciNum`` objects and
@@ -127,11 +131,11 @@ to format pairs of numbers as value/uncertainty pairs.
 This can be done by passing two numbers into a ``Formatter`` call or by
 using the ``SciNum`` object.
 
->>> sform = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
->>> print(sform(123456.654321, 0.00345))
+>>> formatter = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
+>>> print(formatter(123456.654321, 0.00345))
 123 456.654 3 ± 0.003 4
->>> sform = Formatter(ndigits=4, exp_mode="engineering")
->>> print(sform(123456.654321, 0.00345))
+>>> formatter = Formatter(ndigits=4, exp_mode="engineering")
+>>> print(formatter(123456.654321, 0.00345))
 (123.456654321 ± 0.000003450)e+03
 
 >>> num = SciNum(123456.654321, 0.00345)

sciform-0.34.0/docs/source/api.rst

@@ -0,0 +1,49 @@
+API
+###
+
+.. module:: sciform
+   :noindex:
+
+Formatting
+==========
+
+.. autoclass:: Formatter(...)
+   :members:
+
+   .. automethod:: __init__(...)
+   .. automethod:: __call__
+
+.. autoclass:: SciNum
+
+.. autoclass:: FormattedNumber()
+   :members:
+   :private-members:
+
+Options
+=======
+
+.. autoclass:: InputOptions()
+   :members:
+
+.. autoclass:: PopulatedOptions()
+   :members:
+
+Auto Options
+============
+
+.. autoclass:: AutoExpVal()
+
+.. autoclass:: AutoDigits()
+
+Global Configuration
+====================
+
+.. autofunction:: get_default_global_options
+
+.. autofunction:: get_global_options
+
+.. autofunction:: set_global_options(...)
+
+.. autofunction:: reset_global_options
+
+.. autoclass:: GlobalOptionsContext(...)

{sciform-0.33.0 → sciform-0.34.0}/docs/source/examples.rst

@@ -20,66 +20,66 @@ available formatting options.
 
 >>> from sciform import Formatter
 >>> num = 12345.54321
->>> sform = Formatter(exp_mode="scientific", round_mode="sig_fig", ndigits=4)
->>> print(sform(num))
+>>> formatter = Formatter(exp_mode="scientific", round_mode="sig_fig", ndigits=4)
+>>> print(formatter(num))
 1.235e+04
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="engineering",
 ...     round_mode="dec_place",
 ...     ndigits=10,
 ...     sign_mode=" ",
 ...     superscript=True,
 ... )
->>> print(sform(num))
+>>> print(formatter(num))
  12.3455432100×10³
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="fixed_point",
 ...     upper_separator=" ",
 ...     decimal_separator=",",
 ...     lower_separator="_",
 ...     sign_mode="+",
 ... )
->>> print(sform(num))
+>>> print(formatter(num))
 +12 345,543_21
 
 >>> num = 0.076543
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="scientific", exp_val=-3, exp_format="parts_per", add_ppth_form=True
 ... )
->>> print(sform(num))
+>>> print(formatter(num))
 76.543 ppth
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="scientific", exp_val=-2, exp_format="prefix", add_c_prefix=True
 ... )
->>> print(sform(num))
+>>> print(formatter(num))
 7.6543 c
->>> sform = Formatter(exp_mode="scientific", exp_val=-6, exp_format="prefix")
->>> print(sform(num))
+>>> formatter = Formatter(exp_mode="scientific", exp_val=-6, exp_format="prefix")
+>>> print(formatter(num))
 76543 μ
->>> sform = Formatter(exp_mode="percent")
->>> print(sform(num))
+>>> formatter = Formatter(exp_mode="percent")
+>>> print(formatter(num))
 7.6543%
 
 >>> num = 3141592.7
 >>> unc = 1618
->>> sform = Formatter()
->>> print(sform(num, unc))
+>>> formatter = Formatter()
+>>> print(formatter(num, unc))
 3141593 ± 1618
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="engineering",
 ...     exp_format="prefix",
 ...     pdg_sig_figs=True,
 ...     pm_whitespace=False,
 ... )
->>> print(sform(num, unc))
+>>> print(formatter(num, unc))
 (3.1416±0.0016) M
 
 >>> num = 314159.27
 >>> unc = 1618
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="engineering_shifted", pdg_sig_figs=True, paren_uncertainty=True
 ... )
->>> print(sform(num, unc))
+>>> print(formatter(num, unc))
 (0.3142(16))e+06
 
 .. _fsml_examples:
@@ -137,52 +137,51 @@ SciNum, and Global Options
 Here are a small selection of examples which demonstrate some of the
 available string formatting options.
 Note that many options are not available through the :ref:`fsml`, so
-these options must be selected by configuring the global default options
-during formatting.
-Here this is done using the :class:`GlobalDefaultsContext` context
-manager, but this could have been done using :func:`set_global_defaults`
+these options must be selected by configuring the global options.
+Here this is done using the :class:`GlobalOptionsContext` context
+manager, but this could have been done using :func:`set_global_options`
 instead.
 
->>> from sciform import SciNum, GlobalDefaultsContext
->>> snum = SciNum(12345.54321)
->>> print(f"{snum:!4e}")
+>>> from sciform import SciNum, GlobalOptionsContext
+>>> num = SciNum(12345.54321)
+>>> print(f"{num:!4e}")
 1.235e+04
->>> print(f"{snum: .10r}")
+>>> print(f"{num: .10r}")
  12.3455432100e+03
->>> with GlobalDefaultsContext(
+>>> with GlobalOptionsContext(
 ...     upper_separator=" ",
 ...     decimal_separator=",",
 ...     lower_separator="_",
 ... ):
-...     print(f"{snum:+}")
+...     print(f"{num:+}")
 +12 345,543_21
 
->>> snum = SciNum(0.076543)
->>> with GlobalDefaultsContext(exp_format="parts_per", add_ppth_form=True):
-...     print(f"{snum:ex-3}")
+>>> num = SciNum(0.076543)
+>>> with GlobalOptionsContext(exp_format="parts_per", add_ppth_form=True):
+...     print(f"{num:ex-3}")
 ...
 76.543 ppth
->>> with GlobalDefaultsContext(exp_format="prefix", add_c_prefix=True):
-...     print(f"{snum:ex-2}")
+>>> with GlobalOptionsContext(exp_format="prefix", add_c_prefix=True):
+...     print(f"{num:ex-2}")
 ...
 7.6543 c
->>> with GlobalDefaultsContext(exp_mode="scientific", exp_val=-6, exp_format="prefix"):
-...     print(f"{snum:ex-6}")
+>>> with GlobalOptionsContext(exp_mode="scientific", exp_val=-6, exp_format="prefix"):
+...     print(f"{num:ex-6}")
 ...
 76543 μ
->>> print(f"{snum:%}")
+>>> print(f"{num:%}")
 7.6543%
 
 >>> num_unc = SciNum(3141592.7, 1618)
 >>> print(f"{num_unc}")
 3141593 ± 1618
->>> with GlobalDefaultsContext(pdg_sig_figs=True, pm_whitespace=False):
+>>> with GlobalOptionsContext(pdg_sig_figs=True, pm_whitespace=False):
 ...     print(f"{num_unc:rp}")
 ...
 (3.1416±0.0016) M
 
 >>> num_unc = SciNum(314159.27, 1618)
->>> with GlobalDefaultsContext(pdg_sig_figs=True):
+>>> with GlobalOptionsContext(pdg_sig_figs=True):
 ...     print(f"{num_unc:#r()}")
 ...
 (0.3142(16))e+06
@@ -296,7 +295,7 @@ lists, arrays, etc.) of numbers.
 
 >>> from sciform import Formatter
 >>>
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="engineering",
 ...     exp_format="prefix",
 ...     pdg_sig_figs=True,
@@ -305,11 +304,11 @@ lists, arrays, etc.) of numbers.
 >>> val_list = [1000, 2000, 3000]
 >>> err_list = [200, 400, 600]
 >>>
->>> val_str_list = list(map(sform, val_list))
+>>> val_str_list = list(map(formatter, val_list))
 >>> print(val_str_list)
 ['1 k', '2 k', '3 k']
 >>>
->>> val_err_str_list = list(map(sform, val_list, err_list))
+>>> val_err_str_list = list(map(formatter, val_list, err_list))
 >>> print(val_err_str_list)
 ['1.00(20) k', '2.0(4) k', '3.0(6) k']
 
@@ -319,16 +318,16 @@ makes this easy.
 
 >>> import numpy as np
 >>>
->>> vec_sform = np.vectorize(sform)
+>>> vec_formatter = np.vectorize(formatter)
 >>> arr = np.array([[1e6, 2e6, 3e6], [4e6, 5e6, 6e6], [7e6, 8e6, 9e6]])
 >>>
 >>> arr_err = np.array([[9e4, 8e4, 7e4], [6e4, 5e4, 4e4], [3e4, 2e4, 1e4]])
 >>>
->>> print(vec_sform(arr))
+>>> print(vec_formatter(arr))
 [['1 M' '2 M' '3 M']
  ['4 M' '5 M' '6 M']
  ['7 M' '8 M' '9 M']]
->>> print(vec_sform(arr, arr_err))
+>>> print(vec_formatter(arr, arr_err))
 [['1.00(9) M' '2.00(8) M' '3.00(7) M']
  ['4.00(6) M' '5.00(5) M' '6.00(4) M']
  ['7.000(30) M' '8.000(20) M' '9.000(10) M']]

{sciform-0.33.0 → sciform-0.34.0}/docs/source/exp replacement.rst

@@ -152,14 +152,14 @@ Note that it is possible, using the ``extra_parts_per_forms`` option to
 override the standard mappings listed above.
 
 >>> from sciform import Formatter
->>> sform = Formatter(
+>>> formatter = Formatter(
 ...     exp_mode="engineering",
 ...     exp_format="parts_per",
 ...     extra_parts_per_forms={-9: None, -12: "ppb"},
 ... )
->>> print(sform(33e-9))
+>>> print(formatter(33e-9))
 33e-09
->>> print(sform(33e-12))
+>>> print(formatter(33e-12))
 33 ppb
 
 IEC Prefixes

{sciform-0.33.0 → sciform-0.34.0}/docs/source/fsml.rst

@@ -139,11 +139,11 @@ for scientific formatting.
   not compatible with the explicit formatting options preferred by
   :mod:`sciform`. The built-in automation features include
 
-  * Automated selection of fixed-point or scientific notation. For
-    :mod:`sciform`, the exponent is either explicitly indicated by the
-    user or resolved from the global default options.
-  * Truncation of trailing zeros without the ``#`` option. For
-    :mod:`sciform`, trailing zeros are never truncated if they fall
+  * Automated selection of fixed-point or scientific notation.
+    For :mod:`sciform`, the exponent mode is either explicitly indicated
+    by the user or resolved from the global options.
+  * Truncation of trailing zeros without the ``#`` option.
+    For :mod:`sciform`, trailing zeros are never truncated if they fall
     within the user-selected decimal place or significant figures
     rounding.
   * Inclusion of a hanging decimal point, e.g. ``123.``.