tdfs4ds 0.2.4.32__py3-none-any.whl → 0.2.4.34__py3-none-any.whl

tdfs4ds/utils/filter_management.py

@@ -2,7 +2,7 @@ import datetime
 import numpy as np  # Needed for np.datetime64 handling in get_date_in_the_past
 import teradataml as tdml
 import tdfs4ds
-from tdfs4ds import logger
+from tdfs4ds import logger, logger_safe
 
 
 def get_hidden_table_name(table_name):
@@ -20,24 +20,60 @@ def get_hidden_table_name(table_name):
 
 class FilterManager:
     """
-    Manage dynamic, filter-driven views over a Teradata table.
-
-    This class maintains a hidden table that stores one or more *filters* (one row
-    per filter definition) and exposes a public view whose SELECT projects the
-    columns from the hidden table for the currently-active filter ID. You can load
-    new filters, switch which filter the view points at, prune older filters, and
-    (optionally) include a time dimension via a `BUSINESS_DATE` column.
+    A utility for managing dynamic, versioned filter sets as database-backed views.
+
+    The FilterManager enables lightweight scenario management by storing multiple
+    filter definitions in a hidden Teradata table and exposing a public view that
+    dynamically switches between them by `filter_id`. Each row in the hidden table
+    represents a complete filter configuration. The active configuration is
+    controlled by updating the view definition rather than rewriting table data.
+
+    Key Features:
+        - Store multiple filter states (scenarios) indexed by `filter_id`
+        - Switch filter states instantly by updating a view
+        - Optionally include time-based slicing using a `BUSINESS_DATE` column
+        - Clone filters between managers (soft or hard clone modes)
+        - Prune obsolete filters to control table size
+        - Retrieve current and historical filter definitions
+
+    Workflow Overview:
+        1. Create a `FilterManager` pointing to a target view name.
+        2. Load one or more filter definitions using `load_filter()`.
+        3. Switch active filters using `update(filter_id)`.
+        4. Inspect the active filter via `display()` or view DDL.
+        5. Optionally prune or clone filters as needed.
+
+    How It Works Internally:
+        - A hidden table named `<view_name>_HIDDEN` stores filter definitions.
+        - A Teradata view named `<view_name>` exposes only the *active* filter row.
+        - Each filter automatically receives a sequential `filter_id`
+          (`ROW_NUMBER()` ordering ensures deterministic assignment).
+        - If time-based filtering is used via `time_column`, a `BUSINESS_DATE`
+          column is added and projected in all operations.
+
+    Parameters:
+        table_name (str): Public view name to manage or create.
+        schema_name (str): Teradata schema where artifacts will be created.
+        filter_id_name (str, optional): Name of the filter ID column. Defaults to `'filter_id'`.
+        time_column (str, optional): Optional name of a timestamp column from input DataFrames
+            that maps to a `BUSINESS_DATE` column for time-aware filters.
 
     Attributes:
-        schema_name (str): Database schema that contains the hidden table and public view.
-        table_name (str): Hidden table name where filter rows are stored.
-        view_name (str): Public view name pointing at the currently active filter row.
-        filter_id_name (str): Column name containing the filter identifier (default 'filter_id').
-        nb_filters (int | None): Number of filters currently stored (max filter_id). Populated when objects exist.
-        col_names (list[str] | None): Columns projected by the view (excludes filter-id and time column).
-        time_filtering (bool | None): Whether a `BUSINESS_DATE` column is present/used.
+        schema_name (str): Target schema for view and hidden table.
+        table_name (str): Name of hidden table storing filters (auto-suffixed with `_HIDDEN`).
+        view_name (str): Name of public view pointing to current filter.
+        filter_id_name (str): Column containing filter ID.
+        nb_filters (int | None): Number of stored filters (None until initialized).
+        col_names (list[str] | None): Columns projected by the view (data columns only).
+        time_filtering (bool | None): True if time-based filtering enabled.
+
+    Notes:
+        - Database objects are only created when `load_filter()` is first called.
+        - Safe for iterative pipeline runs—auto-detects existing artifacts.
+        - Designed for large production tables and Teradata-native workflows.
     """
 
+
     def __init__(self, table_name, schema_name, filter_id_name="filter_id", time_column=None):
         """
         Initialize the FilterManager.
@@ -46,15 +82,6 @@ class FilterManager:
         filter id, and time filtering status) are detected and cached. If they do
         not exist yet, attributes are initialized but no objects are created until
         `load_filter()` is called.
-
-        Args:
-            table_name (str): Public view name to maintain.
-            schema_name (str): Schema where the view and hidden table live.
-            filter_id_name (str, optional): Name of the filter id column. Defaults to 'filter_id'.
-            time_column (str, optional): If provided, indicates the source column
-                in incoming DataFrames to copy into `BUSINESS_DATE` during `load_filter()`.
-                (Note: this parameter is remembered but the actual `BUSINESS_DATE`
-                column is only created/used when `load_filter(time_column=...)` is called.)
         """
         self.schema_name = schema_name
         self.table_name = get_hidden_table_name(table_name)
@@ -63,46 +90,45 @@ class FilterManager:
         self.nb_filters = None
         self.col_names = None
         self.time_filtering = None
-        self._init_time_column = time_column  # remember user hint for later `load_filter` calls
+        self._init_time_column = time_column  # Remember user hint for later
 
-        logger.debug(
-            "Initializing FilterManager",
-            extra={
-                "schema_name": self.schema_name,
-                "view_name": self.view_name,
-                "table_name": self.table_name,
-                "filter_id_name": self.filter_id_name,
-            },
+        logger_safe(
+            "debug",
+            "Initializing FilterManager | schema_name=%s | view_name=%s | table_name=%s | filter_id_name=%s",
+            self.schema_name, self.view_name, self.table_name, self.filter_id_name
         )
 
         if self._exists():
-            logger.info(
-                "Existing filter artifacts detected.",
-                extra={"schema_name": self.schema_name, "view_name": self.view_name, "table_name": self.table_name},
+            logger_safe(
+                "info",
+                "Existing filter artifacts detected | schema_name=%s | view_name=%s | table_name=%s",
+                self.schema_name, self.view_name, self.table_name
             )
+
             df = tdml.DataFrame(tdml.in_schema(self.schema_name, self.table_name))
-            # First column is assumed to be the filter id
-            self.filter_id_name = df.columns[0]
+            self.filter_id_name = df.columns[0]  # First column is assumed to be filter id
+
             self.nb_filters = tdml.execute_sql(
                 f"SEL MAX({self.filter_id_name}) AS nb_filters FROM {self.schema_name}.{self.table_name}"
             ).fetchall()[0][0]
+
             self.time_filtering = self._istimefiltering()
             self.col_names = df.columns[2:] if self.time_filtering else df.columns[1:]
-            logger.debug(
-                "Detected existing configuration.",
-                extra={
-                    "filter_id_name": self.filter_id_name,
-                    "nb_filters": self.nb_filters,
-                    "time_filtering": self.time_filtering,
-                    "col_names": list(self.col_names),
-                },
+
+            logger_safe(
+                "debug",
+                "Detected existing configuration | filter_id_name=%s | nb_filters=%s | time_filtering=%s | col_names=%s",
+                self.filter_id_name, self.nb_filters, self.time_filtering, list(self.col_names)
             )
+
         else:
-            logger.info(
-                "No existing filter artifacts found; will be created by load_filter().",
-                extra={"schema_name": self.schema_name, "view_name": self.view_name, "table_name": self.table_name},
+            logger_safe(
+                "info",
+                "No existing filter artifacts found; will be created by load_filter() | schema_name=%s | view_name=%s",
+                self.schema_name, self.view_name
             )
 
+
     def _istimefiltering(self):
         """
         Determine if the hidden table includes a `BUSINESS_DATE` column.
@@ -148,7 +174,7 @@ class FilterManager:
         Raises:
             ValueError: If `time_column` is provided but not present in `df`.
         """
-        logger.info("Loading filters", extra={"rows": len(df), "time_column": time_column})
+        logger.info("Loading filters", extra={"rows": df.shape[0], "time_column": time_column})
 
         if time_column and time_column not in df.columns:
             logger.error("Specified time_column not found in DataFrame.", extra={"time_column": time_column})
@@ -263,15 +289,17 @@ class FilterManager:
         Raises:
             ValueError: If filter artifacts do not exist yet.
         """
-        logger.info("Updating active filter", extra={"filter_id": filter_id})
+        
 
         if not self._exists():
-            logger.error("Filter artifacts not initialized.")
+            logger_safe("error", "Filter artifacts not initialized.")
             raise ValueError("The filter has not been initialized with load_filter() or has been deleted.")
 
         if self.time_filtering:
+            select_cols_str  = ["BUSINESS_DATE"] + list(self.col_names)
             select_cols = ",".join(["BUSINESS_DATE"] + list(self.col_names))
         else:
+            select_cols_str = list(self.col_names)
             select_cols = ",".join(self.col_names)
 
         query = f"""
@@ -280,8 +308,14 @@ class FilterManager:
         FROM {self.schema_name}.{self.table_name}
         WHERE {self.filter_id_name} = {filter_id}
         """
-        logger.debug("Replacing view with new filter", extra={"query": query})
+        logger_safe("info", "Updating active filter | %s", ','.join([f"{c}:{v}" for c,v in zip(select_cols_str, tdml.execute_sql(f"SEL * FROM {self.schema_name}.{self.view_name}").fetchall()[0])]))
+
+        if getattr(tdfs4ds, "DEBUG_MODE", False):
+            logger_safe("debug", "Replacing view with new filter:\n%s", query)
+
         tdml.execute_sql(query)
+        logger_safe("debug", "View %s.%s updated to filter_id=%s", self.schema_name, self.view_name, filter_id)
+
 
     def display(self):
         """

tdfs4ds/utils/time_management.py

@@ -1,6 +1,6 @@
 import teradataml as tdml
 import datetime
-from tdfs4ds import logger
+from tdfs4ds import logger, logger_safe
 import re
 
 import tdfs4ds
@@ -22,23 +22,62 @@ def get_hidden_table_name(table_name: str) -> str:
 
 class TimeManager:
     """
-    Manage time-step metadata for a Teradata table and a companion view.
-
-    This class maintains a hidden physical table (``<view>_HIDDEN``) that stores
-    sequential time steps (``TIME_ID``) mapped to a business date/time
-    (``BUSINESS_DATE``). It also maintains a public view (``<view>``) that
-    exposes the *current* business date/time by filtering the hidden table on
-    a specific ``TIME_ID``.
-
-    Attributes:
-        schema_name: Target database/schema.
-        table_name: Hidden physical table name (``<view>_HIDDEN``).
-        view_name: Public view name (``<view>``).
-        time_id: Name of the incrementing identifier column (default: ``"time_id"``).
-        nb_time_steps: Number of time steps currently stored in the hidden table
-            (``None`` if the hidden table does not exist yet).
-        data_type: SQL data type of ``BUSINESS_DATE`` (e.g., ``DATE``,
-            ``TIMESTAMP WITH TIME ZONE``), set after load/inspection.
+    Manage versioned business time steps behind a Teradata-backed public view.
+
+    `TimeManager` stores a sequence of time “snapshots” in a hidden physical
+    table (`<view_name>_HIDDEN`) with two columns:
+    - `TIME_ID` (1..N): the step index, assigned deterministically via
+      `ROW_NUMBER()` over the input time column.
+    - `BUSINESS_DATE`: the business date/time associated with each step. When
+      loading, the SQL type is inferred and upcast to `TIMESTAMP WITH TIME ZONE`
+      when needed to preserve offsets.
+
+    A companion public view (`<view_name>`) always exposes the *current* business
+    date by filtering the hidden table on a single `TIME_ID`. Changing the
+    current step only rewrites the view definition—no data is mutated.
+
+    Key capabilities
+    - Load/replace the hidden table from a pandas DataFrame (`load_time_steps`).
+    - Switch the active time step by `TIME_ID` (`update`).
+    - Inspect the current date/time (`display`, `get_date_in_the_past`).
+    - Generate a timeline view up to (or strictly before) the current step
+      (`generate_timeline`).
+    - Prune older steps and renumber so the earliest remaining step becomes 1
+      (`prune_time`).
+    - Clone from another `TimeManager` (soft link or hard copy) and optionally
+      take ownership of the hidden table (`clone_timer`, `take_ownership`).
+    - Introspect the active step by parsing the view DDL (`get_current_timeid`,
+      `print_view_ddl`).
+
+    Workflow overview
+      1) Instantiate `TimeManager` with a target `view_name` and `schema_name`.
+      2) Call `load_time_steps(df, time_column)` to (re)create the hidden table and
+         point the public view at `TIME_ID = 1`.
+      3) Use `update(time_id)` to switch the active business date.
+      4) (Optional) Create derivative timeline views, prune older steps, or clone.
+
+    Parameters
+        table_name (str): Base public view name to manage (e.g., "MY_VIEW").
+        schema_name (str): Teradata schema/database that holds the artifacts.
+
+    Attributes
+        schema_name (str): Target schema for the view and hidden table.
+        table_name (str): Hidden table name (`<view_name>_HIDDEN`).
+        view_name (str): Public view name (`<view_name>`).
+        time_id (str): Name of the step identifier column (default: "time_id").
+        nb_time_steps (int | None): Number of steps detected after load/inspection.
+        data_type (str | None): SQL data type of `BUSINESS_DATE` (e.g., `DATE`,
+            `TIMESTAMP WITH TIME ZONE`), inferred during load/inspection.
+
+    Notes
+        - On initialization, if the hidden table already exists, metadata
+          (`data_type`, `nb_time_steps`) is auto-detected.
+        - `load_time_steps` will drop and recreate the hidden table to match the
+          inferred schema, then rebuild the public view.
+        - “Soft” cloning points this manager’s view at the source hidden table;
+          “hard” cloning copies the table into this schema and marks it owned.
+        - Ownership controls whether `_drop()` is allowed to remove the hidden
+          table (use `take_ownership` to promote ownership when appropriate).
     """
 
     def __init__(self, table_name: str, schema_name: str) -> None:
@@ -133,7 +172,8 @@ class TimeManager:
             logger.debug("Dropped existing table %s.%s (if existed).", self.schema_name, self.table_name)
         except Exception as e:
             # Not fatal; the table might not exist. Log at debug when in dev, warning otherwise.
-            msg = f"Error dropping table {self.schema_name}.{self.table_name}: {e}"
+            e_str = str(e).split('\n')[0]
+            msg = f"Error dropping table {self.schema_name}.{self.table_name}: {e_str}"
             if tdfs4ds.DEBUG_MODE:
                 logger.debug(msg)
             else:
@@ -156,7 +196,7 @@ class TimeManager:
             schema_name=self.schema_name,
             if_exists="append"
         )
-        logger.info("Inserted %s time steps into %s.%s.", len(df_), self.schema_name, self.table_name)
+        logger.info("Inserted %s time steps into %s.%s.", df_.shape[0], self.schema_name, self.table_name)
 
         # Step 6: Update view
         create_view_sql = f"""
@@ -240,12 +280,15 @@ class TimeManager:
             FROM {self.schema_name}.{self.table_name}
             WHERE TIME_ID = {time_id}
             """
-            if tdfs4ds.DEBUG_MODE:
-                logger.debug("Executing view update:\n%s", query)
+            if getattr(tdfs4ds, "DEBUG_MODE", False):
+                logger_safe("debug", "Executing view update:\n%s", query)
+
             tdml.execute_sql(query)
-            logger.info("Updated view %s.%s to TIME_ID=%s.", self.schema_name, self.view_name, time_id)
+            logger_safe("info", "Updated view %s.%s to TIME_ID=%s.", self.schema_name, self.view_name, time_id)
+
         else:
-            logger.warning(
+            logger_safe(
+                "warning",
                 "Cannot update view: hidden table %s.%s does not exist.",
                 self.schema_name, self.table_name
             )

{tdfs4ds-0.2.4.32.dist-info → tdfs4ds-0.2.4.34.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tdfs4ds
-Version: 0.2.4.32
+Version: 0.2.4.34
 Summary: A python package to simplify the usage of feature store using Teradata Vantage ...
 Author: Denis Molin
 Requires-Python: >=3.6

{tdfs4ds-0.2.4.32.dist-info → tdfs4ds-0.2.4.34.dist-info}/RECORD

@@ -2,7 +2,7 @@ tdfs/__init__.py,sha256=7AcO7uB1opRCt7t2JOHworKimfAaDeO3boRW7u9Geo8,23
 tdfs/datasets.py,sha256=-b2MPEKGki2V1M8iUcoDR9uc2krIK7u1CK-EhChvihs,985
 tdfs/feature_store.py,sha256=Honu7eOAXxP4Ivz0mRlhuNkfTDzgZl5HB1WlQUwzcZ0,31354
 tdfs/data/curves.csv,sha256=q0Tm-0yu7VMK4lHvHpgi1LMeRq0lO5gJy2Q17brKbEM,112488
-tdfs4ds/__init__.py,sha256=cDBV8FsDXDLWddvAHAj6to7GM1MRIvr9IbWTBL16wqA,66290
+tdfs4ds/__init__.py,sha256=Aj0fuEgpIpLho6OOubGRQneD1s7Y8_3isNnZmeB222o,55698
 tdfs4ds/datasets.py,sha256=LE4Gn0muwdyrIrCrbkE92cnafUML63z1lj5bFIIVzmc,3524
 tdfs4ds/feature_engineering.py,sha256=oVnZ2V_XNGE12LKC_fNfkrWSQZLgtYRmaf8Dispi6S4,7081
 tdfs4ds/feature_store.py,sha256=y-oItPZw6nBkBcGAceaATZbkLPTsvpk0OnpzTxYofDs,68576
@@ -17,22 +17,22 @@ tdfs4ds/dataset/dataset.py,sha256=J_fgfsVdR9zSOXrUOqyotqsUD-GlQMGyuld6ueov45w,76
 tdfs4ds/dataset/dataset_catalog.py,sha256=qxS2thDW2MvsRouSFaX1M0sX2J7IzBAYD8Yf22Tsd5k,16638
 tdfs4ds/feature_store/__init__.py,sha256=a7NPCkpTx40UR5LRErwnskpABG2Vuib7F5wUjaUGCnI,209
 tdfs4ds/feature_store/entity_management.py,sha256=9ltytv3yCTG84NZXBpb1Tlkf9pOxvrNb0MVidU4pwvE,10157
-tdfs4ds/feature_store/feature_data_processing.py,sha256=rvpnFrV6Tmg8C6xcSQLT_lrFYqZsdSzFXmS-4suK9qg,42847
+tdfs4ds/feature_store/feature_data_processing.py,sha256=7VbrY1FBqK5SbNJYlL3SWKX9t9vwX-yUjkrt9eO9Awc,45017
 tdfs4ds/feature_store/feature_query_retrieval.py,sha256=51c6ZNlLFiBIxNPinS8ot8bjWEIb1QV2eVg69yzVF80,35381
-tdfs4ds/feature_store/feature_store_management.py,sha256=pWM9sjppBgRIg3l1ksoDJsM1fnaZlWtnuE3JuOP_2mY,54736
+tdfs4ds/feature_store/feature_store_management.py,sha256=yXLbINYLA-lzd0t_6TzEe9a8Anlum4x8TRoxZU3FIr8,54276
 tdfs4ds/process_store/__init__.py,sha256=npHR_xju5ecGmWfYHDyteLwiU3x-cL4HD3sFK_th7xY,229
 tdfs4ds/process_store/process_followup.py,sha256=PvLcU7meg3ljBlPfuez3qwTVqpHHhVJxYxGqjgiHE8E,7265
-tdfs4ds/process_store/process_query_administration.py,sha256=DsIt97cBoJ7NcpQzbQt55eUFNgXGdOMm5Hh2aX5v0PY,7762
-tdfs4ds/process_store/process_registration_management.py,sha256=F8VlBoL-de98KnkMvqxnE3WtAYcvWqDtX-KcKiRlhKI,36250
+tdfs4ds/process_store/process_query_administration.py,sha256=AOufkJ6DFUpBiGm-6Q6Dq0Aovw31UGTscZ3Ya0ewS-0,7851
+tdfs4ds/process_store/process_registration_management.py,sha256=2fFjt4Pmh3An1BUFvRX3xABSlQrlWiEiPQStH3A9Xpk,36130
 tdfs4ds/process_store/process_store_catalog_management.py,sha256=eVUU9uanyXCUkzi2vcHbJPL9qFiXVasnCxPGr-r9EY8,16090
 tdfs4ds/utils/__init__.py,sha256=-yTMfDLZbQnIRQ64s_bczzT21tDW2A8FZeq9PX5SgFU,168
-tdfs4ds/utils/filter_management.py,sha256=wn3glXJTc5Bdb_EZMEiwx06XawgaKiCSIbAXGwG31s0,23226
+tdfs4ds/utils/filter_management.py,sha256=5_8fYYtl8RQgbIi6L_1geNM0wJMm3t1n4QvNA5DnaQg,24760
 tdfs4ds/utils/info.py,sha256=sShnUxXMlvCtQ6xtShDhqdpTr6sMG0dZQhNBFgUENDY,12058
 tdfs4ds/utils/lineage.py,sha256=gy5M42qy5fvdWmlohAY3WPYoqAyp5VakeEmeT1YjrJQ,37839
 tdfs4ds/utils/query_management.py,sha256=nAcE8QY1GWAKgOtb-ubSfDVcnYbU7Ge8CruVRLoPtmY,6356
-tdfs4ds/utils/time_management.py,sha256=556DfHpNnCPQzy48p9fBLoupO00ZYZxfG5R_9JCXocU,29094
+tdfs4ds/utils/time_management.py,sha256=asIWvK5K81NNwAGqC-9Tv4Timscxyv0vyuPFs01whu0,31461
 tdfs4ds/utils/visualization.py,sha256=5S528KoKzzkrAdCxfy7ecyqKvAXBoibNvHwz_u5ISMs,23167
-tdfs4ds-0.2.4.32.dist-info/METADATA,sha256=l3dvKqLjImS2cVyZ9jNAXgFkSFHiaDky_KnX3b9Fs_A,14326
-tdfs4ds-0.2.4.32.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
-tdfs4ds-0.2.4.32.dist-info/top_level.txt,sha256=wMyVkMvnBn8RRt1xBveGQxOpWFijPMPkMiE7G2mi8zo,8
-tdfs4ds-0.2.4.32.dist-info/RECORD,,
+tdfs4ds-0.2.4.34.dist-info/METADATA,sha256=7ndN6tocMjqxVwvuu6MaPa_6rU8R2O2wOWXBnpvGO3E,14326
+tdfs4ds-0.2.4.34.dist-info/WHEEL,sha256=R0nc6qTxuoLk7ShA2_Y-UWkN8ZdfDBG2B6Eqpz2WXbs,91
+tdfs4ds-0.2.4.34.dist-info/top_level.txt,sha256=wMyVkMvnBn8RRt1xBveGQxOpWFijPMPkMiE7G2mi8zo,8
+tdfs4ds-0.2.4.34.dist-info/RECORD,,