Metadata-Version: 2.4
Name: pandas-arango
Version: 0.1.2
Summary: A connector between ArangoDB and pandas DataFrames
Author-email: Alexandru Petenchea <alex.petenchea@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Alex Petenchea
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/apetenchea/pandas-arango
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.2
Requires-Dist: python-arango>=8.0
Provides-Extra: example
Requires-Dist: matplotlib>=3.10; extra == "example"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx==8.2.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "docs"
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

# pandas-arango

`pandas-arango` is a synchronous connector for moving data between ArangoDB
documents and pandas DataFrames. It supports AQL and collection reads, chunked
results, and batched insert, update, replace, and upsert operations.

## Requirements

- Python 3.11 or newer
- pandas 2.2 or newer
- python-arango 8.0 or newer
- A running ArangoDB server

Install it with:

```console
python -m pip install pandas-arango
```

## Quickstart

Connect with `python-arango`, read documents into a DataFrame, use pandas, and
write the result to another collection:

```python
from arango import ArangoClient
from pandas_arango import read_collection, write_collection

client = ArangoClient(hosts="http://127.0.0.1:8529")
database = client.db("my_database", username="root", password="passwd")

users = read_collection(
    database,
    "users",
    columns=["_key", "name", "active"],
)
active_users = users.loc[users["active"]]

result = write_collection(
    active_users,
    database,
    "active_users",
    mode="upsert",
    create_collection=True,
)
print(result.written_count)
```

Use `read_aql` for custom queries and pass `chunksize` for large results.

### Advanced example

Converters let you store Python values that are not JSON-compatible by
default. This example preserves decimal prices as strings, converts UUIDs to
document keys, omits missing fields, and reads matching documents in chunks:

```python
from decimal import Decimal
from uuid import uuid4

import pandas as pd
from pandas_arango import read_aql, write_collection

measurements = pd.DataFrame(
    [
        {
            "measurement_id": uuid4(),
            "price": Decimal("19.95"),
            "captured_at": pd.Timestamp.now(tz="UTC"),
            "comment": pd.NA,
        }
    ]
)

write_collection(
    measurements,
    database,
    "measurements",
    key_column="measurement_id",
    create_collection=True,
    null_policy="omit",
    converters={"measurement_id": str, "price": str},
)

chunks = read_aql(
    database,
    """
    FOR measurement IN measurements
        FILTER TO_NUMBER(measurement.price) >= @minimum_price
        RETURN measurement
    """,
    bind_vars={"minimum_price": 10},
    chunksize=10_000,
)
for chunk in chunks:
    print(chunk[["_key", "price", "captured_at"]])
```

## Constraints

- Nested objects and arrays remain values in DataFrame cells by default.
- AQL projection is preferred; client-side flattening is opt-in.
- Writes accept JSON-compatible values. Other values require converters.
- Timezone-naive timestamps are rejected instead of assuming a timezone.

## More information

- [Example notebook](examples/example.ipynb)
- [Documentation](docs/index.rst)
- [Contributing and development](CONTRIBUTING.md)
