pylpg 0.1.0__tar.gz

pylpg-0.1.0/.commitlintrc.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

pylpg-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Deploy documentation
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows: ["Release"]
+    types: [completed]
+
+jobs:
+  deploy-docs:
+    name: Deploy documentation
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        ref: main
+        fetch-depth: 0
+
+    - name: Get latest tag and checkout
+      id: get_tag
+      run: |
+        LATEST_TAG=$(git describe --tags --abbrev=0 --match "v[0-9]*" origin/main)
+        echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+        git checkout $LATEST_TAG
+
+    - name: Configure Git Credentials
+      run: |
+        git config user.name github-actions[bot]
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+    - uses: actions/setup-python@v6
+      with:
+        python-version: 3.x
+    - name: Cache dependencies
+      uses: actions/cache@v5
+      with:
+        key: mkdocs-material-${{ github.run_id }}
+        path: ~/.cache
+        restore-keys: |
+          mkdocs-material-
+    - name: Install MkDocs and dependencies
+      run: pip install mkdocs-material griffe-fieldz mkdocstrings-python griffe-inherited-docstrings
+    - name: Generate changelog
+      uses: orhun/git-cliff-action@v4
+      with:
+        config: cliff.toml
+        args: --verbose
+      env:
+        OUTPUT: docs/CHANGELOG.md
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Deploy documentation
+      run: mkdocs gh-deploy --force

pylpg-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,202 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  test:
+    name: Run tests
+    uses: ./.github/workflows/tests.yml
+
+  build:
+    name: Build package
+    needs:
+    - test
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+        ref: main
+        fetch-depth: 0
+
+    - name: Get latest tag
+      id: get_tag
+      run: |
+        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+          LATEST_TAG=$(git describe --tags --abbrev=0 --match "v[0-9]*" origin/main)
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+          git checkout $LATEST_TAG
+        else
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        fi
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+    - name: Install pypa/build
+      run: python3 -m pip install build --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the packages
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  testpypi:
+    name: Publish package to TestPyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pylpg
+
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish package to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish package to PyPI
+    needs:
+    - testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pylpg
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  changelog:
+    name: Generate changelog
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        ref: main
+        fetch-depth: 0
+
+    - name: Get tag
+      id: get_tag
+      run: |
+        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+          LATEST_TAG=$(git describe --tags --abbrev=0 --match "v[0-9]*" origin/main)
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+        else
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Generate changelog for this release
+      uses: orhun/git-cliff-action@v4
+      id: cliff
+      with:
+        config: cliff.toml
+        args: --latest --strip header
+      env:
+        OUTPUT: CHANGELOG_RELEASE.md
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Upload changelog snippet
+      uses: actions/upload-artifact@v5
+      with:
+        name: changelog-snippet
+        path: CHANGELOG_RELEASE.md
+
+  github-release:
+    name: Create GitHub Release
+    needs:
+    - pypi
+    - changelog
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout to get tag info
+      uses: actions/checkout@v5
+      with:
+        ref: main
+        fetch-depth: 0
+
+    - name: Get latest tag
+      id: get_tag
+      run: |
+        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+          LATEST_TAG=$(git describe --tags --abbrev=0 --match "v[0-9]*" origin/main)
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+        else
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Download dist artifacts
+      uses: actions/download-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Download changelog snippet
+      uses: actions/download-artifact@v5
+      with:
+        name: changelog-snippet
+
+    - name: Extract version from tag
+      run: |
+        TAG="${{ steps.get_tag.outputs.tag }}"
+        echo "VERSION=${TAG#v}" >> $GITHUB_ENV
+
+    - name: Build release body
+      run: |
+        cat > RELEASE_BODY.md << 'HEADER'
+        ## What's Changed
+        HEADER
+        cat CHANGELOG_RELEASE.md >> RELEASE_BODY.md
+        cat >> RELEASE_BODY.md << EOF
+
+        ## Installation
+
+        \`\`\`bash
+        pip install pylpg==${{ env.VERSION }}
+        \`\`\`
+
+        ## Links
+
+        - [Documentation](https://rougny.github.io/pylpg/)
+        - [PyPI](https://pypi.org/project/pylpg/${{ env.VERSION }}/)
+        EOF
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: ${{ steps.get_tag.outputs.tag }}
+        files: dist/*
+        body_path: RELEASE_BODY.md

pylpg-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,68 @@
+name: Tests
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - testing
+      - main
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+    services:
+      neo4j:
+        image: neo4j:5
+        env:
+          NEO4J_AUTH: neo4j/testpassword
+        ports:
+          - 7687:7687
+        options: >-
+          --health-cmd "cypher-shell -u neo4j -p testpassword 'RETURN 1'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+      falkordb:
+        image: falkordb/falkordb:latest
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+          allow-prereleases: true
+      - name: Install uv and tox
+        run: pip install uv tox tox-uv
+      - name: Run tests with tox
+        env:
+          CI: true
+        run: tox -e py310-min,py311-min,py312-min,py313-min,py314-min

pylpg-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+*.pdf
+*.swp
+*.pyc
+build/
+__pycache__/
+.ipynb_checkpoints/
+dist/
+.tox/
+.coverage
+htmlcov/
+site/
+plans/
+debates/
+benchmarks/
+TODO.txt

pylpg-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.20.0 # Use the latest version
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies: ['@commitlint/config-conventional']

pylpg-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

pylpg-0.1.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+`pylpg` is a Python Object Graph Mapper (OGM) for labeled property graph databases (Neo4j, FalkorDB, FalkorDBLite). It maps Python classes to graph nodes/relationships and generates Cypher queries for CRUD operations.
+
+## Development commands
+
+```bash
+# Install (uses uv + hatchling)
+uv sync --all-extras
+
+# Lint
+uv run ruff check src/ tests/
+
+# Format
+uv run ruff format src/ tests/
+
+# Test (requires Docker for Neo4j and FalkorDB containers)
+uv run pytest tests/ -v
+
+# Test with coverage
+uv run pytest tests/ --cov=pylpg --cov-report=term
+
+# Test across Python versions
+uv run tox -e py310-min,py311-min,py312-min,py313-min
+
+# Build docs
+uv run mkdocs build
+
+# Serve docs locally
+uv run mkdocs serve
+```
+
+## Code style
+
+- Always use absolute imports: `import x` then `x.y`, never `from x import y`.
+- Use full words for variable names, no abbreviations (e.g. `type_` not `t`, `annotation` not `ann`, `relationship` not `rel`). Exception: `cls` is allowed.
+- No runtime value validation on properties — validation only happens at class definition time (type checking in `validate_properties`). The database backend is the ultimate authority on what values it accepts.
+- Always run ruff check and ruff format after code changes.
+- When calling functions across modules, use named parameters.
+
+## Architecture
+
+All source code is under `src/pylpg/`.
+
+- **`node.py`** — `Node` base class with global label/name registries for hydration. Subclasses define graph nodes via type-annotated attributes. Labels default to class name.
+- **`relationship.py`** — `Relationship` base class (requires `__type__`, `source`, `target`). Descriptor classes (`RelationshipTo`, `RelationshipFrom`, `RelationshipUndirected`) attach traversal and `connect()` capabilities to Node subclasses.
+- **`types.py`** — Property type utilities. Extracts primitive properties and relationship descriptors, validates types at class definition time.
+- **`cypher.py`** — Shared Cypher query builder used by cypher-based backends. Not imported by session.
+- **`session.py`** — Orchestrates persistence via `save()`, `delete()`, `execute_query()`. Handles node hydration from query results.
+- **`backend/`** — `Backend` ABC with full CRUD, batch, and traversal operations:
+  - `Neo4jBackend` — uses UNWIND for batch operations
+  - `FalkorDBBackend` — uses individual queries for batch (optimal for FalkorDB)
+  - `FalkorDBLiteBackend` — embedded FalkorDB, inherits from FalkorDBBackend
+
+## Design decisions
+
+- **No custom exceptions** — plain `ValueError`/`TypeError` are sufficient.
+- **No runtime value validation** — only class-definition-time type checking.
+- **`__init_subclass__` over metaclass** — simpler, no metaclass conflicts.
+- **Backend-specific batch strategies** — Neo4j uses UNWIND queries, FalkorDB uses individual queries. Each backend implements `save_batch()` optimally.
+- **Global node registry** — `Node._label_registry` and `Node._name_registry` enable hydration without passing target classes through the call chain.
+- **Session is orchestration only** — all database operations live on the backend. The session dispatches and handles Python-side concerns (ID mapping, hydration).

pylpg-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: pylpg
+Version: 0.1.0
+Summary: A Python Object Graph Mapper for labeled property graph databases
+Project-URL: Homepage, https://github.com/rougny/pylpg
+Project-URL: Issues, https://github.com/rougny/pylpg/issues
+Author-email: Adrien Rougny <adrienrougny@gmail.com>
+License: GPL-3.0-or-later
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: falkordb>=1.0; extra == 'all'
+Requires-Dist: neo4j>=5.0; extra == 'all'
+Provides-Extra: falkordb
+Requires-Dist: falkordb>=1.0; extra == 'falkordb'
+Provides-Extra: falkordblite
+Requires-Dist: falkordblite>=0.1; (python_version >= '3.12') and extra == 'falkordblite'
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == 'neo4j'
+Description-Content-Type: text/markdown
+
+# pylpg
+
+A Python Object Graph Mapper for labeled property graph databases.
+
+## Features
+
+- Simple model definition using Python type annotations
+- Multi-backend: Neo4j, FalkorDB, FalkorDBLite (embedded)
+- Session-based persistence with node binding
+- Transactional batch operations (Neo4j)
+- Node hydration from raw query results
+
+## Installation
+
+```bash
+pip install pylpg[neo4j]        # Neo4j
+pip install pylpg[falkordb]     # FalkorDB
+pip install pylpg[falkordblite] # FalkorDBLite (embedded, no server)
+```
+
+## Quick example
+
+```python
+import pylpg.node
+import pylpg.relationship
+import pylpg.session
+import pylpg.backend.neo4j
+
+class Person(pylpg.node.Node):
+    name: str
+    age: int | None = None
+
+class Knows(pylpg.relationship.Relationship):
+    __type__ = "KNOWS"
+    since: str | None = None
+
+backend = pylpg.backend.neo4j.Neo4jBackend(
+    hostname="localhost",
+    username="neo4j",
+    password="password",
+)
+
+with pylpg.session.Session(backend) as session:
+    alice = Person(name="Alice", age=30)
+    bob = Person(name="Bob")
+    session.save(alice)
+    session.save(bob)
+
+    rel = Knows(source=alice, target=bob, since="2024")
+    session.save(rel)
+```
+
+## Documentation
+
+Full documentation is available at [https://adrienrougny.github.io/pylpg/](https://adrienrougny.github.io/pylpg/).
+
+## License
+
+GPLv3. See [LICENSE](LICENSE) for details.

pylpg-0.1.0/README.md

@@ -0,0 +1,59 @@
+# pylpg
+
+A Python Object Graph Mapper for labeled property graph databases.
+
+## Features
+
+- Simple model definition using Python type annotations
+- Multi-backend: Neo4j, FalkorDB, FalkorDBLite (embedded)
+- Session-based persistence with node binding
+- Transactional batch operations (Neo4j)
+- Node hydration from raw query results
+
+## Installation
+
+```bash
+pip install pylpg[neo4j]        # Neo4j
+pip install pylpg[falkordb]     # FalkorDB
+pip install pylpg[falkordblite] # FalkorDBLite (embedded, no server)
+```
+
+## Quick example
+
+```python
+import pylpg.node
+import pylpg.relationship
+import pylpg.session
+import pylpg.backend.neo4j
+
+class Person(pylpg.node.Node):
+    name: str
+    age: int | None = None
+
+class Knows(pylpg.relationship.Relationship):
+    __type__ = "KNOWS"
+    since: str | None = None
+
+backend = pylpg.backend.neo4j.Neo4jBackend(
+    hostname="localhost",
+    username="neo4j",
+    password="password",
+)
+
+with pylpg.session.Session(backend) as session:
+    alice = Person(name="Alice", age=30)
+    bob = Person(name="Bob")
+    session.save(alice)
+    session.save(bob)
+
+    rel = Knows(source=alice, target=bob, since="2024")
+    session.save(rel)
+```
+
+## Documentation
+
+Full documentation is available at [https://adrienrougny.github.io/pylpg/](https://adrienrougny.github.io/pylpg/).
+
+## License
+
+GPLv3. See [LICENSE](LICENSE) for details.

pylpg-0.1.0/cliff.toml

@@ -0,0 +1,52 @@
+[changelog]
+header = """# Changelog
+
+All notable changes to pylpg will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Conventional Commits](https://www.conventionalcommits.org/).
+
+"""
+body = """
+{%- macro remote_url() -%}
+  https://github.com/rougny/pylpg
+{%- endmacro -%}
+
+{% if version -%}
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else -%}
+## [Unreleased]
+{% endif -%}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | upper_first }}
+{% for commit in commits %}
+- {{ commit.message | upper_first | trim }}\
+  {% if commit.scope %} *({{ commit.scope }})*{% endif %}\
+  {% if commit.breaking %} **BREAKING**{% endif -%}
+{% endfor %}
+{% endfor %}
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+split_commits = false
+commit_parsers = [
+  { message = "^feat", group = "Added" },
+  { message = "^fix", group = "Fixed" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Changed" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^style", group = "Styling" },
+  { message = "^test", group = "Testing" },
+  { message = "^ci", group = "CI/CD" },
+  { message = "^chore", group = "Miscellaneous" },
+  { message = ".*", group = "Other" },
+]
+protect_breaking_commits = false
+filter_commits = false
+tag_pattern = "v[0-9]+\\.[0-9]+\\.[0-9]+"
+sort_commits = "newest"

pylpg-0.1.0/docs/about.md

@@ -0,0 +1,3 @@
+## License
+
+This code is distributed under the [GPLv3 license](https://www.gnu.org/licenses/gpl-3.0.html).

pylpg-0.1.0/docs/api_reference/backend/base.md

@@ -0,0 +1,3 @@
+# Backend (base)
+
+::: pylpg.backend.base

pylpg-0.1.0/docs/api_reference/backend/falkordb.md

@@ -0,0 +1,3 @@
+# FalkorDB backend
+
+::: pylpg.backend.falkordb

pylpg-0.1.0/docs/api_reference/backend/falkordblite.md

@@ -0,0 +1,3 @@
+# FalkorDBLite backend
+
+::: pylpg.backend.falkordblite

pylpg-0.1.0/docs/api_reference/backend/neo4j.md

@@ -0,0 +1,3 @@
+# Neo4j backend
+
+::: pylpg.backend.neo4j

pylpg-0.1.0/docs/api_reference/node.md

@@ -0,0 +1,3 @@
+# Node
+
+::: pylpg.node

pylpg-0.1.0/docs/api_reference/relationship.md

@@ -0,0 +1,3 @@
+# Relationship
+
+::: pylpg.relationship

pylpg-0.1.0/docs/api_reference/session.md

@@ -0,0 +1,3 @@
+# Session
+
+::: pylpg.session

pylpg-0.1.0/docs/api_reference/types.md

@@ -0,0 +1,3 @@
+# Types
+
+::: pylpg.types