Metadata-Version: 2.1
Name: sciform
Version: 0.31.1
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
Project-URL: documentation, https://sciform.readthedocs.io
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff ; 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'

.. image:: https://www.repostatus.org/badges/latest/wip.svg
     :target: https://www.repostatus.org/#wip
     :alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
.. image:: https://img.shields.io/readthedocs/sciform?logo=readthedocs&link=https%3A%2F%2Fsciform.readthedocs.io%2Fen%2Fstable%2F
     :target: https://sciform.readthedocs.io/en/stable/
     :alt: Read the Docs
.. image:: https://img.shields.io/pypi/v/sciform?logo=pypi
     :target: https://pypi.org/project/sciform/
     :alt: PyPI - Version
.. image:: https://img.shields.io/pypi/pyversions/sciform?logo=python
     :target: https://pypi.org/project/sciform/
     :alt: PyPI - Python Version
.. image:: https://img.shields.io/codecov/c/github/jagerber48/sciform?logo=codecov
     :target: https://codecov.io/gh/jagerber48/sciform
     :alt: Codecov
.. image:: https://img.shields.io/github/actions/workflow/status/jagerber48/sciform/python-package.yml?logo=github%20actions
     :target: https://github.com/jagerber48/sciform/blob/main/.github/workflows/python-package.yml
     :alt: GitHub Workflow Status


#######
sciform
#######

|  **Repository:** `<https://github.com/jagerber48/sciform>`_
|  **Documentation:** `<https://sciform.readthedocs.io/en/stable/>`_
|  **PyPi:** `<https://pypi.org/project/sciform/>`_

========
Overview
========

``sciform`` is used to convert python numbers into strings according to
a variety of user-selected scientific formatting options including
decimal, binary, fixed-point, scientific and engineering formats.
Where possible, formatting follows documented standards such as those
published by `BIPM <https://www.bipm.org/en/>`_ or
`IEC <https://iec.ch/homepage>`_.
``sciform`` provides certain options, such as engineering notation,
well-controlled significant figure rounding, and separator customization
which are not provided by the python built-in
`format specification mini-language (FSML) <https://docs.python.org/3/library/string.html#format-specification-mini-language>`_.

============
Installation
============

Install the latest stable version from
`PyPi <https://pypi.org/project/sciform/>`_ with::

   python -m pip install sciform

or install the latest development version from
`GitHub <https://github.com/jagerber48/sciform>`_ with::

   python -m pip install git+https://github.com/jagerber48/sciform.git

``sciform`` is compatible with Python versions >=3.9.

==================
Under Construction
==================

The ``sciform`` package is still in early stages of development.
The API is not stable.
Class, function and parameter names and usages have undergone changes
and may continue to change relatively freely until version ``1.0.0`` is
released.
API changes will be announced after new releases in the
`changelog <https://sciform.readthedocs.io/en/stable/project.html#changelog>`_.
If you have an idea or opinion about how ``sciform`` should be designed,
now is a great time to
`post a discussion topic <https://github.com/jagerber48/sciform/discussions>`_
about it!

``sciform`` is currently undergoing review by the
`PyOpenSci <https://www.pyopensci.org/>`_ community.
You can view the on-going review
`here <https://github.com/pyOpenSci/software-submission/issues/121>`_.

=====
Usage
=====

``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(
...     round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
... )
>>> print(sform(51413.14159265359))
51 413.141 593
>>> sform = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
>>> print(sform(123456.78))
123.5e+03

Users can also format numbers by constructing ``SciNum`` objects and
using string formatting to format the ``SciNum`` instances according
to a custom FSML.

>>> from sciform import SciNum
>>> num = SciNum(12345)
>>> print(f"{num:!2f}")
12000
>>> print(f"{num:!2r}")
12e+03

In addition to formatting individual numbers, ``sciform`` can be used
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))
123 456.654 3 ± 0.003 4
>>> sform = Formatter(ndigits=4, exp_mode="engineering")
>>> print(sform(123456.654321, 0.00345))
(123.456654321 ± 0.000003450)e+03

>>> num = SciNum(123456.654321, 0.00345)
>>> print(f"{num:!2f}")
123456.6543 ± 0.0034
>>> print(f"{num:!2f()}")
123456.6543(34)

Note that the above examples demonstrate that ``sciform`` uses
`"round-to-even" <https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even>`_
rounding.

>>> print(f"{SciNum(865):!2}")
860
>>> print(f"{SciNum(875):!2}")
880

================
Acknowledgements
================

``sciform`` was heavily motivated by the prefix formatting provided in
the `prefixed <https://github.com/Rockhopper-Technologies/prefixed>`_
package and the value ± uncertainty formatting in the
`uncertainties <https://github.com/lebigot/uncertainties>`_ package.
