kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/lib/ontology/basic/base.py

@@ -0,0 +1,102 @@
+from abc import ABC
+from typing import Dict, Any
+
+# Avoid circular imports by using type hint strings
+# from .concept import Concept
+
+
+class ConceptInstance(ABC):
+    """Abstract base class for concept instances (e.g., Object, Relation)
+
+        Attributes:
+            concept (Concept): The concept definition this instance belongs to.
+            values (Dict[str, Any]): Instance members and their corresponding values.
+    """
+
+    def __init__(self, concept: "Concept", values: Dict[str, Any]):
+        """Initialize concept instance
+
+        Args:
+            concept (Concept): The concept this instance belongs to.
+            values (Dict[str, Any]): Instance members and their corresponding values.
+
+        Raises:
+            TypeError: If concept is not an instance of Concept.
+            ValueError: If the provided values do not match the members or type requirements of Concept.
+        """
+        # Delayed import to avoid circular dependencies
+        from .concept import Concept
+
+        if not isinstance(concept, Concept):
+            raise TypeError("必须提供一个 Concept 实例")
+
+        # 1. Verify that the member exists and is complete
+        providedMembers = set(values.keys())
+        if not concept.validateMembers(providedMembers):
+            missing = set(concept.members.keys()) - providedMembers
+            extra = providedMembers - set(concept.members.keys())
+            errorMsg = f"实例的成员与 Concept '{concept.name}' 不匹配。"
+            if missing:
+                errorMsg += f" 缺少成员: {missing}."
+            if extra:
+                errorMsg += f" 多余成员: {extra}."
+            raise ValueError(errorMsg)
+
+        # 2. Validate member value types
+        for memberName, value in values.items():
+            if not concept.validateMemberValue(memberName, value):
+                expectedType = concept.members[memberName].name
+                actualType = type(value).__name__
+                raise TypeError(
+                    f"成员 '{memberName}' 的值类型错误。期望类型: {expectedType}, 实际类型: {actualType}"
+                )
+
+        # Use object.__setattr__ to avoid triggering custom __setattr__
+        object.__setattr__(self, "concept", concept)
+        object.__setattr__(self, "values", values)
+
+    def __getattr__(self, name: str) -> Any:
+        """Allow accessing member values through attributes"""
+        if name == "concept" or name == "values":
+            # Prevent infinite recursion
+            raise AttributeError
+
+        try:
+            # Try to get the value from the values dictionary
+            return self.values[name]
+        except KeyError:
+            # If the value does not exist, an AttributeError is raised.
+            raise AttributeError(
+                f"'{type(self).__name__}' 对象没有属性 '{name}' 或该属性未在 values 中定义"
+            )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Allow setting member values through attributes (if the member is defined in the Concept)"""
+        if name in ["concept", "values"]:
+            # Allow setting internal attributes
+            object.__setattr__(self, name, value)
+        elif name in self.concept.members:
+            # Validate the type of the new value
+            if not self.concept.validateMemberValue(name, value):
+                expectedType = self.concept.members[name].name
+                actualType = type(value).__name__
+                raise TypeError(
+                    f"尝试设置的成员 '{name}' 的值类型错误。期望类型: {expectedType}, 实际类型: {actualType}"
+                )
+            # Set value
+            self.values[name] = value
+        else:
+            raise AttributeError(
+                f"无法设置属性 '{name}'，因为它不是 Concept '{self.concept.name}' 定义的成员"
+            )
+
+    def __repr__(self) -> str:
+        """Return the string representation of the instance."""
+        return f"{type(self).__name__}(concept='{self.concept.name}', values={self.values})"
+
+    # Additional generic instance methods can be added
+    # For example, get the value of a specific member, check if a member exists, etc.
+
+
+# Additional general instance methods can be added
+# For example, retrieving the value of a specific member, checking whether a member exists, etc.

dolphin/lib/ontology/basic/concept.py

@@ -0,0 +1,130 @@
+from typing import Set, Dict, Any
+from enum import Enum, auto
+
+
+class ConceptMemberType(Enum):
+    """Type of Concept Members"""
+
+    STRING = auto()
+    NUMBER = auto()
+    BOOLEAN = auto()
+    OBJECT = auto()  # Referencing Other Objects
+    RELATION = auto()  # Referencing Other Relations
+    ANY = auto()  # Any type
+
+
+class Concept:
+    """Define the contract (structure) for concepts
+
+        A Concept defines a set of required member names and their types.
+        Each member can have type constraints used to validate values during instantiation.
+    """
+
+    def __init__(self, name: str, members: Dict[str, ConceptMemberType]):
+        """Initialize Concept
+
+        Args:
+            name (str): The name of the concept
+            members (Dict[str, ConceptMemberType]): A mapping from member names to their types
+
+        Raises:
+            ValueError: If the name is empty or no members are defined
+        """
+        if not name:
+            raise ValueError("概念名称不能为空")
+        if not members:
+            raise ValueError("概念必须至少定义一个成员")
+
+        self.name = name
+        self.members = members
+        self.mappings = []
+
+    def __repr__(self) -> str:
+        members_str = {name: type.name for name, type in self.members.items()}
+        return f"Concept(name='{self.name}', members={members_str})"
+
+    def addMapping(self, mapping):
+        self.mappings.append(mapping)
+
+    def getDataSourceSchemas(self) -> Dict[str, Any]:
+        """Get the schema of all associated data sources"""
+        dataSourceSchemas = {}
+        for mapping in self.mappings:
+            dataSourceSchemas[mapping.space] = mapping.getDataSourceSchema()
+        return dataSourceSchemas
+
+    def validateMembers(self, provided_members: Set[str]) -> bool:
+        """Check whether the provided member set fully matches the requirements defined by this Concept
+
+        Args:
+            provided_members (Set[str]): Set of member names to validate
+
+        Returns:
+            bool: True if the provided members exactly match the defined members
+        """
+        return set(self.members.keys()) == provided_members
+
+    def validateMemberValue(self, memberName: str, value: Any) -> bool:
+        """Validate whether the member's value meets the type requirements
+
+        Args:
+            member_name (str): The name of the member
+            value (Any): The value to validate
+
+        Returns:
+            bool: True if the value meets the type requirements
+
+        Raises:
+            KeyError: If the member name does not exist
+        """
+        if memberName not in self.members:
+            raise KeyError(f"成员 '{memberName}' 未在概念 '{self.name}' 中定义")
+
+        expectedType = self.members[memberName]
+
+        # If the type is ANY, return True directly
+        if expectedType == ConceptMemberType.ANY:
+            return True
+
+        # Validate according to the expected type
+        if expectedType == ConceptMemberType.STRING:
+            return isinstance(value, str)
+        elif expectedType == ConceptMemberType.BOOLEAN:
+            # Note: In Python, bool is a subclass of int; BOOLEAN must be checked first
+            return isinstance(value, bool)
+        elif expectedType == ConceptMemberType.NUMBER:
+            # Exclude bool from NUMBER to avoid misjudging True/False as numbers
+            return isinstance(value, (int, float)) and not isinstance(value, bool)
+        elif expectedType == ConceptMemberType.OBJECT:
+            from .object import Object
+
+            return isinstance(value, Object)
+        elif expectedType == ConceptMemberType.RELATION:
+            from .relation import Relation
+
+            return isinstance(value, Relation)
+
+        return False  # Unknown type
+
+    def validateValues(self, values: Dict[str, Any]) -> bool:
+        """Validate that all values conform to the concept definition
+
+        Args:
+            values (Dict[str, Any]): Dictionary of values to validate
+
+        Returns:
+            bool: True if all values meet the requirements
+        """
+        if not self.validateMembers(set(values.keys())):
+            return False
+
+        return all(
+            self.validateMemberValue(name, value) for name, value in values.items()
+        )
+
+    def toDict(self) -> Dict[str, Any]:
+        """Convert concepts to dictionary"""
+        return {
+            "name": self.name,
+            "members": {name: type_.name for name, type_ in self.members.items()},
+        }

dolphin/lib/ontology/basic/object.py

@@ -0,0 +1,11 @@
+from dolphin.lib.ontology.basic.base import ConceptInstance
+
+
+class Object(ConceptInstance):
+    """A concrete instance (object) representing a Concept.
+
+        The Object must adhere to the member contract defined by its associated Concept.
+        The values of members can be any Python type, or references to other Object/Relation.
+    """
+
+    pass  # All basic functions inherit from ConceptInstance

dolphin/lib/ontology/basic/relation.py

@@ -0,0 +1,63 @@
+from typing import Dict, Any
+
+from dolphin.lib.ontology.basic.base import ConceptInstance
+from dolphin.lib.ontology.basic.concept import Concept
+
+
+class Relation(ConceptInstance):
+    """A concrete instance (relation) of a Concept
+
+        A Relation must adhere to the member contract defined by its associated Concept.
+        The values of members are typically used to connect Objects, but may also be any Python type.
+    """
+
+    pass  # All basic functions inherit from ConceptInstance
+
+    def __init__(self, concept: Concept, values: Dict[str, Any]):
+        """Initialize Relation
+
+        Args:
+            concept (Concept): The Concept to which this Relation belongs.
+            values (Dict[str, Any]): The members of the Relation and their corresponding values.
+
+        Raises:
+            ValueError: If the provided values do not meet the member requirements of the Concept.
+            TypeError: If concept is not an instance of Concept.
+        """
+        if not isinstance(concept, Concept):
+            raise TypeError("必须提供一个 Concept 实例")
+
+        provided_members = set(values.keys())
+        if not concept.validateMembers(provided_members):
+            missing = concept.members - provided_members
+            extra = provided_members - concept.members
+            error_msg = f"Relation 的成员与 Concept '{concept.name}' 不匹配。"
+            if missing:
+                error_msg += f" 缺少成员: {missing}."
+            if extra:
+                error_msg += f" 多余成员: {extra}."
+            # Strict mode: missing or extra members are not allowed.
+            raise ValueError(error_msg)
+
+        self.concept = concept
+        self.values = values
+
+    def __getattr__(self, name: str) -> Any:
+        """Allow accessing member values through attributes"""
+        if name in self.values:
+            return self.values[name]
+        raise AttributeError(f"'{type(self).__name__}' 对象没有属性 '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Allow setting member values through attributes (if the member is defined)"""
+        if name in ["concept", "values"]:
+            super().__setattr__(name, value)
+        elif name in self.concept.members:
+            self.values[name] = value
+        else:
+            raise AttributeError(
+                f"无法设置属性 '{name}'，因为它不是 Concept '{self.concept.name}' 定义的成员"
+            )
+
+    def __repr__(self) -> str:
+        return f"Relation(concept='{self.concept.name}', values={self.values})"

dolphin/lib/ontology/datasource/__init__.py

@@ -0,0 +1,27 @@
+from .datasource import DataSource
+
+# 延迟导入 SQL 相关的数据源类（需要 sqlalchemy）
+# 如果 sqlalchemy 未安装，这些类将不可用，但不会阻止模块导入
+try:
+    from .sql import DataSourceSql, DataSourceMysql, DataSourceSqlite
+    from .oracle_datasource import DataSourceOracle
+    _SQL_AVAILABLE = True
+except ImportError:
+    # sqlalchemy 未安装，这些类不可用
+    _SQL_AVAILABLE = False
+    DataSourceSql = None
+    DataSourceMysql = None
+    DataSourceSqlite = None
+    DataSourceOracle = None
+
+__all__ = [
+    "DataSource",
+]
+
+if _SQL_AVAILABLE:
+    __all__.extend([
+        "DataSourceSql",
+        "DataSourceMysql",
+        "DataSourceSqlite",
+        "DataSourceOracle",
+    ])

dolphin/lib/ontology/datasource/datasource.py

@@ -0,0 +1,66 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, TYPE_CHECKING
+
+# Modify the import, use the correct DataSourceType
+from dolphin.core.common.enums import Messages
+from dolphin.core.config import DataSourceType
+
+# Use TYPE_CHECKING to avoid circular imports
+if TYPE_CHECKING:
+    from dolphin.lib.ontology.mapping import Mapping
+
+
+class DataSource(ABC):
+    """Data source abstract base class"""
+
+    def __init__(self, name: str, type: DataSourceType, config: Dict[str, Any]):
+        self.name = name
+        self.config = config
+        self.schema = None
+
+    @abstractmethod
+    def connect(self) -> Any:
+        """Establish a connection to the data source"""
+        pass
+
+    @abstractmethod
+    def get_schema(self) -> Dict[str, List[str]]:
+        """Get the schema information of the data source (e.g., tables and columns)"""
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close data source connection"""
+        pass
+
+    @abstractmethod
+    def test_connection(self) -> bool:
+        """Test whether the data source connection is successful"""
+        pass
+
+    @abstractmethod
+    def executeQuery(self, query: str, fetchColumns: bool = True) -> Dict[str, Any]:
+        """Execute query query"""
+        pass
+
+    @abstractmethod
+    def sampleData(self, conceptName: str, count: int = 10) -> Messages:
+        """Get sample data according to concept"""
+        pass
+
+    @abstractmethod
+    def scan(self) -> List["Mapping"]:
+        """Scan the data source schema to generate Concept objects and their corresponding Mappings.
+
+                Returns a list of Mappings, where each Mapping represents the mapping relationship
+                from a data source entity (e.g., a table) to its corresponding Concept.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def type(self) -> DataSourceType:
+        """Return the data source type (using config.DataSourceType)"""
+        pass
+
+    # More general methods, such as execute_query, can be added as needed