From 6175d5f38b0381ccbf3ede2d0de9df0a432baaf3 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:51:03 +0200 Subject: 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 67e156c..47d8886 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,8 @@ extensions = [ "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 0000000..85c26f2 --- /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 8268585..108b43e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,6 +120,7 @@ User Guide getting tutorial defining-quantities + formatting numpy nonmult log_units -- cgit v1.2.1 From ba75cb96de4d82c8723eb227a44b4fa365e1f60c Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:55:21 +0200 Subject: 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 85c26f2..99a4a3e 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``) ``#`` -======== =============== ============================ +======== =================================================== ============================= -- cgit v1.2.1 From b8dbc4ebdb315edb1834fd1c36f3f028378e28bc Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 12:56:51 +0200 Subject: add the ipython dependency --- requirements_docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements_docs.txt b/requirements_docs.txt index c698538..23f8119 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 -- cgit v1.2.1 From f73d9c7641c9cc0fcbc57e3e1ee9fa351f00b822 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 21 Aug 2021 18:17:51 +0200 Subject: enable napoleon type preprocessing --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 47d8886..03a2b83 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,6 +111,10 @@ pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] +# -- Options for extensions ---------------------------------------------------- +# napoleon +napoleon_preprocess_types = True + # -- Options for HTML output --------------------------------------------------- -- cgit v1.2.1 From ede160a895bf7c632fccd6af47612507f8ede5ef Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 11:56:14 +0200 Subject: 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 99a4a3e..50b5011 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}"``) +======== =================================================== ================================ -- cgit v1.2.1 From 4b3bd493eda29d5e8dfae18e7c865c742af37ac8 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 11:59:01 +0200 Subject: 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 50b5011..12ac9ce 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 --------- -- cgit v1.2.1 From b273758106984ccf9bc502bafc1ad1a34024068d Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:06:33 +0200 Subject: 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 12ac9ce..1d1bc91 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 -- cgit v1.2.1 From 2ed6ef60e704e7707adaaf0925985b6747011fec Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:07:00 +0200 Subject: 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 1d1bc91..743506f 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 --------- ======== =================================================== ================================ -- cgit v1.2.1 From 3f6771fc8c6ec5bd6516b60496ecc469b37f016b Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:08:53 +0200 Subject: 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 03a2b83..2441af9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -327,7 +327,13 @@ epub_copyright = copyright # 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 ----------------------------------------------------- -- cgit v1.2.1 From 61a4976cdd07ad3a18d6c120e66a878b7fcf99b8 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:28:41 +0200 Subject: wording --- docs/formatting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index 743506f..00d516c 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 -- cgit v1.2.1 From e623e7e110e838d5f36b72ce3d7ea628fa6d2883 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 22 Aug 2021 12:30:34 +0200 Subject: update CHANGES --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index 477aa09..2899c0c 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 -- cgit v1.2.1 From 3eb1bd89b4b6b76818adec7f0fd99ef6b4219e14 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 10:58:46 +0200 Subject: 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 00d516c..9a479ba 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 -- cgit v1.2.1 From db2edea587f5489256b36dc67ee3202d673ad4e1 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 11:02:37 +0200 Subject: 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 9a479ba..8126592 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 --------------------- -- cgit v1.2.1 From 8e460e6071f34f7a779230af0c49b7ecdc16f953 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:04:03 +0200 Subject: typo --- docs/formatting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatting.rst b/docs/formatting.rst index 8126592..b43498c 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 -- cgit v1.2.1 From 74113bedd3e2f2225f45098f3a6ff5513b53a8ff Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:06:01 +0200 Subject: 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 b43498c..a0a414b 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 -- cgit v1.2.1 From ae923961923e4386fa2562a98b22ba017c129982 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 30 Aug 2021 12:10:13 +0200 Subject: 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 a0a414b..4a76cd8 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] -- cgit v1.2.1 From bd3abffb2a556642f02e70d85de847a35e78ecf2 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:49:27 +0200 Subject: upgrade sphinx --- requirements_docs.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements_docs.txt b/requirements_docs.txt index 23f8119..df568fe 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,3 +1,4 @@ +sphinx>=3 ipython matplotlib nbsphinx -- cgit v1.2.1 From 151a7e22efd8ff8e96c38cc685eb3c567c9c4892 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:55:15 +0200 Subject: 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 4a76cd8..a0a414b 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 df568fe..450c3ce 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,4 +1,4 @@ -sphinx>=3 +sphinx ipython matplotlib nbsphinx -- cgit v1.2.1 From 7a7d7291e552c023324b60eb1b3f780d4e589d05 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 22:59:26 +0200 Subject: another attempt --- docs/formatting.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/formatting.rst b/docs/formatting.rst index a0a414b..8728578 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 -- cgit v1.2.1 From 0d3e0ed2b84fa71ecff9c5184c4706f76dda5c6b Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:08:04 +0200 Subject: 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 8728578..9c207d1 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 -- cgit v1.2.1 From 00c535043fdae5f7a0f8ae2df9d0c20b0b8da77b Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:11:32 +0200 Subject: 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 9c207d1..e5f9896 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] -- cgit v1.2.1 From 1e86f0fdde718a4ce9e29979bce67bf42f99925a Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 3 Sep 2021 23:15:02 +0200 Subject: 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 e5f9896..74fb8bd 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] -- cgit v1.2.1