sibi-dst 2025.1.13__py3-none-any.whl → 2025.8.2__py3-none-any.whl

sibi_dst/utils/base.py

@@ -1,117 +1,252 @@
-import asyncio
-from .log_utils import Logger
+import abc
+import threading
+import weakref
+from typing import Self, Optional, Callable
 
-class ManagedResource:
-    """
-    A base class providing context management for resources like loggers and filesystems.
+import fsspec
+
+from sibi_dst.utils import Logger
 
-    It handles the creation and cleanup of these resources, ensuring they are only
-    closed if they were created by the instance itself.
-    """
 
-    def __init__(self, **kwargs):
-        self.debug = kwargs.get("debug", False)
-        self.verbose = kwargs.get("verbose", False)
+class ManagedResource(abc.ABC):
+    """
+    Boilerplate ABC for components that manage a logger and an optional fsspec filesystem,
+    with sync/async lifecycle helpers, lazy FS creation via an optional factory, and
+    configurable cleanup-error logging.
+    """
 
-        # --- Logger Management (Refactored) ---
-        logger = kwargs.get("logger")
-        if logger:
-            # An existing logger instance was provided by the user
+    def __init__(
+        self,
+        *,
+        verbose: bool = False,
+        debug: bool = False,
+        log_cleanup_errors: bool = True,
+        logger: Optional[Logger] = None,
+        fs: Optional[fsspec.AbstractFileSystem] = None,
+        fs_factory: Optional[Callable[[], fsspec.AbstractFileSystem]] = None,
+        **_: object,
+    ) -> None:
+        # ---- Declared upfront for type checkers
+        self.logger: Logger
+        self.fs: Optional[fsspec.AbstractFileSystem] = None
+        self._fs_factory: Optional[Callable[[], fsspec.AbstractFileSystem]] = None
+        self._owns_logger: bool = False
+        self._owns_fs: bool = False
+        self._is_closed: bool = False
+        self._closing: bool = False
+        self._close_lock = threading.RLock()
+
+        self.verbose = verbose
+        self.debug = debug
+        self._log_cleanup_errors = log_cleanup_errors
+
+        # ---- Logger ownership
+        if logger is None:
+            self.logger = Logger.default_logger(logger_name=self.__class__.__name__)
+            self._owns_logger = True
+            level = Logger.DEBUG if self.debug else (Logger.INFO if self.verbose else Logger.WARNING)
+            self.logger.set_level(level)
+        else:
             self.logger = logger
-            self._own_logger = False
-            self.logger.debug(f"'{self.__class__.__name__}' is tapping into an existing logger.")
+            self._owns_logger = False  # do not mutate external logger
+
+        # ---- FS ownership & lazy creation
+        if fs is not None:
+            self.fs = fs
+            self._owns_fs = False
+            self._fs_factory = None
+        elif fs_factory is not None:
+            # Lazy: don't create until first use
+            self._fs_factory = fs_factory
+            self._owns_fs = True  # we will own it *if* created
+            self.fs = None
         else:
-            # No pre-configured logger, so we will create and "own" a new one.
-            self._own_logger = True
-            logger_config = kwargs.get("logger_config", {})
-
-            # Set default logger_name if not specified in the config
-            logger_config.setdefault("logger_name", self.__class__.__name__)
+            self.fs = None
+            self._owns_fs = False
+            self._fs_factory = None
 
-            # Set log_level based on debug flag, but respect user-provided level
-            default_level = Logger.DEBUG if self.debug else Logger.INFO
-            logger_config.setdefault("log_level", default_level)
+        # Register a GC-time finalizer that does not capture self
+        self_ref = weakref.ref(self)
+        self._finalizer = weakref.finalize(self, self._finalize_static, self_ref)
 
-            # Create the logger using the provided or default configuration
-            self.logger = Logger.default_logger(**logger_config)
-            if self.logger:
-                self.logger.debug(f"'{self.__class__.__name__}' is starting its own logger.")
+        if self.debug:
+            try:
+                self.logger.debug("Component %s initialized. %s", self.__class__.__name__, repr(self))
+            except Exception:
+                pass
 
-        fs = kwargs.get("fs")
-        self._own_fs = fs is None
-        self.fs = fs or None # we want to allow None as a valid fs to trigger a failure if needed
+    # ---------- Introspection ----------
+    @property
+    def is_closed(self) -> bool:
+        return self._is_closed
 
-        self._entered = False
+    @property
+    def closed(self) -> bool:  # alias
+        return self._is_closed
 
-    def __enter__(self):
-        """Enter the runtime context."""
-        self._entered = True
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        logger_status = "own" if self._owns_logger else "external"
+        if self.fs is None and self._fs_factory is not None:
+            fs_status = "own(lazy)"
+        elif self.fs is None:
+            fs_status = "none"
+        else:
+            fs_status = "own" if self._owns_fs else "external"
+        return (f"<{class_name} debug={self.debug} verbose={self.verbose} "
+                f"log_cleanup_errors={self._log_cleanup_errors} "
+                f"logger={logger_status} fs={fs_status}>")
+
+    # ---------- Subclass hooks ----------
+    def _cleanup(self) -> None:
+        """Sync cleanup for resources created BY THE SUBCLASS."""
+        return
+
+    async def _acleanup(self) -> None:
+        """Async cleanup for resources created BY THE SUBCLASS."""
+        return
+
+    # ---------- FS helpers ----------
+    def _ensure_fs(self) -> Optional[fsspec.AbstractFileSystem]:
+        """Create the FS lazily if a factory was provided. Return fs (or None)."""
+        if self.fs is None and self._fs_factory is not None:
+            created = self._fs_factory()
+            if not isinstance(created, fsspec.AbstractFileSystem):
+                raise TypeError(f"fs_factory() must return fsspec.AbstractFileSystem, got {type(created)!r}")
+            self.fs = created
+            # _owns_fs already True when factory is present
+        return self.fs
+
+    def require_fs(self) -> fsspec.AbstractFileSystem:
+        """Return a filesystem or raise if not configured/creatable."""
+        fs = self._ensure_fs()
+        if fs is None:
+            raise RuntimeError(
+                f"{self.__class__.__name__}: filesystem is required but not configured"
+            )
+        return fs
+
+    # ---------- Shared shutdown helpers (no logging; safe for late shutdown) ----------
+    def _release_owned_fs(self) -> None:
+        if self._owns_fs:
+            # ensure creation state is respected even if never used
+            _ = self.fs or None  # no-op; if never created, nothing to close
+            if self.fs is not None:
+                close = getattr(self.fs, "close", None)
+                try:
+                    if callable(close):
+                        close()
+                finally:
+                    self.fs = None
+
+    def _shutdown_logger(self) -> None:
+        if self._owns_logger:
+            try:
+                self.logger.shutdown()
+            except Exception:
+                pass
+
+    def _shutdown_owned_resources(self) -> None:
+        self._release_owned_fs()
+        self._shutdown_logger()
+
+    # ---------- Public lifecycle (sync) ----------
+    def close(self) -> None:
+        with self._close_lock:
+            if self._is_closed or self._closing:
+                return
+            self._closing = True
+
+        try:
+            self._cleanup()
+        except Exception:
+            # Only include traceback when debug=True
+            if self._log_cleanup_errors:
+                try:
+                    self.logger.error(
+                        "Error during %s._cleanup()", self.__class__.__name__,
+                        exc_info=self.debug
+                    )
+                except Exception:
+                    pass
+            raise
+        finally:
+            with self._close_lock:
+                self._is_closed = True
+                self._closing = False
+            self._shutdown_owned_resources()
+            if self.debug:
+                try:
+                    self.logger.debug("Component %s closed.", self.__class__.__name__)
+                except Exception:
+                    pass
+
+    # ---------- Public lifecycle (async) ----------
+    async def aclose(self) -> None:
+        with self._close_lock:
+            if self._is_closed or self._closing:
+                return
+            self._closing = True
+
+        try:
+            await self._acleanup()
+        except Exception:
+            # Only include traceback when debug=True
+            if self._log_cleanup_errors:
+                try:
+                    self.logger.error(
+                        "Error during %s._acleanup()", self.__class__.__name__,
+                        exc_info=self.debug
+                    )
+                except Exception:
+                    pass
+            raise
+        finally:
+            with self._close_lock:
+                self._is_closed = True
+                self._closing = False
+            self._shutdown_owned_resources()
+            if self.debug:
+                try:
+                    self.logger.debug("Async component %s closed.", self.__class__.__name__)
+                except Exception:
+                    pass
+
+    # ---------- Context managers ----------
+    def __enter__(self) -> Self:
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        """Exit the runtime context and trigger cleanup."""
-        self.cleanup()
-        return False  # Propagate exceptions
-
-    # --- Asynchronous Context Management ---
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self.close()
+        return False  # propagate exceptions
 
-    async def __aenter__(self):
-        """Enter the runtime context for 'async with' statements."""
-        self._entered = True
+    async def __aenter__(self) -> Self:
         return self
 
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Exit the runtime context and trigger cleanup for 'async with' statements."""
-        await self.acleanup()
-        return False  # Propagate exceptions
-
-    def __repr__(self) -> str:
-        """Return an unambiguous string representation of the ManagedResource."""
-        # Dynamically get the name of the class or subclass
-        class_name = self.__class__.__name__
-
-        # Determine the status of the logger and filesystem
-        logger_status = "own" if self._own_logger else "external"
-        fs_status = "own" if self._own_fs else "external"
-
-        return (
-            f"<{class_name} debug={self.debug}, "
-            f"logger='{logger_status}', fs='{fs_status}'>"
-        )
-
-    def cleanup(self):
-        """
-        Cleanup resources managed by this instance.
-        """
-        if self._own_fs and hasattr(self.fs, "clear_instance_cache"):
-            if self.logger:
-                self.logger.debug(f"'{self.__class__.__name__}' is clearing its own filesystem cache.")
-            self.fs.clear_instance_cache()
-
-        if self._own_logger and hasattr(self.logger, "shutdown"):
-            # Ensure the logger exists before trying to use or shut it down
-            if self.logger:
-                self.logger.debug(f"'{self.__class__.__name__}' is shutting down its own logger.")
-                self.logger.shutdown()
-            self.logger = None  # Set to None after shutdown
-
-        self._entered = False
-
-    async def acleanup(self):
-        """
-        Async Cleanup resources managed by this instance.
-        """
-        if self._own_fs and hasattr(self.fs, "clear_instance_cache"):
-            if self.logger:
-                self.logger.debug(f"'{self.__class__.__name__}' is clearing its own filesystem cache.")
-            self.fs.clear_instance_cache()
-
-        if self._own_logger and hasattr(self.logger, "shutdown"):
-            # Ensure the logger exists before trying to use or shut it down
-            if self.logger:
-                self.logger.debug(f"'{self.__class__.__name__}' is shutting down its own logger.")
-                self.logger.shutdown()
-            self.logger = None  # Set to None after shutdown
-
-        self._entered = False
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        await self.aclose()
+        return False
+
+    # ---------- Finalizer ( at Garbage Collection-time absolutely silent) ----------
+    @staticmethod
+    def _finalize_static(ref: "weakref.ReferenceType[ManagedResource]") -> None:
+        obj = ref()
+        if obj is None:
+            return
+        # No logging here; interpreter may be tearing down.
+        # Best-effort silent cleanup; avoid locks and context managers.
+        try:
+            if not obj._is_closed:
+                try:
+                    obj._cleanup()
+                except Exception:
+                    pass
+                obj._is_closed = True
+                try:
+                    obj._shutdown_owned_resources()
+                except Exception:
+                    pass
+        except Exception:
+            # do not show anything at garbage collection time
+            pass
 

sibi_dst/utils/business_days.py

@@ -0,0 +1,248 @@
+import datetime as dt
+from typing import Any, Dict, Iterable, Optional
+from sibi_dst.utils import Logger
+import numpy as np
+import pandas as pd
+import dask.dataframe as dd
+
+
+# ---------------- Vectorized helpers (used by Dask map_partitions) ----------------
+
+def _to_np_days(series: pd.Series) -> np.ndarray:
+    """Coerce to numpy datetime64[D] with NaT-safe conversion."""
+    # Use pandas for robust parsing, then cast to date-days
+    s = pd.to_datetime(series, errors="coerce")
+    # Convert to numpy datetime64[D] (day precision)
+    return s.values.astype("datetime64[D]")
+
+
+def _vectorized_busday_count(
+        part: pd.DataFrame,
+        begin_col: str,
+        end_col: str,
+        holidays: Iterable[str],
+        weekmask: Optional[str],
+        inclusive: bool,
+) -> pd.Series:
+    start = _to_np_days(part[begin_col])  # numpy datetime64[D]
+    end = _to_np_days(part[end_col])  # numpy datetime64[D]
+
+    kwargs: Dict[str, Any] = {}
+    if holidays:
+        kwargs["holidays"] = np.array(list(holidays), dtype="datetime64[D]")
+    if weekmask:
+        kwargs["weekmask"] = weekmask
+
+    end_adj = end
+    if inclusive:
+        with np.errstate(invalid="ignore"):
+            end_adj = end + np.timedelta64(1, "D")
+
+    valid = (~pd.isna(start)) & (~pd.isna(end))  # numpy bool mask
+    result = np.full(part.shape[0], np.nan, dtype="float64")
+    if valid.any():
+        counts = np.busday_count(
+            start[valid].astype("datetime64[D]"),
+            end_adj[valid].astype("datetime64[D]"),
+            **kwargs,
+        ).astype("float64")
+        result[valid] = counts
+
+    return pd.Series(result, index=part.index)
+
+
+def _vectorized_busday_offset(
+        part: pd.DataFrame,
+        start_col: str,
+        n_days_col: str,
+        holidays: Iterable[str],
+        weekmask: Optional[str],
+        roll: str,
+) -> pd.Series:
+    start = _to_np_days(part[start_col])  # numpy datetime64[D]
+    n_days = pd.to_numeric(part[n_days_col], errors="coerce").to_numpy()  # numpy float -> cast later
+
+    kwargs: Dict[str, Any] = {"roll": roll}
+    if holidays:
+        kwargs["holidays"] = np.array(list(holidays), dtype="datetime64[D]")
+    if weekmask:
+        kwargs["weekmask"] = weekmask
+
+    valid = (~pd.isna(start)) & (~pd.isna(n_days))  # numpy bool mask
+    out = np.full(part.shape[0], np.datetime64("NaT", "ns"), dtype="datetime64[ns]")
+    if valid.any():
+        offs = np.busday_offset(
+            start[valid].astype("datetime64[D]"),
+            n_days[valid].astype("int64"),
+            **kwargs,
+        ).astype("datetime64[ns]")
+        out[valid] = offs
+
+    return pd.Series(out, index=part.index)
+
+
+# ---------------- BusinessDays ----------------
+
+class BusinessDays:
+    """
+    Business day calculations with custom holidays and optional weekmask.
+
+    Features
+    - Scalar helpers:
+        - get_business_days_count(begin, end, inclusive=False) -> int
+        - add_business_days(start_date, n_days, roll='forward') -> np.datetime64
+    - Dask DataFrame helpers (vectorized via map_partitions):
+        - calc_business_days_from_df(df, begin_col, end_col, result_col='business_days', inclusive=False)
+        - calc_sla_end_date(df, start_date_col, n_days_col, result_col='sla_end_date', roll='forward')
+
+    Parameters
+    ----------
+    holiday_list : dict[str, list[str]] | Iterable[str]
+        Either a mapping of year -> [YYYY-MM-DD, ...] or a flat iterable of YYYY-MM-DD strings.
+    logger : Any
+        Logger with .debug/.info/.warning/.error.
+    weekmask : str | None
+        A numpy business day weekmask like '1111100' (Mon–Fri). None means default Mon–Fri.
+        Examples:
+            '1111100' -> Mon-Fri
+            '1111110' -> Mon-Sat
+    """
+
+    def __init__(
+            self,
+            holiday_list: Dict[str, list[str]] | Iterable[str],
+            debug: bool = False,
+            logger: Optional[Logger] = None,
+            weekmask: Optional[str] = None,
+    ) -> None:
+        self.debug = debug
+        self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
+        self.weekmask = weekmask
+
+        # Normalize holidays to a flat, sorted tuple of 'YYYY-MM-DD'
+        if isinstance(holiday_list, dict):
+            flat = [d for _, days in sorted(holiday_list.items()) for d in days]
+        else:
+            flat = list(holiday_list)
+        # Deduplicate while preserving order
+        seen = set()
+        flat_unique = []
+        for d in flat:
+            if d not in seen:
+                seen.add(d)
+                flat_unique.append(d)
+        self.holidays: tuple[str, ...] = tuple(flat_unique)
+
+    # -------- Scalar API --------
+
+    def get_business_days_count(
+            self,
+            begin_date: str | dt.date | pd.Timestamp,
+            end_date: str | dt.date | pd.Timestamp,
+            *,
+            inclusive: bool = False,
+    ) -> int:
+        """Business days between two dates. If inclusive=True, include the end date."""
+        b = pd.to_datetime(begin_date).date()
+        e = pd.to_datetime(end_date).date()
+
+        kwargs: Dict[str, Any] = {}
+        if self.holidays:
+            kwargs["holidays"] = np.array(self.holidays, dtype="datetime64[D]")
+        if self.weekmask:
+            kwargs["weekmask"] = self.weekmask
+
+        if inclusive:
+            e_np = np.datetime64(e) + np.timedelta64(1, "D")
+        else:
+            e_np = np.datetime64(e)
+
+        val = int(np.busday_count(np.datetime64(b), e_np, **kwargs))
+        return val
+
+    def add_business_days(
+            self,
+            start_date: str | dt.date | pd.Timestamp,
+            n_days: int,
+            *,
+            roll: str = "forward",
+    ) -> np.datetime64:
+        """
+        Add (or subtract) business days to a date. Returns numpy datetime64[D].
+        roll: {'forward','backward','following','preceding','modifiedfollowing',
+               'modifiedpreceding','nat'}
+        """
+        s = pd.to_datetime(start_date).date()
+        kwargs: Dict[str, Any] = {"roll": roll}
+        if self.holidays:
+            kwargs["holidays"] = np.array(self.holidays, dtype="datetime64[D]")
+        if self.weekmask:
+            kwargs["weekmask"] = self.weekmask
+
+        return np.busday_offset(np.datetime64(s), int(n_days), **kwargs)
+
+    # -------- Dask API --------
+
+    def calc_business_days_from_df(
+            self,
+            df: dd.DataFrame,
+            begin_date_col: str,
+            end_date_col: str,
+            result_col: str = "business_days",
+            *,
+            inclusive: bool = False,
+    ) -> dd.DataFrame:
+        """
+        Vectorized business-day difference between two date columns.
+        Produces float64 (NaN where either side is missing).
+        """
+        missing = {begin_date_col, end_date_col} - set(df.columns)
+        if missing:
+            self.logger.error(f"Missing columns: {missing}")
+            raise ValueError("Required columns are missing from DataFrame")
+
+        return df.assign(
+            **{
+                result_col: df.map_partitions(
+                    _vectorized_busday_count,
+                    begin_col=begin_date_col,
+                    end_col=end_date_col,
+                    holidays=self.holidays,
+                    weekmask=self.weekmask,
+                    inclusive=inclusive,
+                    meta=(result_col, "f8"),
+                )
+            }
+        )
+
+    def calc_sla_end_date(
+            self,
+            df: dd.DataFrame,
+            start_date_col: str,
+            n_days_col: str,
+            result_col: str = "sla_end_date",
+            *,
+            roll: str = "forward",
+    ) -> dd.DataFrame:
+        """
+        Vectorized business-day offset for SLA end date.
+        Produces datetime64[ns] with NaT where invalid.
+        """
+        missing = {start_date_col, n_days_col} - set(df.columns)
+        if missing:
+            self.logger.error(f"Missing columns: {missing}")
+            raise ValueError("Required columns are missing from DataFrame")
+
+        return df.assign(
+            **{
+                result_col: df.map_partitions(
+                    _vectorized_busday_offset,
+                    start_col=start_date_col,
+                    n_days_col=n_days_col,
+                    holidays=self.holidays,
+                    weekmask=self.weekmask,
+                    roll=roll,
+                    meta=(result_col, "datetime64[ns]"),
+                )
+            }
+        )