masworks 0.1.0.dev20260205__py3-none-any.whl

masworks/MasDatabase/__init__.py

@@ -0,0 +1,37 @@
+"""
+MasDatabase module for MasWorks library.
+
+Provides MasWorks-specific database functionality including session management
+and ORM models for time series data. This module contains domain-specific
+database operations, while generic database utilities are in utils/.
+"""
+
+from ..utils.database_connection import DatabaseManager
+from .models import TimeSeriesData, TimeSeriesMeta, TimeSeriesSelector, RefData, TickerMapping, TimeSeriesScheduler
+# Old SessionManager moved to recycle/ - use TimeSeriesSessionManager instead
+from .generic_session import GenericSessionManager
+from .time_series_session import TimeSeriesSessionManager
+from .base import DatabaseBase
+from .operations import SeriesOperationMixin, BloombergOperationsMixin
+from .decorators import handle_series_operation_errors
+from .utilities import update_threshold_daily_close, create_update_filter, parse_time_string
+# TimeSeriesContext imported on demand to avoid circular imports
+
+__all__ = [
+    "DatabaseManager",
+    "GenericSessionManager",
+    "TimeSeriesSessionManager",
+    "TimeSeriesData",
+    "TimeSeriesMeta",
+    "TimeSeriesSelector",
+    "RefData",
+    "TickerMapping",
+    "TimeSeriesScheduler",
+    "DatabaseBase",
+    "SeriesOperationMixin",
+    "BloombergOperationsMixin",
+    "handle_series_operation_errors",
+    "update_threshold_daily_close",
+    "create_update_filter",
+    "parse_time_string",
+]

masworks/MasDatabase/base.py

@@ -0,0 +1,116 @@
+"""
+Database base functionality for MasWorks library.
+
+Provides shared database infrastructure including connection management,
+feed initialization, and common utilities used by both reader and admin classes.
+"""
+import logging
+from typing import Dict, Any
+
+from masworks.config import Config
+from masworks.utils.database_connection import DatabaseManager
+from .time_series_session import TimeSeriesSessionManager
+from masworks.feeds import BridgeFeed, FredFeed, DatastreamFeed
+from masworks.constants import SOURCE_ALIASES
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseBase:
+    """
+    Base class for database operations in MasWorks.
+    
+    Provides shared infrastructure including database connections and common utilities.
+    This class is not meant to be used directly - use MasTimeSeriesReader for read 
+    operations or MasTimeSeriesAdmin for write operations.
+    
+    Note: Feed operations are only available in MasTimeSeriesAdmin.
+    """
+    
+    def __init__(self, config: Config, auto_create_tables: bool = True):
+        """
+        Initialize DatabaseBase.
+        
+        Args:
+            config: Configuration object with database and feed settings
+            auto_create_tables: If True, automatically create database tables if they don't exist
+        """
+        self.config = config
+        
+        # Initialize database components
+        self.db_manager = DatabaseManager(config.database)
+        
+        # Check if this is a versioned class
+        # Versioned classes should use create_version() for versioned tables,
+        # not auto-create current tables
+        is_versioned = self._is_versioned_class()
+        
+        # Create tables if requested and they don't exist
+        # Skip for versioned classes (they should use create_version() explicitly)
+        if auto_create_tables and not is_versioned:
+            self.db_manager.create_tables_if_not_exist()
+        
+        # Session manager will be attached by subclasses as needed
+        self.session_manager = None
+    
+    def _is_versioned_class(self) -> bool:
+        """
+        Check if this instance is a versioned class.
+        
+        Uses lazy import to avoid circular dependency issues.
+        
+        Returns:
+            True if this is a VersionedTimeSeriesBase subclass, False otherwise
+        """
+        try:
+            # Lazy import to avoid circular dependency
+            # Use absolute import path to avoid issues
+            from masworks.versioned_time_series_base import VersionedTimeSeriesBase
+            return isinstance(self, VersionedTimeSeriesBase)
+        except (ImportError, AttributeError):
+            # Fallback: check class name if import fails
+            # This handles edge cases but shouldn't normally be needed
+            class_name = self.__class__.__name__
+            return 'Versioned' in class_name and 'TimeSeries' in class_name
+        
+        # Note: Feed initialization moved to TimeSeriesAdmin
+        # Feeds are only needed for admin operations, not read-only operations
+    
+    def test_connection(self) -> bool:
+        """
+        Test database connection.
+        
+        Returns:
+            True if connection is successful, False otherwise
+        """
+        return self.db_manager.test_connection()
+    
+    def create_tables(self) -> bool:
+        """
+        Manually create all database tables.
+        
+        Returns:
+            True if tables were created successfully, False otherwise
+        """
+        return self.db_manager.create_tables()
+    
+    def create_tables_if_not_exist(self) -> bool:
+        """
+        Create database tables only if they don't already exist.
+        
+        Returns:
+            True if tables exist or were created successfully, False otherwise
+        """
+        return self.db_manager.create_tables_if_not_exist()
+    
+    def close(self):
+        """
+        Close database connections and cleanup resources.
+        
+        Should be called when done with the instance to properly cleanup resources.
+        """
+        self.db_manager.close()
+    
+    # Note: Feed-related methods (get_available_feeds, get_feed_info) 
+    # have been moved to TimeSeriesAdmin where feeds are actually available.
+    # DatabaseBase only provides database operations, not feed operations.

masworks/MasDatabase/context.py

@@ -0,0 +1,58 @@
+"""
+Context manager for MasWorks time series operations.
+
+This module provides TimeSeriesContext which is a convenient context manager
+for time series operations, specifically designed for MasWorks time series
+database operations.
+"""
+from typing import Optional, Union
+
+from masworks.config import Config
+
+
+class TimeSeriesContext:
+    """
+    Context manager wrapper for time series operations.
+    
+    Provides a convenient way to use TimeSeriesReader or TimeSeriesAdmin with automatic
+    resource cleanup using Python's 'with' statement.
+    
+    Example:
+        # For read operations
+        with TimeSeriesContext(config, mode="reader") as reader:
+            data = reader.get_series_data(ticker='SPX Index', field='PX_LAST')
+        
+        # For admin operations
+        with TimeSeriesContext(config, mode="admin") as admin:
+            result = admin.upsert_series('SPX Index', 'PX_LAST')
+    """
+    
+    def __init__(self, config: Config, mode: str = "admin"):
+        """
+        Initialize TimeSeriesContext.
+        
+        Args:
+            config: Configuration object with database and feed settings
+            mode: Operation mode - "reader" for read-only, "admin" for full access
+        """
+        self.config = config
+        self.mode = mode
+        self._instance: Optional[Union['MasTimeSeriesReader', 'MasTimeSeriesAdmin']] = None
+    
+    def __enter__(self) -> Union['MasTimeSeriesReader', 'MasTimeSeriesAdmin']:
+        """Enter context manager and initialize the appropriate class."""
+        # Import here to avoid circular imports
+        from masworks.mas_time_series_reader import MasTimeSeriesReader
+        from masworks.mas_time_series_admin import MasTimeSeriesAdmin
+        
+        if self.mode == "reader":
+            self._instance = MasTimeSeriesReader(self.config)
+        else:
+            self._instance = MasTimeSeriesAdmin(self.config)
+        return self._instance
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Exit context manager and cleanup resources."""
+        if self._instance:
+            self._instance.close()
+        return False

masworks/MasDatabase/decorators.py

@@ -0,0 +1,37 @@
+"""
+Database decorators for MasWorks library.
+"""
+import logging
+from functools import wraps
+from typing import Any, Callable
+
+from ..feeds import DataFeedError
+from ..constants import STATUS_CODES
+
+logger = logging.getLogger(__name__)
+
+
+def handle_series_operation_errors(func: Callable) -> Callable:
+    """
+    Decorator to standardize error handling for series operations.
+    
+    Args:
+        func: The function to wrap
+        
+    Returns:
+        Wrapped function with error handling
+    """
+    @wraps(func)
+    def wrapper(self, *args, **kwargs) -> Any:
+        try:
+            return func(self, *args, **kwargs)
+        except DataFeedError as e:
+            ticker = kwargs.get('ticker', args[0] if args else 'unknown')
+            logger.error(f"Data feed error for {ticker}: {e}")
+            return {"status": STATUS_CODES['FEED_ERROR'], "error": str(e)}
+        except Exception as e:
+            ticker = kwargs.get('ticker', args[0] if args else 'unknown')
+            operation = func.__name__.replace('_series', '')
+            logger.error(f"{operation.title()} failed for {ticker}: {e}")
+            return {"status": STATUS_CODES['ERROR'], "error": str(e)}
+    return wrapper

masworks/MasDatabase/generic_session.py

@@ -0,0 +1,228 @@
+"""
+Generic session management for database operations.
+
+This module provides a generic SessionManager that can work with any database
+schema and table structure, without hardcoded dependencies.
+"""
+
+import logging
+from typing import Optional, List, Dict, Any
+import pandas as pd
+from sqlalchemy import text
+from sqlalchemy.exc import SQLAlchemyError
+from contextlib import contextmanager
+
+from ..utils.session_base import BaseSessionManager
+from ..utils.database_connection import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class GenericSessionManager(BaseSessionManager):
+    """
+    Generic session manager for database operations.
+    
+    Provides generic database session management that can work with any
+    database schema and table structure without hardcoded dependencies.
+    """
+    
+    def __init__(self, db_manager: DatabaseManager, chunk_size: int = 5000):
+        """
+        Initialize GenericSessionManager.
+        
+        Args:
+            db_manager: DatabaseManager instance
+            chunk_size: Size of chunks for bulk operations
+        """
+        super().__init__(db_manager, chunk_size)
+        # Track temp tables for reuse within session
+        self._temp_tables = {}  # {table_name: connection_id}
+        self._conn = None
+    
+    def _get_connection(self):
+        """
+        Get the current connection or create a new one.
+        
+        Returns:
+            Database connection object
+        """
+        if self._conn is None:
+            self._conn = self.db_manager.engine.connect()
+        return self._conn
+    
+    def _close_connection(self):
+        """Close the current connection if it exists."""
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+    
+    def _get_schema(self) -> str:
+        """Get the database schema from config."""
+        return self.db_manager.config.schema
+    
+    def _get_or_create_temp_table(self, temp_table: str, source_table: str = None, schema: str = None) -> str:
+        """
+        Get existing temp table or create new one for reuse within session.
+        
+        Args:
+            temp_table: Name of temp table to create/reuse
+            source_table: Source table to copy structure from (if None, defaults to "TS_Data")
+            schema: Database schema name (if None, uses config schema)
+            
+        Returns:
+            Name of temp table to use
+        """
+        # Generate temp table name if not provided
+        if temp_table is None:
+            import time
+            import random
+            timestamp = int(time.time() * 1000) % 10000
+            random_suffix = random.randint(10, 99)
+            temp_table = f"#tmp_{timestamp}_{random_suffix}"
+        
+        # Get connection
+        conn = self._get_connection()
+        
+        # Get connection ID for tracking
+        conn_id = id(conn)
+        
+        # Check if we can reuse an existing temp table
+        if temp_table in self._temp_tables and self._temp_tables[temp_table] == conn_id:
+            # Reuse existing temp table - just truncate it
+            try:
+                conn.execute(text(f"TRUNCATE TABLE {temp_table}"))
+                logger.debug(f"Reusing existing temp table: {temp_table}")
+                return temp_table
+            except Exception as e:
+                logger.warning(f"Failed to truncate temp table {temp_table}, will recreate: {e}")
+                # Fall through to create new table
+        
+        # Get table name and schema from model if not provided
+        if source_table is None or schema is None:
+            # Default to TimeSeriesData table info, but allow override
+            if source_table is None:
+                source_table = "TS_Data"  # Default table name
+            
+            if schema is None:
+                schema = self._get_schema()  # Use config schema
+        
+        # Create new temp table
+        self.create_temp_table(conn, temp_table, source_table, schema)
+        self._temp_tables[temp_table] = conn_id
+        logger.debug(f"Created new temp table: {temp_table}")
+        return temp_table
+    
+    def _get_or_create_temp_table_from_model(self, temp_table: str, model_class) -> str:
+        """
+        Get existing temp table or create new one using SQLAlchemy model information.
+        
+        Args:
+            temp_table: Name of temp table to create/reuse
+            model_class: SQLAlchemy model class to get table name and schema from
+            
+        Returns:
+            Name of temp table to use
+        """
+        # Extract table name and schema from model
+        source_table = model_class.__tablename__
+        schema = model_class.__table_args__["schema"]
+        
+        # Use the main method with extracted parameters
+        return self._get_or_create_temp_table(temp_table, source_table, schema)
+    
+    def _cleanup_temp_table(self, temp_table: str):
+        """
+        Clean up temp table, but keep it for reuse if possible.
+        
+        Args:
+            temp_table: Name of temp table to clean up
+        """
+        try:
+            # Get connection
+            conn = self._get_connection()
+            
+            # Debug: Check connection type
+            logger.debug(f"Cleaning up temp table {temp_table}, connection type: {type(conn)}")
+            
+            # Check if connection has execute method
+            if not hasattr(conn, 'execute'):
+                logger.warning(f"Connection object {type(conn)} does not have execute method, skipping cleanup for {temp_table}")
+                return
+            
+            # Try to truncate first (for reuse)
+            conn.execute(text(f"TRUNCATE TABLE {temp_table}"))
+            logger.debug(f"Truncated temp table for reuse: {temp_table}")
+        except Exception as e:
+            # If truncate fails, try to drop
+            try:
+                logger.debug(f"Truncate failed for {temp_table}: {e}, trying drop")
+                conn.execute(text(f"DROP TABLE {temp_table}"))
+                logger.debug(f"Dropped temp table: {temp_table}")
+                # Remove from tracking
+                if temp_table in self._temp_tables:
+                    del self._temp_tables[temp_table]
+            except Exception as drop_error:
+                logger.warning(f"Could not clean up {temp_table}: {drop_error}")
+    
+    def _cleanup_all_temp_tables(self):
+        """
+        Clean up all temp tables for the current connection.
+        """
+        # Get connection
+        conn = self._get_connection()
+        conn_id = id(conn)
+        
+        tables_to_remove = []
+        
+        for temp_table, tracked_conn_id in self._temp_tables.items():
+            if tracked_conn_id == conn_id:
+                try:
+                    conn.execute(text(f"DROP TABLE {temp_table}"))
+                    logger.debug(f"Dropped temp table: {temp_table}")
+                    tables_to_remove.append(temp_table)
+                except Exception as e:
+                    logger.warning(f"Failed to clean up temp table {temp_table}: {e}")
+        
+        # Remove from tracking
+        for temp_table in tables_to_remove:
+            del self._temp_tables[temp_table]
+    
+    @contextmanager
+    def bulk_operations_context(self):
+        """
+        Context manager for bulk operations that reuses connections and temp tables.
+        
+        This reuses an existing connection if available, or creates a new one and keeps it open.
+        Optimized for sequences of operations where you want to reuse temp tables for better performance.
+        
+        Example:
+            with session_manager.bulk_operations_context() as conn:
+                result1 = session_manager.some_operation(df1, conn=conn)
+                result2 = session_manager.some_operation(df2, conn=conn)
+        """
+        # If we already have a connection, use it
+        if self._conn is not None:
+            yield self._conn
+        else:
+            # Create new connection and keep it open
+            conn = self.db_manager.engine.connect()
+            try:
+                self._conn = conn
+                yield conn
+            finally:
+                # Don't close - let it stay in self._conn for future use
+                # Just clean up temp tables
+                self._cleanup_all_temp_tables()
+    
+    def close(self):
+        """Close database connections and cleanup resources."""
+        # Clean up any remaining temp tables
+        if hasattr(self, '_temp_tables'):
+            self._cleanup_all_temp_tables()
+            self._temp_tables.clear()
+        
+        # Close current connection
+        self._close_connection()
+        
+        # Close base class resources
+        super().close()