investify-utils 2.0.0a6__tar.gz → 2.0.0a7__tar.gz

{investify_utils-2.0.0a6 → investify_utils-2.0.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investify-utils
-Version: 2.0.0a6
+Version: 2.0.0a7
 Summary: Shared utilities for Investify services
 Author-Email: Investify <dev@investify.vn>
 License: MIT
@@ -24,6 +24,9 @@ Provides-Extra: kafka
 Requires-Dist: confluent-kafka[avro,schemaregistry]>=2.0; extra == "kafka"
 Provides-Extra: s3
 Requires-Dist: boto3>=1.34; extra == "s3"
+Provides-Extra: helpers
+Requires-Dist: pandas>=2.0; extra == "helpers"
+Requires-Dist: numpy>=2.0; extra == "helpers"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"

investify_utils-2.0.0a7/investify_utils/__init__.py

@@ -0,0 +1,28 @@
+"""
+Investify Utils - Shared utilities for Investify services.
+
+Install with optional dependencies:
+    pip install investify-utils[postgres]        # Sync PostgreSQL client
+    pip install investify-utils[postgres-async]  # Async PostgreSQL client
+    pip install investify-utils[kafka]           # Kafka Avro producer/consumer
+    pip install investify-utils[s3]              # S3 client
+    pip install investify-utils[helpers]         # Timestamp/SQL utilities
+
+Usage:
+    # Logging (no extra required)
+    from investify_utils.logging import setup_logging
+
+    # PostgreSQL
+    from investify_utils.postgres import PostgresClient, AsyncPostgresClient
+
+    # Kafka
+    from investify_utils.kafka import AvroProducer, AvroConsumer
+
+    # S3
+    from investify_utils.s3 import S3Client
+
+    # Helpers
+    from investify_utils.helpers import convert_to_pd_timestamp, create_sql_in_filter
+"""
+
+__version__ = "2.0.0a7"

investify_utils-2.0.0a7/investify_utils/helpers.py

@@ -0,0 +1,154 @@
+"""
+Common helper utilities for Investify services.
+
+Usage:
+    from investify_utils.helpers import convert_to_pd_timestamp, create_sql_in_filter
+"""
+
+import datetime as dt
+import importlib.util
+import logging
+import sys
+from numbers import Integral, Number, Real
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Timestamp Utilities
+# =============================================================================
+
+
+def convert_to_pd_timestamp(timestamp) -> pd.Timestamp | None:
+    """
+    Convert various timestamp formats to pandas Timestamp.
+
+    Args:
+        timestamp: Can be None, pd.Timestamp, number (unix), string, datetime, or np.datetime64
+
+    Returns:
+        pd.Timestamp or None
+    """
+    if timestamp is None:
+        return None
+
+    if isinstance(timestamp, pd.Timestamp):
+        return timestamp
+
+    if isinstance(timestamp, Number):
+        return pd.Timestamp.fromtimestamp(float(timestamp), tz=dt.UTC)
+
+    if isinstance(timestamp, str | dt.datetime | np.datetime64):
+        try:
+            return pd.Timestamp(timestamp, tzinfo=dt.UTC)
+        except Exception as e:
+            logger.error(repr(e))
+            return timestamp
+
+    return timestamp
+
+
+# =============================================================================
+# SQL Utilities
+# =============================================================================
+
+
+def convert_to_sql_value(value: Integral | Real | str | dt.datetime | dt.date) -> str:
+    """
+    Convert Python value to SQL literal string.
+
+    Args:
+        value: Integer, float, string, datetime, or date
+
+    Returns:
+        SQL-safe string representation
+    """
+    if isinstance(value, Integral):
+        value = int(value)
+    elif isinstance(value, Real):
+        value = float(value)
+    elif isinstance(value, str):
+        value = f"'{value}'"
+    elif isinstance(value, dt.datetime):
+        value = value.isoformat(sep=" ")
+        value = f"'{value}'"
+    elif isinstance(value, dt.date):
+        value = value.isoformat()
+        value = f"'{value}'"
+    else:
+        raise ValueError(f"Not supported type={type(value)}")
+
+    return str(value)
+
+
+def create_sql_in_filter(
+    col_name: str,
+    values: list[Integral | Real | str | dt.datetime | dt.date],
+    not_in: bool = False,
+) -> str:
+    """
+    Create SQL IN or NOT IN filter clause.
+
+    Args:
+        col_name: Column name
+        values: List of values
+        not_in: Use NOT IN instead of IN
+
+    Returns:
+        SQL filter string like "col IN (1, 2, 3)"
+    """
+    operator = "NOT IN" if not_in else "IN"
+    values_str = ", ".join([convert_to_sql_value(value) for value in values])
+    return f"{col_name} {operator} ({values_str})"
+
+
+def create_sql_logical_filter(
+    filters: list[str],
+    operator: Literal["AND", "OR"],
+    inner_bracket: bool = False,
+    outer_bracket: bool = False,
+) -> str:
+    """
+    Combine multiple SQL filters with AND/OR.
+
+    Args:
+        filters: List of filter strings
+        operator: "AND" or "OR"
+        inner_bracket: Wrap each filter in parentheses
+        outer_bracket: Wrap result in parentheses
+
+    Returns:
+        Combined filter string
+    """
+    operator_sep = f" {operator} "
+    if inner_bracket:
+        filters = [f"({filter})" for filter in filters]
+    return f"({operator_sep.join(filters)})" if outer_bracket else operator_sep.join(filters)
+
+
+# =============================================================================
+# Module Utilities
+# =============================================================================
+
+
+def import_module_from_path(file_path: str, module_name: str):
+    """
+    Dynamically import a Python module from a file path.
+
+    Args:
+        file_path: Path to the Python file
+        module_name: Name to register the module as
+
+    Returns:
+        Imported module object
+    """
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    logger.info(f"Loading `{spec.name}` from `{spec.origin}`")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module

investify_utils-2.0.0a7/investify_utils/logging.py

@@ -0,0 +1,81 @@
+"""
+Logging utilities for Investify services.
+
+Usage:
+    from investify_utils.logging import setup_logging
+
+    setup_logging()
+    logger = logging.getLogger(__name__)
+"""
+
+import logging
+import os
+from enum import IntEnum, auto
+from logging.handlers import RotatingFileHandler
+
+old_factory = logging.getLogRecordFactory()
+default_logging_fmt = "%(asctime)s - %(origin)-30s - %(levelname)s - %(message)s"
+
+
+class TextColor(IntEnum):
+    """ANSI text colors for terminal output."""
+
+    BLACK = 0
+    RED = auto()
+    GREEN = auto()
+    YELLOW = auto()
+    BLUE = auto()
+    MAGENTA = auto()
+    CYAN = auto()
+    WHITE = auto()
+
+    @staticmethod
+    def colorize(text: str, color: "TextColor") -> str:
+        """Wrap text with ANSI color codes."""
+        return f"\033[0;{30 + color}m{text}\033[0m"
+
+
+def record_factory(*args, **kwargs):
+    """Custom log record factory that adds origin (filename:lineno)."""
+    record = old_factory(*args, **kwargs)
+    record.origin = f"{record.filename}:{record.lineno}"
+    return record
+
+
+def setup_logging(level=logging.INFO, logging_fmt=default_logging_fmt):
+    """
+    Configure logging with origin field (filename:lineno).
+
+    Args:
+        level: Logging level (default: INFO)
+        logging_fmt: Log format string
+    """
+    logging.setLogRecordFactory(record_factory)
+    logging.basicConfig(format=logging_fmt, level=level)
+
+
+def setup_file_logging(
+    filename: str,
+    level=logging.INFO,
+    max_megabytes: int = 1,
+    backup_count: int = 3,
+    logging_fmt: str = default_logging_fmt,
+):
+    """
+    Configure rotating file logging.
+
+    Args:
+        filename: Log file path
+        level: Logging level
+        max_megabytes: Max file size before rotation
+        backup_count: Number of backup files to keep
+        logging_fmt: Log format string
+    """
+    filepath, _ = os.path.split(filename)
+    if filepath and not os.path.isdir(filepath):
+        os.makedirs(filepath)
+
+    max_log_size = int(max_megabytes * 1024 * 1024)
+    handler = RotatingFileHandler(filename=filename, maxBytes=max_log_size, backupCount=backup_count)
+    logging.setLogRecordFactory(record_factory)
+    logging.basicConfig(format=logging_fmt, level=level, handlers=[handler])

{investify_utils-2.0.0a6 → investify_utils-2.0.0a7}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "investify-utils"
-version = "2.0.0a6"
+version = "2.0.0a7"
 description = "Shared utilities for Investify services"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -46,6 +46,10 @@ kafka = [
 s3 = [
     "boto3>=1.34",
 ]
+helpers = [
+    "pandas>=2.0",
+    "numpy>=2.0",
+]
 dev = [
     "pytest",
     "pytest-asyncio",

investify_utils-2.0.0a6/investify_utils/__init__.py

@@ -1,13 +0,0 @@
-"""
-Investify Utils - Shared utilities for Investify services.
-
-Install with optional dependencies:
-    pip install investify-utils[postgres]        # Sync PostgreSQL client
-    pip install investify-utils[postgres-async]  # Async PostgreSQL client
-    pip install investify-utils[postgres-all]    # Both clients
-
-Usage:
-    from investify_utils.postgres import PostgresClient, AsyncPostgresClient
-"""
-
-__version__ = "2.0.0a2"