pyseekdb 0.1.0.dev3__py3-none-any.whl

pyseekdb/__init__.py

@@ -0,0 +1,90 @@
+"""
+SeekDBClient - Unified vector database client wrapper
+
+Based on seekdb and pymysql, providing a simple and unified API.
+
+Supports three modes:
+1. Embedded mode - using local seekdb
+2. Server mode - connecting to remote seekdb via pymysql
+3. OceanBase mode - connecting to OceanBase via pymysql
+
+Examples:
+    >>> import seekdbclient
+
+    >>> # Embedded mode - Collection management
+    >>> client = seekdbclient.Client(path="./seekdb", database="test")
+
+    >>> # Server mode - Collection management
+    >>> client = seekdbclient.Client(
+    ...     host='localhost',
+    ...     port=2881,
+    ...     database="test",
+    ...     user="root",
+    ...     password="pass"
+    ... )
+
+    >>> # OceanBase mode - Collection management
+    >>> ob_client = seekdbclient.OBClient(
+    ...     host='localhost',
+    ...     port=2881,
+    ...     tenant="test",
+    ...     database="test",
+    ...     user="root",
+    ...     password=""
+    ... )
+
+    >>> # Admin client - Database management
+    >>> admin = seekdbclient.AdminClient(path="./seekdb")
+    >>> admin.create_database("new_db")
+    >>> databases = admin.list_databases()
+"""
+import logging
+import importlib.metadata
+
+from .client import (
+    BaseConnection,
+    BaseClient,
+    ClientAPI,
+    SeekdbEmbeddedClient,
+    SeekdbServerClient,
+    OceanBaseServerClient,
+    Client,
+    OBClient,
+    AdminAPI,
+    AdminClient,
+    OBAdminClient,
+    Database,
+)
+from .client.collection import Collection
+from .client.query_result import QueryResult
+
+try:
+  __version__ = importlib.metadata.version("seekdbclient")
+except importlib.metadata.PackageNotFoundError:
+  __version__ = "0.0.1.dev1"
+
+__author__ = "SeekDBClient Team"
+
+__all__ = [
+    'BaseConnection',
+    'BaseClient',
+    'ClientAPI',
+    'SeekdbEmbeddedClient',
+    'SeekdbServerClient',
+    'OceanBaseServerClient',
+    'Client',
+    'OBClient',
+    'Collection',
+    'QueryResult',
+    'AdminAPI',
+    'AdminClient',
+    'OBAdminClient',
+    'Database',
+]
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+

pyseekdb/client/__init__.py

@@ -0,0 +1,324 @@
+"""
+SeekDBClient client module
+
+Provides client and admin factory functions with strict separation:
+
+Collection Management (ClientAPI):
+- Client() - Smart factory for Embedded/Server mode
+- OBClient() - OceanBase client factory
+- Returns: _ClientProxy (collection operations only)
+
+Database Management (AdminAPI):
+- AdminClient() - Smart factory for Embedded/Server mode  
+- OBAdminClient() - OceanBase admin factory
+- Returns: _AdminClientProxy (database operations only)
+
+All factories use the underlying ServerAPI implementations:
+- SeekdbEmbeddedClient - Local seekdb
+- SeekdbServerClient - Remote seekdb via pymysql
+- OceanBaseServerClient - OceanBase via pymysql
+"""
+import logging
+from typing import Optional, Union
+
+from .base_connection import BaseConnection
+from .client_base import BaseClient, ClientAPI
+from .client_seekdb_embedded import SeekdbEmbeddedClient
+from .client_seekdb_server import SeekdbServerClient
+from .client_oceanbase_server import OceanBaseServerClient
+from .admin_client import AdminAPI, _AdminClientProxy, _ClientProxy
+from .database import Database
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    'BaseConnection',
+    'BaseClient',
+    'ClientAPI',
+    'SeekdbEmbeddedClient',
+    'SeekdbServerClient',
+    'OceanBaseServerClient',
+    'Client',
+    'OBClient',
+    'AdminAPI',
+    'AdminClient',
+    'OBAdminClient',
+    'Database',
+]
+
+
+def Client(
+    path: Optional[str] = None,
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+    database: str = "test",
+    user: Optional[str] = None,
+    password: str = "",
+    **kwargs
+) -> _ClientProxy:
+    """
+    Smart client factory function (returns ClientProxy for collection operations only)
+    
+    Automatically selects embedded or server mode based on parameters:
+    - If path is provided, uses embedded mode
+    - If host/port is provided, uses server mode
+    
+    Returns a ClientProxy that only exposes collection operations.
+    For database management, use AdminClient().
+    
+    Args:
+        path: seekdb data directory path (embedded mode)
+        host: server address (server mode)
+        port: server port (server mode)
+        database: database name
+        user: username (server mode)
+        password: password (server mode)
+        **kwargs: other parameters
+    
+    Returns:
+        _ClientProxy: A proxy that only exposes collection operations
+    
+    Examples:
+        >>> # Embedded mode
+        >>> client = Client(path="/path/to/seekdb", database="db1")
+        >>> client.create_collection("my_collection")  # ✅ Available
+        >>> # client.create_database("new_db")  # ❌ Not available
+        
+        >>> # Server mode
+        >>> client = Client(
+        ...     host='localhost',
+        ...     port=2882,
+        ...     database="db1",
+        ...     user="u01",
+        ...     password="pass"
+        ... )
+    """
+    # Determine mode and create appropriate server
+    if path is not None:
+        # Embedded mode
+        logger.info(f"Creating embedded client: path={path}, database={database}")
+        server = SeekdbEmbeddedClient(
+            path=path,
+            database=database,
+            **kwargs
+        )
+    
+    elif host is not None:
+        # Server mode
+        if port is None:
+            port = 2882  # Default port
+        if user is None:
+            user = "root"
+        
+        logger.info(
+            f"Creating server mode client: {user}@{host}:{port}/{database}"
+        )
+        server = SeekdbServerClient(
+            host=host,
+            port=port,
+            database=database,
+            user=user,
+            password=password,
+            **kwargs
+        )
+    
+    else:
+        raise ValueError(
+            "Must provide either path (embedded mode) or host (server mode) parameter"
+        )
+    
+    # Return ClientProxy (only exposes collection operations)
+    return _ClientProxy(server=server)
+
+
+def OBClient(
+    host: str = "localhost",
+    port: int = 2881,
+    tenant: str = "test",
+    database: str = "test",
+    user: str = "root",
+    password: str = "",
+    **kwargs
+) -> _ClientProxy:
+    """
+    OceanBase client factory function (returns ClientProxy for collection operations only)
+    
+    Returns a ClientProxy that only exposes collection operations.
+    For database management, use OBAdminClient().
+    
+    Args:
+        host: server address
+        port: server port (default 2881)
+        tenant: tenant name
+        database: database name
+        user: username (without tenant suffix)
+        password: password
+        **kwargs: other parameters
+    
+    Returns:
+        _ClientProxy: A proxy that only exposes collection operations
+    
+    Examples:
+        >>> client = OBClient(
+        ...     host='localhost',
+        ...     port=2881,
+        ...     tenant="tenant1",
+        ...     database="db1",
+        ...     user="u01",
+        ...     password="pass"
+        ... )
+        >>> client.create_collection("my_collection")  # ✅ Available
+        >>> # client.create_database("new_db")  # ❌ Not available
+    """
+    logger.info(
+        f"Creating OceanBase client: {user}@{tenant}@{host}:{port}/{database}"
+    )
+    
+    server = OceanBaseServerClient(
+        host=host,
+        port=port,
+        tenant=tenant,
+        database=database,
+        user=user,
+        password=password,
+        **kwargs
+    )
+    
+    # Return ClientProxy (only exposes collection operations)
+    return _ClientProxy(server=server)
+
+
+def AdminClient(
+    path: Optional[str] = None,
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+    user: Optional[str] = None,
+    password: str = "",
+    **kwargs
+) -> _AdminClientProxy:
+    """
+    Smart admin client factory function (proxy pattern)
+    
+    Automatically selects embedded or server mode based on parameters:
+    - If path is provided, uses embedded mode
+    - If host/port is provided, uses server mode
+    
+    Returns a lightweight AdminClient proxy that only exposes database operations.
+    For collection management, use Client().
+    
+    Args:
+        path: seekdb data directory path (embedded mode)
+        host: server address (server mode)
+        port: server port (server mode)
+        user: username (server mode)
+        password: password (server mode)
+        **kwargs: other parameters
+    
+    Returns:
+        _AdminClientProxy: A proxy that only exposes database operations
+    
+    Examples:
+        >>> # Embedded mode
+        >>> admin = AdminClient(path="/path/to/seekdb")
+        >>> admin.create_database("new_db")  # ✅ Available
+        >>> # admin.create_collection("coll")  # ❌ Not available
+        
+        >>> # Server mode
+        >>> admin = AdminClient(
+        ...     host='localhost',
+        ...     port=2882,
+        ...     user="root",
+        ...     password="pass"
+        ... )
+    """
+    # Determine mode and create appropriate server
+    if path is not None:
+        # Embedded mode
+        logger.info(f"Creating embedded admin client: path={path}")
+        server = SeekdbEmbeddedClient(
+            path=path,
+            database="information_schema",  # Use system database for admin operations
+            **kwargs
+        )
+    
+    elif host is not None:
+        # Server mode
+        if port is None:
+            port = 2882  # Default port
+        if user is None:
+            user = "root"
+        
+        logger.info(
+            f"Creating server mode admin client: {user}@{host}:{port}"
+        )
+        server = SeekdbServerClient(
+            host=host,
+            port=port,
+            database="information_schema",  # Use system database
+            user=user,
+            password=password,
+            **kwargs
+        )
+    
+    else:
+        raise ValueError(
+            "Must provide either path (embedded mode) or host (server mode) parameter"
+        )
+    
+    # Return AdminClient proxy (only exposes database operations)
+    return _AdminClientProxy(server=server)
+
+
+def OBAdminClient(
+    host: str = "localhost",
+    port: int = 2881,
+    tenant: str = "test",
+    user: str = "root",
+    password: str = "",
+    **kwargs
+) -> _AdminClientProxy:
+    """
+    OceanBase admin client factory function (proxy pattern)
+    
+    Returns a lightweight AdminClient proxy that only exposes database operations.
+    For collection management, use OBClient().
+    
+    Args:
+        host: server address
+        port: server port (default 2881)
+        tenant: tenant name
+        user: username (without tenant suffix)
+        password: password
+        **kwargs: other parameters
+    
+    Returns:
+        _AdminClientProxy: A proxy that only exposes database operations
+    
+    Examples:
+        >>> admin = OBAdminClient(
+        ...     host='localhost',
+        ...     port=2881,
+        ...     tenant="tenant1",
+        ...     user="root",
+        ...     password="pass"
+        ... )
+        >>> admin.create_database("new_db")  # ✅ Available
+        >>> # admin.create_collection("coll")  # ❌ Not available
+    """
+    logger.info(
+        f"Creating OceanBase admin client: {user}@{tenant}@{host}:{port}"
+    )
+    
+    server = OceanBaseServerClient(
+        host=host,
+        port=port,
+        tenant=tenant,
+        database="information_schema",  # Use system database
+        user=user,
+        password=password,
+        **kwargs
+    )
+    
+    # Return AdminClient proxy (only exposes database operations)
+    return _AdminClientProxy(server=server)
+

pyseekdb/client/admin_client.py

@@ -0,0 +1,202 @@
+"""
+Admin client interface and implementation for database management
+
+Also includes ClientProxy for strict separation of Collection vs Database operations
+"""
+from abc import ABC, abstractmethod
+from typing import List, Optional, Sequence, TYPE_CHECKING
+
+from .database import Database
+
+if TYPE_CHECKING:
+    from .client_base import BaseClient, ClientAPI
+    from .collection import Collection
+
+DEFAULT_TENANT = "test"
+
+
+class AdminAPI(ABC):
+    """
+    Abstract admin API interface for database management.
+    Defines the contract for database operations.
+    """
+    
+    @abstractmethod
+    def create_database(self, name: str, tenant: str = DEFAULT_TENANT) -> None:
+        """
+        Create database
+        
+        Args:
+            name: database name
+            tenant: tenant name (for OceanBase)
+        """
+        pass
+    
+    @abstractmethod
+    def get_database(self, name: str, tenant: str = DEFAULT_TENANT) -> Database:
+        """
+        Get database object
+        
+        Args:
+            name: database name
+            tenant: tenant name (for OceanBase)
+            
+        Returns:
+            Database object
+        """
+        pass
+    
+    @abstractmethod
+    def delete_database(self, name: str, tenant: str = DEFAULT_TENANT) -> None:
+        """
+        Delete database
+        
+        Args:
+            name: database name
+            tenant: tenant name (for OceanBase)
+        """
+        pass
+    
+    @abstractmethod
+    def list_databases(
+        self,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        tenant: str = DEFAULT_TENANT
+    ) -> Sequence[Database]:
+        """
+        List all databases
+        
+        Args:
+            limit: maximum number of results to return
+            offset: number of results to skip
+            tenant: tenant name (for OceanBase)
+            
+        Returns:
+            Sequence of Database objects
+        """
+        pass
+
+
+class _AdminClientProxy(AdminAPI):
+    """
+    A lightweight facade that delegates all operations to the underlying ServerAPI (BaseClient).
+    The actual logic is in the specific client implementations (Embedded/Server/OceanBase).
+    
+    Note: This is an internal class. Users should use the AdminClient() factory function.
+    """
+    
+    _server: "BaseClient"
+    
+    def __init__(self, server: "BaseClient") -> None:
+        """
+        Initialize admin client with a server implementation
+        
+        Args:
+            server: The underlying client that implements the actual logic
+        """
+        self._server = server
+    
+    def create_database(self, name: str, tenant: str = DEFAULT_TENANT) -> None:
+        """Proxy to server implementation"""
+        return self._server.create_database(name=name, tenant=tenant)
+    
+    def get_database(self, name: str, tenant: str = DEFAULT_TENANT) -> Database:
+        """Proxy to server implementation"""
+        return self._server.get_database(name=name, tenant=tenant)
+    
+    def delete_database(self, name: str, tenant: str = DEFAULT_TENANT) -> None:
+        """Proxy to server implementation"""
+        return self._server.delete_database(name=name, tenant=tenant)
+    
+    def list_databases(
+        self,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        tenant: str = DEFAULT_TENANT
+    ) -> Sequence[Database]:
+        """Proxy to server implementation"""
+        return self._server.list_databases(limit=limit, offset=offset, tenant=tenant)
+    
+    def __repr__(self):
+        return f"<AdminClient server={self._server}>"
+    
+    def __enter__(self):
+        """Context manager support - delegate to server"""
+        self._server.__enter__()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support - delegate to server"""
+        return self._server.__exit__(exc_type, exc_val, exc_tb)
+
+
+class _ClientProxy:
+    """
+    Internal client proxy for collection operations only.
+    Strictly separates collection management from database management.
+    
+    Note: This is an internal class. Users should use the Client() factory function.
+    """
+    
+    _server: "BaseClient"
+    
+    def __init__(self, server: "BaseClient") -> None:
+        """
+        Initialize client with a server implementation
+        
+        Args:
+            server: The underlying client that implements the actual logic
+        """
+        self._server = server
+    
+    def create_collection(
+        self,
+        name: str,
+        dimension: Optional[int] = None,
+        **kwargs
+    ) -> "Collection":
+        """Proxy to server implementation - collection operations only"""
+        return self._server.create_collection(name=name, dimension=dimension, **kwargs)
+    
+    def get_collection(self, name: str) -> "Collection":
+        """Proxy to server implementation - collection operations only"""
+        return self._server.get_collection(name=name)
+    
+    def delete_collection(self, name: str) -> None:
+        """Proxy to server implementation - collection operations only"""
+        return self._server.delete_collection(name=name)
+    
+    def list_collections(self) -> List["Collection"]:
+        """Proxy to server implementation - collection operations only"""
+        return self._server.list_collections()
+    
+    def has_collection(self, name: str) -> bool:
+        """Proxy to server implementation - collection operations only"""
+        return self._server.has_collection(name=name)
+    
+    def get_or_create_collection(
+        self,
+        name: str,
+        dimension: Optional[int] = None,
+        **kwargs
+    ) -> "Collection":
+        """Proxy to server implementation - collection operations only"""
+        return self._server.get_or_create_collection(name=name, dimension=dimension, **kwargs)
+    
+    def count_collection(self) -> int:
+        """Proxy to server implementation - collection operations only"""
+        return self._server.count_collection()
+    
+    def __repr__(self):
+        return f"<Client server={self._server}>"
+    
+    def __enter__(self):
+        """Context manager support - delegate to server"""
+        self._server.__enter__()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support - delegate to server"""
+        return self._server.__exit__(exc_type, exc_val, exc_tb)
+

pyseekdb/client/base_connection.py

@@ -0,0 +1,82 @@
+"""
+Base connection interface definition
+"""
+from abc import ABC, abstractmethod
+from typing import Any
+
+class _Transaction:
+    """
+    Internal transaction object
+    """
+    def __init__(self, connection: "BaseConnection"):
+        self._connection = connection
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None:
+            self._connection.rollback()
+        else:
+            self._connection.commit()
+
+class BaseConnection(ABC):
+    """
+    Abstract base class for connection management.
+    Defines unified connection interface for all clients.
+    """
+    
+    # ==================== Connection Management ====================
+    
+    @abstractmethod
+    def _ensure_connection(self) -> Any:
+        """Ensure connection is established (internal method)"""
+        pass
+    
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Check connection status"""
+        pass
+    
+    @abstractmethod
+    def _cleanup(self):
+        """Internal cleanup method to close connection and release resources"""
+        pass
+    
+    @abstractmethod
+    def execute(self, sql: str) -> Any:
+        """Execute SQL statement (basic functionality)"""
+        pass
+
+    
+    @abstractmethod
+    def get_raw_connection(self) -> Any:
+        """Get raw connection object"""
+        pass
+    
+    @property
+    @abstractmethod
+    def mode(self) -> str:
+        """Return client mode (e.g., 'SeekdbEmbeddedClient', 'SeekdbServerClient', 'OceanBaseServerClient')"""
+        pass
+    
+    # ==================== Context Manager ====================
+    
+    def __enter__(self):
+        """Context manager support"""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support: automatic resource cleanup"""
+        self._cleanup()
+    
+    def __del__(self):
+        """Destructor: ensure connection is closed to prevent resource leaks"""
+        try:
+            if hasattr(self, '_connection') and self.is_connected():
+                self._cleanup()
+        except Exception:
+            # Ignore all exceptions in destructor
+            # Avoid issues during interpreter shutdown
+            pass
+