velocity-python 0.0.109__py3-none-any.whl → 0.0.161__py3-none-any.whl

velocity/db/core/transaction.py

@@ -6,6 +6,7 @@ from velocity.db.core.result import Result
 from velocity.db.core.column import Column
 from velocity.db.core.database import Database
 from velocity.db.core.sequence import Sequence
+from velocity.db.utils import mask_config_for_display
 from velocity.misc.db import randomword
 
 debug = False
@@ -22,10 +23,14 @@ class Transaction:
         self.__pg_types = {}
 
     def __str__(self):
-        c = self.engine.config
-        server = c.get("host", c.get("server"))
-        database = c.get("database")
-        return f"{self.engine.sql.server}.transaction({server}:{database})"
+        config = mask_config_for_display(self.engine.config)
+
+        if isinstance(config, dict):
+            server = config.get("host", config.get("server"))
+            database = config.get("database", config.get("dbname"))
+            return f"{self.engine.sql.server}.transaction({server}:{database})"
+
+        return f"{self.engine.sql.server}.transaction({config})"
 
     def __enter__(self):
         return self
@@ -164,17 +169,25 @@ class Transaction:
         """
         return Row(self.table(tablename), pk, lock=lock)
 
-    def get(self, tablename, where, lock=None):
-        """
-        Shortcut to table.get().
-        """
-        return self.table(tablename).get(where, lock=lock)
-
-    def find(self, tablename, where, lock=None):
-        """
-        Shortcut to table.find().
-        """
-        return self.table(tablename).find(where, lock=lock)
+    def get(self, tablename, where, lock=None, use_where=False):
+        """Shortcut to table.get() with optional ``use_where`` passthrough."""
+        return self.table(tablename).get(where, lock=lock, use_where=use_where)
+
+    def find(
+        self,
+        tablename,
+        where,
+        lock=None,
+        use_where=False,
+        raise_if_missing=False,
+    ):
+        """Shortcut to table.find() with ``use_where``/``raise_if_missing`` passthrough."""
+        return self.table(tablename).find(
+            where,
+            lock=lock,
+            use_where=use_where,
+            raise_if_missing=raise_if_missing,
+        )
 
     def column(self, tablename, colname):
         """

velocity/db/exceptions.py

@@ -5,108 +5,132 @@ Database exceptions for the velocity library.
 
 class DbException(Exception):
     """Base class for all database exceptions."""
+
     pass
 
 
 class DbApplicationError(DbException):
     """Application-level database error."""
+
     pass
 
 
 class DbForeignKeyMissingError(DbException):
     """Foreign key constraint violation."""
+
     pass
 
 
 class DbDatabaseMissingError(DbException):
     """Database does not exist."""
+
     pass
 
 
 class DbTableMissingError(DbException):
     """Table does not exist."""
+
     pass
 
 
 class DbColumnMissingError(DbException):
     """Column does not exist."""
+
     pass
 
 
 class DbTruncationError(DbException):
     """Data truncation error."""
+
     pass
 
 
 class DbConnectionError(DbException):
     """Database connection error."""
+
     pass
 
 
 class DbDuplicateKeyError(DbException):
     """Duplicate key constraint violation."""
+
     pass
 
 
 class DbObjectExistsError(DbException):
     """Database object already exists."""
+
     pass
 
 
 class DbLockTimeoutError(DbException):
     """Lock timeout error."""
+
     pass
 
 
 class DbRetryTransaction(DbException):
     """Transaction should be retried."""
+
     pass
 
 
 class DbDataIntegrityError(DbException):
     """Data integrity constraint violation."""
+
     pass
 
 
 class DbQueryError(DbException):
     """Database query error."""
+
     pass
 
 
 class DbTransactionError(DbException):
     """Database transaction error."""
+
+    pass
+
+
+class DbSchemaLockedError(DbApplicationError):
+    """Raised when attempting to modify schema while schema is locked."""
+
     pass
 
 
 class DuplicateRowsFoundError(Exception):
     """Multiple rows found when expecting single result."""
+
     pass
 
 
 # Add aliases for backward compatibility with engine.py
 class DatabaseError(DbException):
     """Generic database error - alias for DbException."""
+
     pass
 
+
 __all__ = [
     # Base exceptions
-    'DbException',
-    'DatabaseError',
-    
+    "DbException",
+    "DatabaseError",
     # Specific exceptions
-    'DbApplicationError',
-    'DbForeignKeyMissingError', 
-    'DbDatabaseMissingError',
-    'DbTableMissingError',
-    'DbColumnMissingError',
-    'DbTruncationError',
-    'DbConnectionError',
-    'DbDuplicateKeyError',
-    'DbObjectExistsError',
-    'DbLockTimeoutError',
-    'DbRetryTransaction',
-    'DbDataIntegrityError',
-    'DbQueryError',
-    'DbTransactionError',
-    'DuplicateRowsFoundError',
+    "DbApplicationError",
+    "DbForeignKeyMissingError",
+    "DbDatabaseMissingError",
+    "DbTableMissingError",
+    "DbColumnMissingError",
+    "DbTruncationError",
+    "DbConnectionError",
+    "DbDuplicateKeyError",
+    "DbObjectExistsError",
+    "DbLockTimeoutError",
+    "DbRetryTransaction",
+    "DbDataIntegrityError",
+    "DbQueryError",
+    "DbTransactionError",
+    "DbSchemaLockedError",
+    "DuplicateRowsFoundError",
 ]

velocity/db/servers/base/__init__.py

@@ -0,0 +1,9 @@
+"""
+Base abstract classes for database server implementations.
+"""
+from .sql import BaseSQLDialect
+from .types import BaseTypes
+from .operators import BaseOperators
+from .initializer import BaseInitializer
+
+__all__ = ["BaseSQLDialect", "BaseTypes", "BaseOperators", "BaseInitializer"]

velocity/db/servers/base/initializer.py

@@ -0,0 +1,70 @@
+"""
+Abstract base class for database initialization.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+from velocity.db.core import engine
+
+
+class BaseInitializer(ABC):
+    """
+    Abstract base class for database connection initialization.
+    
+    Each database implementation should provide a concrete implementation
+    of the initialize method to set up database connections properly.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def initialize(config: Optional[Dict[str, Any]] = None, schema_locked: bool = False, **kwargs) -> engine.Engine:
+        """
+        Initialize a database engine with the appropriate driver and configuration.
+        
+        Args:
+            config: Configuration dictionary (can be None)
+            schema_locked: Boolean to lock schema modifications (default: False)
+            **kwargs: Additional configuration parameters
+            
+        Returns:
+            Configured Engine instance
+            
+        Raises:
+            ImportError: If required database driver is not available
+            ValueError: If configuration is invalid
+        """
+        pass
+
+    @staticmethod
+    def _merge_config(base_config: Dict[str, Any], config: Optional[Dict[str, Any]], **kwargs) -> Dict[str, Any]:
+        """
+        Helper method to merge configuration from multiple sources.
+        
+        Args:
+            base_config: Base configuration (e.g., from environment)
+            config: User-provided configuration
+            **kwargs: Additional keyword arguments
+            
+        Returns:
+            Merged configuration dictionary
+        """
+        final_config = base_config.copy()
+        if config:
+            final_config.update(config)
+        final_config.update(kwargs)
+        return final_config
+
+    @staticmethod
+    def _validate_required_config(config: Dict[str, Any], required_keys: list[str]) -> None:
+        """
+        Validate that required configuration keys are present.
+        
+        Args:
+            config: Configuration to validate
+            required_keys: List of required configuration keys
+            
+        Raises:
+            ValueError: If required keys are missing
+        """
+        missing_keys = [key for key in required_keys if key not in config]
+        if missing_keys:
+            raise ValueError(f"Missing required configuration keys: {missing_keys}")

velocity/db/servers/base/operators.py

@@ -0,0 +1,98 @@
+"""
+Abstract base class for database operator mapping implementations.
+"""
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class BaseOperators(ABC):
+    """
+    Abstract base class that defines the interface for database operator mappings.
+    
+    Each database implementation should provide concrete implementations of operator
+    mappings to handle conversion between Velocity.DB operators and SQL operators.
+    """
+
+    @classmethod
+    @abstractmethod
+    def get_operators(cls) -> Dict[str, str]:
+        """
+        Returns a dictionary mapping Velocity.DB operators to SQL operators.
+        
+        This method should return a complete mapping of all operators supported
+        by this database implementation.
+        
+        Returns:
+            Dictionary mapping operator symbols to SQL operators
+            
+        Examples:
+            {
+                "=": "=",
+                "!=": "<>",
+                "<>": "<>", 
+                "%": "LIKE",
+                "!%": "NOT LIKE",
+                "%%": "ILIKE",  # PostgreSQL case-insensitive
+                "!%%": "NOT ILIKE",
+                "><": "BETWEEN",
+                "!><": "NOT BETWEEN",
+                # ... etc
+            }
+        """
+        pass
+
+    @classmethod
+    def get_base_operators(cls) -> Dict[str, str]:
+        """
+        Returns common operators supported by most databases.
+        Subclasses can use this as a starting point and override specific operators.
+        
+        Returns:
+            Dictionary of common SQL operators
+        """
+        return {
+            "=": "=",
+            "==": "=",
+            "!=": "<>",
+            "<>": "<>",
+            "!": "<>",
+            "<": "<",
+            ">": ">", 
+            "<=": "<=",
+            ">=": ">=",
+            "%": "LIKE",
+            "!%": "NOT LIKE",
+            "><": "BETWEEN",
+            "!><": "NOT BETWEEN",
+            ">!<": "NOT BETWEEN",
+        }
+
+    @classmethod
+    def supports_case_insensitive_like(cls) -> bool:
+        """
+        Returns True if this database supports case-insensitive LIKE operations.
+        
+        Returns:
+            True if database supports ILIKE or similar
+        """
+        return False
+
+    @classmethod
+    def supports_regex(cls) -> bool:
+        """
+        Returns True if this database supports regular expressions.
+        
+        Returns:
+            True if database supports regex operators
+        """
+        return False
+
+    @classmethod
+    def get_regex_operators(cls) -> Dict[str, str]:
+        """
+        Returns regex operators if supported by this database.
+        
+        Returns:
+            Dictionary of regex operators or empty dict if not supported
+        """
+        return {}