From 6175d5f38b0381ccbf3ede2d0de9df0a432baaf3 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:51:03 +0200 Subject: [PATCH 01/22] first draft of the format docs --- docs/conf.py | 2 ++ docs/formatting.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 80 insertions(+) create mode 100644 docs/formatting.rst diff --git a/docs/conf.py b/docs/conf.py index 67e156c11..47d888652 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,8 @@ "sphinx.ext.mathjax", "matplotlib.sphinxext.plot_directive", "nbsphinx", + "IPython.sphinxext.ipython_directive", + "IPython.sphinxext.ipython_console_highlighting", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/formatting.rst b/docs/formatting.rst new file mode 100644 index 000000000..85c26f230 --- /dev/null +++ b/docs/formatting.rst @@ -0,0 +1,77 @@ +.. _formatting: +.. currentmodule:: pint + + +.. ipython:: python + :suppress: + + import pint + + +String formatting +================= +A :doc:`format specification ` used to format :py:class:`Unit` objects in +e.g. f-strings consists of a ``type`` and optionally a "modifier", where the order does +not matter. For example, ``P~`` and ``~P`` have the same effect. If the ``type`` is +omitted, or when using the :py:class:`str` builtin, the object's +:py:attr:`Unit.default_format` property is used, falling back to +:py:attr:`UnitRegistry.default_format` if that is not set. If both are unset, the +default format (``"D"``) is used. + +.. note:: + + Modifiers may still be used without specifying the type: ``"~"`` is a valid format + specification. + +Let's look at some examples: + +.. ipython:: python + + ureg = pint.UnitRegistry() + u = ureg.kg * ureg.m / ureg.s ** 2 + + f"{u:P}" # using the pretty format + f"{u:~P}" # short pretty + f"{u:P~}" # also short pretty + + # default format + u.default_format + ureg.default_format + str(u) # default: default + f"{u:~}" # default: short default + ureg.default_format = "C" # registry default to compact + f"{u}" # default: compact + u.default_format = "P" + f"{u}" # default: pretty + u.default_format = "" # TODO: switch to None + ureg.default_format = "" # TODO: switch to None + f"{u}" # default: default + +**TODO**: describe quantity formats + +Unit Format Types +----------------- +``pint`` comes with a variety of unit formats: + +======= =============== ====================================================================== +Spec Name Example +======= =============== ====================================================================== +``D`` default ``kilogram * meter / second ** 2`` +``P`` pretty ``kilogram·meter/second²`` +``H`` HTML ``kilogram meter/second2`` +``L`` latex ``\frac{\mathrm{kilogram} \cdot \mathrm{meter}}{\mathrm{second}^{2}}`` +``Lx`` latex siunitx ``\si[]{\kilo\gram\meter\per\second\squared}`` +``C`` compact ``kilogram*meter/second**2`` +======= =============== ====================================================================== + +Quantity Formats +---------------- + +Modifiers +--------- +======== =============== ============================ +Modifier Description Example +======== =============== ============================ +``~`` Short unit name ``kg·m/s²`` (Format: ``~P``) +``#`` +======== =============== ============================ diff --git a/docs/index.rst b/docs/index.rst index 826858520..108b43e50 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,6 +120,7 @@ User Guide getting tutorial defining-quantities + formatting numpy nonmult log_units From ba75cb96de4d82c8723eb227a44b4fa365e1f60c Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:55:21 +0200 Subject: [PATCH 02/22] fix the table --- docs/formatting.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 85c26f230..99a4a3e82 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -69,9 +69,9 @@ Quantity Formats Modifiers --------- -======== =============== ============================ -Modifier Description Example -======== =============== ============================ -``~`` Short unit name ``kg·m/s²`` (Format: ``~P``) +======== =================================================== ============================= +Modifier Meaning Example +======== =================================================== ============================= +``~`` Use the unit's symbol instead of its canonical name ``kg·m/s²`` (Format: ``~P``) ``#`` -======== =============== ============================ +======== =================================================== ============================= From b8dbc4ebdb315edb1834fd1c36f3f028378e28bc Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:56:51 +0200 Subject: [PATCH 03/22] add the ipython dependency --- requirements_docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements_docs.txt b/requirements_docs.txt index c698538d3..23f8119fa 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -7,6 +7,7 @@ pandas==1.2.4 pint-pandas jupyter_client ipykernel +ipython graphviz xarray pooch From f73d9c7641c9cc0fcbc57e3e1ee9fa351f00b822 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 18:17:51 +0200 Subject: [PATCH 04/22] enable napoleon type preprocessing --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 47d888652..03a2b8386 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,6 +111,10 @@ # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] +# -- Options for extensions ---------------------------------------------------- +# napoleon +napoleon_preprocess_types = True + # -- Options for HTML output --------------------------------------------------- From ede160a895bf7c632fccd6af47612507f8ede5ef Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 11:56:14 +0200 Subject: [PATCH 05/22] document the quantity modifier --- docs/formatting.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 99a4a3e82..50b50111a 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -69,9 +69,9 @@ Quantity Formats Modifiers --------- -======== =================================================== ============================= +======== =================================================== ================================ Modifier Meaning Example -======== =================================================== ============================= -``~`` Use the unit's symbol instead of its canonical name ``kg·m/s²`` (Format: ``~P``) -``#`` -======== =================================================== ============================= +======== =================================================== ================================ +``~`` Use the unit's symbol instead of its canonical name ``kg·m/s²`` (``f"{u:~P}"``) +``#`` Call :py:meth:`Quantity.to_compact` first ``1.0 m·mg/s²`` (``f"{q:#~P}"``) +======== =================================================== ================================ From 4b3bd493eda29d5e8dfae18e7c865c742af37ac8 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 11:59:01 +0200 Subject: [PATCH 06/22] add quantity format spec examples --- docs/formatting.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index 50b50111a..12ac9ce8a 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -66,6 +66,18 @@ Spec Name Example Quantity Formats ---------------- +.. ipython:: python + + q = 1e-6 * u + + # modifiers + f"{q:~P}" # short pretty + f"{q:~#P}" # compact short pretty + f"{q:P#~}" # also compact short pretty + + # additional magnitude format + f"{q:.2f~#P}" # short compact pretty with 8 float digits + f"{q:#~}" # compact short default Modifiers --------- From b273758106984ccf9bc502bafc1ad1a34024068d Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:06:33 +0200 Subject: [PATCH 07/22] move the unit format spec description into its own section --- docs/formatting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index 12ac9ce8a..1d1bc914a 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -10,6 +10,8 @@ String formatting ================= +Unit Format Specifications +-------------------------- A :doc:`format specification ` used to format :py:class:`Unit` objects in e.g. f-strings consists of a ``type`` and optionally a "modifier", where the order does not matter. For example, ``P~`` and ``~P`` have the same effect. If the ``type`` is From 2ed6ef60e704e7707adaaf0925985b6747011fec Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:07:00 +0200 Subject: [PATCH 08/22] describe the structure of quantity formats --- docs/formatting.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 1d1bc914a..743506fda 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -49,8 +49,6 @@ Let's look at some examples: ureg.default_format = "" # TODO: switch to None f"{u}" # default: default -**TODO**: describe quantity formats - Unit Format Types ----------------- ``pint`` comes with a variety of unit formats: @@ -66,8 +64,13 @@ Spec Name Example ``C`` compact ``kilogram*meter/second**2`` ======= =============== ====================================================================== -Quantity Formats ----------------- +Quantity Format Specifications +------------------------------ +In addition to the structure of :py:class:`Unit` format specifications, +:py:class:`Quantity` format specifications also may contain a format spec for the +magnitude. For example, ``".8f~P"`` formats the magnitude in floating point notation +with 8 digits and the unit in the short pretty format. + .. ipython:: python q = 1e-6 * u @@ -81,6 +84,10 @@ Quantity Formats f"{q:.2f~#P}" # short compact pretty with 8 float digits f"{q:#~}" # compact short default +Quantity Format Types +--------------------- +There are no special quantity formats yet. + Modifiers --------- ======== =================================================== ================================ From 3f6771fc8c6ec5bd6516b60496ecc469b37f016b Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:08:53 +0200 Subject: [PATCH 09/22] extend the intersphinx settings --- docs/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 03a2b8386..2441af954 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -327,7 +327,13 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"http://docs.python.org/": None} +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "numpy": ("https://numpy.org/doc/stable", None), + "matplotlib": ("https://matplotlib.org/stable/", None), + "dask": ("https://docs.dask.org/en/latest", None), + "sparse": ("https://sparse.pydata.org/en/latest/", None), +} # -- Doctest configuration ----------------------------------------------------- From 61a4976cdd07ad3a18d6c120e66a878b7fcf99b8 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:28:41 +0200 Subject: [PATCH 10/22] wording --- docs/formatting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index 743506fda..00d516cc6 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -71,6 +71,8 @@ In addition to the structure of :py:class:`Unit` format specifications, magnitude. For example, ``".8f~P"`` formats the magnitude in floating point notation with 8 digits and the unit in the short pretty format. +Let's look at some more examples: + .. ipython:: python q = 1e-6 * u From e623e7e110e838d5f36b72ce3d7ea628fa6d2883 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:30:34 +0200 Subject: [PATCH 11/22] update CHANGES --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index 477aa095b..2899c0c9d 100644 --- a/CHANGES +++ b/CHANGES @@ -16,6 +16,7 @@ Pint Changelog - Fix string formatting of numpy array scalars - Fix default format for Measurement class (Issue #1300) - Fix parsing of pretty units with same exponents but different sign. (Issue #1360) +- Add documentation for the string format options (Issue #1357, #1375) ### Breaking Changes From 3eb1bd89b4b6b76818adec7f0fd99ef6b4219e14 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 10:58:46 +0200 Subject: [PATCH 12/22] rewrite the unit format docs --- docs/formatting.rst | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 00d516cc6..9a479ba6f 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -10,21 +10,31 @@ String formatting ================= -Unit Format Specifications --------------------------- -A :doc:`format specification ` used to format :py:class:`Unit` objects in -e.g. f-strings consists of a ``type`` and optionally a "modifier", where the order does -not matter. For example, ``P~`` and ``~P`` have the same effect. If the ``type`` is -omitted, or when using the :py:class:`str` builtin, the object's -:py:attr:`Unit.default_format` property is used, falling back to -:py:attr:`UnitRegistry.default_format` if that is not set. If both are unset, the -default format (``"D"``) is used. +The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g. +through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format +specifications `. The basic format is:: + + [magnitude format][modifier][unit format] + +where each part is optional and the order of these is arbitrary. + +In case any part (except the modifier) is omitted, the corresponding value in +:py:attr:`Quantity.default_format` or :py:attr:`Unit.default_format` is filled in. If +that is not set (it evaluates to ``False``), :py:attr:`UnitRegistry.default_format` is +used. If both are not set, the global default of ``"D"`` and the magnitude's default +format are used instead. .. note:: - Modifiers may still be used without specifying the type: ``"~"`` is a valid format + Modifiers may be used without specifying any format: ``"~"`` is a valid format specification. + +Unit Format Specifications +-------------------------- +The :py:class:`Unit` class ignores the magnitude format part, and the unit format +consists of just the type. + Let's look at some examples: .. ipython:: python From db2edea587f5489256b36dc67ee3202d673ad4e1 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 11:02:37 +0200 Subject: [PATCH 13/22] rewrite the quantity format docs --- docs/formatting.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 9a479ba6f..8126592e1 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -76,10 +76,8 @@ Spec Name Example Quantity Format Specifications ------------------------------ -In addition to the structure of :py:class:`Unit` format specifications, -:py:class:`Quantity` format specifications also may contain a format spec for the -magnitude. For example, ``".8f~P"`` formats the magnitude in floating point notation -with 8 digits and the unit in the short pretty format. +The magnitude format is forwarded to the magnitude (for a unit-spec of ``H`` the +magnitude's ``_repr_html_`` is called). Let's look at some more examples: @@ -94,7 +92,7 @@ Let's look at some more examples: # additional magnitude format f"{q:.2f~#P}" # short compact pretty with 8 float digits - f"{q:#~}" # compact short default + f"{q:#~}" # short compact default Quantity Format Types --------------------- From 8e460e6071f34f7a779230af0c49b7ecdc16f953 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:04:03 +0200 Subject: [PATCH 14/22] typo --- docs/formatting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 8126592e1..b43498cfe 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -91,7 +91,7 @@ Let's look at some more examples: f"{q:P#~}" # also compact short pretty # additional magnitude format - f"{q:.2f~#P}" # short compact pretty with 8 float digits + f"{q:.2f~#P}" # short compact pretty with 2 float digits f"{q:#~}" # short compact default Quantity Format Types From 74113bedd3e2f2225f45098f3a6ff5513b53a8ff Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:06:01 +0200 Subject: [PATCH 15/22] add more details --- docs/formatting.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index b43498cfe..a0a414b9a 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -33,7 +33,7 @@ format are used instead. Unit Format Specifications -------------------------- The :py:class:`Unit` class ignores the magnitude format part, and the unit format -consists of just the type. +consists of just the format type. Let's look at some examples: @@ -52,6 +52,7 @@ Let's look at some examples: str(u) # default: default f"{u:~}" # default: short default ureg.default_format = "C" # registry default to compact + str(u) # default: compact f"{u}" # default: compact u.default_format = "P" f"{u}" # default: pretty From ae923961923e4386fa2562a98b22ba017c129982 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:10:13 +0200 Subject: [PATCH 16/22] don't specify the language --- docs/formatting.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index a0a414b9a..4a76cd8cd 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -12,7 +12,10 @@ String formatting ================= The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g. through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format -specifications `. The basic format is:: +specifications `. The basic format is: + + +.. code:: [magnitude format][modifier][unit format] From bd3abffb2a556642f02e70d85de847a35e78ecf2 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:49:27 +0200 Subject: [PATCH 17/22] upgrade sphinx --- requirements_docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements_docs.txt b/requirements_docs.txt index 23f8119fa..df568febd 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,3 +1,4 @@ +sphinx>=3 ipython matplotlib nbsphinx From 151a7e22efd8ff8e96c38cc685eb3c567c9c4892 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:55:15 +0200 Subject: [PATCH 18/22] convert back to a literal block --- docs/formatting.rst | 5 +---- requirements_docs.txt | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 4a76cd8cd..a0a414b9a 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -12,10 +12,7 @@ String formatting ================= The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g. through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format -specifications `. The basic format is: - - -.. code:: +specifications `. The basic format is:: [magnitude format][modifier][unit format] diff --git a/requirements_docs.txt b/requirements_docs.txt index df568febd..450c3ce99 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,4 +1,4 @@ -sphinx>=3 +sphinx ipython matplotlib nbsphinx From 7a7d7291e552c023324b60eb1b3f780d4e589d05 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:59:26 +0200 Subject: [PATCH 19/22] another attempt --- docs/formatting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index a0a414b9a..872857833 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -14,8 +14,10 @@ The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings ( through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format specifications `. The basic format is:: + [magnitude format][modifier][unit format] + where each part is optional and the order of these is arbitrary. In case any part (except the modifier) is omitted, the corresponding value in From 0d3e0ed2b84fa71ecff9c5184c4706f76dda5c6b Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:08:04 +0200 Subject: [PATCH 20/22] move to an extra block --- docs/formatting.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 872857833..9c207d177 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -12,12 +12,12 @@ String formatting ================= The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g. through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format -specifications `. The basic format is:: +specifications `. The basic format is: +:: [magnitude format][modifier][unit format] - where each part is optional and the order of these is arbitrary. In case any part (except the modifier) is omitted, the corresponding value in From 00c535043fdae5f7a0f8ae2df9d0c20b0b8da77b Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:11:32 +0200 Subject: [PATCH 21/22] try code-block --- docs/formatting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 9c207d177..e5f98967c 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -14,7 +14,7 @@ The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings ( through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format specifications `. The basic format is: -:: +.. code-block:: [magnitude format][modifier][unit format] From 1e86f0fdde718a4ce9e29979bce67bf42f99925a Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:15:02 +0200 Subject: [PATCH 22/22] try to set the language to none --- docs/formatting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index e5f98967c..74fb8bdd6 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -14,7 +14,7 @@ The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings ( through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format specifications `. The basic format is: -.. code-block:: +.. code-block:: none [magnitude format][modifier][unit format]