pyconvexity 0.1.0__py3-none-any.whl

pyconvexity/__init__.py

@@ -0,0 +1,120 @@
+"""
+PyConvexity - Python library for energy system modeling and optimization.
+
+This library provides the core functionality of the Convexity desktop application
+as a reusable, pip-installable package for building and solving energy system models.
+"""
+
+# Version information
+from pyconvexity._version import __version__
+
+__author__ = "Convexity Team"
+
+# Core imports - always available
+from pyconvexity.core.errors import (
+    PyConvexityError,
+    DatabaseError,
+    ValidationError,
+    ComponentNotFound,
+    AttributeNotFound,
+)
+
+from pyconvexity.core.types import (
+    StaticValue,
+    TimeseriesPoint,
+    Component,
+    Network,
+    CreateNetworkRequest,
+    CreateComponentRequest,
+)
+
+from pyconvexity.core.database import (
+    create_database_with_schema,
+    database_context,
+    open_connection,
+    validate_database,
+)
+
+# Import main API functions
+from pyconvexity.models import (
+    # Component operations
+    get_component, create_component, update_component, delete_component,
+    list_components_by_type, list_component_attributes,
+    
+    # Attribute operations  
+    set_static_attribute, set_timeseries_attribute, get_attribute, delete_attribute,
+    
+    # Network operations
+    create_network, get_network_info, get_network_time_periods, list_networks,
+    create_carrier, list_carriers, get_network_config, set_network_config,
+    get_master_scenario_id, resolve_scenario_id,
+)
+
+from pyconvexity.validation import (
+    get_validation_rule, list_validation_rules, validate_timeseries_alignment
+)
+
+# High-level API functions
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    
+    # Core types
+    "StaticValue",
+    "TimeseriesPoint", 
+    "Component",
+    "Network",
+    "CreateNetworkRequest",
+    "CreateComponentRequest",
+    
+    # Database operations
+    "create_database_with_schema",
+    "database_context", 
+    "open_connection",
+    "validate_database",
+    
+    # Exceptions
+    "PyConvexityError",
+    "DatabaseError",
+    "ValidationError",
+    "ComponentNotFound",
+    "AttributeNotFound",
+    
+    # Component operations
+    "get_component", "create_component", "update_component", "delete_component",
+    "list_components_by_type", "list_component_attributes",
+    
+    # Attribute operations
+    "set_static_attribute", "set_timeseries_attribute", "get_attribute", "delete_attribute",
+    
+    # Network operations
+    "create_network", "get_network_info", "get_network_time_periods", "list_networks",
+    "create_carrier", "list_carriers", "get_network_config", "set_network_config",
+    "get_master_scenario_id", "resolve_scenario_id",
+    
+    # Validation
+    "get_validation_rule", "list_validation_rules", "validate_timeseries_alignment",
+]
+
+# Optional imports with graceful fallbacks
+try:
+    from pyconvexity.solvers.pypsa import PyPSASolver
+    __all__.append("PyPSASolver")
+except ImportError:
+    # PyPSA not available
+    pass
+
+try:
+    from pyconvexity.io.excel import ExcelImporter, ExcelExporter
+    __all__.extend(["ExcelImporter", "ExcelExporter"])
+except ImportError:
+    # Excel dependencies not available
+    pass
+
+try:
+    from pyconvexity.io.netcdf import NetCDFImporter, NetCDFExporter
+    __all__.extend(["NetCDFImporter", "NetCDFExporter"])
+except ImportError:
+    # NetCDF dependencies not available
+    pass

pyconvexity/_version.py

@@ -0,0 +1,2 @@
+# This file is automatically updated by GitHub Actions during release
+__version__ = "0.1.0"  # Default version for local development

pyconvexity/core/__init__.py

@@ -0,0 +1,64 @@
+"""
+Core module for PyConvexity.
+
+Contains fundamental types, database operations, and error handling.
+"""
+
+from pyconvexity.core.errors import (
+    PyConvexityError,
+    DatabaseError,
+    ValidationError,
+    ComponentNotFound,
+    AttributeNotFound,
+    InvalidDataType,
+    TimeseriesError,
+)
+
+from pyconvexity.core.types import (
+    StaticValue,
+    TimeseriesPoint,
+    AttributeValue,
+    ValidationRule,
+    Component,
+    Network,
+    TimePeriod,
+    TimeseriesValidationResult,
+    CreateComponentRequest,
+    CreateNetworkRequest,
+)
+
+from pyconvexity.core.database import (
+    DatabaseContext,
+    open_connection,
+    validate_database,
+    create_database_with_schema,
+)
+
+__all__ = [
+    # Errors
+    "PyConvexityError",
+    "DatabaseError", 
+    "ValidationError",
+    "ComponentNotFound",
+    "AttributeNotFound",
+    "InvalidDataType",
+    "TimeseriesError",
+    
+    # Types
+    "StaticValue",
+    "TimeseriesPoint",
+    "AttributeValue", 
+    "ValidationRule",
+    "Component",
+    "Network",
+    "TimePeriod",
+    "TimeseriesValidationResult",
+    "CreateComponentRequest",
+    "CreateNetworkRequest",
+    
+    # Database
+    "DatabaseContext",
+    "open_connection",
+    "validate_database", 
+    "create_database_with_schema",
+]

pyconvexity/core/database.py

@@ -0,0 +1,314 @@
+"""
+Database connection and schema management for PyConvexity.
+
+Provides clean abstractions for database operations with proper connection
+management, schema validation, and resource cleanup.
+"""
+
+import sqlite3
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, List, Optional
+
+from pyconvexity.core.errors import ConnectionError, DatabaseError, ValidationError
+
+
+class DatabaseContext:
+    """
+    Context manager for database connections with automatic cleanup.
+    
+    Provides a clean way to manage database connections with proper
+    resource cleanup and error handling.
+    """
+    
+    def __init__(self, db_path: str, read_only: bool = False):
+        self.db_path = db_path
+        self.read_only = read_only
+        self.connection: Optional[sqlite3.Connection] = None
+    
+    def __enter__(self) -> sqlite3.Connection:
+        self.connection = open_connection(self.db_path, read_only=self.read_only)
+        return self.connection
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.connection:
+            if exc_type is None:
+                # No exception, commit any pending changes
+                self.connection.commit()
+            else:
+                # Exception occurred, rollback
+                self.connection.rollback()
+            self.connection.close()
+            self.connection = None
+
+
+@contextmanager
+def database_context(db_path: str, read_only: bool = False) -> Generator[sqlite3.Connection, None, None]:
+    """
+    Context manager function for database connections.
+    
+    Args:
+        db_path: Path to the SQLite database file
+        read_only: If True, open in read-only mode
+        
+    Yields:
+        sqlite3.Connection: Database connection with proper configuration
+        
+    Example:
+        with database_context("model.db") as conn:
+            cursor = conn.execute("SELECT * FROM networks")
+            networks = cursor.fetchall()
+    """
+    with DatabaseContext(db_path, read_only) as conn:
+        yield conn
+
+
+def open_connection(db_path: str, read_only: bool = False) -> sqlite3.Connection:
+    """
+    Open database connection with proper settings.
+    
+    Args:
+        db_path: Path to the SQLite database file
+        read_only: If True, open in read-only mode
+        
+    Returns:
+        sqlite3.Connection: Configured database connection
+        
+    Raises:
+        ConnectionError: If database connection fails
+    """
+    try:
+        # Build connection URI for read-only mode if needed
+        if read_only:
+            uri = f"file:{db_path}?mode=ro"
+            conn = sqlite3.connect(uri, uri=True)
+        else:
+            conn = sqlite3.connect(db_path)
+        
+        # Configure connection
+        conn.row_factory = sqlite3.Row  # Enable column access by name
+        conn.execute("PRAGMA foreign_keys = ON")  # Enable foreign key constraints
+        
+        # Set reasonable timeouts
+        conn.execute("PRAGMA busy_timeout = 30000")  # 30 second timeout
+        
+        return conn
+        
+    except sqlite3.Error as e:
+        raise ConnectionError(f"Failed to open database at {db_path}: {e}") from e
+
+
+def validate_database(conn: sqlite3.Connection) -> None:
+    """
+    Validate database schema has required tables.
+    
+    Args:
+        conn: Database connection to validate
+        
+    Raises:
+        ValidationError: If required tables are missing
+    """
+    required_tables = [
+        "networks",
+        "components", 
+        "component_attributes",
+        "attribute_validation_rules",
+        "carriers",
+        "scenarios"
+    ]
+    
+    missing_tables = []
+    
+    for table in required_tables:
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?", 
+            (table,)
+        )
+        if not cursor.fetchone():
+            missing_tables.append(table)
+    
+    if missing_tables:
+        raise ValidationError(
+            f"Required tables not found in database: {', '.join(missing_tables)}"
+        )
+
+
+def create_database_with_schema(db_path: str) -> None:
+    """
+    Create a new database and apply the complete schema.
+    
+    Args:
+        db_path: Path where the new database should be created
+        
+    Raises:
+        DatabaseError: If schema files cannot be found or applied
+    """
+    db_path_obj = Path(db_path)
+    
+    # Ensure parent directory exists
+    if db_path_obj.parent and not db_path_obj.parent.exists():
+        db_path_obj.parent.mkdir(parents=True, exist_ok=True)
+        
+    # Remove existing file if it exists, to ensure a clean start
+    if db_path_obj.exists():
+        db_path_obj.unlink()
+    
+    # Find schema files
+    schema_dir = _find_schema_directory()
+    if not schema_dir:
+        raise DatabaseError("Could not find schema directory")
+    
+    schema_files = [
+        "01_core_schema.sql",
+        "02_data_metadata.sql", 
+        "03_validation_data.sql",
+        "04_scenario_schema.sql"
+    ]
+    
+    # Verify all schema files exist
+    missing_files = []
+    for filename in schema_files:
+        schema_file = schema_dir / filename
+        if not schema_file.exists():
+            missing_files.append(filename)
+    
+    if missing_files:
+        raise DatabaseError(f"Schema files not found: {', '.join(missing_files)}")
+    
+    # Create connection and apply schemas
+    try:
+        conn = sqlite3.connect(db_path)
+        
+        # Enable foreign key constraints
+        conn.execute("PRAGMA foreign_keys = ON")
+        
+        # Execute schemas in order
+        for filename in schema_files:
+            schema_file = schema_dir / filename
+            with open(schema_file, 'r') as f:
+                conn.executescript(f.read())
+        
+        conn.close()
+        
+    except sqlite3.Error as e:
+        # Clean up partial database on error
+        if db_path_obj.exists():
+            db_path_obj.unlink()
+        raise DatabaseError(f"Failed to create database schema: {e}") from e
+
+
+def _find_schema_directory() -> Optional[Path]:
+    """
+    Find the schema directory in various possible locations.
+    
+    Returns:
+        Path to schema directory or None if not found
+    """
+    # Try bundled location first (PyInstaller)
+    for p in sys.path:
+        candidate = Path(p) / "schema"
+        if candidate.exists() and candidate.is_dir():
+            return candidate
+    
+    # Try relative to this file (development mode)
+    current_file = Path(__file__)
+    
+    # Look for schema in the main project
+    # Assuming pyconvexity/src/pyconvexity/core/database.py
+    # and schema is at project_root/schema
+    project_root = current_file.parent.parent.parent.parent.parent
+    dev_schema_dir = project_root / "schema"
+    if dev_schema_dir.exists():
+        return dev_schema_dir
+    
+    # Try package data location
+    try:
+        import importlib.resources
+        schema_path = importlib.resources.files('pyconvexity') / 'data' / 'schema'
+        if schema_path.is_dir():
+            return Path(str(schema_path))
+    except (ImportError, AttributeError):
+        pass
+    
+    return None
+
+
+def get_database_info(conn: sqlite3.Connection) -> dict:
+    """
+    Get information about the database structure and contents.
+    
+    Args:
+        conn: Database connection
+        
+    Returns:
+        Dictionary with database information
+    """
+    info = {
+        "tables": [],
+        "networks": 0,
+        "components": 0,
+        "attributes": 0,
+        "scenarios": 0,
+        "carriers": 0
+    }
+    
+    # Get table list
+    cursor = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+    )
+    info["tables"] = [row[0] for row in cursor.fetchall()]
+    
+    # Get counts for main entities
+    count_queries = {
+        "networks": "SELECT COUNT(*) FROM networks",
+        "components": "SELECT COUNT(*) FROM components", 
+        "attributes": "SELECT COUNT(*) FROM component_attributes",
+        "scenarios": "SELECT COUNT(*) FROM scenarios",
+        "carriers": "SELECT COUNT(*) FROM carriers"
+    }
+    
+    for key, query in count_queries.items():
+        try:
+            cursor = conn.execute(query)
+            info[key] = cursor.fetchone()[0]
+        except sqlite3.Error:
+            # Table might not exist
+            info[key] = 0
+    
+    return info
+
+
+def check_database_compatibility(conn: sqlite3.Connection) -> dict:
+    """
+    Check if database is compatible with current PyConvexity version.
+    
+    Args:
+        conn: Database connection
+        
+    Returns:
+        Dictionary with compatibility information
+    """
+    result = {
+        "compatible": True,
+        "version": None,
+        "issues": [],
+        "warnings": []
+    }
+    
+    try:
+        validate_database(conn)
+    except ValidationError as e:
+        result["compatible"] = False
+        result["issues"].append(str(e))
+    
+    # Check for version information (if we add a version table later)
+    try:
+        cursor = conn.execute("SELECT version FROM database_version LIMIT 1")
+        row = cursor.fetchone()
+        if row:
+            result["version"] = row[0]
+    except sqlite3.Error:
+        result["warnings"].append("No version information found in database")
+    
+    return result

pyconvexity/core/errors.py

@@ -0,0 +1,100 @@
+"""
+Error classes for PyConvexity.
+
+These mirror the error handling from the original Rust implementation
+while providing Python-specific enhancements.
+"""
+
+from typing import Optional
+
+
+class PyConvexityError(Exception):
+    """Base exception for all PyConvexity errors"""
+    pass
+
+
+class DatabaseError(PyConvexityError):
+    """Database-related errors"""
+    pass
+
+
+class ConnectionError(DatabaseError):
+    """Database connection failed"""
+    pass
+
+
+class ValidationError(PyConvexityError):
+    """Data validation error"""
+    pass
+
+
+class ComponentNotFound(PyConvexityError):
+    """Component not found in database"""
+    
+    def __init__(self, component_id: int, message: Optional[str] = None):
+        self.component_id = component_id
+        if message is None:
+            message = f"Component not found: {component_id}"
+        super().__init__(message)
+
+
+class AttributeNotFound(PyConvexityError):
+    """Attribute not found for component"""
+    
+    def __init__(self, component_id: int, attribute_name: str, message: Optional[str] = None):
+        self.component_id = component_id
+        self.attribute_name = attribute_name
+        if message is None:
+            message = f"Attribute not found: component {component_id}, attribute '{attribute_name}'"
+        super().__init__(message)
+
+
+class InvalidDataType(ValidationError):
+    """Invalid data type for attribute"""
+    
+    def __init__(self, expected: str, actual: str, message: Optional[str] = None):
+        self.expected = expected
+        self.actual = actual
+        if message is None:
+            message = f"Invalid data type: expected {expected}, got {actual}"
+        super().__init__(message)
+
+
+class TimeseriesError(PyConvexityError):
+    """Timeseries serialization/deserialization error"""
+    pass
+
+
+class NetworkNotFound(PyConvexityError):
+    """Network not found in database"""
+    
+    def __init__(self, network_id: int, message: Optional[str] = None):
+        self.network_id = network_id
+        if message is None:
+            message = f"Network not found: {network_id}"
+        super().__init__(message)
+
+
+class ScenarioNotFound(PyConvexityError):
+    """Scenario not found in database"""
+    
+    def __init__(self, scenario_id: int, message: Optional[str] = None):
+        self.scenario_id = scenario_id
+        if message is None:
+            message = f"Scenario not found: {scenario_id}"
+        super().__init__(message)
+
+
+class CarrierNotFound(PyConvexityError):
+    """Carrier not found in database"""
+    
+    def __init__(self, carrier_id: int, message: Optional[str] = None):
+        self.carrier_id = carrier_id
+        if message is None:
+            message = f"Carrier not found: {carrier_id}"
+        super().__init__(message)
+
+
+# Legacy aliases for backward compatibility with existing code
+# These will be deprecated in future versions
+DbError = PyConvexityError