pandas-arango 0.1.2__tar.gz

pandas_arango-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+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.

pandas_arango-0.1.2/PKG-INFO

@@ -0,0 +1,166 @@
+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)

pandas_arango-0.1.2/README.md

@@ -0,0 +1,110 @@
+# 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)

pandas_arango-0.1.2/pandas_arango/__init__.py

@@ -0,0 +1,13 @@
+"""ArangoDB integration for pandas."""
+
+from pandas_arango.read import iter_aql, read_aql, read_collection
+from pandas_arango.write import WriteError, WriteResult, write_collection
+
+__all__ = [
+    "WriteError",
+    "WriteResult",
+    "iter_aql",
+    "read_aql",
+    "read_collection",
+    "write_collection",
+]

pandas_arango-0.1.2/pandas_arango/errors.py

@@ -0,0 +1 @@
+"""Package-specific exceptions."""

pandas_arango-0.1.2/pandas_arango/normalize.py

@@ -0,0 +1 @@
+"""Document and DataFrame normalization helpers."""

pandas_arango-0.1.2/pandas_arango/py.typed

@@ -0,0 +1 @@
+