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

karrio/lib.py

@@ -1,7 +1,10 @@
 import typing
+import base64
+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
@@ -25,11 +28,14 @@ Job = utils.Job
 OptionEnum = utils.OptionEnum
 Enum = utils.Enum
 Flag = utils.Flag
+StrEnum = utils.StrEnum
+identity = utils.identity
 
 
 # -----------------------------------------------------------
 # raw types utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def join(
@@ -63,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
 
@@ -76,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:
@@ -93,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,
@@ -142,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]:
@@ -159,9 +212,34 @@ def to_money(
         return None
 
 
+def to_list(
+    value: typing.Union[T, typing.List[T]] = None,
+) -> typing.List[T]:
+    """Ensures the input value is a list.
+
+    Example:
+        result1 = to_list("test")
+        print(result1)  # ["test"]
+
+        result2 = to_int(["test"])
+        print(result2)  # ["test"]
+
+    :param value: a value that can be parsed into integer.
+    :return: a list of values.
+    """
+
+    if value is None:
+        return []
+
+    return value if isinstance(value, list) else [value]
+
+
+# endregion
+
 # -----------------------------------------------------------
 # Date and Time utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def ftime(
@@ -172,9 +250,23 @@ def ftime(
 ) -> typing.Optional[str]:
     return utils.DF.ftime(
         time_str,
-        current_format,
-        output_format,
-        try_formats,
+        current_format=current_format,
+        output_format=output_format,
+        try_formats=try_formats,
+    )
+
+
+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,
     )
 
 
@@ -185,8 +277,8 @@ def fdate(
 ) -> typing.Optional[str]:
     return utils.DF.fdate(
         date_str,
-        current_format,
-        try_formats,
+        current_format=current_format,
+        try_formats=try_formats,
     )
 
 
@@ -198,9 +290,9 @@ def fdatetime(
 ) -> typing.Optional[str]:
     return utils.DF.fdatetime(
         date_str,
-        current_format,
-        output_format,
-        try_formats,
+        current_format=current_format,
+        output_format=output_format,
+        try_formats=try_formats,
     )
 
 
@@ -217,14 +309,29 @@ def to_date(
 ) -> datetime.datetime:
     return utils.DF.date(
         date_value,
-        current_format,
-        try_formats,
+        current_format=current_format,
+        try_formats=try_formats,
+    )
+
+
+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
+
 # -----------------------------------------------------------
 # JSON, XML and object utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def to_object(
@@ -246,7 +353,7 @@ def to_object(
 def to_dict(
     value: typing.Any,
     clear_empty: bool = None,
-) -> dict:
+) -> typing.Union[dict, list, typing.Any]:
     """Parse value into a Python dictionay.
 
     :param value: a value that can converted in dictionary.
@@ -269,6 +376,7 @@ def to_json(
 def to_xml(
     value: typing.Union[utils.Element, typing.Any],
     encoding: str = "utf-8",
+    prefixes: dict = None,
     **kwargs,
 ) -> str:
     """Turn a XML typed object into a XML text.
@@ -277,7 +385,12 @@ def to_xml(
     :param encoding: an optional encoding type.
     :return: a XML string.
     """
+
     if utils.XP.istypedxmlobject(value):
+        if prefixes is not None:
+            _prefix = prefixes.get(value.__class__.__name__) or ""
+            apply_namespaceprefix(value, _prefix, prefixes)
+
         return utils.XP.export(value, **kwargs)
 
     return utils.XP.xml_tostring(value, encoding)
@@ -310,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,
@@ -361,9 +495,51 @@ 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
+
 # -----------------------------------------------------------
 # Shipping request options utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def to_shipping_options(
@@ -442,9 +618,12 @@ def to_connection_config(
     )
 
 
+# endregion
+
 # -----------------------------------------------------------
 # Address utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def to_zip4(
@@ -484,9 +663,12 @@ def to_address(
     return units.ComputedAddress(address)
 
 
+# endregion
+
 # -----------------------------------------------------------
 # Multi-piece shipment utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def to_multi_piece_rates(
@@ -544,20 +726,29 @@ def to_packages(
     max_weight: units.Weight = None,
     options: dict = None,
     package_option_type: typing.Type[utils.Enum] = utils.Enum,
+    shipping_options_initializer: typing.Callable = None,
 ) -> units.Packages:
     return units.Packages(
         parcels=parcels,
         presets=presets,
         required=required,
         max_weight=max_weight,
-        options=units.ShippingOptions(options or {}, package_option_type),
+        options=(
+            units.ShippingOptions(options or {}, package_option_type)
+            if (isinstance(options, dict) or options is None)
+            else options
+        ),
         package_option_type=package_option_type,
+        shipping_options_initializer=shipping_options_initializer,
     )
 
 
+# endregion
+
 # -----------------------------------------------------------
 # async and backgroung code execution utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def run_concurently(
@@ -575,23 +766,40 @@ def run_asynchronously(
     return utils.exec_async(predicate, sequence)
 
 
+# endregion
+
 # -----------------------------------------------------------
 # HTTP requests utility functions.
 # -----------------------------------------------------------
+# region
 
 
 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
 
 # -----------------------------------------------------------
 # image and document processing utility functions.
 # -----------------------------------------------------------
+# region
 
 
 def image_to_pdf(
@@ -604,13 +812,13 @@ def image_to_pdf(
 
 def bundle_pdfs(
     base64_strings: typing.List[str],
-) -> utils.PdfMerger:
+) -> PyPDF2.PdfMerger:
     return utils.bundle_pdfs(base64_strings)
 
 
 def bundle_imgs(
     base64_strings: typing.List[str],
-) -> utils.Image:
+):
     return utils.bundle_imgs(base64_strings)
 
 
@@ -652,9 +860,24 @@ def decode(byte: bytes):
     )
 
 
+def encode_base64(byte: bytes):
+    return (
+        failsafe(lambda: base64.encodebytes(byte).decode("utf-8"))
+        or failsafe(lambda: base64.encodebytes(byte).decode("ISO-8859-1"))
+        or base64.encodebytes(byte).decode("utf-8")
+    )
+
+
+def binary_to_base64(binary_string: str):
+    return utils.binary_to_base64(binary_string)
+
+
+# endregion
+
 # -----------------------------------------------------------
 # other utilities functions
 # -----------------------------------------------------------
+# region
 
 
 def failsafe(callable: typing.Callable[[], T], warning: str = None) -> T:
@@ -664,3 +887,6 @@ def failsafe(callable: typing.Callable[[], T], warning: str = None) -> T:
     don't mind if it fails.
     """
     return utils.failsafe(callable, warning=warning)
+
+
+# endregion

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