Metadata-Version: 2.4
Name: glace
Version: 0.1.6
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: mypy>=1.8 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Python bindings for the Glace embedded graph database
Keywords: graph,database,cypher,embedded,graph-database,knowledge-graph
Author-email: Lovelace Labs <contact@lovelace.dev>
Maintainer-email: Lovelace Labs <contact@lovelace.dev>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/lovelace-labs/glace-py/issues
Project-URL: Changelog, https://github.com/lovelace-labs/glace-py/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/lovelace-labs/glace-py#readme
Project-URL: Homepage, https://github.com/lovelace-labs/glace
Project-URL: Repository, https://github.com/lovelace-labs/glace-py

<header>
<p align="center">
    <img src="res/logo/glace-logo.png" width="20%" alt="Glace Logo">
</p>
<h1 align='center' biblio='border-bottom: none;'>glace</h1>
<h3 align='center'>Embedded Graph Database for Python</h3>
<p align="center">
    <a href="https://pypi.org/project/glace/"><img src="https://img.shields.io/pypi/v/glace.svg" alt="PyPI version"></a>
    <a href="https://pypi.org/project/glace/"><img src="https://img.shields.io/pypi/pyversions/glace.svg" alt="Python versions"></a>
    <a href="https://github.com/lovelace-labs/glace-py/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/glace.svg" alt="License"></a>
    <a href="https://github.com/lovelace-labs/glace-py/actions"><img src="https://github.com/lovelace-labs/glace-py/workflows/CI/badge.svg" alt="CI"></a>
</p>
</header>

<br/>

---

# Glace Python Bindings

Python bindings for [Glace](https://github.com/lovelace-labs/glace), an embedded graph database with Cypher support.

## Installation

```bash
pip install glace
```

### From Source

```bash
# Clone the repository
git clone https://github.com/lovelace-labs/glace-py.git
cd glace-py

# Install maturin
pip install maturin

# Build and install in development mode
maturin develop
```

## Quick Start

```python
import glace

# Create an in-memory database
db = glace.Database.in_memory()
conn = db.connect()

# Create schema
conn.execute("CREATE NODE TABLE Person(name STRING, age INT64, PRIMARY KEY(name))")
conn.execute("CREATE REL TABLE Knows(FROM Person TO Person)")

# Insert data
conn.execute("CREATE (p:Person {name: 'Alice', age: 30})")
conn.execute("CREATE (p:Person {name: 'Bob', age: 25})")
conn.execute("""
    MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
    CREATE (a)-[:Knows]->(b)
""")

# Query data
result = conn.execute("MATCH (p:Person)-[:Knows]->(f:Person) RETURN p.name, f.name")
for row in result:
    print(f"{row['p.name']} knows {row['f.name']}")

# Convert to DataFrame (requires pandas)
df = result.to_df()
print(df)
```

## Features

- **Cypher Support**: Full Cypher query language support
- **Embedded**: Runs in-process, no external dependencies
- **High Performance**: Written in Rust with columnar storage
- **ACID Transactions**: Full transactional support

## API Reference

### Database

```python
# Open a persistent database
db = glace.Database.open("./my_graph.db")

# Create an in-memory database
db = glace.Database.in_memory()

# Get database info
print(db.path)         # Path or None for in-memory
print(db.is_in_memory) # True for in-memory databases

# Create a connection
conn = db.connect()

# Checkpoint (flush to disk)
db.checkpoint()
```

### Connection

```python
# Execute queries
result = conn.execute("MATCH (p:Person) RETURN p.name")

# Execute multiple statements
results = conn.execute_multi("""
    CREATE (p:Person {name: 'Alice'});
    CREATE (p:Person {name: 'Bob'});
""")

# Transactions
conn.begin()
try:
    conn.execute("CREATE (p:Person {name: 'Charlie'})")
    conn.commit()
except:
    conn.rollback()
    raise

# Context manager for transactions
with conn:  # Automatically begins transaction
    conn.execute("CREATE (p:Person {name: 'Dave'})")
# Automatically commits on success, rollbacks on exception
```

### QueryResult

```python
result = conn.execute("MATCH (p:Person) RETURN p.name, p.age")

# Iterate over rows
for row in result:
    print(row["name"], row["age"])

# Access by index
first_row = result[0]
last_row = result[-1]

# Get metadata
print(result.columns)  # ['name', 'age']
print(len(result))     # Number of rows
print(result.message)  # Success message for DDL/DML

# Convert to list
rows = result.to_list()

# Convert to DataFrame (requires pandas)
df = result.to_df()
```

## Development

### Building

```bash
# Install development dependencies
pip install maturin pytest

# Build in development mode
maturin develop

# Run tests
pytest
```

### Running Tests

```bash
pytest tests/
```

## License

MIT License - see [LICENSE](LICENSE) for details.

