add transparent_preferences

Author: Ken Kundert

doc/releases.rst

@@ -12,6 +12,9 @@ Latest development release
 - Add spacer keyword argument to :meth:`Quantity.render`,
   :meth:`Quantity.fixed` and :meth:`Quantity.binary`.
 - Add support for scaling with binary scale factors.
+- Add USD and bps unit conversions
+- Add support # modifier to f & g formats
+- Add *transparent_preferences* :class:`Quantity` attribute.
 
 
 2.20 (2024-04-27)

doc/user.rst

@@ -1468,6 +1468,41 @@ of 'K' as a scale factor to avoid confusion with Kelvin units.
     5.3 kK
     3.18 K
 
+The first time a subclass is used to create a *Quantity* subclass object the 
+preferences from the parent class are copied into the subclass.  After that 
+point, any changes made to the preferences of the parent class no longer affect 
+the subclass.  However, this behavior can be altered by adding the 
+*transparent_preferences* attribute to the subclass definition:
+
+.. code-block:: python
+
+    >>> class Decibels(Quantity):
+    ...     units = 'dB'
+    ...     prec=1
+
+    >>> gain = Decibels(-40)
+
+    >>> with Quantity.prefs(minus=Quantity.minus_sign):
+    ...     print(gain)
+    -40 dB
+
+    >>> class Decibels(Quantity):
+    ...     units = 'dB'
+    ...     prec=1
+    ...     transparent_preferences = True
+
+    >>> gain = Decibels(-40)
+
+    >>> with Quantity.prefs(minus=Quantity.minus_sign):
+    ...     print(gain)
+    −40 dB
+
+It is a bit subtle, but if you look carefully at the minus sign in the second 
+case, you can see that it looks a little longer.  That is because the normal 
+hyphen was replaced by the unicode minus sign.  That did not happen in the first 
+case because *Decibels* was disconnected from any changes to *Quantity*'s 
+preferences.
+
 
 .. _scaling with subclasses:
 

pyproject.toml

@@ -40,7 +40,7 @@ requires = ["flit_core >=2,<4"]
 build-backend = "flit_core.buildapi"
 
 [tool.ruff]
-exclude = [".tox", "doc", "tests", "Diffs"]
+exclude = [".tox", "doc", "tests", ".diffs"]
 
 [tool.ruff.lint]
 select = ["F"]

quantiphy/quantiphy.py

@@ -658,35 +658,54 @@ class Quantity(float):
 
     # preferences {{{2
     _initialized = False
+    transparent_preferences = False
+        # if set true, subclasses will use current preferences from the parent
+        # class, even those that have changed since the subclass was created.
 
     # initialize preferences {{{3
     @classmethod
     def _initialize_preferences(cls):
-        if cls._initialized == id(cls):
-            return
-        cls.reset_prefs()
+        if cls._initialized != id(cls):
+            cls.reset_prefs()
 
     # reset preferences {{{3
     @classmethod
-    def reset_prefs(cls):
+    def reset_prefs(cls, transparent=None):
         """Reset preferences
 
+        :arg bool transparent:
+            If true this class inherits current preferences from the parent
+            classes.  In false, the parents preferences are copied into this
+            class the first time it is used, and any changes made to the parents
+            preferences after first use are ignored.  The default is false.
+
         Resets all preferences to the current preferences of the parent class.
         If there is no parent class, they are reset to their defaults.
         """
+        if transparent is None:
+            transparent = cls.transparent_preferences
+
         cls._initialized = id(cls)
         if cls == Quantity:
+            # this is the base class
             prefs = DEFAULTS
+            transparent = False
         else:
+            # this is a subclass
             parent = cls.__mro__[1]
                 # for some reason I cannot get super to work right
             prefs = parent._preferences
-        # copy dict so any changes made to parent's preferences do not affect us
-        prefs = dict(prefs)
+
+        if not transparent:
+            # copy dict so subsequent changes made to parent's preferences do not affect us
+            prefs = dict(prefs)
+
+        cls.transparent_preferences = transparent
+
         cls._preferences = ChainMap({}, prefs)
             # use chain to support use of contexts
             # put empty map in as first so user never accidentally deletes or
-            # changes one of the initial preferences
+            # modifies one of the initial preferences
 
     # set preferences {{{3
     @classmethod
@@ -1139,6 +1158,7 @@ def get_pref(cls, name):
 
         """
         cls._initialize_preferences()
+
         try:
             return getattr(cls, name, cls._preferences[name])
         except KeyError:
@@ -1154,11 +1174,15 @@ def __init__(self, cls, kwargs):
         def __enter__(self):
             cls = self.cls
             cls._initialize_preferences()
-            cls._preferences = cls._preferences.new_child()
+            cls._preferences.maps.insert(0, {})
+                # do not use ChainMap.new_child() as that creates a new ChainMap,
+                # orphaning the original, which could be being used by a subclass
             cls.set_prefs(**self.kwargs)
 
         def __exit__(self, *args):
-            self.cls._preferences = self.cls._preferences.parents
+            self.cls._preferences.maps.pop(0)
+                # do not use ChainMap.parents as that creates a new ChainMap,
+                # orphaning the original, which could be being used by a subclass
 
     # now, return the context manager
     @classmethod

tests/test_doctests.py

@@ -33,7 +33,7 @@ def test_manual():
     Quantity.reset_prefs()
     expected_test_count = {
         '../doc/index.rst': 31,
-        '../doc/user.rst': 458,
+        '../doc/user.rst': 464,
         '../doc/api.rst': 0,
         '../doc/examples.rst': 42,
         '../doc/accessories.rst': 12,

tests/test_format.py

@@ -54,6 +54,7 @@ def test_format():
     assert exception.value.args[0] == "Unknown format code 'x' for object of type 'float'"
 
 def test_full_format():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
     Quantity.set_prefs(prec='full')
     q = Quantity('f = 1420.405751786 MHz — frequency of hydrogen line')
@@ -121,6 +122,7 @@ def test_full_format():
 
 
 def test_width():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
     Quantity.set_prefs(prec='full')
     q=Quantity('f = 1420.405751786 MHz -- frequency of hydrogen line')
@@ -154,6 +156,7 @@ def test_width():
     assert '{:#25.0p}'.format(q) == '           1420405752. Hz'
 
 def test_currency():
+    Quantity.reset_prefs()
     Quantity.set_prefs(
         spacer = None,
         show_label = None,
@@ -197,6 +200,7 @@ def test_currency():
     assert float(q) == 2e-9
 
 def test_exceptional():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
     Quantity.set_prefs(prec='full')
     q=Quantity('light = inf Hz -- a high frequency')
@@ -223,6 +227,7 @@ def test_exceptional():
     assert '{:,.2P}'.format(q) == 'light = inf Hz'
 
 def test_scaled_format():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
     Quantity.set_prefs(prec=None)
     q=Quantity('Tboil = 100 °C -- boiling point of water')
@@ -255,6 +260,7 @@ def test_scaled_format():
     assert '{:#,.2P°F}'.format(q) == 'Tboil = 212.00 °F'
 
 def test_number_fmt():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
     Quantity.set_prefs(prec=None)
     with Quantity.prefs(number_fmt='{whole:>3s}{frac:<4s} {units:<2s}'):
@@ -331,6 +337,7 @@ def fmt_num(whole, frac, units):
         assert '<{:s}>'.format(Quantity('123,4 mm')) == '<123,4   mm>'
 
 def test_alignment():
+    Quantity.reset_prefs()
     assert '<{:<16s}>'.format(Quantity('h')) == '<662.61e-36 J-s  >'
     assert '<{:^16s}>'.format(Quantity('h')) == '< 662.61e-36 J-s >'
     assert '<{:>16s}>'.format(Quantity('h')) == '<  662.61e-36 J-s>'
@@ -339,6 +346,7 @@ def test_alignment():
     assert '<{:>17s}>'.format(Quantity('h')) == '<   662.61e-36 J-s>'
 
 def test_format_method():
+    Quantity.reset_prefs()
     Quantity.set_prefs(
         spacer = None,
         show_label = None,
@@ -414,6 +422,7 @@ def test_format_method():
     assert q.format('#,P') == 'f = 1,420,405,751.7860 Hz'
 
 def test_render():
+    Quantity.reset_prefs()
     Quantity.set_prefs(
         spacer = None,
         show_label = None,
@@ -484,6 +493,7 @@ def test_render():
     assert q.render(prec=4, strip_zeros=True, strip_radix=True) == '$123.45'
 
 def test_sign():
+    Quantity.reset_prefs()
     Quantity.set_prefs(spacer=None, show_label=None, label_fmt=None, label_fmt_full=None, show_desc=False)
 
     # Positive numbers
@@ -735,6 +745,8 @@ def test_sign():
         assert '{:p}'.format(q) == '−inf Hz'
 
 def test_radix_comma_output():
+    Quantity.reset_prefs()
+
     with Quantity.prefs(
         spacer = None,
         show_label = None,
@@ -777,6 +789,7 @@ def test_radix_comma_output():
         assert '{:,.2P}'.format(q) == 'c = 299.792.458 m/s'
 
 def test_plus_minus():
+    Quantity.reset_prefs()
     with Quantity.prefs(
         spacer = None,
         show_label = None,
@@ -814,6 +827,7 @@ def test_plus_minus():
         assert qmm.render(form='sia') == '−1 us'
 
 def test_radix_comma_input():
+    Quantity.reset_prefs()
     with Quantity.prefs(
         spacer = None,
         show_label = None,
@@ -851,6 +865,7 @@ def test_radix_comma_input():
         assert Quantity('$1.00e8').render() == '$100M'
 
 def test_radix_comma_exception():
+    Quantity.reset_prefs()
     with pytest.raises(ValueError) as exception:
         with Quantity.prefs(
             radix = ',',
@@ -875,6 +890,7 @@ def test_radix_comma_exception():
 
 
 def test_output_sf():
+    Quantity.reset_prefs()
     with Quantity.prefs(output_sf = Quantity.all_sf):
         q=Quantity('c')
         assert f"{Quantity(1e35, 'Hz')}" == '100e33 Hz'