cypher-graphdb 0.1.1__tar.gz

cypher_graphdb-0.1.1/.env.age.example

@@ -0,0 +1,32 @@
+# CypherGraphDB Library Configuration for Apache AGE
+#
+# This configuration connects to the Apache AGE backend started via Docker Compose.
+# Assumes you have started the AGE stack with:
+#   cd infrastructure
+#   task stack:age:up
+# or
+#   task age:up
+#
+# The AGE container exposes port 8432 on localhost for PostgreSQL connections.
+
+# Backend type
+CGDB_BACKEND=age
+
+# Connection info for Apache AGE backend
+# Uses PostgreSQL protocol connecting to localhost:8432 (exposed from Docker)
+# Format: postgresql://user:password@host:port/database
+# Note: Use plain postgresql:// (not postgresql+psycopg://) for the lib
+CGDB_CINFO=postgresql://postgres:postgres@localhost:8432/graphdb
+
+# Graph name (required for AGE)
+# AGE requires a graph name - default is 'main'
+CGDB_GRAPH=main
+
+# Read-only mode (optional, default: false)
+# When true, prevents write operations
+CGDB_READ_ONLY=false
+
+# Auto-create graph if it doesn't exist (optional, default: false)
+# When true, automatically creates the graph on first connection
+# Useful for automated setups and avoiding manual graph creation
+CGDB_CREATE_GRAPH_IF_NOT_EXISTS=true

cypher_graphdb-0.1.1/.env.example

@@ -0,0 +1,19 @@
+# Graph Backend Configuration
+# Backend driver / provider identifier.
+# Currently supported:
+# memgraph for Memgraph
+# age for Apache AGE
+#
+CGDB_BACKEND=memgraph
+# Connection info / DSN or host:port as required by backend implementation
+# Example for Memgraph: bolt://localhost:7687
+CGDB_CINFO=
+# Graph / database (logical) name if applicable
+CGDB_GRAPH=
+# Auto-create graph if it doesn't exist (optional, default: false)
+# When true, automatically creates the graph on first connection (AGE only)
+CGDB_CREATE_GRAPH_IF_NOT_EXISTS=false
+
+
+
+

cypher_graphdb-0.1.1/.env.memgraph.example

@@ -0,0 +1,29 @@
+# CypherGraphDB Library Configuration for Memgraph
+#
+# This configuration connects to the Memgraph backend started via Docker Compose.
+# Assumes you have started the Memgraph stack with:
+#   cd infrastructure
+#   task stack:memgraph:up
+# or
+#   task memgraph:up
+#
+# The Memgraph container exposes port 7687 on localhost for Bolt protocol connections.
+
+# Backend type
+CGDB_BACKEND=memgraph
+
+# Connection info for Memgraph backend
+# Uses Bolt protocol connecting to localhost:7687 (exposed from Docker)
+CGDB_CINFO=bolt://localhost:7687
+
+# Graph / database name (optional for Memgraph)
+# Memgraph doesn't require a graph name - leave empty
+CGDB_GRAPH=
+
+# Read-only mode (optional, default: false)
+# When true, prevents write operations
+CGDB_READ_ONLY=false
+
+# Auto-create graph if it doesn't exist (optional, default: false)
+# Note: This setting has no effect for Memgraph (only applies to AGE backend)
+CGDB_CREATE_GRAPH_IF_NOT_EXISTS=false

cypher_graphdb-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: Core CI/CD
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**/*.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+  checks: write
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        python-version: ['3.13']
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Ensure uv cache directory exists
+        run: mkdir -p ~/.cache/uv
+
+      - name: Cache uv packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-${{ matrix.python-version }}-
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            cmake \
+            build-essential \
+            libpq-dev \
+            pkg-config \
+            zlib1g-dev \
+            libzstd-dev
+
+      - name: Install dependencies
+        run: |
+          uv pip install setuptools psycopg "antlr4-python3-runtime==4.11.1"
+          uv pip install --no-build-isolation -e ".[dev,build,examples,docs]"
+
+      - name: Lint code
+        run: .venv/bin/ruff check src tests
+
+      - name: Run unit tests
+        run: .venv/bin/pytest -m unit -x
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: test
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Ensure uv cache directory exists
+        run: mkdir -p ~/.cache/uv
+
+      - name: Cache uv packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-3.13-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-3.13-
+
+      - name: Create virtual environment
+        run: uv venv
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            cmake \
+            build-essential \
+            libpq-dev \
+            pkg-config \
+            zlib1g-dev \
+            libzstd-dev
+
+      - name: Install dependencies
+        run: |
+          uv pip install setuptools psycopg "antlr4-python3-runtime==4.11.1"
+          uv pip install --no-build-isolation -e ".[dev,build,examples,docs]"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7
+
+

cypher_graphdb-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,86 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing (OIDC)
+
+jobs:
+  test:
+    name: Lint and Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            cmake \
+            build-essential \
+            libpq-dev \
+            pkg-config \
+            zlib1g-dev \
+            libzstd-dev
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install setuptools psycopg "antlr4-python3-runtime==4.11.1"
+          uv pip install --no-build-isolation -e ".[dev]"
+
+      - name: Lint code
+        run: .venv/bin/ruff check src tests
+
+      - name: Run unit tests
+        run: .venv/bin/pytest -m unit -x
+
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: test
+    environment: pypi
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Required for setuptools-scm
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cypher_graphdb-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

cypher_graphdb-0.1.1/.gitignore

@@ -0,0 +1,109 @@
+.idea/
+.vscode/
+*.py[cod]
+*.so
+*.egg/
+*.egg-info/
+.DS_Store
+dist/
+build/
+site/
+.venv/
+__pycache__/
+.tox/
+.mypy_cache/
+.pytest_cache/
+.coverage
+.ruff_cache
+htmlcov/
+docs/coverage/
+tests/coverage.xml
+.cgdb_history
+.scannerwork
+~*.*
+
+# Exclude all .env files except .env.example
+.env*
+!.env*.example
+!.env.production
+
+# Ensure root CONTRIBUTING.md is not excluded
+!CONTRIBUTING.md
+
+# mkdocs build and cache ignores
+site/
+docs/coverage/
+docs/__pycache__/
+docs/.DS_Store
+
+# Excel and CSV files in root folder
+/*.xls
+/*.xlsx
+/*.csv
+
+# Cypher query files in root folder
+/*.cypher
+/*.cypherl
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Exclude repomix output
+repomix-output.*

cypher_graphdb-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+###############################
+# pre-commit configuration
+#
+# Strategy:
+# - Use only "local" hooks so we can orchestrate via Taskfile tasks.
+# - Split fast feedback (pre-commit) from deeper validation (pre-push).
+# - Keep pass_filenames: false because tasks already know what to operate on.
+#
+# Tips:
+# - Skip all hooks:    git commit -m "msg" --no-verify
+# - Run hooks manually: task fct
+# - Update hooks:       task pre-commit:update
+###############################
+repos:
+  - repo: local
+    hooks:
+      # -------------------------------
+      # Pre-commit (fast) hooks
+      # -------------------------------
+      - id: pre-commit
+        name: "format+check+tests (quick)"
+        entry: bash -c 'task fct'
+        language: system
+        pass_filenames: false
+        files: \.py$
+        always_run: false
+
+      # -------------------------------
+      # Pre-push (deeper) hooks
+      # -------------------------------
+      - id: pre-push
+        name: "pre-push: ruff+pytest full"
+        entry: bash -c 'task fct'
+        language: system
+        pass_filenames: false
+        files: \.py$
+        stages: [pre-push]

cypher_graphdb-0.1.1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure
+- Core functionality for Cypher query language support
+- ORM-like interface for graph databases
+- CLI tool for interactive sessions
+- Documentation system with MkDocs
+
+### Changed
+
+### Fixed

cypher_graphdb-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to CypherGraphDB Core
+
+Thank you for considering contributing to CypherGraphDB Core! This document outlines the process for contributing to the project and provides guidelines to make the process smooth for everyone involved.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.13+
+- Task runner (`task`)
+- uv package manager
+
+### Setting Up Development Environment
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/petrarca/cypher-graphdb-core.git`
+3. Set up the development environment:
+   ```bash
+   cd cypher-graphdb-core
+   task install
+   ```
+
+## Development Workflow
+
+### Branch Naming
+
+Use descriptive branch names with prefixes:
+- `feature/` for new features
+- `fix/` for bug fixes
+- `docs/` for documentation changes
+- `refactor/` for code refactoring
+
+Example: `feature/add-neo4j-support`
+
+### Coding Standards
+
+- Follow PEP 8 style guidelines
+- Use ruff for linting and formatting
+- Add type annotations to all functions and methods
+- Write tests for new functionality
+- Document your code using Google-style docstrings (see [Documentation Guide](docs/documentation-guide.md))
+
+### Testing
+
+Run tests before submitting a pull request:
+
+```bash
+task test
+```
+
+Ensure all tests pass and aim for good test coverage.
+
+### Documentation
+
+- Update documentation for any changes to the API
+- Follow the [Documentation Guide](docs/documentation-guide.md) for docstring format
+- Build and check documentation locally:
+  ```bash
+  task build:docs
+  task serve:docs
+  ```
+
+## Pull Request Process
+
+1. Update the README.md and documentation with details of changes if applicable
+2. Run the linter and tests to ensure code quality: `task fct`
+3. Submit a pull request with a clear description of the changes
+4. Address any feedback from code reviews
+
+## Commit Messages
+
+Write clear, concise commit messages that explain the changes made. Follow the conventional commits format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+Types include: feat, fix, docs, style, refactor, test, chore
+
+Example: `feat(cli): add support for interactive mode`
+
+## Reporting Bugs
+
+When reporting bugs, include:
+
+- A clear, descriptive title
+- Steps to reproduce the issue
+- Expected behavior
+- Actual behavior
+- Environment details (OS, Python version, etc.)
+
+## Feature Requests
+
+Feature requests are welcome! Please provide:
+
+- A clear description of the feature
+- The motivation for the feature
+- Any potential implementation details
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the Apache License 2.0.