flowquery 1.0.16 → 1.0.17

package/flowquery-py/README.md

@@ -0,0 +1,166 @@
+# FlowQuery Python Implementation
+
+This is the Python implementation of FlowQuery, a declarative query language for data processing pipelines.
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://github.com/microsoft/FlowQuery.git
+cd FlowQuery/flowquery-py
+pip install -e .
+```
+
+### With Development Dependencies
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Command Line Interface
+
+After installation, you can start the interactive REPL:
+
+```bash
+flowquery
+```
+
+### Using Conda (Alternative)
+
+**Windows (PowerShell):**
+
+```powershell
+cd flowquery-py
+.\setup_env.ps1
+conda activate flowquery
+```
+
+**Linux/macOS:**
+
+```bash
+cd flowquery-py
+chmod +x setup_env.sh
+./setup_env.sh
+conda activate flowquery
+```
+
+The setup scripts automatically:
+
+1. Read the Python version from `pyproject.toml`
+2. Create a conda environment named `flowquery`
+3. Install the package with all dev dependencies
+
+## Requirements
+
+- Python 3.10+ (defined in `pyproject.toml`)
+- pytest (for running tests)
+- pytest-asyncio (for async test support)
+- aiohttp (for HTTP requests)
+
+All dependencies are managed in `pyproject.toml`.
+
+## Programmatic Usage
+
+```python
+import asyncio
+from flowquery import Runner
+
+runner = Runner("WITH 1 as x RETURN x + 1 as result")
+asyncio.run(runner.run())
+print(runner.results)  # [{'result': 2}]
+```
+
+## Running Tests
+
+```bash
+pytest tests/
+```
+
+## Project Structure
+
+```
+flowquery-py/
+├── pyproject.toml       # Dependencies & project config (single source of truth)
+├── setup_env.ps1        # Windows conda setup script
+├── setup_env.sh         # Linux/macOS conda setup script
+├── README.md
+├── src/
+│   ├── __init__.py          # Main package entry point
+│   ├── extensibility.py     # Public API for custom functions
+│   ├── compute/
+│   │   └── runner.py        # Query execution engine
+│   ├── graph/
+│   │   ├── node.py          # Graph node representation
+│   │   ├── relationship.py  # Graph relationship representation
+│   │   ├── pattern.py       # Pattern matching
+│   │   └── database.py      # In-memory graph database
+│   ├── io/
+│   │   └── command_line.py  # Interactive REPL
+│   ├── parsing/
+│   │   ├── parser.py        # Main parser
+│   │   ├── ast_node.py      # AST node base class
+│   │   ├── expressions/     # Expression types (numbers, strings, operators)
+│   │   ├── functions/       # Built-in and custom functions
+│   │   ├── operations/      # Query operations (WITH, RETURN, UNWIND, etc.)
+│   │   ├── components/      # LOAD clause components
+│   │   ├── data_structures/ # Arrays, objects, lookups
+│   │   └── logic/           # CASE/WHEN/THEN/ELSE
+│   ├── tokenization/
+│   │   ├── tokenizer.py     # Lexer
+│   │   ├── token.py         # Token class
+│   │   └── ...              # Token types and mappers
+│   └── utils/
+│       ├── string_utils.py  # String manipulation utilities
+│       └── object_utils.py  # Object utilities
+└── tests/
+    ├── test_extensibility.py
+    ├── compute/
+    │   └── test_runner.py
+    ├── graph/
+    │   ├── test_create.py
+    │   ├── test_data.py
+    │   └── test_match.py
+    ├── parsing/
+    │   ├── test_parser.py
+    │   ├── test_context.py
+    │   └── test_expression.py
+    └── tokenization/
+        ├── test_tokenizer.py
+        ├── test_token_mapper.py
+        └── test_trie.py
+```
+
+## Creating Custom Functions
+
+```python
+from flowquery.extensibility import Function, FunctionDef
+
+@FunctionDef({
+    "description": "Converts a string to uppercase",
+    "category": "string",
+    "parameters": [
+        {"name": "text", "description": "String to convert", "type": "string"}
+    ],
+    "output": {"description": "Uppercase string", "type": "string"}
+})
+class UpperCase(Function):
+    def __init__(self):
+        super().__init__("uppercase")
+        self._expected_parameter_count = 1
+
+    def value(self) -> str:
+        return str(self.get_children()[0].value()).upper()
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Homepage](https://github.com/microsoft/FlowQuery/flowquery-py)
+- [Repository](https://github.com/microsoft/FlowQuery/flowquery-py)
+- [Issues](https://github.com/microsoft/FlowQuery/issues)

package/flowquery-py/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "flowquery"
+version = "1.0.0"
+description = "A declarative query language for data processing pipelines"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "FlowQuery Contributors"}
+]
+keywords = ["query", "data-processing", "pipeline", "declarative"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database :: Front-Ends",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "aiohttp>=3.8.0",
+]
+
+[project.scripts]
+flowquery = "flowquery.io.command_line:main"
+
+[project.urls]
+Homepage = "https://github.com/microsoft/FlowQuery/flowquery-py"
+Repository = "https://github.com/microsoft/FlowQuery/flowquery-py"
+Documentation = "https://github.com/microsoft/FlowQuery/flowquery-py#readme"
+Issues = "https://github.com/microsoft/FlowQuery/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-dir]
+"flowquery" = "src"
+"flowquery.compute" = "src/compute"
+"flowquery.graph" = "src/graph"
+"flowquery.io" = "src/io"
+"flowquery.parsing" = "src/parsing"
+"flowquery.parsing.components" = "src/parsing/components"
+"flowquery.parsing.data_structures" = "src/parsing/data_structures"
+"flowquery.parsing.expressions" = "src/parsing/expressions"
+"flowquery.parsing.functions" = "src/parsing/functions"
+"flowquery.parsing.logic" = "src/parsing/logic"
+"flowquery.parsing.operations" = "src/parsing/operations"
+"flowquery.tokenization" = "src/tokenization"
+"flowquery.utils" = "src/utils"
+
+[tool.setuptools]
+packages = ["flowquery", "flowquery.compute", "flowquery.graph", "flowquery.io", "flowquery.parsing", "flowquery.parsing.components", "flowquery.parsing.data_structures", "flowquery.parsing.expressions", "flowquery.parsing.functions", "flowquery.parsing.logic", "flowquery.parsing.operations", "flowquery.tokenization", "flowquery.utils"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.pytest-asyncio]
+mode = "auto"

package/flowquery-py/setup_env.ps1

@@ -0,0 +1,92 @@
+# FlowQuery Python Environment Setup Script for Windows (PowerShell)
+# This script creates a conda environment for FlowQuery development
+
+Write-Host "========================================"
+Write-Host "FlowQuery Python Environment Setup"
+Write-Host "========================================"
+Write-Host ""
+
+# Check if conda is available
+$condaPath = Get-Command conda -ErrorAction SilentlyContinue
+if (-not $condaPath) {
+    Write-Host "ERROR: Conda is not installed or not in PATH." -ForegroundColor Red
+    Write-Host "Please install Anaconda or Miniconda first."
+    exit 1
+}
+
+# Set environment name
+$envName = "flowquery"
+
+# Get Python version from pyproject.toml
+$pyprojectContent = Get-Content "pyproject.toml" -Raw
+if ($pyprojectContent -match 'requires-python\s*=\s*">=([0-9.]+)"') {
+    $pythonVersion = $matches[1]
+} else {
+    $pythonVersion = "3.10"  # fallback
+}
+Write-Host "Using Python version: $pythonVersion"
+
+# Check if environment already exists
+$envList = conda env list
+if ($envList -match "^$envName\s") {
+    Write-Host "Environment '$envName' already exists."
+    $recreate = Read-Host "Do you want to recreate it? (y/n)"
+    if ($recreate -eq "y" -or $recreate -eq "Y") {
+        Write-Host "Removing existing environment..."
+        conda env remove -n $envName -y
+    } else {
+        Write-Host "Keeping existing environment..."
+        Write-Host ""
+        Write-Host "========================================"
+        Write-Host "Environment ready!"
+        Write-Host "========================================"
+        Write-Host ""
+        Write-Host "To activate the environment, run:"
+        Write-Host "    conda activate $envName" -ForegroundColor Cyan
+        Write-Host ""
+        Write-Host "To run tests:"
+        Write-Host "    pytest tests/" -ForegroundColor Cyan
+        Write-Host ""
+        Write-Host "To deactivate when done:"
+        Write-Host "    conda deactivate" -ForegroundColor Cyan
+        exit 0
+    }
+}
+
+# Create the environment
+Write-Host ""
+Write-Host "Creating conda environment '$envName' with Python $pythonVersion..."
+conda create -n $envName python=$pythonVersion pip -y
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to create conda environment." -ForegroundColor Red
+    exit 1
+}
+
+# Activate and install package in dev mode
+Write-Host ""
+Write-Host "Installing package in development mode..."
+conda activate $envName
+pip install -e ".[dev]"
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to install package." -ForegroundColor Red
+    exit 1
+}
+
+Write-Host ""
+Write-Host "========================================"
+Write-Host "Environment created successfully!" -ForegroundColor Green
+Write-Host "========================================"
+Write-Host ""
+Write-Host "To activate the environment, run:"
+Write-Host "    conda activate $envName" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "To run tests:"
+Write-Host "    pytest tests/" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "To deactivate when done:"
+Write-Host "    conda deactivate" -ForegroundColor Cyan
+Write-Host ""

package/flowquery-py/setup_env.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# FlowQuery Python Environment Setup Script for Linux/macOS
+# This script creates a conda environment for FlowQuery development
+
+echo "========================================"
+echo "FlowQuery Python Environment Setup"
+echo "========================================"
+echo
+
+# Check if conda is available
+if ! command -v conda &> /dev/null; then
+    echo "ERROR: Conda is not installed or not in PATH."
+    echo "Please install Anaconda or Miniconda first."
+    exit 1
+fi
+
+# Set environment name
+ENV_NAME="flowquery"
+
+# Get Python version from pyproject.toml
+PYTHON_VERSION=$(grep -oP 'requires-python\s*=\s*">=\K[0-9.]+' pyproject.toml 2>/dev/null || echo "3.10")
+echo "Using Python version: $PYTHON_VERSION"
+
+# Check if environment already exists
+if conda env list | grep -q "^${ENV_NAME} "; then
+    echo "Environment '${ENV_NAME}' already exists."
+    read -p "Do you want to recreate it? (y/n): " RECREATE
+    if [[ "$RECREATE" =~ ^[Yy]$ ]]; then
+        echo "Removing existing environment..."
+        conda env remove -n "$ENV_NAME" -y
+    else
+        echo "Keeping existing environment..."
+        echo
+        echo "========================================"
+        echo "Environment ready!"
+        echo "========================================"
+        echo
+        echo "To activate the environment, run:"
+        echo "    conda activate $ENV_NAME"
+        echo
+        echo "To run tests:"
+        echo "    pytest tests/"
+        echo
+        echo "To deactivate when done:"
+        echo "    conda deactivate"
+        exit 0
+    fi
+fi
+
+# Create the environment
+echo
+echo "Creating conda environment '${ENV_NAME}' with Python ${PYTHON_VERSION}..."
+conda create -n "$ENV_NAME" python="$PYTHON_VERSION" pip -y
+
+if [ $? -ne 0 ]; then
+    echo
+    echo "ERROR: Failed to create conda environment."
+    exit 1
+fi
+
+# Activate and install package in dev mode
+echo
+echo "Installing package in development mode..."
+source "$(conda info --base)/etc/profile.d/conda.sh"
+conda activate "$ENV_NAME"
+pip install -e ".[dev]"
+
+if [ $? -ne 0 ]; then
+    echo
+    echo "ERROR: Failed to install package."
+    exit 1
+fi
+
+echo
+echo "========================================"
+echo "Environment created successfully!"
+echo "========================================"
+echo
+echo "To activate the environment, run:"
+echo "    conda activate $ENV_NAME"
+echo
+echo "To run tests:"
+echo "    pytest tests/"
+echo
+echo "To deactivate when done:"
+echo "    conda deactivate"
+echo

package/flowquery-py/src/__init__.py

@@ -0,0 +1,34 @@
+"""
+FlowQuery - A declarative query language for data processing pipelines.
+
+This is the Python implementation of FlowQuery.
+"""
+
+from .compute.runner import Runner
+from .io.command_line import CommandLine
+from .parsing.parser import Parser
+from .parsing.functions.function import Function
+from .parsing.functions.aggregate_function import AggregateFunction
+from .parsing.functions.async_function import AsyncFunction
+from .parsing.functions.predicate_function import PredicateFunction
+from .parsing.functions.reducer_element import ReducerElement
+from .parsing.functions.function_metadata import (
+    FunctionDef,
+    FunctionMetadata,
+    FunctionCategory,
+)
+
+__all__ = [
+    "Runner",
+    "CommandLine",
+    "Parser",
+    "Function",
+    "AggregateFunction",
+    "AsyncFunction",
+    "PredicateFunction",
+    "ReducerElement",
+    "FunctionDef",
+    "FunctionMetadata",
+    "FunctionCategory",
+]
+

package/flowquery-py/src/__main__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+"""FlowQuery command-line entry point.
+
+Run with: python -m src
+"""
+
+from . import CommandLine
+
+if __name__ == "__main__":
+    CommandLine().loop()

package/flowquery-py/src/compute/__init__.py

@@ -0,0 +1,5 @@
+"""Compute module for FlowQuery."""
+
+from .runner import Runner
+
+__all__ = ["Runner"]

package/flowquery-py/src/compute/runner.py

@@ -0,0 +1,60 @@
+"""Executes a FlowQuery statement and retrieves the results."""
+
+from typing import Any, Dict, List, Optional
+
+from ..parsing.ast_node import ASTNode
+from ..parsing.operations.operation import Operation
+from ..parsing.parser import Parser
+
+
+class Runner:
+    """Executes a FlowQuery statement and retrieves the results.
+    
+    The Runner class parses a FlowQuery statement into an AST and executes it,
+    managing the execution flow from the first operation to the final return statement.
+    
+    Example:
+        runner = Runner("WITH 1 as x RETURN x")
+        await runner.run()
+        print(runner.results)  # [{ x: 1 }]
+    """
+
+    def __init__(
+        self,
+        statement: Optional[str] = None,
+        ast: Optional[ASTNode] = None
+    ):
+        """Creates a new Runner instance and parses the FlowQuery statement.
+        
+        Args:
+            statement: The FlowQuery statement to execute
+            ast: An already-parsed AST (optional)
+            
+        Raises:
+            ValueError: If neither statement nor AST is provided
+        """
+        if (statement is None or statement == "") and ast is None:
+            raise ValueError("Either statement or AST must be provided")
+        
+        _ast = ast if ast is not None else Parser().parse(statement)
+        self._first: Operation = _ast.first_child()
+        self._last: Operation = _ast.last_child()
+
+    async def run(self) -> None:
+        """Executes the parsed FlowQuery statement.
+        
+        Raises:
+            Exception: If an error occurs during execution
+        """
+        await self._first.initialize()
+        await self._first.run()
+        await self._first.finish()
+
+    @property
+    def results(self) -> List[Dict[str, Any]]:
+        """Gets the results from the executed statement.
+        
+        Returns:
+            The results from the last operation (typically a RETURN statement)
+        """
+        return self._last.results

package/flowquery-py/src/extensibility.py

@@ -0,0 +1,52 @@
+"""FlowQuery Extensibility API
+
+This module provides all the exports needed to create custom FlowQuery functions.
+
+Example:
+    from flowquery.extensibility import Function, FunctionDef
+    
+    @FunctionDef({
+        'description': "Converts a string to uppercase",
+        'category': "string",
+        'parameters': [{'name': "text", 'description': "String to convert", 'type': "string"}],
+        'output': {'description': "Uppercase string", 'type': "string"}
+    })
+    class UpperCase(Function):
+        def __init__(self):
+            super().__init__("uppercase")
+            self._expected_parameter_count = 1
+        
+        def value(self) -> str:
+            return str(self.get_children()[0].value()).upper()
+"""
+
+# Base function classes for creating custom functions
+from .parsing.functions.function import Function
+from .parsing.functions.aggregate_function import AggregateFunction
+from .parsing.functions.async_function import AsyncFunction
+from .parsing.functions.predicate_function import PredicateFunction
+from .parsing.functions.reducer_element import ReducerElement
+
+# Decorator and metadata types for function registration
+from .parsing.functions.function_metadata import (
+    FunctionDef,
+    FunctionMetadata,
+    FunctionDefOptions,
+    ParameterSchema,
+    OutputSchema,
+    FunctionCategory,
+)
+
+__all__ = [
+    "Function",
+    "AggregateFunction",
+    "AsyncFunction",
+    "PredicateFunction",
+    "ReducerElement",
+    "FunctionDef",
+    "FunctionMetadata",
+    "FunctionDefOptions",
+    "ParameterSchema",
+    "OutputSchema",
+    "FunctionCategory",
+]

package/flowquery-py/src/graph/__init__.py

@@ -0,0 +1,31 @@
+"""Graph module for FlowQuery."""
+
+from .node import Node
+from .relationship import Relationship
+from .pattern import Pattern
+from .patterns import Patterns
+from .pattern_expression import PatternExpression
+from .database import Database
+from .hops import Hops
+from .node_data import NodeData
+from .node_reference import NodeReference
+from .relationship_data import RelationshipData
+from .relationship_reference import RelationshipReference
+from .physical_node import PhysicalNode
+from .physical_relationship import PhysicalRelationship
+
+__all__ = [
+    "Node",
+    "Relationship",
+    "Pattern",
+    "Patterns",
+    "PatternExpression",
+    "Database",
+    "Hops",
+    "NodeData",
+    "NodeReference",
+    "RelationshipData",
+    "RelationshipReference",
+    "PhysicalNode",
+    "PhysicalRelationship",
+]