Improved documentation about extending the registry

3 files changed, 58 insertions, 26 deletions

diff --git a/CHANGES b/CHANGES
index 49fbfd4..9037b47 100644
--- a/CHANGES
+++ b/CHANGES
@@ -9,6 +9,9 @@ Pint Changelog
 - Improved typing experience.
 - Migrated fully to pyproject.toml.
 - Migrated to ruff.
+- In order to make static typing possible as required by mypy
+  and similar tools, the way to subclass the registry has been
+  changed.
 
 
 0.21 (2023-05-01)
diff --git a/docs/advanced/custom-registry-class.rst b/docs/advanced/custom-registry-class.rst
index 31f3d76..856349c 100644
--- a/docs/advanced/custom-registry-class.rst
+++ b/docs/advanced/custom-registry-class.rst
@@ -9,7 +9,7 @@ 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
+to have a simpler and lighter registry. Just pick what you need
 and create your own.
 
 - FormattingRegistry: adds the capability to format quantities and units into string.
@@ -31,15 +31,16 @@ For example:
 .. doctest::
 
     >>> import pint
-    >>> class MyRegistry(pint.facets.NonMultiplicativeRegistry, pint.facets.PlainRegistry):
+    >>> class MyRegistry(pint.facets.NonMultiplicativeRegistry):
     ...     pass
 
 
-Subclassing
------------
+.. note::
+   `NonMultiplicativeRegistry` is a subclass from `PlainRegistry`, and therefore
+   it is not required to add it explicitly to `MyRegistry` bases.
 
-If you want to add the default registry class some specific functionality,
-you can subclass it:
+
+You can add some specific functionality to your new registry.
 
 .. doctest::
 
@@ -51,13 +52,20 @@ you can subclass it:
     ...         """
 
 
-If you want to create your own Quantity class, you must tell
-your registry about it:
+
+Custom Quantity and Unit class
+------------------------------
+
+You can also create your own Quantity and Unit class, you must derive
+from Quantity (or Unit) and tell your registry about it.
+
+For example, if you want to create a new `UnitRegistry` subclass you
+need to  derive the Quantity and Unit classes from it.
 
 .. doctest::
 
     >>> import pint
-    >>> class MyQuantity:
+    >>> class MyQuantity(pint.UnitRegistry.Quantity):
     ...
     ...     # Notice that subclassing pint.Quantity
     ...     # is not necessary.
@@ -68,16 +76,32 @@ your registry about it:
     ...     def to_my_desired_format(self):
     ...         """Do something else
     ...         """
-    >>>
-    >>> class MyRegistry(pint.UnitRegistry):
     ...
-    ...     _quantity_class = MyQuantity
+    >>> class MyUnit(pint.UnitRegistry.Unit):
     ...
-    ...     # The same you can be done with
-    ...     # _unit_class
-    ...     # _measurement_class
+    ...     # 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
+    ...         """
+
 
+Then, you need to create a custom registry but deriving from `GenericUnitRegistry` so you
+can specify the types of
+
+.. doctest::
+    >>> # from typing_extensions import TypeAlias # Python 3.9
+    >>> from typing import TypeAlias # Python 3.10+
+    >>> class MyRegistry(pint.GenericUnitRegistry[MyQuantity, pint.Unit]):
+    ...
+    ...     Quantity: TypeAlias = MyQuantity
+    ...     Unit: TypeAlias = MyUnit
+    ...
 
 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.
+registry class, you can actually subclass just the `PlainRegistry`, and
+`GenericPlainRegistry`.
diff --git a/pint/registry.py b/pint/registry.py
index fc20459..e978e36 100644
--- a/pint/registry.py
+++ b/pint/registry.py
@@ -53,16 +53,21 @@ class Unit(
     pass
 
 
-class UnitRegistry(
-    facets.GenericSystemRegistry[Quantity, Unit],
-    facets.GenericContextRegistry[Quantity, Unit],
-    facets.GenericDaskRegistry[Quantity, Unit],
-    facets.GenericNumpyRegistry[Quantity, Unit],
-    facets.GenericMeasurementRegistry[Quantity, Unit],
-    facets.GenericFormattingRegistry[Quantity, Unit],
-    facets.GenericNonMultiplicativeRegistry[Quantity, Unit],
-    facets.GenericPlainRegistry[Quantity, Unit],
+class GenericUnitRegistry(
+    Generic[facets.QuantityT, facets.UnitT],
+    facets.GenericSystemRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericContextRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericDaskRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericNumpyRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericMeasurementRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericFormattingRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericNonMultiplicativeRegistry[facets.QuantityT, facets.UnitT],
+    facets.GenericPlainRegistry[facets.QuantityT, facets.UnitT],
 ):
+    pass
+
+
+class UnitRegistry(GenericUnitRegistry[Quantity, Unit]):
     """The unit registry stores the definitions and relationships between units.
 
     Parameters