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

karrio/core/utils/__init__.py

@@ -7,7 +7,7 @@ from karrio.core.utils.datetime import DATEFORMAT as DF
 from karrio.core.utils.xml import XMLPARSER as XP, Element
 from karrio.core.utils.serializable import Serializable, Deserializable
 from karrio.core.utils.pipeline import Pipeline, Job
-from karrio.core.utils.enum import Enum, Flag, OptionEnum, svcEnum
+from karrio.core.utils.enum import Enum, Flag, StrEnum, OptionEnum, svcEnum
 from karrio.core.utils.tracing import Tracer, Record, Trace
 from karrio.core.utils.transformer import to_multi_piece_rates, to_multi_piece_shipment
 from karrio.core.utils.caching import Cache

karrio/core/utils/datetime.py

@@ -1,14 +1,14 @@
-from typing import Union, List
-from datetime import datetime
+import typing
+from datetime import datetime, timedelta, timezone
 
 
 class DATEFORMAT:
     @staticmethod
     def date(
-        date_value: Union[str, int, datetime] = None,
+        date_value: typing.Union[str, int, datetime] = None,
         current_format: str = "%Y-%m-%d",
-        try_formats: List[str] = None,
-    ) -> datetime:
+        try_formats: typing.List[str] = None,
+    ) -> typing.Optional[datetime]:
         if date_value is None:
             return None
 
@@ -30,11 +30,58 @@ 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: Union[str, int, datetime] = None,
+        date_str: typing.Union[str, int, datetime] = None,
         current_format: str = "%Y-%m-%d",
-        try_formats: List[str] = None,
+        try_formats: typing.List[str] = None,
     ):
         date = DATEFORMAT.date(
             date_str, current_format=current_format, try_formats=try_formats
@@ -45,13 +92,15 @@ class DATEFORMAT:
 
     @staticmethod
     def fdatetime(
-        date_str: Union[str, int, datetime] = None,
+        date_str: typing.Union[str, int, datetime] = None,
         current_format: str = "%Y-%m-%d %H:%M:%S",
         output_format: str = "%Y-%m-%d %H:%M:%S",
-        try_formats: List[str] = None,
+        try_formats: typing.List[str] = None,
     ):
         date = DATEFORMAT.date(
-            date_str, current_format=current_format, try_formats=try_formats
+            date_str,
+            current_format=current_format,
+            try_formats=try_formats,
         )
         if date is None:
             return None
@@ -62,7 +111,7 @@ class DATEFORMAT:
         time_str: str,
         current_format: str = "%H:%M:%S",
         output_format: str = "%H:%M",
-        try_formats: List[str] = None,
+        try_formats: typing.List[str] = None,
     ):
         time = DATEFORMAT.date(
             time_str, current_format=current_format, try_formats=try_formats
@@ -72,7 +121,20 @@ class DATEFORMAT:
         return time.strftime(output_format)
 
     @staticmethod
-    def ftimestamp(timestamp: Union[str, int] = None):
+    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,9 +1,11 @@
 import attr
-from typing import Optional, Type, Any, Callable, cast
-from enum import Enum as BaseEnum, Flag as BaseFlag, EnumMeta
+import enum
+import typing
 
+BaseStrEnum = getattr(enum, "StrEnum", enum.Flag)
 
-class MetaEnum(EnumMeta):
+
+class MetaEnum(enum.EnumMeta):
     def __contains__(cls, item):
         if item is None:
             return False
@@ -12,15 +14,21 @@ class MetaEnum(EnumMeta):
 
         return super().__contains__(item)
 
-    def map(cls, key: Any):
+    def map(cls, key: typing.Any):
         if key in cls:
             return EnumWrapper(key, cls[key])
-        elif key in cast(Any, cls)._value2member_map_:
+        elif key in typing.cast(typing.Any, cls)._value2member_map_:
             return EnumWrapper(key, cls(key))
-        elif key in [str(v.value) for v in cast(Any, cls).__members__.values()]:
+        elif key in [
+            str(v.value) for v in typing.cast(typing.Any, cls).__members__.values()
+        ]:
             return EnumWrapper(
                 key,
-                next(v for v in cast(Any, cls).__members__.values() if v.value == key),
+                next(
+                    v
+                    for v in typing.cast(typing.Any, cls).__members__.values()
+                    if v.value == key
+                ),
             )
 
         return EnumWrapper(key)
@@ -29,18 +37,22 @@ class MetaEnum(EnumMeta):
         return {name: enum.value for name, enum in self.__members__.items()}
 
 
-class Enum(BaseEnum, metaclass=MetaEnum):
+class Enum(enum.Enum, metaclass=MetaEnum):
     pass
 
 
-class Flag(BaseFlag, metaclass=MetaEnum):
+class Flag(enum.Flag, metaclass=MetaEnum):
+    pass
+
+
+class StrEnum(BaseStrEnum, metaclass=MetaEnum):  # type: ignore
     pass
 
 
 @attr.s(auto_attribs=True)
 class EnumWrapper:
-    key: Any
-    enum: Optional[Enum] = None
+    key: typing.Any
+    enum: typing.Optional[Enum] = None
 
     @property
     def name(self):
@@ -65,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: Callable = str
-    state: Any = None
+    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, self.default)
 
-    def __getitem__(self, type: Callable = None) -> "OptionEnum":
-        return OptionEnum("", type or self.type, self.state)
+    def __call__(self, value: typing.Any = None) -> "OptionEnum":
+        """Create a new OptionEnum instance with the specified value.
 
-    def __call__(self, value: Any = None) -> "OptionEnum":
+        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: Type
-    compute: Callable
-    value: Any = None
+    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: Optional[bool]) -> bool:
+        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: Optional[bool]) -> str:
+        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: Type = str) -> "Spec":
-        """A Spec defined as "Type" means that when it is specified in a payload,
+    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: Optional[type]) -> type:  # type: ignore
+        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: 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: Optional[type]) -> Spec:  # type: ignore
+        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

@@ -4,19 +4,20 @@ import ssl
 import uuid
 import string
 import base64
+import PyPDF2
 import asyncio
 import logging
 import urllib.parse
-from PyPDF2 import PdfMerger
-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()
@@ -72,8 +73,8 @@ def image_to_pdf(image_str: str, rotate: int = None, resize: dict = None) -> str
     return base64.b64encode(new_buffer.getvalue()).decode("utf-8")
 
 
-def bundle_pdfs(base64_strings: List[str]) -> PdfMerger:
-    merger = PdfMerger(strict=False)
+def bundle_pdfs(base64_strings: List[str]) -> PyPDF2.PdfMerger:
+    merger = PyPDF2.PdfMerger(strict=False)
 
     for b64_str in base64_strings:
         buffer = to_buffer(b64_str)
@@ -82,17 +83,17 @@ def bundle_pdfs(base64_strings: List[str]) -> 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:
@@ -144,6 +145,12 @@ def zpl_to_pdf(zpl_str: str, width: int, height: int, dpmm: int = 12) -> str:
     return doc
 
 
+def binary_to_base64(binary_str: str) -> str:
+    buffer = to_buffer(binary_str)
+
+    return base64.b64encode(buffer.getvalue()).decode("utf-8")
+
+
 def decode_bytes(byte):
     return (
         failsafe(lambda: byte.decode("utf-8"))
@@ -155,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 = (
@@ -175,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
@@ -182,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..."
@@ -224,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)
@@ -252,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)
 
 
@@ -289,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