Merge #1633staging

1633: Simplify registry subclassing r=hgrecco a=hgrecco

- [x] Closes #1631
- [x] Executed ``pre-commit run --all-files`` with no errors
- [x] The change is fully covered by automated unit tests
- [x] Documented in docs/ as appropriate
- [x] Added an entry to the CHANGES file


Co-authored-by: Hernan <hernan.grecco@gmail.com>
Co-authored-by: Hernan Grecco <hernan.grecco@gmail.com>

2 files changed, 84 insertions, 0 deletions

diff --git a/docs/advanced_guides.rst b/docs/advanced_guides.rst
index cc2c495..580ddb7 100644
--- a/docs/advanced_guides.rst
+++ b/docs/advanced_guides.rst
@@ -12,3 +12,4 @@ Advanced Guides
     user/measurement
     user/pitheorem
     user/currencies
+    user/custom-registry-class
diff --git a/docs/user/custom-registry-class.rst b/docs/user/custom-registry-class.rst
new file mode 100644
index 0000000..31f3d76
--- /dev/null
+++ b/docs/user/custom-registry-class.rst
@@ -0,0 +1,83 @@
+.. _custom_registry_class:
+
+Custom registry class
+=====================
+
+Pay as you go
+-------------
+
+Pint registry functionality is divided into facets. The default
+UnitRegistry inherits from all of them, providing a full fledged
+and feature rich registry. However, in certain cases you might want
+to have a simpler and light registry. Just pick what you need
+and create your own.
+
+- FormattingRegistry: adds the capability to format quantities and units into string.
+- SystemRegistry: adds the capability to work with system of units.
+- GroupRegistry: adds the capability to group units.
+- MeasurementRegistry: adds the capability to handle measurements (quantities with uncertainties).
+- NumpyRegistry: adds the capability to interoperate with NumPy.
+- DaskRegistry: adds the capability to interoperate with Dask.
+- ContextRegistry: the capability to contexts: predefined conversions
+  between incompatible dimensions.
+- NonMultiplicativeRegistry: adds the capability to handle nonmultiplicative units (offset, logarithmic).
+- PlainRegistry: base implementation for registry, units and quantities.
+
+The only required one is `PlainRegistry`, the rest are completely
+optional.
+
+For example:
+
+.. doctest::
+
+    >>> import pint
+    >>> class MyRegistry(pint.facets.NonMultiplicativeRegistry, pint.facets.PlainRegistry):
+    ...     pass
+
+
+Subclassing
+-----------
+
+If you want to add the default registry class some specific functionality,
+you can subclass it:
+
+.. doctest::
+
+    >>> import pint
+    >>> class MyRegistry(pint.UnitRegistry):
+    ...
+    ...     def my_specific_function(self):
+    ...         """Do something
+    ...         """
+
+
+If you want to create your own Quantity class, you must tell
+your registry about it:
+
+.. doctest::
+
+    >>> import pint
+    >>> class MyQuantity:
+    ...
+    ...     # Notice that subclassing pint.Quantity
+    ...     # is not necessary.
+    ...     # Pint will inspect the Registry class and create
+    ...     # a Quantity class that contains all the
+    ...     # required parents.
+    ...
+    ...     def to_my_desired_format(self):
+    ...         """Do something else
+    ...         """
+    >>>
+    >>> class MyRegistry(pint.UnitRegistry):
+    ...
+    ...     _quantity_class = MyQuantity
+    ...
+    ...     # The same you can be done with
+    ...     # _unit_class
+    ...     # _measurement_class
+
+
+While these examples demonstrate how to add functionality to the default
+registry class, you can actually subclass just the PlainRegistry or any
+combination of facets.