karrio 2023.5.1__py3-none-any.whl → 2025.5rc1__py3-none-any.whl

karrio/core/utils/number.py

@@ -1,12 +1,14 @@
-from typing import Union, Optional
-from decimal import Decimal
+import math
+import typing
+import decimal
 
 
 class NUMBERFORMAT:
     @staticmethod
     def decimal(
-        value: Union[str, float, bytes] = None, quant: Optional[float] = None
-    ) -> Optional[float]:
+        value: typing.Union[str, float, bytes] = None,
+        quant: typing.Optional[float] = None,
+    ) -> typing.Optional[float]:
         """Parse a value into a valid decimal number.
 
         :param value: a value that can be parsed to float.
@@ -16,14 +18,53 @@ class NUMBERFORMAT:
         if value is None or isinstance(value, bool):
             return None
         if quant is not None:
-            return float(Decimal(str(value)).quantize(Decimal(str(quant))))
+            _result = float(
+                decimal.Decimal(str(value)).quantize(decimal.Decimal(str(quant)))
+            )
+            return _result if _result != 0 else float(decimal.Decimal(str(value)))
 
         return round(float(value), 2)
 
+    @staticmethod
+    def numeric_decimal(
+        value: typing.Union[str, float, bytes] = None,
+        total_digits: int = 3,
+        decimal_digits: int = 3,
+    ) -> str:
+        """Convert a float to a zero-padded string with customizable total length and decimal places.
+
+        Args:
+        value (float): A floating point number to be formatted.
+        total_digits (int): The total length of the output string (including both numeric and decimal parts).
+        decimal_digits (int): The number of decimal digits (d) in the final output.
+
+        Returns:
+        str: A zero-padded string of total_digits length, with the last decimal_digits as decimals.
+
+        Examples:
+        >>> format_to_custom_numeric_decimal(1.0, 7, 3)  # NNNNddd
+        '0001000'
+
+        >>> format_to_custom_numeric_decimal(1.0, 8, 3)  # NNNNNddd
+        '00001000'
+
+        >>> format_to_custom_numeric_decimal(1.0, 6, 3)  # NNNddd
+        '001000'
+        """
+        if value is None or isinstance(value, bool):
+            return None
+
+        # Multiply the input float by 10^decimal_digits to scale the decimal part
+        scaling_factor = 10**decimal_digits
+        scaled_value = int(value * scaling_factor)
+
+        # Format as a zero-padded string with the total number of digits
+        return f"{scaled_value:0{total_digits}d}"
+
     @staticmethod
     def integer(
-        value: Union[str, int, bytes] = None, base: int = None
-    ) -> Optional[int]:
+        value: typing.Union[str, int, bytes] = None, base: int = None
+    ) -> typing.Optional[int]:
         """Parse a value into a valid integer number.
 
         :param value: a value that can be parsed into integer.
@@ -32,4 +73,7 @@ class NUMBERFORMAT:
         """
         if value is None or isinstance(value, bool):
             return None
-        return int(value if base is None else base * round(float(value) / base))
+
+        return math.ceil(
+            float(value) if base is None else base * round(float(value) / base)
+        )

karrio/core/utils/string.py

@@ -7,15 +7,19 @@ class STRINGFORMAT:
         *values,
         join: bool = False,
         separator: str = " ",
+        trim: bool = False,
     ) -> typing.Optional[typing.Union[str, typing.List[str]]]:
         """Concatenate a set of string values into a list of string or a single joined text.
 
         :param values: a set of string values.
         :param join: indicate whether to join into a single string.
         :param separator: the text separator if joined into a single string.
+        :param trim: indicate whether to trim the string values.
         :return: a string, list of string or None.
         """
-        strings = [s for s in values if s not in ["", None]]
+        strings = [
+            "".join(s.split(" ")) if trim else s for s in values if s not in ["", None]
+        ]
 
         if len(strings) == 0:
             return None
@@ -24,3 +28,50 @@ class STRINGFORMAT:
             return separator.join(strings)
 
         return strings
+
+    @staticmethod
+    def to_snake_case(input_string: typing.Optional[str]) -> typing.Optional[str]:
+        """Convert any string format to snake case."""
+        if input_string is None:
+            return None
+
+        # Handle camelCase, PascalCase, and consecutive uppercase letters
+        s = ""
+        for i, char in enumerate(input_string):
+            if char.isupper():
+                if i > 0 and not input_string[i - 1].isupper():
+                    s += "_"
+                s += char.lower()
+            else:
+                s += char
+
+        # Handle spaces, hyphens, and other separators
+        s = "".join([c.lower() if c.isalnum() else "_" for c in s])
+
+        # Remove leading/trailing underscores and collapse multiple underscores
+        return "_".join(filter(None, s.split("_")))
+
+    @staticmethod
+    def to_slug(
+        *values,
+        separator: str = "_",
+    ) -> typing.Optional[str]:
+        """Convert a set of string values into a slug string."""
+
+        processed_values = []
+        for value in values:
+            if value not in ["", None]:
+                # Convert to lowercase and replace spaces with separator
+                processed = value.lower().replace(" ", separator)
+                # Replace other non-alphanumeric characters with separator
+                processed = "".join(
+                    c if c.isalnum() or c == separator else separator for c in processed
+                )
+                # Remove consecutive separators
+                while separator * 2 in processed:
+                    processed = processed.replace(separator * 2, separator)
+                # Remove leading and trailing separators
+                processed = processed.strip(separator)
+                processed_values.append(processed)
+
+        return separator.join(processed_values) if processed_values else None

karrio/core/utils/transformer.py

@@ -46,16 +46,23 @@ def to_multi_piece_rates(
                     **acc,
                     charge.name: models.ChargeDetails(
                         name=charge.name,
-                        amount=charge.amount
-                        + getattr(acc.get(charge.name), "amount", 0.0),
+                        amount=utils.NF.decimal(
+                            charge.amount + getattr(acc.get(charge.name), "amount", 0.0)
+                        ),
+                        currency=charge.currency,
                     ),
                 },
                 all_charges,
                 {},
             )
-            total_charge = sum(
-                (utils.NF.decimal(rate.total_charge or 0.0) for rate in similar_rates),
-                0.0,
+            total_charge = utils.NF.decimal(
+                sum(
+                    (
+                        utils.NF.decimal(rate.total_charge or 0.0)
+                        for rate in similar_rates
+                    ),
+                    0.0,
+                )
             )
             multi_piece_rates.append(
                 models.RateDetails(

karrio/core/validators.py

@@ -0,0 +1,88 @@
+"""
+Abstract base class for address validators.
+
+This module defines the interface that all address validators must implement.
+"""
+
+import typing
+
+class AddressValidatorAbstract:
+    """
+    Abstract base class for address validators.
+
+    All address validators must implement this interface.
+    """
+
+    @staticmethod
+    def get_info(is_authenticated: bool = None) -> dict:
+        """
+        Get information about the validator.
+
+        Args:
+            is_authenticated: Whether authenticated information should be returned
+
+        Returns:
+            Dictionary with information about the validator
+
+        Raises:
+            Exception: If the method is not implemented
+        """
+        raise Exception("get_info method is not implemented")
+
+    @staticmethod
+    def get_url() -> str:
+        """
+        Get the URL for the validation API.
+
+        Returns:
+            URL string for the validation API
+
+        Raises:
+            Exception: If the method is not implemented
+        """
+        raise Exception("get_url method is not implemented")
+
+    @staticmethod
+    def get_api_key() -> str:
+        """
+        Get the API key for the validation service.
+
+        Returns:
+            API key string
+
+        Raises:
+            Exception: If the method is not implemented or no API key is configured
+        """
+        raise Exception("get_api_key method is not implemented")
+
+    @staticmethod
+    def format_address(address) -> str:
+        """
+        Format an address object for the validation API.
+
+        Args:
+            address: Address object to format
+
+        Returns:
+            Formatted address string
+
+        Raises:
+            Exception: If the method is not implemented
+        """
+        raise Exception("format_address method is not implemented")
+
+    @staticmethod
+    def validate(address) -> typing.Any:
+        """
+        Validate an address using the service.
+
+        Args:
+            address: Address object to validate
+
+        Returns:
+            Address validation result
+
+        Raises:
+            Exception: If the method is not implemented
+        """
+        raise Exception("validate method is not implemented")