sciform 0.32.3__tar.gz → 0.34.0__tar.gz

{sciform-0.32.3 → sciform-0.34.0}/.github/workflows/python-package.yml

@@ -19,27 +19,31 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install ruff blackdoc pytest pytest-cov
         python -m pip install -e .[dev]
-    - name: Lint/format with ruff
+    - name: Lint/format source code and docs
       run: |
         ruff check .
         ruff format . --check
-    - name: Lint/format docs
+    - name: Test source code and docs
       run: |
-        blackdoc .
-    - name: Test with pytest
-      run: |
-        pytest --cov --doctest-glob="*.rst"
+        coverage run -m unittest
+        coverage report
+        coverage xml
+        python -m sphinx -b doctest docs/source/ docs/build/doctest/
     - name: Upload coverage reports to Codecov
       uses: codecov/codecov-action@v3
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        flags: ${{ matrix.python-version }}
+        files: coverage.xml
+        fail_ci_if_error: true
+        verbose: true

{sciform-0.32.3 → sciform-0.34.0}/.github/workflows/python-publish.yml

@@ -21,9 +21,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies

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

@@ -12,6 +12,149 @@ 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)
+-------------------
+
+Added
+^^^^^
+
+* Added the ``FormattedNumber`` class.
+  This class is a subclass of ``str`` and is now returned by the
+  ``Formatter`` instead of ``str``.
+  The ``FormattedNumber`` class allows post-conversion to ASCII, HTML,
+  and LaTeX formats.
+  [`#114 <https://github.com/jagerber48/sciform/issues/114>`_]
+* Added separate flags for code coverage reports for each python
+  version.
+
+Changed
+^^^^^^^
+
+* In addition to removing the ``latex`` option from the ``Formatter`` in
+  favor of the introduction of the ``FormattedNumber`` class, the
+  LaTeX conversion algorithm has been slightly modified.
+
+    * Left and right parentheses are no longer converted to ``"\left("``
+      and ``"\right)"`` due to introducing strange spacing issues.
+      See
+      `Spacing around \\left and \\right <https://tex.stackexchange.com/questions/2607/spacing-around-left-and-right>`_.
+    * Previously spaces within the ``sciform`` output were handled
+      inconsistently and occasionally required confusing extra handling.
+      Now any spaces in the input string are directly and explicitly
+      converted into math mode medium spaces: ``"\:"``.
+    * ``"μ"`` is now included in the math mode ``\text{}`` environment
+      and converted to ``"\textmu"``.
+
+* **[BREAKING]** Renamed ``fill_char`` to ``left_pad_char``.
+  [`#126 <https://github.com/jagerber48/sciform/issues/126>`_]
+* Slimmed down ``[dev]`` optional dependencies and created
+  ``[examples]`` optional dependencies.
+  The former includes development tools, while the latter includes
+  the heavy-weight requirements needed to run all the examples,
+  including, e.g. ``jupyter``, ``scipy``, etc.
+* Cleaned up and improved github actions for testing and
+  linting/formatting.
+  [`#136 <https://github.com/jagerber48/sciform/issues/136>`_]
+
+    * Use ``unittest`` and ``coverage`` instead of ``pytest``.
+    * The requirements to run the automation match the ``[dev]``
+      optional dependencies.
+    * Cache ``pip`` requirements to avoid unnecessarily downloading
+      dependencies.
+    * Remove a defunct ``blackdoc`` test.
+      Hopefully this can be replaced when ``ruff`` provides
+      functionality for formatting ``.rst`` files.
+
+Fixed
+^^^^^
+
+* Fixed a bug where value/uncertainty pairs formatted in the
+  ``"parts_per"`` format with zero exponent would appear with redundant
+  parentheses, e.g. ``"(1.2 ± 0.1)"``.
+  [`#130 <https://github.com/jagerber48/sciform/issues/130>`_]
+
+Removed
+^^^^^^^
+
+* **[BREAKING]** Removed the ``latex`` option in favor of the
+  introduction of the ``FormattedNumber.as_latex()`` method.
+  This removal simplifies the formatting algorithm by separating LaTeX
+  formatting from other tasks like exponent string resolution.
+  The ``latex`` option also introduced a potential confusion with the
+  ``superscript`` option, which had no effect when ``latex=True``.
+
+----
+
 0.32.3 (2024-01-11)
 -------------------
 

{sciform-0.32.3/src/sciform.egg-info → sciform-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sciform
-Version: 0.32.3
+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
@@ -21,13 +21,17 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
 Requires-Dist: sphinx; extra == "dev"
 Requires-Dist: sphinx-rtd-theme; extra == "dev"
 Requires-Dist: sphinx-toolbox; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
-Requires-Dist: scipy; extra == "dev"
-Requires-Dist: matplotlib; extra == "dev"
-Requires-Dist: tabulate; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: numpy; extra == "examples"
+Requires-Dist: scipy; extra == "examples"
+Requires-Dist: matplotlib; extra == "examples"
+Requires-Dist: tabulate; extra == "examples"
+Requires-Dist: jupyter; extra == "examples"
 
 .. image:: https://www.repostatus.org/badges/latest/wip.svg
      :target: https://www.repostatus.org/#wip
@@ -128,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
@@ -158,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.32.3 → 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.32.3 → sciform-0.34.0}/docs/source/conf.py

@@ -40,6 +40,8 @@ html_theme_options = {
 todo_include_todos = True
 todo_emit_warnings = True
 
+autodoc_member_order = "bysource"
+
 # For wrapping of text in tables
 html_css_files = [
     "css/custom.css",

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

@@ -20,68 +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(
-...     exp_mode="engineering_shifted",
-...     pdg_sig_figs=True,
-...     paren_uncertainty=True
+>>> 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:
@@ -115,7 +113,7 @@ has two significant figures.
 The ``()`` indicates that the value/uncertainty pair should be formatted
 using the parentheses uncertainty format.
 
->>> print(f'{SciNum(123):ex-3p}')
+>>> print(f"{SciNum(123):ex-3p}")
 123000 m
 
 In the preceding example the ``e`` indicates that scientific notation
@@ -123,7 +121,7 @@ should be used.
 The ``x-3`` indicates that the exponent will be forced to equal ``-3``.
 Finally the ``p`` indicates that the SI prefix mode should be used.
 
->>> print(f'{SciNum(123): .-1f}')
+>>> print(f"{SciNum(123): .-1f}")
  120
 
 In this example the leading space indicates a leading space should be
@@ -139,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
@@ -298,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,
@@ -307,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']
 
@@ -321,20 +318,16 @@ makes this easy.
 
 >>> import numpy as np
 >>>
->>> vec_sform = np.vectorize(sform)
->>> arr = np.array([[1e6, 2e6, 3e6],
-...                 [4e6, 5e6, 6e6],
-...                 [7e6, 8e6, 9e6]])
+>>> 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]])
+>>> 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.32.3 → 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