dftly 0.0.1__py3-none-any.whl

dftly/__init__.py

@@ -0,0 +1,13 @@
+"""dftly - DataFrame Transformation Language parser."""
+
+from .nodes import Column, Expression, Literal
+from .parser import Parser, from_yaml, parse
+
+__all__ = [
+    "Column",
+    "Expression",
+    "Literal",
+    "Parser",
+    "parse",
+    "from_yaml",
+]

dftly/grammar.lark

@@ -0,0 +1,88 @@
+%import common.WS
+%ignore WS
+STRING: /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/
+
+PLUS: "+"
+MINUS: "-"
+AT: "@"
+AS: /as/i
+IF: /if/i
+ELSE: /else/i
+AND_SYM: "&&"
+OR_SYM: "||"
+NOT_SYM: "!"
+NOT_MATCH.2: /not\s+match/i
+AND.2: "and"i
+OR.2: "or"i
+NOT.2: "not"i
+NAME: /[A-Za-z_][A-Za-z0-9_]*/
+IN: /in/i
+NUMBER: /\d+(?:\.\d+)?/
+REGEX_PAREN_TOKEN.2: /\([^\s]+\)/
+REGEX_TOKEN: /[^\s()]+/
+LPAR: "("
+RPAR: ")"
+EXTRACT.2: /extract/i
+GROUP.2: /group/i
+OF.2: /of/i
+FROM.2: /from/i
+MATCH.2: /match/i
+AGAINST.2: /against/i
+
+start: expr
+
+?expr: conditional
+
+conditional: bool_expr IF bool_expr ELSE expr   -> ifexpr
+           | bool_expr
+
+?bool_expr: bool_expr (OR|OR_SYM) bool_term   -> or_expr
+          | bool_term
+
+?bool_term: bool_term (AND|AND_SYM) bool_factor   -> and_expr
+          | bool_factor
+
+?bool_factor: (NOT|NOT_SYM) bool_factor       -> not_expr
+            | in_expr
+
+?in_expr: additive IN set_literal        -> value_in_set
+        | additive IN range_literal      -> value_in_range
+        | additive
+
+?additive: additive PLUS multiplicative
+         | additive MINUS multiplicative
+         | multiplicative
+
+?multiplicative: multiplicative AT unary  -> resolve_ts
+               | unary
+
+?unary: primary
+
+primary: call_expr
+       | regex_extract
+       | regex_match
+       | NAME AS STRING  -> parse_as_format
+       | NAME AS NAME   -> cast
+       | NUMBER         -> number
+       | STRING         -> string
+       | NAME           -> name
+       | group
+
+group: "(" expr ")" -> paren_expr
+
+call_expr: NAME "(" [args] ")"   -> func
+args: expr ("," expr)*   -> arg_list
+
+set_literal: "{" [args] "}"   -> literal_set
+
+range_literal: "[" expr "," expr "]"   -> range_inc
+             | "[" expr "," expr ")"   -> range_ie
+             | "(" expr "," expr "]"   -> range_ei
+             | "(" expr "," expr ")"   -> range_exc
+
+regex_extract: EXTRACT (GROUP NUMBER OF)? regex FROM expr
+regex_match: MATCH regex AGAINST expr -> regex_match
+           | NOT_MATCH regex AGAINST expr -> regex_match
+regex: REGEX_PAREN_TOKEN
+     | REGEX_TOKEN
+     | STRING

dftly/nodes.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Mapping,
+    Optional,
+    TYPE_CHECKING,
+    Union,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - imported for type checking only
+    from .parser import Parser
+
+
+class NodeBase:
+    """Base utilities for node dataclasses."""
+
+    KEY: ClassVar[str]
+
+    @staticmethod
+    def _validate_keys(
+        mapping: Mapping[str, Any],
+        allowed: set[str],
+        *,
+        label: str,
+        required: Optional[set[str]] = None,
+    ) -> None:
+        required = required or set()
+        extra = set(mapping) - allowed
+        if extra:
+            raise ValueError(f"invalid {label} keys: {extra}")
+        missing = required - set(mapping)
+        if missing:
+            raise ValueError(f"{label} missing required keys: {missing}")
+
+    @classmethod
+    def _validate_map(cls, value: Any, **kwargs: Any) -> Any:
+        """Optional hook to validate the mapping value."""
+        return value
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, Any], **kwargs: Any) -> "NodeBase":
+        cls._validate_keys(
+            mapping,
+            {cls.KEY},
+            label=f"{cls.KEY} mapping",
+            required={cls.KEY},
+        )
+        value = cls._validate_map(mapping[cls.KEY], **kwargs)
+        if isinstance(value, Mapping):
+            return cls(**value)
+        return cls(value)
+
+
+@dataclass
+class Literal(NodeBase):
+    """A literal value."""
+
+    KEY: ClassVar[str] = "literal"
+
+    value: Any
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"literal": self.value}
+
+
+@dataclass
+class Column(NodeBase):
+    """Reference to a dataframe column."""
+
+    KEY: ClassVar[str] = "column"
+
+    name: str
+    type: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str):
+            raise TypeError("column name must be a string")
+        if self.type is not None and not isinstance(self.type, str):
+            raise TypeError("column type must be a string")
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {"name": self.name}
+        if self.type is not None:
+            data["type"] = self.type
+        return {"column": data}
+
+    @classmethod
+    def _validate_map(
+        cls,
+        value: Any,
+        *,
+        input_schema: Optional[Mapping[str, Optional[str]]] = None,
+    ) -> Mapping[str, Any]:
+        if isinstance(value, str):
+            typ = None if input_schema is None else input_schema.get(value)
+            return {"name": value, "type": typ}
+        if isinstance(value, Mapping):
+            cls._validate_keys(
+                value, {"name", "type"}, label="column", required={"name"}
+            )
+            name = value["name"]
+            typ = value.get("type")
+            if typ is None and input_schema is not None:
+                typ = input_schema.get(name)
+            return {"name": name, "type": typ}
+        raise TypeError("column value must be a string or mapping")
+
+
+@dataclass
+class Expression(NodeBase):
+    """A parsed expression."""
+
+    KEY: ClassVar[str] = "expression"
+
+    type: str
+    arguments: Union[List[Any], Dict[str, Any]]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.type, str):
+            raise TypeError("expression type must be a string")
+        if not isinstance(self.arguments, (list, dict)):
+            raise TypeError("expression arguments must be list or dict")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"expression": {"type": self.type, "arguments": self.arguments}}
+
+    @classmethod
+    def _validate_map(
+        cls,
+        value: Any,
+        *,
+        parser: "Parser",
+    ) -> Mapping[str, Any]:
+        if not isinstance(value, Mapping):
+            raise TypeError("expression value must be a mapping")
+        cls._validate_keys(
+            value, {"type", "arguments"}, label="expression", required={"type"}
+        )
+        expr_type = value["type"]
+        args = value.get("arguments", [])
+        parsed_args = parser._parse_arguments(args)
+        return {"type": expr_type, "arguments": parsed_args}