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

karrio/core/utils/datetime.py

@@ -1,5 +1,5 @@
 import typing
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 
 
 class DATEFORMAT:
@@ -30,6 +30,53 @@ class DATEFORMAT:
 
         return datetime.strptime(str(date_value), current_format)
 
+    @staticmethod
+    def next_business_datetime(
+        date_value: typing.Union[str, datetime] = None,
+        current_format: str = "%Y-%m-%d %H:%M:%S",
+        try_formats: typing.List[str] = None,
+        start_hour: int = 10,
+        end_hour: int = 17,
+    ) -> typing.Optional[datetime]:
+        date = DATEFORMAT.date(
+            date_value, current_format=current_format, try_formats=try_formats
+        )
+        if date is None:
+            return None
+
+        # Define business hours
+        _start_hour = start_hour
+        _end_hour = end_hour
+
+        # If date has no time component, set it to current time
+        if date.hour == 0 and date.minute == 0 and date.second == 0:
+            now = datetime.now()
+            date = date.replace(hour=now.hour, minute=now.minute, second=now.second)
+
+        # If the given datetime is within business hours, return it
+        if DATEFORMAT.is_business_hour(date):
+            return date
+
+        # If it's outside business hours, calculate the next business datetime
+        if date.weekday() >= 5:  # If it's Saturday or Sunday
+            # Move to the next Monday
+            days_to_add = 7 - date.weekday()
+            next_business_day = date + timedelta(days=days_to_add)
+            return next_business_day.replace(
+                hour=_start_hour, minute=0, second=0, microsecond=0
+            )
+        elif date.hour >= _end_hour:  # If it's after business hours
+            # Move to the next business day
+            next_business_day = date + timedelta(days=1)
+            if next_business_day.weekday() >= 5:  # If it's Saturday or Sunday
+                days_to_add = 7 - next_business_day.weekday()
+                next_business_day += timedelta(days=days_to_add)
+            return next_business_day.replace(
+                hour=_start_hour, minute=0, second=0, microsecond=0
+            )
+        else:  # If it's before business hours
+            return date.replace(hour=_start_hour, minute=0, second=0, microsecond=0)
+
     @staticmethod
     def fdate(
         date_str: typing.Union[str, int, datetime] = None,
@@ -77,4 +124,17 @@ class DATEFORMAT:
     def ftimestamp(timestamp: typing.Union[str, int] = None):
         if timestamp is None:
             return None
-        return datetime.utcfromtimestamp(float(timestamp)).strftime("%H:%M")
+        return datetime.fromtimestamp(float(timestamp), timezone.utc).strftime("%H:%M")
+
+    @staticmethod
+    def is_business_hour(dt: datetime):
+        # Define business hours
+        start_hour = 9
+        end_hour = 17
+
+        # Check if the given datetime is within business hours
+        if dt.weekday() >= 5:  # 5 and 6 correspond to Saturday and Sunday
+            return False
+        if dt.hour < start_hour or dt.hour >= end_hour:
+            return False
+        return True

karrio/core/utils/dict.py

@@ -1,3 +1,4 @@
+import re
 import enum
 import attr
 import json
@@ -50,6 +51,10 @@ class DICTPARSE:
         :return: a dictionary.
         """
         _clear_empty = clear_empty is not False
+        if isinstance(entity, str):
+            entity = re.sub(",[ \t\r\n]+}", "}", entity)
+            entity = re.sub(r",[ \t\r\n]+\]", "]", entity)
+
         return json.loads(
             (
                 DICTPARSE.jsonify(entity)

karrio/core/utils/enum.py

@@ -1,7 +1,6 @@
 import attr
 import enum
 import typing
-import karrio.lib as lib
 
 BaseStrEnum = getattr(enum, "StrEnum", enum.Flag)
 
@@ -78,87 +77,173 @@ class EnumWrapper:
 
 @attr.s(auto_attribs=True)
 class OptionEnum:
+    """An option enumeration class for handling typed options.
+
+    Attributes:
+        code: The option code or identifier
+        type: The type converter function or enum type
+        state: The current state value
+        default: The default value to use when none is provided
+    """
     code: str
-    type: typing.Callable = str
+    type: typing.Union[typing.Callable, MetaEnum] = str
     state: typing.Any = None
+    default: typing.Any = None
 
     def __getitem__(self, type: typing.Callable = None) -> "OptionEnum":
-        return OptionEnum("", type or self.type, self.state)
+        return OptionEnum("", type or self.type, self.state, self.default)
 
     def __call__(self, value: typing.Any = None) -> "OptionEnum":
+        """Create a new OptionEnum instance with the specified value.
+
+        Args:
+            value: The value to set. If None and default is provided, default will be used.
+
+        Returns:
+            A new OptionEnum instance with the appropriate state.
+        """
         state = self.state
 
+        # if value is None and default is provided, use default
+        if value is None and self.default is not None:
+            value = self.default
+
         # if type is bool we have an option defined as Flag.
         if self.type is bool:
             state = value is not False
 
+        elif "enum" in str(self.type):
+            state = (
+                (
+                    self.type.map(value).name_or_key  # type: ignore
+                    if hasattr(value, "map")
+                    else self.type[value].name  # type: ignore
+                )
+                if value is not None and value != ""
+                else None
+            )
+
         else:
             state = self.type(value) if value is not None else None
 
-        return OptionEnum(self.code, self.type, state)
+        return OptionEnum(self.code, self.type, state, self.default)
 
 
 @attr.s(auto_attribs=True)
 class Spec:
+    """A specification class for handling typed values with computation logic.
+
+    Attributes:
+        key: The specification key or identifier
+        type: The type of the specification value
+        compute: The computation function to apply
+        value: The current value
+        default: The default value to use when none is provided
+    """
     key: str
     type: typing.Type
     compute: typing.Callable
     value: typing.Any = None
+    default: typing.Any = None
 
     def apply(self, *args, **kwargs):
+        """Apply the computation function to the arguments."""
         return self.compute(*args, **kwargs)
 
     """Spec initialization modes"""
 
     @staticmethod
-    def asFlag(key: str) -> "Spec":
+    def asFlag(key: str, default: typing.Optional[bool] = None) -> "Spec":
         """A Spec defined as "Flag" means that when it is specified in the payload,
         a boolean flag will be returned as value.
+
+        Args:
+            key: The specification key
+            default: Default value to use when none is provided
+
+        Returns:
+            A Spec instance configured as a flag
         """
 
         def compute(value: typing.Optional[bool]) -> bool:
+            # Use default if value is None
+            if value is None and default is not None:
+                value = default
             return value is not False
 
-        return Spec(key, bool, compute)
+        return Spec(key, bool, compute, default=default)
 
     @staticmethod
-    def asKey(key: str) -> "Spec":
+    def asKey(key: str, default: typing.Optional[bool] = None) -> "Spec":
         """A Spec defined as "Key" means that when it is specified in a payload and not flagged as False,
         the spec code will be returned as value.
+
+        Args:
+            key: The specification key
+            default: Default value to use when none is provided
+
+        Returns:
+            A Spec instance configured to return its key
         """
 
         def compute(value: typing.Optional[bool]) -> str:
+            # Use default if value is None
+            if value is None and default is not None:
+                value = default
             return key if (value is not False) else None
 
-        return Spec(key, bool, compute)
+        return Spec(key, bool, compute, default=default)
 
     @staticmethod
-    def asValue(key: str, type: typing.Type = str) -> "Spec":
+    def asValue(key: str, type: typing.Type = str, default: typing.Any = None) -> "Spec":
         """A Spec defined as "typing.Type" means that when it is specified in a payload,
         the value passed by the user will be returned.
+
+        Args:
+            key: The specification key
+            type: The type to convert the value to
+            default: Default value to use when none is provided
+
+        Returns:
+            A Spec instance configured to return the typed value
         """
 
         def compute(value: typing.Optional[type]) -> type:  # type: ignore
+            # Use default if value is None
+            if value is None and default is not None:
+                value = default
             return type(value) if value is not None else None
 
-        return Spec(key, type, compute)
+        return Spec(key, type, compute, default=default)
 
     @staticmethod
-    def asKeyVal(key: str, type: typing.Type = str) -> "Spec":
+    def asKeyVal(key: str, type: typing.Type = str, default: typing.Any = None) -> "Spec":
         """A Spec defined as "Value" means that when it is specified in a payload,
         the a new spec defined as type is returned.
+
+        Args:
+            key: The specification key
+            type: The type to convert the value to
+            default: Default value to use when none is provided
+
+        Returns:
+            A Spec instance configured to return a new Spec with the typed value
         """
 
         def compute_inner_spec(value: typing.Optional[type]) -> Spec:  # type: ignore
+            # Use default if value is None
+            if value is None and default is not None:
+                value = default
+
             computed_value = (
                 getattr(value, "value", None)
                 if hasattr(value, "value")
                 else (type(value) if value is not None else None)
             )
 
-            return Spec(key, type, lambda *_: computed_value, computed_value)
+            return Spec(key, type, lambda *_: computed_value, computed_value, default=default)
 
-        return Spec(key, type, compute_inner_spec)
+        return Spec(key, type, compute_inner_spec, default=default)
 
 
 class svcEnum(str):

karrio/core/utils/helpers.py

@@ -8,15 +8,16 @@ import PyPDF2
 import asyncio
 import logging
 import urllib.parse
-from PIL import Image, ImageFile
+import PIL.Image
+import PIL.ImageFile
 from urllib.error import HTTPError
-from urllib.request import urlopen, Request
+from urllib.request import urlopen, Request, ProxyHandler, build_opener, install_opener
 from typing import List, TypeVar, Callable, Optional, Any, cast
 from concurrent.futures import ThreadPoolExecutor, as_completed
 
 logger = logging.getLogger(__name__)
 ssl._create_default_https_context = ssl._create_unverified_context
-ImageFile.LOAD_TRUNCATED_IMAGES = True
+PIL.ImageFile.LOAD_TRUNCATED_IMAGES = True
 T = TypeVar("T")
 S = TypeVar("S")
 NEW_LINE = """
@@ -46,10 +47,10 @@ def to_buffer(encoded_file: str, **kwargs) -> io.BytesIO:
 
 def image_to_pdf(image_str: str, rotate: int = None, resize: dict = None) -> str:
     buffer = to_buffer(image_str)
-    _image = Image.open(buffer)
+    _image = PIL.Image.open(buffer)
 
     image = (
-        _image.rotate(rotate, Image.NEAREST, expand=True)
+        _image.rotate(rotate, PIL.Image.Resampling.NEAREST, expand=True)
         if rotate is not None
         else _image
     )
@@ -58,12 +59,12 @@ def image_to_pdf(image_str: str, rotate: int = None, resize: dict = None) -> str
         img = image.copy()
         wpercent = resize["width"] / float(img.size[0])
         hsize = int((float(img.size[1]) * float(wpercent)))
-        image = img.resize((resize["width"], hsize), Image.Resampling.LANCZOS)
+        image = img.resize((resize["width"], hsize), PIL.Image.Resampling.LANCZOS)
 
     if resize is not None:
         img = image.copy()
         image = img.resize(
-            (resize["width"], resize["height"]), Image.Resampling.LANCZOS
+            (resize["width"], resize["height"]), PIL.Image.Resampling.LANCZOS
         )
 
     new_buffer = io.BytesIO()
@@ -82,17 +83,17 @@ def bundle_pdfs(base64_strings: List[str]) -> PyPDF2.PdfMerger:
     return merger
 
 
-def bundle_imgs(base64_strings: List[str]) -> Image:
+def bundle_imgs(base64_strings: List[str]):
     image_buffers = [
         io.BytesIO(base64.b64decode(b64_str)) for b64_str in base64_strings
     ]
-    images = [Image.open(buffer) for buffer in image_buffers]
+    images = [PIL.Image.open(buffer) for buffer in image_buffers]
     widths, heights = zip(*(i.size for i in images))
 
     max_width = max(widths)
     total_height = sum(heights)
 
-    image = Image.new("RGB", (max_width, total_height))
+    image = PIL.Image.new("RGB", (max_width, total_height))
 
     x_offset = 0
     for im in images:
@@ -161,6 +162,7 @@ def decode_bytes(byte):
 def process_request(
     request_id: str,
     trace: Callable[[Any, str], Any] = None,
+    proxy: str = None,
     **kwargs,
 ) -> Request:
     payload = (
@@ -181,6 +183,21 @@ def process_request(
 
     _request = Request(**{**kwargs, **payload})
 
+    # Apply proxy settings if provided: Proxy Example` 'username:password@IP_Address:Port'
+    if proxy:
+        proxy_info = proxy.split("@")
+        auth_info, host_port = proxy_info[0], proxy_info[1]
+        auth_info = urllib.parse.unquote(auth_info)
+        auth_encoded = base64.b64encode(auth_info.encode()).decode()
+        proxy_url = f"http://{host_port}"
+
+        # Create a ProxyHandler
+        proxy_handler = ProxyHandler({"http": proxy_url, "https": proxy_url})
+        opener = build_opener(proxy_handler)
+        opener.addheaders = [("Proxy-Authorization", f"Basic {auth_encoded}")]
+        install_opener(opener)
+        logger.info(f"Proxy set to: {proxy_url} with credentials")
+
     logger.info(f"Request URL:: {_request.full_url}")
 
     return _request
@@ -188,15 +205,16 @@ def process_request(
 
 def process_response(
     request_id: str,
-    response,
+    response: Any,
     decoder: Callable,
+    on_ok: Callable[[Any], str] = None,
     trace: Callable[[Any, str], Any] = None,
 ) -> str:
-    try:
-        _response = decoder(response)
-    except Exception as e:
-        logger.error(e)
-        _response = response
+    if on_ok is not None:
+        _response = on_ok(response)
+    else:
+        _data = response.read()
+        _response = failsafe(lambda: decoder(_data)) or _data
 
     if trace:
         _content = _response if isinstance(_response, str) else "undecoded bytes..."
@@ -230,23 +248,29 @@ def process_error(
 
 def request(
     decoder: Callable = decode_bytes,
+    on_ok: Callable[[Any], str] = None,
     on_error: Callable[[HTTPError], str] = None,
     trace: Callable[[Any, str], Any] = None,
+    proxy: str = None,
+    timeout: Optional[int] = None,
     **kwargs,
 ) -> str:
     """Return an HTTP response body.
 
     make a http request (wrapper around Request method from built in urllib)
+    Proxy example: 'Username:Password@IP_Address:Port'
     """
 
     _request_id = str(uuid.uuid4())
     logger.debug(f"sending request ({_request_id})...")
 
     try:
-        _request = process_request(_request_id, trace, **kwargs)
+        _request = process_request(_request_id, trace, proxy, **kwargs)
 
-        with urlopen(_request) as f:
-            _response = process_response(_request_id, f.read(), decoder, trace=trace)
+        with urlopen(_request, timeout=timeout) as f:
+            _response = process_response(
+                _request_id, f, decoder, on_ok=on_ok, trace=trace
+            )
 
     except HTTPError as e:
         _response = process_error(_request_id, e, on_error=on_error, trace=trace)
@@ -258,26 +282,45 @@ def exec_parrallel(
     function: Callable, sequence: List[S], max_workers: int = None
 ) -> List[T]:
     """Return a list of result for function execution on each element of the sequence."""
-    workers = len(sequence) or max_workers or 2
+    if not sequence:
+        return []  # No work to do
+
+    workers = min(len(sequence), max_workers or len(sequence))
+
     with ThreadPoolExecutor(max_workers=workers) as executor:
-        requests = {executor.submit(function, item): item for item in sequence}
-        return [response.result() for response in as_completed(requests)]
+        # Submit tasks
+        futures = [executor.submit(function, item) for item in sequence]
+
+        # Collect results as tasks complete
+        results = []
+        for future in as_completed(futures):
+            try:
+                results.append(future.result())  # Append result of the completed task
+            except Exception as e:
+                results.append(e)  # Optionally handle or log exceptions here
+
+        return results
 
 
 def exec_async(action: Callable, sequence: List[S]) -> List[T]:
-    async def run_tasks(loop):
+    async def run_tasks():
+        # Use asyncio.to_thread instead of loop.run_in_executor
+        # This ensures proper task scheduling and prevents potential task dropping
         return await asyncio.gather(
-            *[loop.run_in_executor(None, lambda: action(args)) for args in sequence]
+            *[asyncio.to_thread(action, args) for args in sequence]
         )
 
-    def run_loop():
-        loop = asyncio.new_event_loop()
-        result = loop.run_until_complete(run_tasks(loop))
-        loop.close()
+    async def run_loop():
+        # Simplified to just return the result of run_tasks
+        # No need for manual loop creation and closing
+        return await run_tasks()
 
-        return result
+    # Use asyncio.run instead of ThreadPoolExecutor
+    # This properly sets up and tears down the event loop
+    # Preventing issues with loop closure and task cleanup
+    result = asyncio.run(run_loop())
 
-    result = ThreadPoolExecutor().submit(run_loop).result()
+    # Cast the result to the expected type
     return cast(List[T], result)
 
 
@@ -295,8 +338,16 @@ class Location:
 
     @property
     def as_zip5(self) -> Optional[str]:
-        if not re.match(r"/^SW\d{5}$/", self.value or ""):
-            return self.value
+        if not self.value:
+            return None
+
+        # Try to extract exactly 5 digits
+        if match := re.search(r"\d{5}", self.value):
+            return match.group(0)
+
+        # If 4 digits, pad with 0
+        if match := re.search(r"\d{4}", self.value):
+            return f"{match.group(0)}0"
 
         return None
 

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