GeneralManager 0.9.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

general_manager/measurement/measurement.py

@@ -4,7 +4,7 @@ from typing import Any, Callable
 import pint
 from decimal import Decimal, getcontext, InvalidOperation
 from operator import eq, ne, lt, le, gt, ge
-
+from pint.facets.plain import PlainQuantity
 
 # Set precision for Decimal
 getcontext().prec = 28
@@ -21,6 +21,16 @@ for currency in currency_units:
 
 class Measurement:
     def __init__(self, value: Decimal | float | int | str, unit: str):
+        """
+        Initialize a Measurement instance with a numeric value and unit.
+        
+        Parameters:
+            value (Decimal | float | int | str): The numeric value to be associated with the unit. Can be a Decimal, float, int, or a string convertible to Decimal.
+            unit (str): The unit of measurement as a string.
+        
+        Raises:
+            TypeError: If the value cannot be converted to a Decimal.
+        """
         if not isinstance(value, (Decimal, float, int)):
             try:
                 value = Decimal(str(value))
@@ -28,22 +38,37 @@ class Measurement:
                 raise TypeError("Value must be a Decimal, float, int or compatible.")
         if not isinstance(value, Decimal):
             value = Decimal(str(value))
-        self.__quantity = self.formatDecimal(value) * ureg.Quantity(1, unit)
+        self.__quantity = ureg.Quantity(self.formatDecimal(value), unit)
 
     def __getstate__(self):
+        """
+        Return a serializable state dictionary containing the magnitude and unit of the measurement.
+        
+        Returns:
+            dict: A dictionary with 'magnitude' as a string and 'unit' as a string, suitable for pickling or other serialization.
+        """
         state = {
-            "magnitude": str(self.quantity.magnitude),
-            "unit": str(self.quantity.units),
+            "magnitude": str(self.magnitude),
+            "unit": str(self.unit),
         }
         return state
 
     def __setstate__(self, state):
+        """
+        Restore the Measurement object from a serialized state dictionary.
+        
+        Parameters:
+            state (dict): A dictionary containing 'magnitude' as a string and 'unit' as a string.
+        """
         value = Decimal(state["magnitude"])
         unit = state["unit"]
-        self.__quantity = self.formatDecimal(value) * ureg.Quantity(1, unit)
+        self.__quantity = ureg.Quantity(self.formatDecimal(value), unit)
 
     @property
-    def quantity(self) -> pint.Quantity:
+    def quantity(self) -> PlainQuantity:
+        """
+        Return the internal quantity as a `PlainQuantity` object from the `pint` library.
+        """
         return self.__quantity
 
     @property
@@ -57,18 +82,24 @@ class Measurement:
     @classmethod
     def from_string(cls, value: str) -> Measurement:
         """
-        Creates a Measurement instance from a string in the format 'value unit'.
+        Parse a string of the form 'value unit' and return a Measurement instance.
         
-        Args:
-            value: A string containing a numeric value and a unit separated by a space (e.g., '10.5 kg').
+        Parameters:
+            value (str): String containing a numeric value and a unit, separated by a space (e.g., '10.5 kg').
         
         Returns:
-            A Measurement instance representing the parsed value and unit.
+            Measurement: The corresponding Measurement object.
         
         Raises:
             ValueError: If the input string does not contain exactly two parts separated by a space.
         """
         splitted = value.split(" ")
+        if len(splitted) == 1:
+            # If only one part, assume it's a dimensionless value
+            try:
+                return cls(Decimal(splitted[0]), "dimensionless")
+            except InvalidOperation:
+                raise ValueError("Invalid value for dimensionless measurement.")
         if len(splitted) != 2:
             raise ValueError("String must be in the format 'value unit'.")
         value, unit = splitted
@@ -86,12 +117,27 @@ class Measurement:
             return value
 
     def to(self, target_unit: str, exchange_rate: float | None = None):
+        """
+        Convert the measurement to a specified target unit, handling both currency and physical unit conversions.
+        
+        For currency units, an explicit exchange rate must be provided if converting between different currencies; otherwise, the original measurement is returned. For physical units, standard unit conversion is performed using the underlying unit registry.
+        
+        Parameters:
+            target_unit (str): The unit to convert the measurement to.
+            exchange_rate (float, optional): The exchange rate to use for currency conversion. Required if converting between different currencies.
+        
+        Returns:
+            Measurement: A new Measurement instance in the target unit.
+        
+        Raises:
+            ValueError: If converting between different currencies without providing an exchange rate.
+        """
         if self.is_currency():
-            if self.quantity.units == ureg(target_unit):
+            if self.unit == ureg(target_unit):
                 return self  # Same currency, no conversion needed
             elif exchange_rate is not None:
                 # Convert using the provided exchange rate
-                value = self.quantity.magnitude * Decimal(str(exchange_rate))
+                value = self.magnitude * Decimal(str(exchange_rate))
                 return Measurement(value, target_unit)
             else:
                 raise ValueError(
@@ -106,14 +152,25 @@ class Measurement:
 
     def is_currency(self):
         # Check if the unit is a defined currency
-        return str(self.quantity.units) in currency_units
+        """
+        Return True if the measurement's unit is one of the defined currency units.
+        """
+        return str(self.unit) in currency_units
 
     def __add__(self, other: Any) -> Measurement:
+        """
+        Add two Measurement instances, supporting both currency and physical units.
+        
+        Addition is allowed only if both operands are currencies of the same unit or both are physical units with compatible dimensions. Raises a TypeError if operands are of different types (currency vs. physical unit) or not Measurement instances, and raises a ValueError if units are incompatible.
+        
+        Returns:
+            Measurement: A new Measurement representing the sum.
+        """
         if not isinstance(other, Measurement):
             raise TypeError("Addition is only allowed between Measurement instances.")
         if self.is_currency() and other.is_currency():
             # Both are currencies
-            if self.quantity.units != other.quantity.units:
+            if self.unit != other.unit:
                 raise ValueError(
                     "Addition between different currencies is not allowed."
                 )
@@ -139,34 +196,49 @@ class Measurement:
             )
 
     def __sub__(self, other: Any) -> Measurement:
+        """
+        Subtracts another Measurement from this one, enforcing unit compatibility.
+        
+        Subtraction is allowed only between two currencies of the same unit or two physical units with compatible dimensions. Raises a TypeError if the operand is not a Measurement or if attempting to subtract a currency from a physical unit (or vice versa). Raises a ValueError if subtracting different currencies or incompatible physical units.
+        
+        Returns:
+            Measurement: The result of the subtraction as a new Measurement instance.
+        """
         if not isinstance(other, Measurement):
             raise TypeError(
                 "Subtraction is only allowed between Measurement instances."
             )
         if self.is_currency() and other.is_currency():
             # Both are currencies
-            if self.quantity.units != other.quantity.units:
+            if self.unit != other.unit:
                 raise ValueError(
                     "Subtraction between different currencies is not allowed."
                 )
             result_quantity = self.quantity - other.quantity
-            return Measurement(
-                Decimal(str(result_quantity.magnitude)), str(self.quantity.units)
-            )
+            return Measurement(Decimal(str(result_quantity.magnitude)), str(self.unit))
         elif not self.is_currency() and not other.is_currency():
             # Both are physical units
             if self.quantity.dimensionality != other.quantity.dimensionality:
                 raise ValueError("Units are not compatible for subtraction.")
             result_quantity = self.quantity - other.quantity
-            return Measurement(
-                Decimal(str(result_quantity.magnitude)), str(self.quantity.units)
-            )
+            return Measurement(Decimal(str(result_quantity.magnitude)), str(self.unit))
         else:
             raise TypeError(
                 "Subtraction between currency and physical unit is not allowed."
             )
 
     def __mul__(self, other: Any) -> Measurement:
+        """
+        Multiply this measurement by another measurement or a numeric value.
+        
+        Multiplication between two currency measurements is not allowed. If multiplied by another measurement, returns a new Measurement with the combined units. If multiplied by a numeric value, returns a new Measurement with the same unit and scaled magnitude.
+        
+        Returns:
+            Measurement: The result of the multiplication as a new Measurement instance.
+        
+        Raises:
+            TypeError: If attempting to multiply two currency measurements or if the operand is not a Measurement or numeric value.
+        """
         if isinstance(other, Measurement):
             if self.is_currency() or other.is_currency():
                 raise TypeError(
@@ -180,15 +252,21 @@ class Measurement:
             if not isinstance(other, Decimal):
                 other = Decimal(str(other))
             result_quantity = self.quantity * other
-            return Measurement(
-                Decimal(str(result_quantity.magnitude)), str(self.quantity.units)
-            )
+            return Measurement(Decimal(str(result_quantity.magnitude)), str(self.unit))
         else:
             raise TypeError(
                 "Multiplication is only allowed with Measurement or numeric values."
             )
 
     def __truediv__(self, other: Any) -> Measurement:
+        """
+        Divide this measurement by another measurement or a numeric value.
+        
+        If dividing by another `Measurement`, both must not be currencies. Returns a new `Measurement` with the resulting value and unit. If dividing by a numeric value, returns a new `Measurement` with the same unit and divided magnitude.
+        
+        Raises:
+            TypeError: If dividing two currency measurements, or if the operand is not a `Measurement` or numeric value.
+        """
         if isinstance(other, Measurement):
             if self.is_currency() and other.is_currency():
                 raise TypeError("Division between two currency amounts is not allowed.")
@@ -200,41 +278,38 @@ class Measurement:
             if not isinstance(other, Decimal):
                 other = Decimal(str(other))
             result_quantity = self.quantity / other
-            return Measurement(
-                Decimal(str(result_quantity.magnitude)), str(self.quantity.units)
-            )
+            return Measurement(Decimal(str(result_quantity.magnitude)), str(self.unit))
         else:
             raise TypeError(
                 "Division is only allowed with Measurement or numeric values."
             )
 
     def __str__(self):
-        if not str(self.quantity.units) == "dimensionless":
-            return f"{self.quantity.magnitude} {self.quantity.units}"
-        return f"{self.quantity.magnitude}"
+        """
+        Return a string representation of the measurement, including the unit unless it is dimensionless.
+        """
+        if not str(self.unit) == "dimensionless":
+            return f"{self.magnitude} {self.unit}"
+        return f"{self.magnitude}"
 
     def __repr__(self):
-        return f"Measurement({self.quantity.magnitude}, '{self.quantity.units}')"
+        """
+        Return a string representation of the Measurement instance for debugging, showing its magnitude and unit.
+        """
+        return f"Measurement({self.magnitude}, '{self.unit}')"
 
     def _compare(self, other: Any, operation: Callable[..., bool]) -> bool:
         """
-        Compares this Measurement with another using the specified comparison operation.
+        Compare this Measurement to another using a specified comparison operation.
         
-        If `other` is a string, it is parsed into a Measurement. Raises a TypeError if
-        `other` is not a Measurement instance. Converts `other` to this instance's unit
-        before applying the comparison. Raises a ValueError if the measurements have
-        incompatible dimensions.
+        If `other` is a string, it is parsed into a Measurement. The comparison is performed after converting `other` to this instance's unit. Raises a TypeError if `other` is not a Measurement or a valid string, and a ValueError if the measurements have incompatible dimensions.
         
-        Args:
-            other: The object to compare with, either a Measurement or a string in the format "value unit".
-            operation: A callable that takes two magnitudes and returns a boolean result.
+        Parameters:
+            other: The object to compare, either a Measurement or a string in the format "value unit".
+            operation: A callable that takes two magnitudes and returns a boolean.
         
         Returns:
-            The result of the comparison operation.
-        
-        Raises:
-            TypeError: If `other` is not a Measurement instance or a valid string representation.
-            ValueError: If the measurements have different dimensions and cannot be compared.
+            bool: The result of the comparison.
         """
         if isinstance(other, str):
             other = Measurement.from_string(other)
@@ -244,9 +319,9 @@ class Measurement:
             raise TypeError("Comparison is only allowed between Measurement instances.")
         try:
             # Convert `other` to the same units as `self`
-            other_converted: pint.Quantity = other.quantity.to(self.quantity.units)  # type: ignore
+            other_converted: pint.Quantity = other.quantity.to(self.unit)  # type: ignore
             # Apply the comparison operation
-            return operation(self.quantity.magnitude, other_converted.magnitude)
+            return operation(self.magnitude, other_converted.magnitude)
         except pint.DimensionalityError:
             raise ValueError("Cannot compare measurements with different dimensions.")
 
@@ -273,16 +348,16 @@ class Measurement:
 
     def __ge__(self, other: Any) -> bool:
         """
-        Returns True if this measurement is greater than or equal to another measurement.
+        Return True if this measurement is greater than or equal to another measurement.
         
-        Comparison is performed after converting the other operand to the same unit. Raises a TypeError if the other object is not a Measurement instance or a compatible string, or a ValueError if the units are not compatible.
+        The comparison is performed after converting the other operand to the same unit as this measurement. Raises a TypeError if the other object is not a Measurement instance or a compatible string, or a ValueError if the units are incompatible.
         """
         return self._compare(other, ge)
 
     def __hash__(self) -> int:
         """
-        Returns a hash value based on the magnitude and unit of the measurement.
+        Return a hash value derived from the measurement's magnitude and unit.
         
-        This enables Measurement instances to be used in hash-based collections such as sets and dictionaries.
+        Enables use of Measurement instances in hash-based collections such as sets and dictionaries.
         """
-        return hash((self.quantity.magnitude, str(self.quantity.units)))
+        return hash((self.magnitude, str(self.unit)))

{generalmanager-0.9.0.dist-info → generalmanager-0.9.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.9.0
+Version: 0.9.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License-Expression: MIT

{generalmanager-0.9.0.dist-info → generalmanager-0.9.1.dist-info}/RECORD

@@ -37,7 +37,7 @@ general_manager/manager/groupManager.py,sha256=8dpZUfm7aFL4lraUWv4qbbDRClQZaYxw4
 general_manager/manager/input.py,sha256=-pJXGJ-g2-OxZfl4Buj3mQkf05fN4p8MsR2Lh9BQcEo,3208
 general_manager/manager/meta.py,sha256=IN5Xzz4lcUBe2umqvBz84qoyjkzKubNaMwfuYFQjFGU,5631
 general_manager/measurement/__init__.py,sha256=X97meFujBldE5v0WMF7SmKeGpC5R0JTczfLo_Lq1Xek,84
-general_manager/measurement/measurement.py,sha256=e_FjHieeJbBtjXGCO9J7vRPw6KCkMrOxwWjaD0m8ee4,11777
+general_manager/measurement/measurement.py,sha256=0jVU6eZmEwDs0CW_W_RpUxaWDPd9J4uQXWPpxMkfJWQ,16079
 general_manager/measurement/measurementField.py,sha256=iq9Hqe6ZGX8CxXm4nIqTAWTRkQVptzpqE9ExX-jFyNs,5928
 general_manager/permission/__init__.py,sha256=5UlDERN60Vn8obGVkT-cOM8kHjzmoxgK5w5FgTCDhGE,59
 general_manager/permission/basePermission.py,sha256=14iKo6qVmaUdg1sAz-gSZyNtpVKAAapIhutVAMDf93c,6056
@@ -49,8 +49,8 @@ general_manager/rule/__init__.py,sha256=4Har5cfPD1fmOsilTDod-ZUz3Com-tkl58jz7yY4
 general_manager/rule/handler.py,sha256=z8SFHTIZ0LbLh3fV56Mud0V4_OvWkqJjlHvFqau7Qfk,7334
 general_manager/rule/rule.py,sha256=3FVCKGL7BTVoStdgOTdWQwuoVRIxAIAilV4VOzouDpc,10759
 general_manager/utils/testing.py,sha256=R6l-9PVAgxeVywvynkzSR6xXcHCu4z2UzRqzHDVrBUY,5591
-generalmanager-0.9.0.dist-info/licenses/LICENSE,sha256=YGFm0ieb4KpkMRRt2qnWue6uFh0cUMtobwEBkHwajhc,1450
-generalmanager-0.9.0.dist-info/METADATA,sha256=jZGL1zcuGh2BUBCCpafvSZH2qIVWtcdk4FltvRj-06M,6205
-generalmanager-0.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-generalmanager-0.9.0.dist-info/top_level.txt,sha256=sTDtExP9ga-YP3h3h42yivUY-A2Q23C2nw6LNKOho4I,16
-generalmanager-0.9.0.dist-info/RECORD,,
+generalmanager-0.9.1.dist-info/licenses/LICENSE,sha256=YGFm0ieb4KpkMRRt2qnWue6uFh0cUMtobwEBkHwajhc,1450
+generalmanager-0.9.1.dist-info/METADATA,sha256=KlP-5CSEpz1tbI4ec2SzBKT8aSCBWhiUboTS5zgLzoQ,6205
+generalmanager-0.9.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+generalmanager-0.9.1.dist-info/top_level.txt,sha256=sTDtExP9ga-YP3h3h42yivUY-A2Q23C2nw6LNKOho4I,16
+generalmanager-0.9.1.dist-info/RECORD,,