zyxdb 0.1.0__tar.gz

zyxdb-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.1
+Name: zyxdb
+Version: 0.1.0
+Summary: Python bindings for ZYX graph database engine
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: C++
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Project-URL: Homepage, https://github.com/nexepic/zyx
+Project-URL: Repository, https://github.com/nexepic/zyx
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Description-Content-Type: text/markdown
+
+# zyxdb
+
+Python bindings for [ZYX](https://github.com/nicklauslititz/zyx), a high-performance embeddable graph database engine with Cypher query support.
+
+## Installation
+
+```bash
+pip install zyxdb
+```
+
+### Build from source
+
+```bash
+cd bindings/python
+pip install -e ".[test]"
+```
+
+## Quick Start
+
+```python
+import zyxdb
+
+# Open a database (creates if not exists)
+db = zyxdb.Database("/tmp/mydb")
+
+# Create nodes with Cypher
+db.execute("CREATE (n:Person {name: $name, age: $age})", name="Alice", age=30)
+
+# Query with iteration
+for row in db.execute("MATCH (n:Person) RETURN n.name AS name, n.age AS age"):
+    print(row["name"], row["age"])
+
+# Batch insert
+db.create_nodes("Person", [
+    {"name": "Bob", "age": 25},
+    {"name": "Carol", "age": 35},
+])
+
+# Transactions with context manager
+with db.begin_transaction() as tx:
+    tx.execute("CREATE (n:Movie {title: 'Matrix'})")
+    tx.execute(
+        "MATCH (a:Person {name: 'Alice'}), (m:Movie {title: 'Matrix'}) "
+        "CREATE (a)-[:WATCHED]->(m)"
+    )
+    tx.commit()
+
+# Read-only transaction
+with db.begin_read_only_transaction() as tx:
+    for row in tx.execute("MATCH (n) RETURN count(n) AS cnt"):
+        print(row["cnt"])
+
+# Direct node/edge creation by ID (high performance)
+id1 = db.create_node_ret_id("Person", {"name": "Dave"})
+id2 = db.create_node_ret_id("Person", {"name": "Eve"})
+db.create_edge_by_id(id1, id2, "KNOWS", {"since": 2024})
+
+# Shortest path
+path = db.get_shortest_path(id1, id2)
+
+db.close()
+```
+
+## Context Manager
+
+```python
+with zyxdb.Database("/tmp/mydb") as db:
+    db.execute("CREATE (n:Test {x: 1})")
+    # Auto-closes on exit
+```
+
+## Supported Value Types
+
+| Python | ZYX |
+|--------|-----|
+| `None` | null |
+| `bool` | bool |
+| `int` | int64 |
+| `float` | double |
+| `str` | string |
+| `list[float]` | vector (embeddings) |
+| `list[str]` | string list |
+| `list` (mixed) | heterogeneous list |
+| `dict` | map |
+
+## API Reference
+
+### `Database(path, *, open=True)`
+
+- `execute(cypher, **params)` — Execute Cypher query with keyword parameters
+- `begin_transaction()` — Start a read-write transaction
+- `begin_read_only_transaction()` — Start a read-only transaction
+- `create_node(label, props)` — Create a node (label can be `str` or `list[str]`)
+- `create_node_ret_id(label, props)` — Create a node, return its ID
+- `create_nodes(label, props_list)` — Batch create nodes
+- `create_edge_by_id(src_id, dst_id, type, props)` — Create edge between known IDs
+- `get_shortest_path(start_id, end_id, max_depth=15)` — Find shortest path
+- `save()` — Flush to disk
+- `close()` — Close the database
+
+### `Transaction`
+
+- `execute(cypher, **params)` — Execute within transaction
+- `commit()` — Commit changes
+- `rollback()` — Roll back changes
+- `is_active` — Whether transaction is still active
+- `is_read_only` — Whether read-only
+
+### `Result`
+
+- Iterable: `for row in result` yields `dict[str, Any]`
+- `column_names` — List of column names
+- `duration` — Query execution time (ms)
+- `is_success` — Whether query succeeded
+- `error` — Error message or `None`
+
+## License
+
+Apache License 2.0

zyxdb-0.1.0/README.md

@@ -0,0 +1,119 @@
+# zyxdb
+
+Python bindings for [ZYX](https://github.com/nicklauslititz/zyx), a high-performance embeddable graph database engine with Cypher query support.
+
+## Installation
+
+```bash
+pip install zyxdb
+```
+
+### Build from source
+
+```bash
+cd bindings/python
+pip install -e ".[test]"
+```
+
+## Quick Start
+
+```python
+import zyxdb
+
+# Open a database (creates if not exists)
+db = zyxdb.Database("/tmp/mydb")
+
+# Create nodes with Cypher
+db.execute("CREATE (n:Person {name: $name, age: $age})", name="Alice", age=30)
+
+# Query with iteration
+for row in db.execute("MATCH (n:Person) RETURN n.name AS name, n.age AS age"):
+    print(row["name"], row["age"])
+
+# Batch insert
+db.create_nodes("Person", [
+    {"name": "Bob", "age": 25},
+    {"name": "Carol", "age": 35},
+])
+
+# Transactions with context manager
+with db.begin_transaction() as tx:
+    tx.execute("CREATE (n:Movie {title: 'Matrix'})")
+    tx.execute(
+        "MATCH (a:Person {name: 'Alice'}), (m:Movie {title: 'Matrix'}) "
+        "CREATE (a)-[:WATCHED]->(m)"
+    )
+    tx.commit()
+
+# Read-only transaction
+with db.begin_read_only_transaction() as tx:
+    for row in tx.execute("MATCH (n) RETURN count(n) AS cnt"):
+        print(row["cnt"])
+
+# Direct node/edge creation by ID (high performance)
+id1 = db.create_node_ret_id("Person", {"name": "Dave"})
+id2 = db.create_node_ret_id("Person", {"name": "Eve"})
+db.create_edge_by_id(id1, id2, "KNOWS", {"since": 2024})
+
+# Shortest path
+path = db.get_shortest_path(id1, id2)
+
+db.close()
+```
+
+## Context Manager
+
+```python
+with zyxdb.Database("/tmp/mydb") as db:
+    db.execute("CREATE (n:Test {x: 1})")
+    # Auto-closes on exit
+```
+
+## Supported Value Types
+
+| Python | ZYX |
+|--------|-----|
+| `None` | null |
+| `bool` | bool |
+| `int` | int64 |
+| `float` | double |
+| `str` | string |
+| `list[float]` | vector (embeddings) |
+| `list[str]` | string list |
+| `list` (mixed) | heterogeneous list |
+| `dict` | map |
+
+## API Reference
+
+### `Database(path, *, open=True)`
+
+- `execute(cypher, **params)` — Execute Cypher query with keyword parameters
+- `begin_transaction()` — Start a read-write transaction
+- `begin_read_only_transaction()` — Start a read-only transaction
+- `create_node(label, props)` — Create a node (label can be `str` or `list[str]`)
+- `create_node_ret_id(label, props)` — Create a node, return its ID
+- `create_nodes(label, props_list)` — Batch create nodes
+- `create_edge_by_id(src_id, dst_id, type, props)` — Create edge between known IDs
+- `get_shortest_path(start_id, end_id, max_depth=15)` — Find shortest path
+- `save()` — Flush to disk
+- `close()` — Close the database
+
+### `Transaction`
+
+- `execute(cypher, **params)` — Execute within transaction
+- `commit()` — Commit changes
+- `rollback()` — Roll back changes
+- `is_active` — Whether transaction is still active
+- `is_read_only` — Whether read-only
+
+### `Result`
+
+- Iterable: `for row in result` yields `dict[str, Any]`
+- `column_names` — List of column names
+- `duration` — Query execution time (ms)
+- `is_success` — Whether query succeeded
+- `error` — Error message or `None`
+
+## License
+
+Apache License 2.0

zyxdb-0.1.0/meson.build

@@ -0,0 +1,222 @@
+project('zyxdb', 'cpp',
+        version : run_command(
+            'python3', '-c',
+            'import re, pathlib; print(re.search(r"version\\s*:\\s*\'([^\']+)\'", pathlib.Path("' + meson.current_source_dir() / '..' / '..' / 'meson.build' + '").read_text()).group(1))',
+            check : true).stdout().strip(),
+        default_options : [
+            'cpp_std=c++20',
+            'warning_level=3',
+            'werror=false',
+            'buildtype=release',
+            'default_library=static',
+        ])
+
+# Resolve the root of the main ZYX project (two levels up from bindings/python)
+zyx_root = meson.current_source_dir() / '..' / '..'
+
+cxx = meson.get_compiler('cpp')
+
+# Windows macro conflict guards
+if host_machine.system() == 'windows'
+    add_project_arguments('-DNOMINMAX', '-DNOGDI', language : 'cpp')
+endif
+
+# ==============================================================================
+# Dependencies (same as root meson.build)
+# ==============================================================================
+zlib_dep = dependency('zlib')
+boost_dep = dependency('boost', modules : ['filesystem', 'system'])
+cli11_dep = dependency('CLI11')
+
+antlr4_dep = dependency('antlr4-cppruntime', required : false)
+if not antlr4_dep.found()
+    antlr4_dep = dependency('antlr4-runtime', method : 'cmake',
+                            modules : ['antlr4_static'], required : true)
+endif
+
+# ==============================================================================
+# ANTLR4 generated parser sources + implementation
+# ==============================================================================
+parser_dir = zyx_root / 'src' / 'query' / 'parser' / 'cypher' / 'generated'
+parser_impl_dir = zyx_root / 'src' / 'query' / 'parser' / 'cypher'
+
+_py = import('python').find_installation()
+
+# Generated parser files
+_find_parser = run_command(_py, '-c', '''
+import os, sys
+d = sys.argv[1]
+source_dir = sys.argv[2]
+for f in sorted(os.listdir(d)):
+    if f.endswith(".cpp"):
+        print(os.path.relpath(os.path.join(d, f), source_dir))
+''', parser_dir, meson.current_source_dir(), check : true)
+_parser_files = _find_parser.stdout().strip().split('\n')
+parser_src = []
+foreach f : _parser_files
+    if f != ''
+        parser_src += files(f)
+    endif
+endforeach
+
+# Parser implementation files (CypherParserImpl, helpers, clauses, etc.)
+_find_parser_impl = run_command(_py, '-c', '''
+import os, sys
+base_dir = sys.argv[1]
+source_dir = sys.argv[2]
+seen = set()
+for line in sys.argv[3].splitlines():
+    if line.strip():
+        seen.add(os.path.normpath(line.strip()))
+for root, dirs, files_list in os.walk(base_dir):
+    for f in sorted(files_list):
+        if f.endswith(".cpp"):
+            rel = os.path.relpath(os.path.join(root, f), source_dir)
+            if os.path.normpath(rel) not in seen:
+                print(rel)
+''', parser_impl_dir, meson.current_source_dir(), '\n'.join(_parser_files), check : true)
+_parser_impl_files = _find_parser_impl.stdout().strip().split('\n')
+foreach f : _parser_impl_files
+    if f != ''
+        parser_src += files(f)
+    endif
+endforeach
+
+cypher_inc = include_directories(
+    '../../src/query/parser/cypher/generated',
+    '../../src/query/parser/cypher',
+    '../../src/query/parser/cypher/helpers/internal',
+    '../../src/query/parser/cypher/helpers/public',
+)
+
+cypher_dep = declare_dependency(
+    sources : parser_src,
+    include_directories : cypher_inc,
+)
+
+# ==============================================================================
+# inputxx library (required by core/cli)
+# ==============================================================================
+inputxx_src_dir = zyx_root / 'lib' / 'inputxx' / 'src'
+_find_inputxx = run_command(_py, '-c', '''
+import os, sys
+base_dir = sys.argv[1]
+for root, dirs, files in os.walk(base_dir):
+    for f in sorted(files):
+        if f.endswith(".cpp"):
+            print(os.path.relpath(os.path.join(root, f), base_dir))
+''', inputxx_src_dir, check : true)
+inputxx_src = []
+foreach f : _find_inputxx.stdout().strip().split('\n')
+    if f != ''
+        inputxx_src += files(zyx_root / 'lib' / 'inputxx' / 'src' / f)
+    endif
+endforeach
+inputxx_inc = include_directories('../../lib/inputxx/include')
+inputxx_lib = static_library('inputxx',
+    sources : inputxx_src,
+    include_directories : inputxx_inc,
+    install : false,
+)
+inputxx_dep = declare_dependency(
+    include_directories : inputxx_inc,
+    link_with : inputxx_lib,
+)
+
+# ==============================================================================
+# Core library sources (same discovery as src/meson.build)
+# ==============================================================================
+src_dir = zyx_root / 'src'
+_find_src = run_command(_py, '-c', '''
+import os, sys
+base_dir = sys.argv[1]
+source_dir = sys.argv[2]
+exclude = ["query/parser", "cli"]
+for root, dirs, files_list in os.walk(base_dir):
+    rel_root = os.path.relpath(root, base_dir)
+    skip = False
+    for ex in exclude:
+        if rel_root == ex or rel_root.startswith(ex + os.sep):
+            skip = True
+            break
+    if skip:
+        continue
+    for f in sorted(files_list):
+        if f.endswith(".cpp"):
+            print(os.path.relpath(os.path.join(root, f), source_dir))
+''', src_dir, meson.current_source_dir(), check : true)
+_src_files = _find_src.stdout().strip().split('\n')
+db_src = []
+foreach f : _src_files
+    if f != ''
+        db_src += files(f)
+    endif
+endforeach
+
+inc_dirs = include_directories(
+    '../../include',
+    '../../src',
+    '../..',
+    '../../src/query/parser/cypher',
+)
+
+# Generate ProjectConfig.hpp from template
+project_config = configuration_data()
+project_config.set('PROJECT_NAME', 'zyx')
+project_config.set('PROJECT_DISPLAY', 'ZYX')
+project_config.set('PROJECT_VERSION', meson.project_version())
+configure_file(
+    input: zyx_root / 'include' / 'graph' / 'core' / 'ProjectConfig.hpp.in',
+    output: 'ProjectConfig.hpp',
+    configuration: project_config,
+    install: false,
+)
+
+# Python's Token.h defines macros (SEMI, COMMA, etc.) that conflict with
+# ANTLR4 parser method names. Force-include an undef header to neutralize them.
+_undef_header = meson.current_source_dir() / 'undef_python_tokens.h'
+if cxx.get_argument_syntax() == 'msvc'
+    _force_include = ['/FI' + _undef_header]
+else
+    _force_include = ['-include', _undef_header]
+endif
+
+db_lib = static_library('zyx_core',
+    sources : db_src,
+    include_directories : inc_dirs,
+    dependencies : [zlib_dep, boost_dep, cli11_dep, antlr4_dep, cypher_dep, inputxx_dep],
+    cpp_args : ['-DCOVERAGE_SKIP_ZLIB_ERRORS'] + _force_include,
+    install : false,
+)
+
+db_dep = declare_dependency(
+    include_directories : [inc_dirs, cypher_inc],
+    link_with : db_lib,
+    dependencies : [zlib_dep, boost_dep, cli11_dep, antlr4_dep, inputxx_dep],
+)
+
+# ==============================================================================
+# Python extension module
+# ==============================================================================
+py = import('python').find_installation(pure: false)
+
+pybind11_dep = dependency('pybind11', required: true)
+
+zyxdb_core = py.extension_module(
+    '_core',
+    sources: ['src/zyxdb/_core.cpp'],
+    dependencies: [pybind11_dep, db_dep],
+    include_directories: inc_dirs,
+    install: true,
+    subdir: 'zyxdb',
+)
+
+py.install_sources(
+    'src/zyxdb/__init__.py',
+    'src/zyxdb/database.py',
+    'src/zyxdb/result.py',
+    'src/zyxdb/transaction.py',
+    'src/zyxdb/types.py',
+    'src/zyxdb/py.typed',
+    subdir: 'zyxdb',
+)

zyxdb-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["meson-python>=0.16.0", "pybind11>=2.13"]
+build-backend = "mesonpy"
+
+[project]
+name = "zyxdb"
+description = "Python bindings for ZYX graph database engine"
+dynamic = ["version"]
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: C++",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/nexepic/zyx"
+Repository = "https://github.com/nexepic/zyx"

zyxdb-0.1.0/src/zyxdb/__init__.py

@@ -0,0 +1,23 @@
+"""zyxdb — Python bindings for ZYX graph database engine."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from zyxdb._core import DatabaseError
+from zyxdb.database import Database
+from zyxdb.result import Record, Result
+from zyxdb.transaction import Transaction
+from zyxdb.types import Edge, Node
+
+try:
+    __version__ = version("zyxdb")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+__all__ = [
+    "Database",
+    "DatabaseError",
+    "Edge",
+    "Node",
+    "Record",
+    "Result",
+    "Transaction",
+]