graflo 1.1.0__py3-none-any.whl

graflo/filter/onto.py

@@ -0,0 +1,400 @@
+"""Filter expression system for database queries.
+
+This module provides a flexible system for creating and evaluating filter expressions
+that can be translated into different database query languages (AQL, Cypher, Python).
+It includes classes for logical operators, comparison operators, and filter clauses.
+
+Key Components:
+    - LogicalOperator: Enum for logical operations (AND, OR, NOT, IMPLICATION)
+    - ComparisonOperator: Enum for comparison operations (==, !=, >, <, etc.)
+    - AbsClause: Abstract base class for filter clauses
+    - LeafClause: Concrete clause for field comparisons
+    - Clause: Composite clause combining multiple sub-clauses
+    - Expression: Factory class for creating filter expressions from dictionaries
+
+Example:
+    >>> expr = Expression.from_dict({
+    ...     "AND": [
+    ...         {"field": "age", "cmp_operator": ">=", "value": 18},
+    ...         {"field": "status", "cmp_operator": "==", "value": "active"}
+    ...     ]
+    ... })
+    >>> # Converts to: "age >= 18 AND status == 'active'"
+"""
+
+import dataclasses
+import logging
+from abc import ABCMeta, abstractmethod
+from types import MappingProxyType
+
+from graflo.onto import BaseDataclass, BaseEnum, ExpressionFlavor
+
+logger = logging.getLogger(__name__)
+
+
+class LogicalOperator(BaseEnum):
+    """Logical operators for combining filter conditions.
+
+    Attributes:
+        AND: Logical AND operation
+        OR: Logical OR operation
+        NOT: Logical NOT operation
+        IMPLICATION: Logical IF-THEN operation
+    """
+
+    AND = "AND"
+    OR = "OR"
+    NOT = "NOT"
+    IMPLICATION = "IF_THEN"
+
+
+def implication(ops):
+    """Evaluate logical implication (IF-THEN).
+
+    Args:
+        ops: Tuple of (antecedent, consequent)
+
+    Returns:
+        bool: True if antecedent is False or consequent is True
+    """
+    a, b = ops
+    return b if a else True
+
+
+OperatorMapping = MappingProxyType(
+    {
+        LogicalOperator.AND: all,
+        LogicalOperator.OR: any,
+        LogicalOperator.IMPLICATION: implication,
+    }
+)
+
+
+class ComparisonOperator(BaseEnum):
+    """Comparison operators for field comparisons.
+
+    Attributes:
+        NEQ: Not equal (!=)
+        EQ: Equal (==)
+        GE: Greater than or equal (>=)
+        LE: Less than or equal (<=)
+        GT: Greater than (>)
+        LT: Less than (<)
+        IN: Membership test (IN)
+    """
+
+    NEQ = "!="
+    EQ = "=="
+    GE = ">="
+    LE = "<="
+    GT = ">"
+    LT = "<"
+    IN = "IN"
+
+
+@dataclasses.dataclass
+class AbsClause(BaseDataclass, metaclass=ABCMeta):
+    """Abstract base class for filter clauses.
+
+    This class defines the interface for all filter clauses, requiring
+    implementation of the __call__ method to evaluate or render the clause.
+    """
+
+    @abstractmethod
+    def __call__(
+        self,
+        doc_name,
+        kind: ExpressionFlavor = ExpressionFlavor.ARANGO,
+        **kwargs,
+    ):
+        """Evaluate or render the clause.
+
+        Args:
+            doc_name: Name of the document variable in the query
+            kind: Target expression flavor (ARANGO, NEO4J, PYTHON)
+            **kwargs: Additional arguments for evaluation
+
+        Returns:
+            str: Rendered clause in the target language
+        """
+        pass
+
+
+@dataclasses.dataclass
+class LeafClause(AbsClause):
+    """Concrete clause for field comparisons.
+
+    This class represents a single field comparison operation, such as
+    "field >= value" or "field IN [values]".
+
+    Attributes:
+        cmp_operator: Comparison operator to use
+        value: Value(s) to compare against
+        field: Field name to compare
+        operator: Optional operator to apply before comparison
+    """
+
+    cmp_operator: ComparisonOperator | None = None
+    value: list = dataclasses.field(default_factory=list)
+    field: str | None = None
+    operator: str | None = None
+
+    def __post_init__(self):
+        """Convert single value to list if necessary."""
+        if not isinstance(self.value, list):
+            self.value = [self.value]
+
+    def __call__(
+        self,
+        doc_name="doc",
+        kind: ExpressionFlavor = ExpressionFlavor.ARANGO,
+        **kwargs,
+    ):
+        """Render the leaf clause in the target language.
+
+        Args:
+            doc_name: Name of the document variable
+            kind: Target expression flavor
+            **kwargs: Additional arguments
+
+        Returns:
+            str: Rendered clause
+
+        Raises:
+            ValueError: If kind is not implemented
+        """
+        if not self.value:
+            logger.warning(f"for {self} value is not set : {self.value}")
+        if kind == ExpressionFlavor.ARANGO:
+            assert self.cmp_operator is not None
+            return self._cast_arango(doc_name)
+        elif kind == ExpressionFlavor.NEO4J:
+            assert self.cmp_operator is not None
+            return self._cast_cypher(doc_name)
+        elif kind == ExpressionFlavor.PYTHON:
+            return self._cast_python(**kwargs)
+        else:
+            raise ValueError(f"kind {kind} not implemented")
+
+    def _cast_value(self):
+        """Format the comparison value for query rendering.
+
+        Returns:
+            str: Formatted value string
+        """
+        value = f"{self.value[0]}" if len(self.value) == 1 else f"{self.value}"
+        if len(self.value) == 1:
+            if isinstance(self.value[0], str):
+                value = f'"{self.value[0]}"'
+            elif self.value[0] is None:
+                value = "null"
+            else:
+                value = f"{self.value[0]}"
+        return value
+
+    def _cast_arango(self, doc_name):
+        """Render the clause in AQL format.
+
+        Args:
+            doc_name: Document variable name
+
+        Returns:
+            str: AQL clause
+        """
+        const = self._cast_value()
+
+        lemma = f"{self.cmp_operator} {const}"
+        if self.operator is not None:
+            lemma = f"{self.operator} {lemma}"
+
+        if self.field is not None:
+            lemma = f'{doc_name}["{self.field}"] {lemma}'
+        return lemma
+
+    def _cast_cypher(self, doc_name):
+        """Render the clause in Cypher format.
+
+        Args:
+            doc_name: Document variable name
+
+        Returns:
+            str: Cypher clause
+        """
+        const = self._cast_value()
+        if self.cmp_operator == ComparisonOperator.EQ:
+            cmp_operator = "="
+        else:
+            cmp_operator = self.cmp_operator
+        lemma = f"{cmp_operator} {const}"
+        if self.operator is not None:
+            lemma = f"{self.operator} {lemma}"
+
+        if self.field is not None:
+            lemma = f"{doc_name}.{self.field} {lemma}"
+        return lemma
+
+    def _cast_python(self, **kwargs):
+        """Evaluate the clause in Python.
+
+        Args:
+            **kwargs: Additional arguments
+
+        Returns:
+            bool: Evaluation result
+        """
+        field = kwargs.pop(self.field, None)
+        if field is not None:
+            foo = getattr(field, self.operator)
+            return foo(self.value[0])
+        else:
+            return False
+
+
+@dataclasses.dataclass
+class Clause(AbsClause):
+    """Composite clause combining multiple sub-clauses.
+
+    This class represents a logical combination of multiple filter clauses,
+    such as "clause1 AND clause2" or "NOT clause1".
+
+    Attributes:
+        operator: Logical operator to combine clauses
+        deps: List of dependent clauses
+    """
+
+    operator: LogicalOperator
+    deps: list[AbsClause]
+
+    def __call__(
+        self,
+        doc_name="doc",
+        kind: ExpressionFlavor = ExpressionFlavor.ARANGO,
+        **kwargs,
+    ):
+        """Render the composite clause in the target language.
+
+        Args:
+            doc_name: Document variable name
+            kind: Target expression flavor
+            **kwargs: Additional arguments
+
+        Returns:
+            str: Rendered clause
+
+        Raises:
+            ValueError: If operator and dependencies don't match
+        """
+        if kind == ExpressionFlavor.ARANGO or kind == ExpressionFlavor.ARANGO:
+            return self._cast_generic(doc_name=doc_name, kind=kind)
+        elif kind == ExpressionFlavor.PYTHON:
+            return self._cast_python(kind=kind, **kwargs)
+
+    def _cast_generic(self, doc_name, kind):
+        """Render the clause in a generic format.
+
+        Args:
+            doc_name: Document variable name
+            kind: Target expression flavor
+
+        Returns:
+            str: Rendered clause
+
+        Raises:
+            ValueError: If operator and dependencies don't match
+        """
+        if len(self.deps) == 1:
+            if self.operator == LogicalOperator.NOT:
+                return f"{self.operator} {self.deps[0](kind=kind, doc_name=doc_name)}"
+            else:
+                raise ValueError(
+                    f" length of deps = {len(self.deps)} but operator is not"
+                    f" {LogicalOperator.NOT}"
+                )
+        else:
+            return f" {self.operator} ".join(
+                [item(kind=kind, doc_name=doc_name) for item in self.deps]
+            )
+
+    def _cast_python(self, kind, **kwargs):
+        """Evaluate the clause in Python.
+
+        Args:
+            kind: Expression flavor
+            **kwargs: Additional arguments
+
+        Returns:
+            bool: Evaluation result
+
+        Raises:
+            ValueError: If operator and dependencies don't match
+        """
+        if len(self.deps) == 1:
+            if self.operator == LogicalOperator.NOT:
+                return not self.deps[0](kind=kind, **kwargs)
+            else:
+                raise ValueError(
+                    f" length of deps = {len(self.deps)} but operator is not"
+                    f" {LogicalOperator.NOT}"
+                )
+        else:
+            return OperatorMapping[self.operator](
+                [item(kind=kind, **kwargs) for item in self.deps]
+            )
+
+
+@dataclasses.dataclass
+class Expression(AbsClause):
+    """Factory class for creating filter expressions.
+
+    This class provides methods to create filter expressions from dictionaries
+    and evaluate them in different languages.
+    """
+
+    @classmethod
+    def from_dict(cls, current):
+        """Create a filter expression from a dictionary.
+
+        Args:
+            current: Dictionary or list representing the filter expression
+
+        Returns:
+            AbsClause: Created filter expression
+
+        Example:
+            >>> expr = Expression.from_dict({
+            ...     "AND": [
+            ...         {"field": "age", "cmp_operator": ">=", "value": 18},
+            ...         {"field": "status", "cmp_operator": "==", "value": "active"}
+            ...     ]
+            ... })
+        """
+        if isinstance(current, list):
+            if current[0] in ComparisonOperator:
+                return LeafClause(*current)
+            elif current[0] in LogicalOperator:
+                return Clause(*current)
+        elif isinstance(current, dict):
+            k = list(current.keys())[0]
+            if k in LogicalOperator:
+                clauses = [cls.from_dict(v) for v in current[k]]
+                return Clause(operator=k, deps=clauses)
+            else:
+                return LeafClause(**current)
+
+    def __call__(
+        self,
+        doc_name="doc",
+        kind: ExpressionFlavor = ExpressionFlavor.ARANGO,
+        **kwargs,
+    ):
+        """Evaluate the expression in the target language.
+
+        Args:
+            doc_name: Document variable name
+            kind: Target expression flavor
+            **kwargs: Additional arguments
+
+        Returns:
+            str: Rendered expression
+        """
+        pass

graflo/logging.conf

@@ -0,0 +1,22 @@
+[loggers]
+keys=root
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=consoleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=consoleFormatter
+args=(sys.stdout,)
+
+[formatter_consoleFormatter]
+format=%(asctime)s - %(levelname)s - %(name)s - %(funcName)s : %(message)s
+datefmt=%Y-%m-%d %H:%M:%S

graflo/onto.py

@@ -0,0 +1,186 @@
+"""Core ontology and base classes for graph database operations.
+
+This module provides the fundamental data structures and base classes used throughout
+the graph database system. It includes base classes for enums, dataclasses, and
+database-specific configurations.
+
+Key Components:
+    - BaseEnum: Base class for string-based enumerations with flexible membership testing
+    - BaseDataclass: Base class for dataclasses with JSON/YAML serialization support
+    - DBFlavor: Enum for supported database types (ArangoDB, Neo4j)
+    - ExpressionFlavor: Enum for expression language types
+    - AggregationType: Enum for supported aggregation operations
+
+Example:
+    >>> class MyEnum(BaseEnum):
+    ...     VALUE1 = "value1"
+    ...     VALUE2 = "value2"
+    >>> "value1" in MyEnum  # True
+    >>> "invalid" in MyEnum  # False
+"""
+
+import dataclasses
+from copy import deepcopy
+from enum import EnumMeta, StrEnum
+
+from dataclass_wizard import JSONWizard, YAMLWizard
+from dataclass_wizard.enums import DateTimeTo
+
+
+class MetaEnum(EnumMeta):
+    """Metaclass for flexible enumeration membership testing.
+
+    This metaclass allows checking if a value is a valid member of an enum
+    using the `in` operator, even if the value hasn't been instantiated as
+    an enum member.
+
+    Example:
+        >>> class MyEnum(BaseEnum):
+        ...     VALUE = "value"
+        >>> "value" in MyEnum  # True
+        >>> "invalid" in MyEnum  # False
+    """
+
+    def __contains__(cls, item, **kwargs):
+        """Check if an item is a valid member of the enum.
+
+        Args:
+            item: Value to check for membership
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            bool: True if the item is a valid enum member, False otherwise
+        """
+        try:
+            cls(item, **kwargs)
+        except ValueError:
+            return False
+        return True
+
+
+class BaseEnum(StrEnum, metaclass=MetaEnum):
+    """Base class for string-based enumerations.
+
+    This class provides a foundation for string-based enums with flexible
+    membership testing through the MetaEnum metaclass.
+    """
+
+    pass
+
+
+class DBFlavor(BaseEnum):
+    """Supported database types.
+
+    This enum defines the supported graph database types in the system.
+
+    Attributes:
+        ARANGO: ArangoDB database
+        NEO4J: Neo4j database
+    """
+
+    ARANGO = "arango"
+    NEO4J = "neo4j"
+
+
+class ExpressionFlavor(BaseEnum):
+    """Supported expression language types.
+
+    This enum defines the supported expression languages for querying and
+    filtering data.
+
+    Attributes:
+        ARANGO: ArangoDB AQL expressions
+        NEO4J: Neo4j Cypher expressions
+        PYTHON: Python expressions
+    """
+
+    ARANGO = "arango"
+    NEO4J = "neo4j"
+    PYTHON = "python"
+
+
+class AggregationType(BaseEnum):
+    """Supported aggregation operations.
+
+    This enum defines the supported aggregation operations for data analysis.
+
+    Attributes:
+        COUNT: Count operation
+        MAX: Maximum value
+        MIN: Minimum value
+        AVERAGE: Average value
+        SORTED_UNIQUE: Sorted unique values
+    """
+
+    COUNT = "COUNT"
+    MAX = "MAX"
+    MIN = "MIN"
+    AVERAGE = "AVERAGE"
+    SORTED_UNIQUE = "SORTED_UNIQUE"
+
+
+@dataclasses.dataclass
+class BaseDataclass(JSONWizard, JSONWizard.Meta, YAMLWizard):
+    """Base class for dataclasses with serialization support.
+
+    This class provides a foundation for dataclasses with JSON and YAML
+    serialization capabilities. It includes methods for updating instances
+    and accessing field members.
+
+    Attributes:
+        marshal_date_time_as: Format for datetime serialization
+        key_transform_with_dump: Key transformation style for serialization
+    """
+
+    marshal_date_time_as = DateTimeTo.ISO_FORMAT
+    key_transform_with_dump = "SNAKE"
+    # skip_defaults = True
+
+    def update(self, other):
+        """Update this instance with values from another instance.
+
+        This method performs a deep update of the instance's attributes using
+        values from another instance of the same type. It handles different
+        types of attributes (sets, lists, dicts, dataclasses) appropriately.
+
+        Args:
+            other: Another instance of the same type to update from
+
+        Raises:
+            TypeError: If other is not an instance of the same type
+        """
+        if not isinstance(other, type(self)):
+            raise TypeError(
+                f"Expected {type(self).__name__} instance, got {type(other).__name__}"
+            )
+
+        for field in dataclasses.fields(self):
+            name = field.name
+            current_value = getattr(self, name)
+            other_value = getattr(other, name)
+
+            if other_value is None:
+                pass
+            elif isinstance(other_value, set):
+                setattr(self, name, current_value | deepcopy(other_value))
+            elif isinstance(other_value, list):
+                setattr(self, name, current_value + deepcopy(other_value))
+            elif isinstance(other_value, dict):
+                setattr(self, name, {**current_value, **deepcopy(other_value)})
+            elif dataclasses.is_dataclass(type(other_value)):
+                if current_value is not None:
+                    current_value.update(other_value)
+                else:
+                    setattr(self, name, deepcopy(other_value))
+            else:
+                if current_value is None:
+                    setattr(self, name, other_value)
+
+    @classmethod
+    def get_fields_members(cls):
+        """Get list of field members excluding private ones.
+
+        Returns:
+            list[str]: List of public field names
+        """
+        return [k for k in cls.__annotations__ if not k.startswith("_")]

graflo/plot/__init__.py

@@ -0,0 +1,17 @@
+"""Plotting utilities for graph visualization.
+
+This module provides tools for visualizing graph schemas and structures.
+It includes functionality for creating visual representations of graph
+databases, their vertices, edges, and relationships.
+
+Key Components:
+    - SchemaPlotter: Creates visual representations of graph schemas
+
+Example:
+    >>> plotter = SchemaPlotter(schema)
+    >>> plotter.plot("schema.png")
+"""
+
+from .plotter import SchemaPlotter
+
+__all__ = ["SchemaPlotter"]