diff --git a/docs/conf.py b/docs/conf.py index 6a720be8b..67e156c11 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,7 @@ # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.coverage", diff --git a/docs/contexts.rst b/docs/contexts.rst index 9f75c9fdb..4077503fd 100644 --- a/docs/contexts.rst +++ b/docs/contexts.rst @@ -1,4 +1,3 @@ -.. _contexts: Contexts ======== diff --git a/docs/defining-quantities.rst b/docs/defining-quantities.rst new file mode 100644 index 000000000..b0126f36c --- /dev/null +++ b/docs/defining-quantities.rst @@ -0,0 +1,142 @@ +Defining Quantities +=================== + +A quantity in Pint is the product of a unit and a magnitude. + +Pint supports several different ways of defining physical quantities, including +a powerful string parsing system. These methods are largely interchangeable, +though you may **need** to use the constructor form under certain circumstances +(see :doc:`nonmult` for an example of where the constructor form is required). + +By multiplication +----------------- + +If you've read the :ref:`Tutorial`, you're already familiar with defining a +quantity by multiplying a ``Unit()`` and a scalar: + +.. doctest:: + + >>> from pint import UnitRegistry + >>> ureg = UnitRegistry() + >>> ureg.meter + + >>> 30.0 * ureg.meter + + +This works to build up complex units as well: + +.. doctest:: + + >>> 9.8 * ureg.meter / ureg.second**2 + + + +Using the constructor +--------------------- + +In some cases it is useful to define :class:`Quantity() ` +objects using it's class constructor. Using the constructor allows you to +specify the units and magnitude separately. + +We typically abbreviate that constructor as `Q_` to make it's usage less verbose: + +.. doctest:: + + >>> Q_ = ureg.Quantity + >>> Q_(1.78, ureg.meter) + + +As you can see below, the multiplication and constructor methods should produce +the same results: + +.. doctest:: + + >>> Q_(30.0, ureg.meter) == 30.0 * ureg.meter + True + >>> Q_(9.8, ureg.meter / ureg.second**2) + + + +Using string parsing +-------------------- + +Pint includes a powerful parser for detecting magnitudes and units (with or +without prefixes) in strings. Calling the ``UnitRegistry()`` directly +invokes the parsing function: + +.. doctest:: + + >>> 30.0 * ureg('meter') + + >>> ureg('30.0 meters') + + >>> ureg('3000cm').to('meters') + + +The parsing function is also available to the ``Quantity()`` constructor and +the various ``.to()`` methods: + +.. doctest:: + + >>> Q_('30.0 meters') + + >>> Q_(30.0, 'meter') + + >>> Q_('3000.0cm').to('meter') + + +Or as a standalone method on the ``UnitRegistry``: + +.. doctest:: + + >>> 2.54 * ureg.parse_expression('centimeter') + + +It is fairly good at detecting compound units: + +.. doctest:: + + >>> g = ureg('9.8 meters/second**2') + >>> g + + >>> g.to('furlongs/fortnight**2') + + +And behaves well when given dimensionless quantities, which are parsed into +their appropriate objects: + +.. doctest:: + + >>> ureg('2.54') + 2.54 + >>> type(ureg('2.54')) + + >>> Q_('2.54') + + >>> type(Q_('2.54')) + .Quantity'> + +.. note:: Pint's rule for parsing strings with a mixture of numbers and + units is that **units are treated with the same precedence as numbers**. + +For example, the units of + +.. doctest:: + + >>> Q_('3 l / 100 km') + + +may be unexpected at first but, are a consequence of applying this rule. Use +brackets to get the expected result: + +.. doctest:: + + >>> Q_('3 l / (100 km)') + + +.. note:: Since version 0.7, Pint **does not** use eval_ under the hood. + This change removes the `serious security problems`_ that the system is + exposed to when parsing information from untrusted sources. + +.. _eval: http://docs.python.org/3/library/functions.html#eval +.. _`serious security problems`: http://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html diff --git a/docs/developers_reference.rst b/docs/developers_reference.rst index b4a48891f..f2be04636 100644 --- a/docs/developers_reference.rst +++ b/docs/developers_reference.rst @@ -2,8 +2,8 @@ Developer reference =================== -Pint -==== +All Modules +=========== .. automodule:: pint :members: @@ -55,60 +55,3 @@ Pint .. automodule:: pint.util :members: - -.. automodule:: pint.testsuite.helpers - :members: - -.. automodule:: pint.testsuite.parameterized - :members: - -.. automodule:: pint.testsuite.test_babel - :members: - -.. automodule:: pint.testsuite.test_contexts - :members: - -.. automodule:: pint.testsuite.test_converters - :members: - -.. automodule:: pint.testsuite.test_definitions - :members: - -.. automodule:: pint.testsuite.test_errors - :members: - -.. automodule:: pint.testsuite.test_formatter - :members: - -.. automodule:: pint.testsuite.test_infer_base_unit - :members: - -.. automodule:: pint.testsuite.test_issues - :members: - -.. automodule:: pint.testsuite.test_measurement - :members: - -.. automodule:: pint.testsuite.test_numpy - :members: - -.. automodule:: pint.testsuite.test_pint_eval - :members: - -.. automodule:: pint.testsuite.test_pitheorem - :members: - -.. automodule:: pint.testsuite.test_quantity - :members: - -.. automodule:: pint.testsuite.test_systems - :members: - -.. automodule:: pint.testsuite.test_umath - :members: - -.. automodule:: pint.testsuite.test_unit - :members: - -.. automodule:: pint.testsuite.test_util - :members: diff --git a/docs/getting.rst b/docs/getting.rst index 09815fe8a..84239e26b 100644 --- a/docs/getting.rst +++ b/docs/getting.rst @@ -9,13 +9,19 @@ You can install it (or upgrade to the latest version) using pip_:: $ pip install -U pint -That's all! You can check that Pint is correctly installed by starting up python, and importing pint: +That's all! You can check that Pint is correctly installed by starting up python, and importing Pint: .. code-block:: python >>> import pint >>> pint.__version__ # doctest: +SKIP +Or running the test suite: + +.. code-block:: python + + >>> pint.test() + .. note:: If you have an old system installation of Python and you don't want to mess with it, you can try `Anaconda CE`_. It is a free Python distribution by Continuum Analytics that includes many scientific packages. To install pint @@ -23,18 +29,6 @@ That's all! You can check that Pint is correctly installed by starting up python $ conda install -c conda-forge pint -You can check the installation with the following command: - -.. code-block:: python - - >>> pint.test() # doctest: +SKIP - - -On Arch Linux, you can alternatively install Pint from the Arch User Repository -(AUR). The latest release is available as `python-pint`_, and packages tracking -the master branch of the GitHub repository are available as `python-pint-git`_ -and `python2-pint-git`_. - Getting the code ---------------- @@ -56,13 +50,9 @@ Once you have a copy of the source, you can embed it in your Python package, or $ python setup.py install - .. _easy_install: http://pypi.python.org/pypi/setuptools .. _Python: http://www.python.org/ .. _pip: http://www.pip-installer.org/ .. _`Anaconda CE`: https://store.continuum.io/cshop/anaconda -.. _`python-pint`: https://aur.archlinux.org/packages/python-pint/ -.. _`python-pint-git`: https://aur.archlinux.org/packages/python-pint-git/ -.. _`python2-pint-git`: https://aur.archlinux.org/packages/python2-pint-git/ .. _PyPI: https://pypi.python.org/pypi/Pint/ .. _GitHub: https://github.com/hgrecco/pint diff --git a/docs/index.rst b/docs/index.rst index 5d22dda15..5bbbd51df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,8 +17,7 @@ without changing the source code. It supports a lot of numpy mathematical operations **without monkey patching or wrapping numpy**. It has a complete test coverage. It runs in Python 3.6+ with no other -dependency. It is licensed under BSD. - +dependencies. It is licensed under a `BSD 3-clause style license`_. It is extremely easy and natural to use: @@ -39,6 +38,7 @@ and you can make good use of numpy if you want: >>> np.sum(_) +See the :ref:`Tutorial` for more help getting started. Quick Installation ------------------ @@ -57,6 +57,8 @@ or utilizing conda, with the conda-forge channel: and then simply enjoy it! +(See :ref:`Installation ` for more detail.) + Design principles ----------------- @@ -80,12 +82,12 @@ LaTeX and pretty formatting. Unit name translation is available if Babel_ is installed. **Free to choose the numerical type**: You can use any numerical type -(`fraction`, `float`, `decimal`, `numpy.ndarray`, etc). NumPy_ is not required -but supported. +(``fraction``, ``float``, ``decimal``, ``numpy.ndarray``, etc). NumPy_ is not +required, but is supported. **Awesome NumPy integration**: When you choose to use a NumPy_ ndarray, its methods and ufuncs are supported including automatic conversion of units. For example -`numpy.arccos(q)` will require a dimensionless `q` and the units of the output +``numpy.arccos(q)`` will require a dimensionless ``q`` and the units of the output quantity will be radian. **Uncertainties integration**: transparently handles calculations with @@ -98,13 +100,15 @@ points, like positions on a map or absolute temperature scales. **Dependency free**: it depends only on Python and its standard library. It interacts with other packages like numpy and uncertainties if they are installed -**Pandas integration**: Thanks to `Pandas Extension Types`_ it is now possible to use Pint with Pandas. Operations on DataFrames and between columns are units aware, providing even more convenience for users of Pandas DataFrames. For full details, see the `pint-pandas Jupyter notebook`_. +**Pandas integration**: Thanks to `Pandas Extension Types`_ it is now possible to use Pint with Pandas. +Operations on DataFrames and between columns are units aware, providing even more convenience for users +of Pandas DataFrames. For full details, see the `pint-pandas Jupyter notebook`_. When you choose to use a NumPy_ ndarray, its methods and ufuncs are supported including automatic conversion of units. For example -`numpy.arccos(q)` will require a dimensionless `q` and the units of the output -quantity will be radian. +``numpy.arccos(q)`` will require a dimensionless ``q`` and the units +of the output quantity will be radian. User Guide @@ -115,6 +119,7 @@ User Guide getting tutorial + defining-quantities numpy nonmult wrapping @@ -160,3 +165,4 @@ One last thing .. _`Babel`: http://babel.pocoo.org/ .. _`Pandas Extension Types`: https://pandas.pydata.org/pandas-docs/stable/extending.html#extension-types .. _`pint-pandas Jupyter notebook`: https://github.com/hgrecco/pint-pandas/blob/master/notebooks/pandas_support.ipynb +.. _`BSD 3-clause style license`: https://github.com/hgrecco/pint/blob/master/LICENSE diff --git a/docs/measurement.rst b/docs/measurement.rst index 88596c723..a49c8212b 100644 --- a/docs/measurement.rst +++ b/docs/measurement.rst @@ -4,7 +4,13 @@ Using Measurements ================== -Measurements are the combination of two quantities: the mean value and the error (or uncertainty). The easiest ways to generate a measurement object is from a quantity using the `plus_minus` operator. +If you have the `Uncertainties package`_ installed, you can use Pint to keep +track of measurements with specified uncertainty, and not just exact physical +quantities. + +Measurements are the combination of two quantities: the mean value and the error +(or uncertainty). The easiest ways to generate a measurement object is from a +quantity using the ``plus_minus()`` method. .. doctest:: :skipif: not_installed['uncertainties'] @@ -37,7 +43,8 @@ You can also create a Measurement object giving the relative error: >>> print(book_length) (20.0 +/- 2.0) centimeter -Measurements support the same formatting codes as Quantity. For example, to pretty print a measurement with 2 decimal positions: +Measurements support the same formatting codes as Quantity. For example, to pretty +print a measurement with 2 decimal positions: .. doctest:: :skipif: not_installed['uncertainties'] @@ -46,7 +53,8 @@ Measurements support the same formatting codes as Quantity. For example, to pret (20.00 ± 2.00) centimeter -Mathematical operations with Measurements, return new measurements following the `Propagation of uncertainty`_ rules. +Mathematical operations with Measurements, return new measurements following +the `Propagation of uncertainty`_ rules. .. doctest:: :skipif: not_installed['uncertainties'] @@ -57,7 +65,8 @@ Mathematical operations with Measurements, return new measurements following the >>> print('{:.02f}'.format(book_length + width)) (30.00 +/- 2.24) centimeter -.. note:: only linear combinations are currently supported. +.. note:: Only linear combinations are currently supported. .. _`Propagation of uncertainty`: http://en.wikipedia.org/wiki/Propagation_of_uncertainty +.. _`Uncertainties package`: https://uncertainties-python-package.readthedocs.io/en/latest/ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index d2d18e9de..e473ac4f5 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -1,62 +1,110 @@ -.. _tutorial: - Tutorial ======== -Converting Quantities ---------------------- +Follow the steps below and learn how to use Pint to track physical quantities +and perform unit conversions in Python. + +Initializing a Registry +----------------------- -Pint has the concept of Unit Registry, an object within which units are defined -and handled. You start by creating your registry: +Before using Pint, initialize a :class:`UnitRegistry() ` +object. The ``UnitRegistry`` stores the unit definitions, their relationships, +and handles conversions between units. .. doctest:: >>> from pint import UnitRegistry >>> ureg = UnitRegistry() -If no parameter is given to the constructor, the unit registry is populated -with the default list of units and prefixes. -You can now simply use the registry in the following way: +If no parameters are given to the constructor, the ``UnitRegistry`` is populated +with the `default list of units`_ and prefixes. + +Defining a Quantity +------------------- + +Once you've initialized your ``UnitRegistry``, you can define quantities easily: .. doctest:: >>> distance = 24.0 * ureg.meter + >>> distance + >>> print(distance) 24.0 meter - >>> time = 8.0 * ureg.second - >>> print(time) - 8.0 second - >>> print(repr(time)) - -In this code `distance` and `time` are physical quantity objects (`Quantity`). -Physical quantities can be queried for their magnitude, units, and -dimensionality: +As you can see, ``distance`` here is a :class:`Quantity() ` +object that represents a physical quantity. Quantities can be queried for their +magnitude, units, and dimensionality: .. doctest:: - >>> print(distance.magnitude) + >>> distance.magnitude 24.0 - >>> print(distance.units) - meter + >>> distance.units + >>> print(distance.dimensionality) [length] -and can handle mathematical operations between: +and can correctly handle many mathematical operations, including with other +:class:`Quantity() ` objects: .. doctest:: + >>> time = 8.0 * ureg.second + >>> print(time) + 8.0 second >>> speed = distance / time + >>> speed + >>> print(speed) 3.0 meter / second + >>> print(speed.dimensionality) + [length] / [time] + +Notice the built-in parser recognizes prefixed and pluralized units even though +they are not in the definition list: + +.. doctest:: + + >>> distance = 42 * ureg.kilometers + >>> print(distance) + 42 kilometer + >>> print(distance.to(ureg.meter)) + 42000.0 meter + +Pint will complain if you try to use a unit which is not in the registry: + +.. doctest:: -As unit registry knows about the relationship between different units, you can -convert quantities to the unit of choice: + >>> speed = 23 * ureg.snail_speed + Traceback (most recent call last): + ... + UndefinedUnitError: 'snail_speed' is not defined in the unit registry + +You can add your own units to the existing registry, or build your own list. +See the page on :ref:`defining` for more information on that. + +See `String parsing`_ and :doc:`defining-quantities` for more ways of defining +a ``Quantity()`` object. + +``Quantity()`` objects also work well with NumPy arrays, which you can +read about in the section on :doc:`NumPy support `. + +Converting to Different Units +----------------------------- + +As the underlying ``UnitRegistry`` knows the relationships between +different units, you can convert a ``Quantity`` to the units of your choice using +the ``to()`` method, which accepts a string or a :class:`Unit() ` object: .. doctest:: - >>> speed.to(ureg.inch / ureg.minute ) + >>> speed.to('inch/minute') + + >>> ureg.inch / ureg.minute + + >>> speed.to(ureg.inch / ureg.minute) This method returns a new object leaving the original intact as can be seen by: @@ -67,17 +115,18 @@ This method returns a new object leaving the original intact as can be seen by: 3.0 meter / second If you want to convert in-place (i.e. without creating another object), you can -use the `ito` method: +use the ``ito()`` method: .. doctest:: - >>> speed.ito(ureg.inch / ureg.minute ) + >>> speed.ito(ureg.inch / ureg.minute) >>> speed >>> print(speed) 7086.6141... inch / minute -If you ask Pint to perform an invalid conversion: +Pint will complain if you ask it to perform a conversion it doesn't know +how to do: .. doctest:: @@ -86,10 +135,15 @@ If you ask Pint to perform an invalid conversion: ... DimensionalityError: Cannot convert from 'inch / minute' ([length] / [time]) to 'joule' ([length] ** 2 * [mass] / [time] ** 2) -Sometimes, the magnitude of the quantity will be very large or very small. -The method 'to_compact' can adjust the units to make the quantity more -human-readable. +See the section on :doc:`contexts` for information about expanding Pint's +automatic conversion capabilities for your application. +Simplifying units +----------------- + +Sometimes, the magnitude of the quantity will be very large or very small. +The method ``to_compact()`` can adjust the units to make a quantity more +human-readable: .. doctest:: @@ -100,7 +154,7 @@ human-readable. >>> print(frequency.to_compact()) 193.414489032... terahertz -There are also methods 'to_base_units' and 'ito_base_units' which automatically +There are also methods ``to_base_units()`` and ``ito_base_units()`` which automatically convert to the reference units with the correct dimensionality: .. doctest:: @@ -116,7 +170,7 @@ convert to the reference units with the correct dimensionality: >>> print(height) 1.752... meter -There are also methods 'to_reduced_units' and 'ito_reduced_units' which perform +There are also methods ``to_reduced_units()`` and ``ito_reduced_units()`` which perform a simplified dimensional reduction, combining units with the same dimensionality but otherwise keeping your unit definitions intact. @@ -136,78 +190,34 @@ but otherwise keeping your unit definitions intact. 14.0 gram If you want pint to automatically perform dimensional reduction when producing -new quantities, the UnitRegistry accepts a parameter `auto_reduce_dimensions`. +new quantities, the ``UnitRegistry`` class accepts a parameter ``auto_reduce_dimensions``. Dimensional reduction can be slow, so auto-reducing is disabled by default. -In some cases it is useful to define physical quantities objects using the -class constructor: - -.. doctest:: - - >>> Q_ = ureg.Quantity - >>> Q_(1.78, ureg.meter) == 1.78 * ureg.meter - True - -(I tend to abbreviate Quantity as `Q_`) The built-in parser recognizes prefixed -and pluralized units even though they are not in the definition list: - -.. doctest:: - - >>> distance = 42 * ureg.kilometers - >>> print(distance) - 42 kilometer - >>> print(distance.to(ureg.meter)) - 42000.0 meter - -If you try to use a unit which is not in the registry: - -.. doctest:: - - >>> speed = 23 * ureg.snail_speed - Traceback (most recent call last): - ... - UndefinedUnitError: 'snail_speed' is not defined in the unit registry - -You can add your own units to the registry or build your own list. More info on -that :ref:`defining` - - String parsing -------------- -Pint can also handle units provided as strings: - -.. doctest:: - - >>> 2.54 * ureg.parse_expression('centimeter') - - -or using the registry as a callable for a short form for `parse_expression`: +Pint includes powerful string parsing for identifying magnitudes and units. In +many cases, units can be defined as strings: .. doctest:: >>> 2.54 * ureg('centimeter') -or using the `Quantity` constructor: +or using the ``Quantity`` constructor: .. doctest:: + >>> Q_ = ureg.Quantity >>> Q_(2.54, 'centimeter') - Numbers are also parsed, so you can use an expression: .. doctest:: >>> ureg('2.54 * centimeter') - -or: - -.. doctest:: - >>> Q_('2.54 * centimeter') @@ -227,48 +237,8 @@ This enables you to build a simple unit converter in 3 lines: >>> Q_(src).to(dst) -Dimensionless quantities can also be parsed into an appropriate object: - -.. doctest:: - - >>> ureg('2.54') - 2.54 - >>> type(ureg('2.54')) - - -or - -.. doctest:: - - >>> Q_('2.54') - - >>> type(Q_('2.54')) - .Quantity'> - -.. note:: Pint´s rule for parsing strings with a mixture of numbers and - units is that **units are treated with the same precedence as numbers**. - -For example, the unit of - -.. doctest:: - - >>> Q_('3 l / 100 km') - - -may be unexpected first but is a consequence of applying this rule. Use -brackets to get the expected result: - -.. doctest:: - - >>> Q_('3 l / (100 km)') - - -.. note:: Since version 0.7, Pint **does not** use eval_ under the hood. - This change removes the `serious security problems`_ that the system is - exposed to when parsing information from untrusted sources. - - -Strings containing values can be parsed using the ``ureg.parse_pattern`` function. A ``format``-like string with the units defined in it is used as the pattern: +Strings containing values can be parsed using the ``ureg.parse_pattern()`` function. +A ``format``-like string with the units defined in it is used as the pattern: .. doctest:: @@ -277,7 +247,8 @@ Strings containing values can be parsed using the ``ureg.parse_pattern`` functio >>> ureg.parse_pattern(input_string, pattern) [, ] -To search for multiple matches, set the ``many`` parameter to ``True``. The following example also demonstrates how the parser is able to find matches in amongst filler characters: +To search for multiple matches, set the ``many`` parameter to ``True``. The following +example also demonstrates how the parser is able to find matches in amongst filler characters: .. doctest:: @@ -297,7 +268,8 @@ The full power of regex can also be employed when writing patterns: *Note that the curly brackets (``{}``) are converted to a float-matching pattern by the parser.* -This function is useful for tasks such as bulk extraction of units from thousands of uniform strings or even very large texts with units dotted around in no particular pattern. +This function is useful for tasks such as bulk extraction of units from thousands +of uniform strings or even very large texts with units dotted around in no particular pattern. .. _sec-string-formatting: @@ -333,7 +305,7 @@ Pint supports float formatting for numpy arrays as well: >>> print('The array is {:+.2E~P}'.format(accel)) The array is [-1.10E+00 +1.00E-06 +1.25E+00 +1.30E+00] m/s² -Pint also supports 'f-strings'_ from python>=3.6 : +Pint also supports `f-strings`_ from python>=3.6 : .. doctest:: @@ -358,9 +330,9 @@ LaTeX representations: >>> # Pretty print >>> 'The pretty representation is {:P}'.format(accel) 'The pretty representation is 1.3 meter/second²' - >>> # Latex print - >>> 'The latex representation is {:L}'.format(accel) - 'The latex representation is 1.3\\ \\frac{\\mathrm{meter}}{\\mathrm{second}^{2}}' + >>> # LaTeX print + >>> 'The LaTeX representation is {:L}'.format(accel) + 'The LaTeX representation is 1.3\\ \\frac{\\mathrm{meter}}{\\mathrm{second}^{2}}' >>> # HTML print - good for Jupyter notebooks >>> 'The HTML representation is {:H}'.format(accel) 'The HTML representation is \\[1.3\\ meter/{second}^{2}\\]' @@ -375,22 +347,23 @@ If you want to use abbreviated unit names, prefix the specification with `~`: 'The pretty representation is 1.3 m/s²' -The same is true for latex (`L`) and HTML (`H`) specs. +The same is true for LaTeX (`L`) and HTML (`H`) specs. .. note:: The abbreviated unit is drawn from the unit registry where the 3rd item in the equivalence chain (ie 1 = 2 = **3**) will be returned when the prefix '~' is used. The 1st item in the chain is the canonical name of the unit. -The formatting specs (ie 'L', 'H', 'P') can be used with Python string 'formatting -syntax'_ for custom float representations. For example, scientific notation: +The formatting specs (ie 'L', 'H', 'P') can be used with Python string +`formatting syntax`_ for custom float representations. For example, scientific +notation: .. doctest:: >>> 'Scientific notation: {:.3e~L}'.format(accel) 'Scientific notation: 1.300\\times 10^{0}\\ \\frac{\\mathrm{m}}{\\mathrm{s}^{2}}' -Pint also supports the LaTeX siunitx package: +Pint also supports the LaTeX `siunitx` package: .. doctest:: :skipif: not_installed['uncertainties'] @@ -415,7 +388,10 @@ Additionally, you can specify a default format specification: 'The acceleration is 1.3 meter/second²' -Finally, if Babel_ is installed you can translate unit names to any language +Localizing +---------- + +If Babel_ is installed you can translate unit names to any language .. doctest:: @@ -453,7 +429,7 @@ Using Pint in your projects If you use Pint in multiple modules within your Python package, you normally want to avoid creating multiple instances of the unit registry. The best way to do this is by instantiating the registry in a single place. For -example, you can add the following code to your package `__init__.py` +example, you can add the following code to your package ``__init__.py`` .. code-block:: @@ -462,7 +438,7 @@ example, you can add the following code to your package `__init__.py` Q_ = ureg.Quantity -Then in `yourmodule.py` the code would be +Then in ``yourmodule.py`` the code would be .. code-block:: @@ -481,7 +457,10 @@ also define the registry as the application registry set_application_registry(ureg) -.. warning:: There are no global units in Pint. All units belong to a registry and you can have multiple registries instantiated at the same time. However, you are not supposed to operate between quantities that belong to different registries. Never do things like this: +.. warning:: There are no global units in Pint. All units belong to a registry and + you can have multiple registries instantiated at the same time. However, you + are not supposed to operate between quantities that belong to different registries. + Never do things like this: .. doctest:: @@ -495,8 +474,7 @@ also define the registry as the application registry False -.. _eval: http://docs.python.org/3/library/functions.html#eval -.. _`serious security problems`: http://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html +.. _`default list of units`: https://github.com/hgrecco/pint/blob/master/pint/default_en.txt .. _`Babel`: http://babel.pocoo.org/ -.. _'formatting syntax': https://docs.python.org/3/library/string.html#format-specification-mini-language -.. _'f-strings': https://www.python.org/dev/peps/pep-0498/ +.. _`formatting syntax`: https://docs.python.org/3/library/string.html#format-specification-mini-language +.. _`f-strings`: https://www.python.org/dev/peps/pep-0498/