karrio 2023.9.2__py3-none-any.whl → 2025.5rc3__py3-none-any.whl

karrio/core/utils/transformer.py

@@ -46,7 +46,7 @@ def to_multi_piece_rates(
                     **acc,
                     charge.name: models.ChargeDetails(
                         name=charge.name,
-                        amount=(
+                        amount=utils.NF.decimal(
                             charge.amount + getattr(acc.get(charge.name), "amount", 0.0)
                         ),
                         currency=charge.currency,
@@ -55,9 +55,14 @@ def to_multi_piece_rates(
                 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")

karrio/lib.py

@@ -4,6 +4,7 @@ import PyPDF2
 import logging
 import datetime
 import functools
+import urllib.parse
 import karrio.core.utils as utils
 import karrio.core.units as units
 import karrio.core.models as models
@@ -68,6 +69,7 @@ def text(
     *values: typing.Union[str, None],
     max: int = None,
     separator: str = None,
+    trim: bool = False,
 ) -> typing.Optional[str]:
     """Returns a joined text
 
@@ -81,15 +83,20 @@ def text(
         result3 = text("string text 1", "string text 2", separator=", ")
         print(result3) # "string text 1, string text 2"
 
+        result4 = text("string text 1 ", trim=True)
+        print(result4) # "string text 1"
+
     :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.
     """
     _text = utils.SF.concat_str(
         *values,
         join=True,
         separator=(separator or " "),
+        trim=trim,
     )
 
     if _text is None:
@@ -98,6 +105,19 @@ def text(
     return typing.cast(str, _text[0:max] if max else _text)
 
 
+def to_snake_case(input_string: typing.Optional[str]) -> typing.Optional[str]:
+    """Convert any string format to snake case."""
+    return utils.SF.to_snake_case(input_string)
+
+
+def to_slug(
+    *values,
+    separator: str = "_",
+) -> typing.Optional[str]:
+    """Convert a set of string values into a slug string, changing camel case to snake_case."""
+    return utils.SF.to_slug(*values, separator=separator)
+
+
 def to_int(
     value: typing.Union[str, int, bytes] = None,
     base: int = None,
@@ -147,6 +167,34 @@ def to_decimal(
     return utils.NF.decimal(value, quant)
 
 
+def to_numeric_decimal(
+    value: typing.Union[str, float, bytes] = None,
+    total_digits: int = 6,
+    decimal_digits: int = 3,
+) -> str:
+    """Convert a float to a zero-padded string with customizable total length and decimal places.
+
+    Args:
+    input_float (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'
+    """
+    return utils.NF.numeric_decimal(value, total_digits, decimal_digits)
+
+
 def to_money(
     value: typing.Union[str, float, bytes] = None,
 ) -> typing.Optional[float]:
@@ -208,6 +256,20 @@ def ftime(
     )
 
 
+def flocaltime(
+    time_str: str,
+    current_format: str = "%H:%M:%S",
+    output_format: str = "%H:%M %p",
+    try_formats: typing.List[str] = None,
+) -> typing.Optional[str]:
+    return utils.DF.ftime(
+        time_str,
+        current_format=current_format,
+        output_format=output_format,
+        try_formats=try_formats,
+    )
+
+
 def fdate(
     date_str: str = None,
     current_format: str = "%Y-%m-%d",
@@ -252,6 +314,18 @@ def to_date(
     )
 
 
+def to_next_business_datetime(
+    date_value: typing.Union[str, datetime.datetime] = None,
+    current_format: str = "%Y-%m-%d %H:%M:%S",
+    try_formats: typing.List[str] = None,
+) -> datetime.datetime:
+    return utils.DF.next_business_datetime(
+        date_value,
+        current_format=current_format,
+        try_formats=try_formats,
+    )
+
+
 # endregion
 
 # -----------------------------------------------------------
@@ -349,6 +423,27 @@ def to_element(
     return utils.XP.to_xml_or_html_element(xml_text, encoding=encoding)
 
 
+def to_query_string(data: dict) -> str:
+    param_list: list = functools.reduce(
+        lambda acc, item: [
+            *acc,
+            *(
+                [(item[0], _) for _ in item[1]]
+                if isinstance(item[1], list)
+                else [(item[0], item[1])]
+            ),
+        ],
+        data.items(),
+        [],
+    )
+
+    return urllib.parse.urlencode(param_list)
+
+
+def to_query_unquote(query_string: str) -> str:
+    return urllib.parse.unquote(query_string)
+
+
 def find_element(
     tag: str,
     in_element: utils.Element,
@@ -400,6 +495,45 @@ def envelope_serializer(
     return to_xml(envelope, namespacedef_=namespace)
 
 
+def load_json(path: str):
+    """Load and parse a JSON file from the given path.
+
+    Args:
+        path (str): The path to the JSON file to be loaded.
+
+    Returns:
+        dict: The parsed JSON content as a Python dictionary.
+
+    Raises:
+        FileNotFoundError: If the specified file is not found.
+        JSONDecodeError: If the file content is not valid JSON.
+        IOError: If there's an error reading the file.
+    """
+    return to_dict(load_file_content(path))
+
+
+def load_file_content(path: str) -> str:
+    """Load the content of a file from the given path.
+
+    Args:
+        path (str): The path to the file to be read.
+
+    Returns:
+        str: The content of the file as a string.
+
+    Raises:
+        FileNotFoundError: If the specified file is not found.
+        IOError: If there's an error reading the file.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as file:
+            return file.read()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"File not found: {path}")
+    except IOError as e:
+        raise IOError(f"Error reading file {path}: {str(e)}")
+
+
 # endregion
 
 # -----------------------------------------------------------
@@ -642,11 +776,22 @@ def run_asynchronously(
 
 def request(
     decoder: typing.Callable = utils.decode_bytes,
+    on_ok: typing.Callable = None,
     on_error: typing.Callable = None,
     trace: typing.Callable[[typing.Any, str], typing.Any] = None,
+    proxy: str = None,
+    timeout: typing.Optional[int] = None,
     **kwargs,
 ) -> str:
-    return utils.request(decoder=decoder, on_error=on_error, trace=trace, **kwargs)
+    return utils.request(
+        decoder=decoder,
+        on_ok=on_ok,
+        on_error=on_error,
+        trace=trace,
+        proxy=proxy,
+        timeout=timeout,
+        **kwargs,
+    )
 
 
 # endregion
@@ -673,7 +818,7 @@ def bundle_pdfs(
 
 def bundle_imgs(
     base64_strings: typing.List[str],
-) -> utils.Image:
+):
     return utils.bundle_imgs(base64_strings)
 
 

karrio/plugins/__init__.py

@@ -0,0 +1,6 @@
+"""
+Karrio Plugins Package.
+
+This package contains plugins for the Karrio shipping system.
+"""
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)  # type: ignore