quantiphy 2.20__tar.gz → 2.22__tar.gz

quantiphy-2.22/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016-2026 Kenneth S. Kundert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{quantiphy-2.20 → quantiphy-2.22}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: quantiphy
-Version: 2.20
+Version: 2.22
 Summary: physical quantities (numbers with units)
 Keywords: quantities,physical quantity,units,SI scale factors,engineering notation,mks,cgs
 Author: Ken Kundert
@@ -16,6 +16,7 @@ Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Utilities
 Classifier: Topic :: Scientific/Engineering
+License-File: LICENSE
 Project-URL: changelog, https://github.com/KenKundert/quantiphy/blob/master/doc/releases.rst
 Project-URL: documentation, https://quantiphy.readthedocs.io
 Project-URL: homepage, https://quantiphy.readthedocs.io
@@ -27,8 +28,8 @@ QuantiPhy — Physical Quantities
 |downloads| |build status| |coverage| |rtd status| |pypi version| |anaconda version| |python version|
 
 | Author: Ken Kundert
-| Version: 2.20
-| Released: 2024-04-27
+| Version: 2.22
+| Released: 2026-06-27
 |
 
 
@@ -102,7 +103,7 @@ Quick Start
 You can find the documentation on `ReadTheDocs
 <https://quantiphy.readthedocs.io>`_.  Install with::
 
-   pip3 install --user quantiphy
+   pip3 install quantiphy
 
 Requires Python 3.6 or newer.  If you using an earlier version of Python,
 install version 2.10 of *QuantiPhy*.

{quantiphy-2.20 → quantiphy-2.22}/README.rst

@@ -4,8 +4,8 @@ QuantiPhy — Physical Quantities
 |downloads| |build status| |coverage| |rtd status| |pypi version| |anaconda version| |python version|
 
 | Author: Ken Kundert
-| Version: 2.20
-| Released: 2024-04-27
+| Version: 2.22
+| Released: 2026-06-27
 |
 
 
@@ -79,7 +79,7 @@ Quick Start
 You can find the documentation on `ReadTheDocs
 <https://quantiphy.readthedocs.io>`_.  Install with::
 
-   pip3 install --user quantiphy
+   pip3 install quantiphy
 
 Requires Python 3.6 or newer.  If you using an earlier version of Python,
 install version 2.10 of *QuantiPhy*.

{quantiphy-2.20 → quantiphy-2.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantiphy"
-version = "2.20"
+version = "2.22"
 description = "physical quantities (numbers with units)"
 readme = "README.rst"
 keywords = [
@@ -38,3 +38,13 @@ changelog = "https://github.com/KenKundert/quantiphy/blob/master/doc/releases.rs
 [build-system]
 requires = ["flit_core >=2,<4"]
 build-backend = "flit_core.buildapi"
+
+[tool.ruff]
+exclude = [".tox", "doc", "tests", ".diffs"]
+
+[tool.ruff.lint]
+select = ["F"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"quantiphy/__init__.py" = ["F401"]  # imported but unused

{quantiphy-2.20 → quantiphy-2.22}/quantiphy/quantiphy.py

@@ -22,7 +22,7 @@ Documentation can be found at https://quantiphy.readthedocs.io.
 """
 
 # MIT License {{{1
-# Copyright (C) 2016-2024 Kenneth S. Kundert
+# Copyright (C) 2016-2026 Kenneth S. Kundert
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -73,21 +73,29 @@ def _scale(scale, unscaled):
     if isinstance(scale, str):
         scaled = UnitConversion._convert_units(scale, unscaled.units, unscaled)
         to_units = scale
-    else:
-        # otherwise, it might be a function
+        return scaled, to_units
+
+    if callable(scale):
         try:
-            scaled, to_units = scale(unscaled, unscaled.units)
-                # passing units as second argument is redundant, deprecated
-        except TypeError:
-            # otherwise, assume it is a scale factor
+            scaled, to_units = scale(unscaled)
+                # do not pass units as second argument, this is the new style
+        except TypeError as e:
             try:
-                # might be a tuple containing scale factor and units
-                multiplier, to_units = scale
-            except TypeError:
-                # otherwise, assume it is just a scale factor
-                multiplier = scale
-                to_units = unscaled.units
-            scaled = multiplier * unscaled
+                scaled, to_units = scale(unscaled, unscaled.units)
+                    # passing units as second argument is redundant, deprecated
+            except TypeError:  # pragma: no cover
+                raise e
+        return scaled, to_units
+
+    # otherwise, assume it is a scale factor
+    try:
+        # might be a tuple containing scale factor and units
+        multiplier, to_units = scale
+    except TypeError:
+        # otherwise, assume it is just a scale factor
+        multiplier = scale
+        to_units = unscaled.units
+    scaled = multiplier * unscaled
     return scaled, to_units
 
 
@@ -367,8 +375,8 @@ def add_constant(value, alias=None, unit_systems=None):
 
 
 # Globals {{{1
-__version__ = '2.20'
-__released__ = '2024-04-27'
+__version__ = '2.22'
+__released__ = '2026-06-27'
 
 # These mappings are only used when reading numbers
 # The key for these mappings must be a single character
@@ -418,18 +426,26 @@ BINARY_MAPPINGS = {
 # These mappings are only used when writing numbers
 BIG_SCALE_FACTORS = 'kMGTPEZYRQ'
     # These must be given in order, one for every three decades.
-    # Use k rather than K, because K looks like a temperature when used alone.
+    # Use k rather than K because K looks like a temperature when used alone.
 
 SMALL_SCALE_FACTORS = 'munpfazyrq'
     # These must be given in order, one for every three decades.
 
-# Supported currency symbols (these go on left side of number)
-CURRENCY_SYMBOLS = '$€¥£₩₺₽₹Ƀ₿Ξ'
+# Supported currency symbols (these precede the number)
+CURRENCY_SYMBOLS = '$€¥£₩₺₽₹Ƀ₿฿Ξ'
+
+# Units that abut the number.
+# % is controversial, NIST and ISO say that a space should be used to separate
+# the percent sign from a number, but the Chicago Manual of Style says the
+# opposite.
+TIGHT_UNITS = '''°'"′″'''
+    # The code is written assuming that TIGHT_UNITS includes only single
+    # character symbols, though the user can add multi-character tight units.
 
 # Unit symbols that are not simple letters.
 # Do not include % as it will be picked up when converting text to numbers,
 # which is generally not desired (you would end up converting 0.001% to 1m%).
-UNIT_SYMBOLS = '°ÅΩƱΩ℧¢$€¥£₩₺₽₹Ƀ₿șΞΔ'
+UNIT_SYMBOLS = """ÅΩƱΩ℧Δ¢ș""" + CURRENCY_SYMBOLS + TIGHT_UNITS
 
 # Regular expression for recognizing and decomposing string .format method codes
 FORMAT_SPEC = re.compile(r'''\A
@@ -483,6 +499,8 @@ DEFAULTS = dict(
     output_sf = 'TGMkmunpfa',
     plus = '+',
     prec = 4,
+    preferred_quantities = {},
+    _preferred_quantities = {},  # transposed version of preferred_quantities
     preferred_units = {},
     _preferred_units = {},  # transposed version of preferred_units
     radix = '.',
@@ -494,7 +512,7 @@ DEFAULTS = dict(
     spacer = ' ',
     strip_radix = True,
     strip_zeros = True,
-    tight_units = ''' % ° ' " ′ ″ '''.split(),
+    tight_units = list(TIGHT_UNITS),
     unity_sf = '',
 )
 
@@ -642,35 +660,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
@@ -926,12 +963,20 @@ class Quantity(float):
             *QuantiPhy* currently does not add leading plus signs to either
             mantissa or exponent, so this setting is ignored.
 
-        :arg int prec:
-            Default precision  in digits where 0 corresponds to 1 digit.  Must
-            be nonnegative.  This precision is used when the full precision is
-            not required. Default is 4.
+        :arg prec:
+            Default precision in digits where 0 corresponds to 1 digit.  Must
+            be a nonnegative integer or "full".  This precision is used when the
+            full precision is not required. Default is 4.
         :type prec: int or str
 
+        :arg dict preferred_quantities:
+            A dictionary that is used when looking up the preferred quantity when
+            instantiating.  For example, if *preferred_quantities* contains the entry:
+            {Decibels: “dB dBV dBA dBm dBc”} where *Decibels* is a subclass of
+            *Quantity*, then when instantiating a quantity with units “dB”, “dBV”,
+            “dBA”, “dBm”, or “dBc”, the quantity returned would have *Decibels*
+            as its class.
+
         :arg dict preferred_units:
             A dictionary that is used when looking up the preferred units when
             rendering.  For example, if *preferred_units* contains the entry:
@@ -967,15 +1012,19 @@ class Quantity(float):
 
         :type show_label: 'f', 'a', or bool
 
+        :arg bool show_units:
+            Whether the units should be included when rendering a quantity to a
+            string.  By default *show_units* is True.
+
         :arg str spacer:
             The spacer text to be inserted in a string between the numeric value
             and the scale factor when units are present.  Is generally specified
             to be '' or ' '; use the latter if you prefer a space between the
             number and the units. Generally using ' ' makes numbers easier to
             read, particularly with complex units, and using '' is easier to
-            parse.  You could also use a Unicode non-breaking space ' '. For
-            your convenience, you can access a non-breaking space using
-            :attr:`Quantity.non_breaking_space`,
+            parse.  Use of a non-breaking space is preferred when embedding
+            numbers in prose.  For your convenience, you can access a
+            non-breaking spaces using :attr:`Quantity.non_breaking_space`,
             :attr:`Quantity.narrow_non_breaking_space`, or
             :attr:`Quantity.thin_space`.
 
@@ -1053,13 +1102,21 @@ class Quantity(float):
         if isinstance(kwargs.get('known_units'), str):
             kwargs['known_units'] = kwargs['known_units'].split()
 
+        # split preferred_quantities
+        if 'preferred_quantities' in kwargs:
+            kwargs['_preferred_quantities'] = {
+                unit : quantity
+                for quantity, units in kwargs['preferred_quantities'].items()
+                for unit in units.split()
+            }
+
         # split preferred_units
         if 'preferred_units' in kwargs:
-            _preferred_units = {}
-            for preferred_unit, undesired in kwargs['preferred_units'].items():
-                for each in undesired.split():
-                    _preferred_units[each] = preferred_unit
-            kwargs['_preferred_units'] = _preferred_units
+            kwargs['_preferred_units'] = {
+                unit : preferred
+                for preferred, units in kwargs['preferred_units'].items()
+                for unit in units.split()
+            }
 
         # check for unknown output scale factors
         if kwargs.get('output_sf'):
@@ -1119,6 +1176,7 @@ class Quantity(float):
 
         """
         cls._initialize_preferences()
+
         try:
             return getattr(cls, name, cls._preferences[name])
         except KeyError:
@@ -1134,11 +1192,15 @@ class Quantity(float):
         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
@@ -1518,7 +1580,7 @@ class Quantity(float):
             )
         )
         cls.embedded_e_notation_only = re.compile(
-            '{left_delimit}{sign}{mantissa}{exponent}{space}{smpl_units}{right_delimit}'.format(
+            r'{left_delimit}{sign}{mantissa}{exponent}{space}{smpl_units}\b'.format(
                 **locals()
             )
         )
@@ -1671,7 +1733,13 @@ class Quantity(float):
 
         # create the underlying data structure and add attributes {{{3
         try:
-            self = float.__new__(cls, number)
+            preferred_quantities = cls._preferences["_preferred_quantities"]
+            preferred_quantity = preferred_quantities[units]
+            assert issubclass(preferred_quantity, cls)
+        except (AttributeError, KeyError):
+            preferred_quantity = cls
+        try:
+            self = float.__new__(preferred_quantity, number)
         except TypeError:
             raise InvalidNumber(number)
         if units:
@@ -1783,11 +1851,12 @@ class Quantity(float):
               are taken to the be desired units and the behavior is the same as
               if a string were given, except that *cls* defaults to the given
               subclass.
+        :type scale: real, pair, function, string, or quantity
+
         :arg class cls:
             Class to use for return value. If not given, the class of self is
             used it the units do not change, in which case :class:`Quantity` is
             used.
-        :type scale: real, pair, function, string, or quantity
 
         :raises UnknownConversion(QuantiPhyError, KeyError):
             A unit conversion was requested and there is no corresponding unit
@@ -1864,8 +1933,8 @@ class Quantity(float):
     def render(
         self,
         *,
-        form=None, show_units=None, prec=None, show_label=None,
-        strip_zeros=None, strip_radix=None, scale=None, negligible=None
+        form=None, show_units=None, prec=None, show_label=None, strip_zeros=None,
+        strip_radix=None, spacer=None, scale=None, negligible=None
     ):
         # description {{{3
         """Convert quantity to a string.
@@ -1980,6 +2049,7 @@ class Quantity(float):
         show_units = self.show_units if show_units is None else show_units
         strip_zeros = self.strip_zeros if strip_zeros is None else strip_zeros
         strip_radix = self.strip_radix if strip_radix is None else strip_radix
+        spacer = self.spacer if spacer is None else spacer
         negligible = self.negligible if negligible is None else negligible
         units = self._preferred_units.get(self.units, self.units) if show_units else ''
         if prec is None:
@@ -2102,7 +2172,7 @@ class Quantity(float):
         # combine mantissa, scale factor, and units and return the result {{{3
         if sf_is_exp == 'unk':
             sf_is_exp = (sf == eexp)
-        value = self._combine(mantissa, sf, units, self.spacer, sf_is_exp)
+        value = self._combine(mantissa, sf, units, spacer, sf_is_exp)
         return self._label(value, show_label)
 
     # fixed() {{{2
@@ -2110,7 +2180,7 @@ class Quantity(float):
         self,
         *,
         show_units=None, prec=None, show_label=None, show_commas=None,
-        strip_zeros=None, strip_radix=None, scale=None,
+        strip_zeros=None, strip_radix=None, spacer=None, scale=None,
     ):
         # description {{{3
         """Convert quantity to fixed-point string.
@@ -2212,6 +2282,7 @@ class Quantity(float):
         show_commas = self.show_commas if show_commas is None else show_commas
         strip_zeros = self.strip_zeros if strip_zeros is None else strip_zeros
         strip_radix = self.strip_radix if strip_radix is None else strip_radix
+        spacer = self.spacer if spacer is None else spacer
         units = self._preferred_units.get(self.units, self.units) if show_units else ''
         if prec is None:
             prec = self.prec
@@ -2274,13 +2345,13 @@ class Quantity(float):
             mantissa += '0'
 
         # combine mantissa, scale factor and units and return result {{{3
-        value = self._combine(mantissa, '', units, self.spacer)
+        value = self._combine(mantissa, '', units, spacer)
         return self._label(value, show_label)
 
     # binary() {{{2
     def binary(
         self, *, show_units=None, prec=None, show_label=None,
-        strip_zeros=None, strip_radix=None, scale=None,
+        strip_zeros=None, strip_radix=None, spacer=None, scale=None,
     ):
         # description {{{3
         """Convert quantity to string using binary scale factors.
@@ -2365,6 +2436,7 @@ class Quantity(float):
         show_units = self.show_units if show_units is None else show_units
         strip_zeros = self.strip_zeros if strip_zeros is None else strip_zeros
         strip_radix = self.strip_radix if strip_radix is None else strip_radix
+        spacer = self.spacer if spacer is None else spacer
         units = self._preferred_units.get(self.units, self.units) if show_units else ''
         if prec is None:
             prec = self.prec
@@ -2430,7 +2502,7 @@ class Quantity(float):
             mantissa += '0'
 
         # combine mantissa, scale factor and units and return result {{{3
-        value = self._combine(mantissa, sf, units, self.spacer, sf_is_exp)
+        value = self._combine(mantissa, sf, units, spacer, sf_is_exp)
         return self._label(value, show_label)
 
     # is_close() {{{2
@@ -2572,11 +2644,11 @@ class Quantity(float):
         # code {{{3
         match = FORMAT_SPEC.match(template)
         if match:
-            align, alt_form, width, comma, prec, ftype, units = match.groups()
+            align, use_alt_form, width, comma, prec, ftype, units = match.groups()
             scale = units if units else None
             prec = int(prec) if prec else None
             ftype = ftype if ftype else ''
-            alt_form = dict(strip_zeros=False, strip_radix=False) if alt_form else {}
+            alt_form = dict(strip_zeros=False, strip_radix=False) if use_alt_form else {}
             if ftype and ftype in 'dnu':
                 if ftype == 'u':
                     value = scale if scale else self.units
@@ -2629,12 +2701,12 @@ class Quantity(float):
                     ))
                 else:
                     value = float(self)
-                value = '{0:{1}.{2}{3}}'.format(value, comma, prec, ftype)
+                value = '{0:{4}{1}.{2}{3}}'.format(value, comma, prec, ftype, use_alt_form)
                 value = self._map_leading_sign(value)
                 value = self._map_sign(value)
                 width = width.lstrip('0')
                     # format function treats 0 as a padding rather than a width
-                if self.strip_zeros:
+                if alt_form.get("strip_zeros", self.strip_zeros):
                     if 'e' in value:
                         mantissa, exponent = value.split('e')
                         if '.' in mantissa:
@@ -2923,7 +2995,8 @@ class Quantity(float):
             end = match.start(0)
             number = match.group(0)
             try:
-                number = Quantity(number).render(**kwargs)
+                q = cls.__new__(cls, number)
+                number = q.render(**kwargs)
             except ValueError:  # pragma: no cover
                 # something unexpected happened
                 # but this is not essential, so ignore it
@@ -2972,7 +3045,8 @@ class Quantity(float):
             end = match.start(0)
             number = match.group(0)
             try:
-                number = Quantity(number).render(**kwargs)
+                q = cls.__new__(cls, number)
+                number = q.render(**kwargs)
             except ValueError:  # pragma: no cover
                 # something unexpected happened
                 # but this is not essential, so ignore it
@@ -3130,9 +3204,6 @@ add_constant(
 # Unit Conversions {{{1
 # UnitConversion class {{{2
 class UnitConversion(object):
-    _unit_conversions = {}
-    _known_units = set()
-
     # description {{{3
     """
     Creates a unit converter.
@@ -3271,6 +3342,11 @@ class UnitConversion(object):
 
     """
 
+    _unit_conversions = {}
+    _known_units = set()
+    _support_si_sf_scaling = True
+    _support_bin_sf_scaling = True
+
     # constructor {{{3
     def __init__(self, to_units, from_units, slope=1, intercept=0):
         self.slope = slope
@@ -3450,6 +3526,26 @@ class UnitConversion(object):
         cls._unit_conversions = {}
         cls._known_units = set()
 
+    @classmethod
+    def enable_sf_scaling(cls, si_scaling=None, bin_scaling=None):
+        """By default the given or desired units in a unit conversion or scaling
+        may include scale factors.  This is true for both SI and binary scale
+        factors.  The scale factor is provided as a prefix on the units.  In
+        rare cases the acceptance of scale factors may create problems.  You can
+        use this method to disable support for interpreting scale factors in
+        unit conversions.
+
+        si_scaling (bool):
+            Enables or disables support for SI scale factor scaling.
+
+        bin_scaling (bool):
+            Enables or disables support for binary scale factor scaling.
+        """
+        if si_scaling is not None:
+            cls._support_si_sf_scaling = si_scaling
+        if bin_scaling is not None:
+            cls._support_bin_sf_scaling = bin_scaling
+
     # fixture() {{{3
     @staticmethod
     def fixture(converter_func):
@@ -3554,6 +3650,8 @@ class UnitConversion(object):
         # If you want this functionality, simply use:
         #     Quantity(value, from_units).scale(to_units)
 
+        orig_to_units, orig_from_units = to_units, from_units
+
         def get_converter(to_units, from_units):
             # handle unity scale factor conversions
             if (
@@ -3571,45 +3669,43 @@ class UnitConversion(object):
             #    b. there is no scale factor on the from_units
             #    c. there are scale factors on both the to_ and from_units
 
+            # separate scale factor from units
+            def extract_sf(units):
+                # check for binary scale factor, all of which are two characters
+                if cls._support_bin_sf_scaling:
+                    sf, unit = units[:2], units[2:]
+                    if sf in BINARY_MAPPINGS:
+                        return sf, unit, BINARY_MAPPINGS[sf]
+
+                # check for SI scale factor, all of which are 1 character
+                if cls._support_si_sf_scaling:
+                    sf, unit = units[:1], units[1:]
+                    if sf in MAPPINGS:
+                        return sf, unit, float('1' + MAPPINGS[sf])
+
+                return None, units, 1
+
+            # separate scale factor from units
             # handle known-unit cases for to_units
-            to_sf = None
-            to_resolved = to_units in cls._known_units                 # case 1
-            if not to_resolved:
-                to_prefix, to_suffix = to_units[:1], to_units[1:]
-                to_resolved = to_prefix in ALL_SF and to_suffix in cls._known_units
-                if to_resolved:
-                    to_sf, to_units = to_prefix, to_suffix             # case 2
+            if to_units in cls._known_units:  # case 1
+                to_sf, to_scale = None, 1
+            else:  # case 2 or 3
+                to_sf, to_units, to_scale = extract_sf(to_units)
 
             # handle known-unit cases for from_units
-            from_sf = None
-            from_resolved = from_units in cls._known_units             # case 1
-            if not from_resolved:
-                from_prefix, from_suffix = from_units[:1], from_units[1:]
-                from_resolved = (
-                    from_prefix in ALL_SF and from_suffix in cls._known_units
-                )
-                if from_resolved:
-                    from_sf, from_units = from_prefix, from_suffix     # case 2
-
-            # handle same-unit cases
-            if not to_resolved and not from_resolved:  # case 3
-                if to_units == from_suffix and from_prefix in ALL_SF:  # case 3a
-                    from_sf, from_units = from_prefix, from_suffix
-                elif from_units == to_suffix and to_prefix in ALL_SF:  # case 3b
-                    to_sf, to_units = to_prefix, to_suffix
-                elif from_prefix in ALL_SF and to_prefix in ALL_SF:    # case 3c
-                    to_sf, to_units = to_prefix, to_suffix
-                    from_sf, from_units = from_prefix, from_suffix
+            if from_units in cls._known_units:  # case 1
+                from_sf, from_scale = None, 1
+            else:  # case 2 or 3
+                from_sf, from_units, from_scale = extract_sf(from_units)
 
-            def get_sf(sf):
-                if sf is None:
-                    return 1
-                return float('1' + MAPPINGS[sf])
+            # handle unknown unit cases (to- and from- must have same units)
+            if to_units == from_units:  # case 3
+                return to_units, from_units, to_scale, from_scale
 
-            if to_sf or from_sf:
-                return to_units, from_units, get_sf(to_sf), get_sf(from_sf)
+            if to_units in cls._known_units or from_units in cls._known_units:  # case 2
+                return to_units, from_units, to_scale, from_scale
 
-            raise UnknownConversion(to_units=to_units, from_units=from_units)
+            raise UnknownConversion(to_units=orig_to_units, from_units=orig_from_units)
 
         to_units, from_units, to_sf, from_sf = get_converter(to_units, from_units)
 
@@ -3618,8 +3714,29 @@ class UnitConversion(object):
             value = Quantity(value, from_units)
         if to_units == from_units:
             return from_sf * value / to_sf
-        converter = cls._unit_conversions[(to_units, from_units)]
-        return converter(value.scale(from_sf)) / to_sf
+        try:
+            converter = cls._unit_conversions[(to_units, from_units)]
+        except KeyError:
+            raise UnknownConversion(to_units=orig_to_units, from_units=orig_from_units)
+        scaled = value.scale(from_sf)
+        try:
+            value = converter(scaled)
+        except TypeError as e:
+            # assume that this scale function is the deprecated form that
+            # expects units as the second argument
+            try:
+                value = converter(scaled, scaled.units)
+            except TypeError:  # pragma: no cover
+                raise e
+        try:
+            value, units = value
+                # the Quantity.scale() method returns the units along with the
+                # scaled value.  This differs from UnitConversion scale
+                # functions, which do not return the units.  This code allows
+                # UnitConversion to work with Quantity.scale() scale functions.
+        except TypeError:
+            pass
+        return value / to_sf
 
 
     # __str__ {{{3
@@ -3649,7 +3766,7 @@ UnitConversion('K', 'F °F', 5/9, 273.15 - 32*5/9)
 UnitConversion('K', 'R °R', 5/9, 0)
 
 # Length/Distance conversions {{{2
-UnitConversion('m', 'micron', 1/1000000)
+UnitConversion('m', 'micron microns', 1/1000000)
 UnitConversion('m', 'Å angstrom', 1/10000000000)
 UnitConversion('m', 'mi mile miles', 1609.344)
 UnitConversion('m', 'ft feet', 0.3048)
@@ -3666,10 +3783,12 @@ UnitConversion('s', 'hr hour hours', 3600)
 UnitConversion('s', 'day days', 86400)
 
 # Bit conversions {{{2
-UnitConversion('b', 'B', 8)
+UnitConversion('b bit bits', 'B byte bytes', 8)
+UnitConversion('bps b/s', 'Bps B/s', 8)
 
-# Bitcoin conversions {{{2
-UnitConversion(['sat', 'sats', 'ș'], ['BTC', 'btc', 'Ƀ', '₿'], 1e8)
+# Currency conversions {{{2
+UnitConversion(['$'], ['USD'], 1)
+UnitConversion(['sat', 'sats', 'ș'], ['BTC', 'btc', 'Ƀ', '₿', '฿'], 1e8)
 
 
 # Quantity functions {{{1
@@ -3771,3 +3890,5 @@ def binary(value, units, params=None, *args, **kwargs):
 
     """
     return Quantity(value, units=units, params=params).binary(*args, **kwargs)
+
+# vim: set sw=4 sts=4 tw=80 fo=ntcqwa12 et spell:

{quantiphy-2.20 → quantiphy-2.22}/quantiphy/quantiphy.pyi

@@ -119,6 +119,7 @@ class Quantity(float):
         show_label: bool | str = ...,
         strip_zeros: bool = ...,
         strip_radix: bool = ...,
+        spacer: str | bool = ...,
         scale: str | float | tuple[float | Quantity, str] | Callable = ...,
         negligible: float = ...,
     ) -> str: ...