arcadedb-python 0.3.0__tar.gz → 0.4.0__tar.gz

{arcadedb_python-0.3.0 → arcadedb_python-0.4.0}/.gitignore

@@ -169,6 +169,7 @@ cython_debug/
 *.cursormemory
 .cursormemory
 memory-bank/
+.cursor/
 
 # macOS
 .DS_Store

{arcadedb_python-0.3.0 → arcadedb_python-0.4.0}/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to the ArcadeDB Python Driver will be documented in this fil
 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).
 
+
+## [0.4.0] - 2026-03-03
+
+### Added
+- **Native openCypher engine**: use `"opencypher"` as the language — this targets ArcadeDB's native openCypher implementation; the old `"cypher"` identifier (Gremlin-based) is superseded
+- **Vector index support**: `create_vector_index()` uses the new LSM_VECTOR / JVector index type; vector property type is `ARRAY_OF_FLOATS` (underscore form, per ArcadeDB manual; `LIST OF FLOAT` and `ARRAY OF FLOATS` are also valid); `vector_search()` uses `vectorNeighbors()` for top-k similarity search; `get_vector_similarity()` supports `vectorCosineSimilarity`, `vectorDotProduct`, `vectorL2Distance`
+- **Logging**: per-module logging via `logging.getLogger(__name__)`; `configure_logging()` and `set_module_log_level()` utilities in `arcadedb_python.logging_config`
+- **`sqlscript` language** added to `AVAILABLE_LANGUAGES` in `config.py`; `bulk_insert`, `bulk_upsert`, `bulk_delete` use it for multi-statement batches
+- **Full live integration test suite** (`tests/test_integration_database.py`): 59 tests covering all public methods including transactions, bulk ops, vector ops, `get_records`, `get_triplets`, `safe_delete_all`, `safe_bulk_operation` (requires running ArcadeDB)
+- **`docs/LOGGING.md`**: logging configuration guide
+
+### Fixed
+- `bulk_insert`, `bulk_upsert`, `bulk_delete`: batch exceptions were silently swallowed when a prior batch had succeeded; they now always propagate immediately; per-batch success count also fixed to track failures per batch, not cumulatively
+- `CREATE PROPERTY` with `IF NOT EXISTS` can cause `Type not found` errors in some contexts — avoid it inside `sqlscript`; use separate `sql` calls instead
+- `cypher_formater`: robust fallback when pygments is unavailable; handles list and `$`-containing string params correctly
+- Error response parsing improved in `sync.py` for non-JSON HTTP error bodies
+- `get_triplets`: multi-strategy fallback (MATCH → edge traversal → per-type query) to handle varied ArcadeDB configurations
+
+### Changed
+- `sync.py`: embedding arrays in log output are truncated to avoid cluttering logs
+
+
+## [0.3.1] - 2025-10-21
+
+**Bug fixes for 0.3.1, README.md now has correct Quick Start Code, docs/API.md added, examples added**
+
+## Fixed
+- In release 0.3.1 will include bug #1 fix (Can't instantiate DatabaseDao). Was fixed with pull request (merged in) #2 Fix string escaping in query parameters and property assignments. This didn't show up with python 3.12, 3.13,  but did with python 3.10, 3.11
+Was fixed in `dao/database.py` with different code for escaping parameters and property assignments.
+- For bug #3 Quick Start: Basic Usage fails, the README.md quick start was updated to have the correct working code to upe
+
+### Documentation
+- Updated `README.md`:  the `README.md` now has the correct working quick start SQL code (have to use SyncClient and give to DatabaseDao, etc), added links to `docs/API.md`, 2 examples/ files, added cypher and gremlin code
+- Added `docs/API.md` documenting the classes and functions / parameters, 4 temp docs while developing removed
+
+### Added
+- In examples/  added `quickstart_example.py` with quick start code from `README.md`, `test_query_langages.py` with cypher and gremlin code from `README.md`, `enhanced_features_demo.py` from development removed
+
+### Changed
+- Updated `pyproject.toml` to have release 0.3.1 
+- `pyproject.toml`, `manifest.in`: docs and examples added to source release
+- `client.py` headers() no content type logging level changed from warning to debug
+- `sync.py` get() and post() logging level changed from info to debug (now won't see all sql calls by default), 
+- `__init__.py` updated to version 0.3.1
+
+
 ## [0.3.0] - 2025-09-23
 
 **Major Enhancement Release for LlamaIndex Integration**

arcadedb_python-0.4.0/PKG-INFO

@@ -0,0 +1,461 @@
+Metadata-Version: 2.4
+Name: arcadedb-python
+Version: 0.4.0
+Summary: Python driver for ArcadeDB - Multi-Model Database with Graph, Document, Key-Value, Vector, and Time-Series support
+Project-URL: Homepage, https://github.com/stevereiner/arcadedb-python
+Project-URL: Documentation, https://docs.arcadedb.com/
+Project-URL: Repository, https://github.com/stevereiner/arcadedb-python
+Project-URL: Bug Tracker, https://github.com/stevereiner/arcadedb-python/issues
+Project-URL: Changelog, https://github.com/stevereiner/arcadedb-python/blob/main/CHANGELOG.md
+Author: Steve Reiner, Adams Rosales, ExtReMLapin
+Maintainer: Steve Reiner
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: arcadedb,database,document,graph,key-value,multi-model,nosql,python-driver,time-series,vector
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.25.0
+Requires-Dist: retry>=0.9.2
+Provides-Extra: cypher
+Requires-Dist: pygments>=2.0.0; extra == 'cypher'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: tox>=4.0.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: psycopg>=3.0.0; extra == 'full'
+Requires-Dist: pygments>=2.0.0; extra == 'full'
+Provides-Extra: postgresql
+Requires-Dist: psycopg>=3.0.0; extra == 'postgresql'
+Description-Content-Type: text/markdown
+
+# ArcadeDB Python Driver
+
+[![PyPI version](https://badge.fury.io/py/arcadedb-python.svg)](https://badge.fury.io/py/arcadedb-python)
+[![Python versions](https://img.shields.io/pypi/pyversions/arcadedb-python.svg)](https://pypi.org/project/arcadedb-python/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+A comprehensive Python driver for [ArcadeDB](https://arcadedb.com) - the Multi-Model Database that supports Graph, Document, Key-Value, Vector, and Time-Series models in a single engine.   [Github for ArcadeDB](https://github.com/ArcadeData/arcadedb) (Apache 2.0).
+
+> **Note:** This package connects to an **ArcadeDB server over REST/HTTP**. If you need to run ArcadeDB **embedded directly inside your Python application** (no separate server process), see [arcadedb-embedded-python](https://github.com/humemai/arcadedb-embedded-python) instead.
+
+## Credits & Attribution
+
+This driver builds upon the work of the original ArcadeDB Python driver contributors:
+
+- **Adams Rosales** ([@adaros92](https://github.com/adaros92)) - Original [arcadedb-python-driver](https://github.com/adaros92/arcadedb-python-driver)
+- **ExtReMLapin** ([@ExtReMLapin](https://github.com/ExtReMLapin)) - Core contributor and enhancements
+
+This modernized version enhances the original work with updated packaging, documentation, tests, new APIs, vector support, etc.
+
+## Features
+
+- **Multi-Model Support**: Work with Graph, Document, Key-Value, Vector, and Time-Series data models
+- **Full API Coverage**: Complete access to ArcadeDB's REST API with SQL, openCypher, Gremlin, GraphQL, and Mongo query languages
+- **Vector Search**: Native LSM_VECTOR index support with `vectorNeighbors()` for AI/ML similarity search
+- **Bulk Operations**: `bulk_insert`, `bulk_upsert`, `bulk_delete` using `sqlscript` for efficient batched writes
+- **Type Annotations**: Type hints on all public methods for better IDE support
+- **Comprehensive Testing**: Full integration test suite (59 tests) against a live ArcadeDB server
+
+## Installation
+
+### Using UV (Recommended)
+
+```bash
+# Install uv if not already installed
+pip install uv
+
+# Create virtual environment and install
+uv venv
+uv pip install arcadedb-python
+```
+
+### Using Pip
+
+```bash
+pip install arcadedb-python
+```
+
+### Optional Dependencies
+
+```bash
+# PostgreSQL driver support
+uv pip install arcadedb-python[postgresql]
+# or: pip install arcadedb-python[postgresql]
+
+# Cypher syntax highlighting
+uv pip install arcadedb-python[cypher]
+# or: pip install arcadedb-python[cypher]
+
+# All optional features
+uv pip install arcadedb-python[full]
+# or: pip install arcadedb-python[full]
+
+# Development dependencies
+uv pip install arcadedb-python[dev]
+# or: pip install arcadedb-python[dev]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from arcadedb_python import DatabaseDao, SyncClient
+
+# Step 1: Create a client connection
+client = SyncClient(
+    host="localhost",
+    port=2480,
+    username="root",
+    password="playwithdata"
+)
+
+# Step 2: Connect to database (or create it)
+if not DatabaseDao.exists(client, "mydb"):
+    db = DatabaseDao.create(client, "mydb")
+else:
+    db = DatabaseDao(client, "mydb")
+
+# Step 3: Create schema (DDL requires is_command=True)
+db.query("sql", "CREATE VERTEX TYPE Person IF NOT EXISTS", is_command=True)
+
+# Step 4: Insert data (DML requires is_command=True)
+db.query("sql", "INSERT INTO Person SET name = 'John', age = 30", is_command=True)
+
+# Step 5: Query data
+result = db.query("sql", "SELECT FROM Person LIMIT 10")
+print(result)
+
+# Step 6: Graph traversal
+result = db.query("sql", """
+    MATCH {type: Person, as: person} 
+    RETURN person.name, person.age
+""")
+print(result)
+```
+
+### Important Notes
+
+- **Use `SyncClient`** to create connections, not `DatabaseDao` directly
+- **Use `is_command=True`** for DDL/DML operations (CREATE, INSERT, UPDATE, DELETE)
+- **SELECT queries** don't need `is_command=True` (it defaults to False)
+- **`IF NOT EXISTS`** is supported for `DOCUMENT TYPE`, `VERTEX TYPE`, and `EDGE TYPE`
+
+## API Documentation
+
+For complete API reference including all methods, parameters, exceptions, and detailed examples:
+
+**📚 [docs/API.md](docs/API.md)** - Comprehensive API documentation covering:
+- `SyncClient` - Connection management
+- `DatabaseDao` - All database operations (query, transactions, bulk operations)
+- Exception handling and error types
+- Configuration options
+- Complete code examples
+
+## Examples
+
+### Available Examples
+
+**[examples/quickstart_example.py](examples/quickstart_example.py)**
+- Complete walkthrough of all Quick Start code
+- All data models: Graph, Document, Key-Value, Time-Series, Vector storage
+- Step-by-step explanations
+- Error handling examples
+
+**[examples/test_query_languages.py](examples/test_query_languages.py)**
+- openCypher query examples
+- Gremlin query examples
+- Database creation and cleanup
+
+### Running Examples
+
+```bash
+# Complete quickstart with all features
+python examples/quickstart_example.py
+
+# Test openCypher and Gremlin queries
+python examples/test_query_languages.py
+```
+
+**Requirements:** ArcadeDB must be running on `localhost:2480` with default credentials (`root`/`playwithdata`)
+
+## Advanced Usage
+
+### Document Operations
+
+Documents are schema-flexible records. They cannot be endpoints of edges.
+Vertices are documents with added capability: they can be connected by edges.
+
+```python
+db.query("sql", "CREATE DOCUMENT TYPE Product IF NOT EXISTS", is_command=True)
+db.query("sql", """
+    INSERT INTO Product CONTENT {
+        "name": "Laptop",
+        "price": 999.99,
+        "specs": {
+            "cpu": "Intel i7",
+            "ram": "16GB"
+        }
+    }
+""", is_command=True)
+
+result = db.query("sql", "SELECT FROM Product")
+print(result)
+```
+
+### Graph Operations
+
+Edges connect **vertex** types only. Both the source and target must be `VERTEX TYPE`.
+
+```python
+# Create vertex types for both ends of the edge
+db.query("sql", "CREATE VERTEX TYPE Customer IF NOT EXISTS", is_command=True)
+db.query("sql", "CREATE VERTEX TYPE ItemType IF NOT EXISTS", is_command=True)
+db.query("sql", "CREATE EDGE TYPE Purchased IF NOT EXISTS", is_command=True)
+
+# Insert vertices
+db.query("sql", "INSERT INTO Customer SET name = 'Alice'", is_command=True)
+db.query("sql", "INSERT INTO ItemType SET name = 'Laptop', price = 999.99", is_command=True)
+
+# Connect them with an edge
+db.query("sql", """
+    CREATE EDGE Purchased
+    FROM (SELECT FROM Customer WHERE name = 'Alice')
+    TO (SELECT FROM ItemType WHERE name = 'Laptop')
+    SET date = sysdate(), amount = 999.99
+""", is_command=True)
+
+# Traverse the graph
+result = db.query("sql", """
+    SELECT expand(out('Purchased')) FROM Customer WHERE name = 'Alice'
+""")
+print(result)
+```
+
+### Key-Value Operations
+
+```python
+db.query("sql", "CREATE DOCUMENT TYPE Settings IF NOT EXISTS", is_command=True)
+db.query("sql", "INSERT INTO Settings SET key = 'theme', value = 'dark'", is_command=True)
+```
+
+### Time-Series Operations
+
+```python
+db.query("sql", "CREATE VERTEX TYPE Sensor IF NOT EXISTS", is_command=True)
+db.query("sql", """
+    INSERT INTO Sensor SET 
+    sensor_id = 'temp_01', 
+    timestamp = sysdate(), 
+    temperature = 23.5
+""", is_command=True)
+```
+
+### Vector Search (for AI/ML applications)
+
+```python
+# Declare the vector property and create an LSM vector index
+db.query("sql", "CREATE VERTEX TYPE DocRecord", is_command=True)
+db.query("sql", "CREATE PROPERTY DocRecord.embedding ARRAY_OF_FLOATS", is_command=True)
+db.create_vector_index("DocRecord", "embedding", dimensions=4)
+
+# Insert documents with embeddings (use CONTENT for structured inserts)
+db.query("sql", """
+    INSERT INTO DocRecord CONTENT {
+        "title": "AI Research Paper",
+        "embedding": [0.1, 0.2, 0.3, 0.4],
+        "content": "Full document text..."
+    }
+""", is_command=True)
+db.query("sql", """
+    INSERT INTO DocRecord CONTENT {
+        "title": "Machine Learning Guide",
+        "embedding": [0.9, 0.8, 0.7, 0.6],
+        "content": "Intro to ML..."
+    }
+""", is_command=True)
+
+# Perform vector similarity search
+results = db.vector_search(
+    type_name="DocRecord",
+    embedding_field="embedding",
+    query_embedding=[0.1, 0.2, 0.3, 0.4],
+    top_k=2
+)
+for doc in results:
+    print(doc["title"])
+```
+
+### Using openCypher
+
+> **Note:** Use `"opencypher"` as the language to target ArcadeDB's native openCypher engine,
+> introduced in recent releases. The older `"cypher"` language identifier used a Cypher
+> implementation built on top of Gremlin and is now superseded by this native engine.
+
+```python
+
+# Create nodes
+db.query("opencypher", "CREATE (p:Person {name: 'John', age: 30})", is_command=True)
+db.query("opencypher", "CREATE (p:Person {name: 'Jane', age: 25})", is_command=True)
+
+# Create relationship
+db.query("opencypher", """
+    MATCH (a:Person {name: 'John'}), (b:Person {name: 'Jane'})
+    CREATE (a)-[:KNOWS]->(b)
+""", is_command=True)
+
+# Query with openCypher
+result = db.query("opencypher", "MATCH (p:Person) RETURN p.name, p.age")
+print(result)
+```
+
+### Using Gremlin
+
+```python
+# Note: Gremlin support may have different performance characteristics than native SQL
+# For large operations, consider using ArcadeDB's native SQL or Java API
+
+# Add vertices
+db.query("gremlin", "g.addV('Person').property('name', 'John').property('age', 30)", is_command=True)
+db.query("gremlin", "g.addV('Person').property('name', 'Jane').property('age', 25)", is_command=True)
+
+# Query with Gremlin
+result = db.query("gremlin", "g.V().hasLabel('Person').values('name')")
+print(result)
+
+# Traversal
+result = db.query("gremlin", "g.V().hasLabel('Person').has('age', gt(20)).values('name', 'age')")
+print(result)
+```
+
+## Configuration Options
+
+### SyncClient Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `host` | str | "localhost" | ArcadeDB server hostname |
+| `port` | int | 2480 | ArcadeDB server port |
+| `username` | str | None | Database username |
+| `password` | str | None | Database password |
+| `protocol` | str | "http" | Protocol ("http" or "https") |
+
+### DatabaseDao.query() Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `language` | str | Required | Query language: "sql", "opencypher", "gremlin", "graphql", "mongo" |
+| `command` | str | Required | The query/command to execute |
+| `is_command` | bool | False | Set True for DDL/DML (CREATE, INSERT, UPDATE, DELETE) |
+| `limit` | int | None | Maximum number of results |
+| `params` | dict | None | Query parameters |
+| `session_id` | str | None | Transaction session ID |
+
+## Requirements
+
+- **Python**: 3.10 or higher
+- **ArcadeDB**: Version 25.8.1 or higher
+- **Dependencies**: 
+  - `requests` >= 2.25.0
+  - `retry` >= 0.9.2
+
+## Development
+
+### Setting up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/stevereiner/arcadedb-python.git
+cd arcadedb-python
+
+# Install uv (if not already installed)
+pip install uv
+
+# Create virtual environment and install dependencies
+uv venv
+uv pip install -e .[dev]
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run black .
+uv run isort .
+uv run flake8
+uv run mypy arcadedb_python
+```
+
+### Building the Package
+
+```bash
+# Build the package
+uv build
+
+# Check the built package
+uv run twine check dist/*
+```
+
+### Running ArcadeDB for Development
+
+```bash
+# Using Docker
+docker run -d --name arcadedb \
+  -p 2480:2480 -p 2424:2424 \
+  -e JAVA_OPTS="-Darcadedb.server.rootPassword=playwithdata" \
+  arcadedata/arcadedb:latest
+
+# Access ArcadeDB Studio at http://localhost:2480
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+### This Project
+- **GitHub**: https://github.com/stevereiner/arcadedb-python
+- **PyPI**: https://pypi.org/project/arcadedb-python/
+- **Issues**: https://github.com/stevereiner/arcadedb-python/issues
+
+### ArcadeDB
+- **Homepage**: https://arcadedb.com
+- **Documentation**: https://docs.arcadedb.com
+- **Main Repository**: https://github.com/ArcadeData/arcadedb
+
+### Original Contributors
+- **Adams Rosales**: https://github.com/adaros92/arcadedb-python-driver
+- **ExtReMLapin**: https://github.com/ExtReMLapin
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.