Metadata-Version: 2.4
Name: ultipa
Version: 6.2.15
Summary: Pure Python Ultipa Driver
Home-page: https://github.com/ultipa/gqldb-drivers
Author: Ultipa Team
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.80.0
Requires-Dist: protobuf>=6.31.1
Requires-Dist: tabulate>=0.9.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.80.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Ultipa Python Driver

Official Python driver for Ultipa graph database (GQL).

## Requirements

- Python 3.10+

## Installation

```bash
pip install ultipa          # base driver
pip install ultipa[ml]      # + graph ML data loaders (torch); see gqldb.ml
```

> **Note:** This is the v6.x driver for Ultipa Graph. If you are using Ultipa v4.x, please install [ultipa==4.5.2](https://pypi.org/project/ultipa/4.5.2/). If you are using Ultipa v5.x, please install [ultipa==5.2.1](https://pypi.org/project/ultipa/5.2.1/).

## Quick Start

```python
from gqldb import GqldbClient
from gqldb.config import GqldbConfig

# Create client
config = GqldbConfig(
    hosts=["localhost:60061"],
    username="admin",
    password="password",
    default_graph="myGraph"
)
client = GqldbClient(config)
client.login("admin", "password")

# Execute query
response = client.gql("MATCH (n) RETURN n LIMIT 10")

print(f"Rows: {len(response.rows)}")
print(f"Columns: {response.columns}")

# Close
client.close()
```

## Features

- GQL query execution with parameters
- Streaming results for large datasets
- Transaction support (begin, commit, rollback)
- Graph management (create, drop, list)
- Bulk import for high-throughput loading
- Algorithm support (CALL algo.pagerank, algo.degree, etc.)
- Graph ML data loaders for PyTorch Geometric / DGL — `gqldb.ml` (`GraphLoader`, `NeighborLoader`, `EdgeLoader`)
- Type hints support
- Health checks

## Errors

Every driver error is a `GqldbError`. An error from the server carries the
engine's error code in `e.code` (for example 5020) and a stable name in
`e.reason` (for example `"FULLTEXT_INDEX_LOADING"`); both are 0 and `""` when
the server sent none. They come from a structured detail on the gRPC error,
never from the message text. `EngineCode` and `ErrorReason` name the common
ones, and `error_detail(exc)` reads them from any exception.

```python
from gqldb import GqldbError, EngineCode

try:
    client.gql("INSERT (:Person {name: 'Alice'})")
except GqldbError as e:
    if e.code == EngineCode.WRITES_COMMITTED:
        pass  # stored although the call failed: do not run it again
```

A `gql` / `gql_stream` call with `QueryConfig(read_only=True)` and no
`transaction_id` is sent again when the server answers 5020 (a fulltext index
is still loading): up to `retry_count` times (default 3), waiting `retry_delay`
(default 0.1 s) and doubling, capped at 2 s, all within the call's timeout.
`retry_count=0` turns it off. After signing in again, or when a result is too
large for `gql`, a call is sent again only if the server refused it before it
ran or it is `read_only` outside a transaction: a request that may have
written is never sent again. An answer marked partly stored
(`partly_stored(e)`: a statement failed after earlier statements of the
request had committed, or a [5024] answer) is never sent again, a 5020
included; never run such a request again as it is. A write conflict (3011,
`WriteConflictError`: nothing stored) is never sent again, with or without a
`transaction_id`: run the whole transaction again yourself, or let
`with_transaction(..., retry_on_conflict=N)` do it. See
[GUIDE.md](GUIDE.md#error-handling).

## Documentation

See [Quick Start](https://www.ultipa.com/docs/drivers/python-quick-start) for detailed usage.

For the graph ML data loaders (streaming features / subgraphs into PyTorch
Geometric / DGL for GNN training), see [`gqldb/ml/README.md`](gqldb/ml/README.md).

## License

MIT License
