Enhance documentation and tests for ArcadeDB Python bindings

tae898 · tae898 · commit 021c53bd7a8d · 2026-01-28T15:52:53.000+01:00
- Updated importer documentation to clarify XML support and provide tips for usage.
- Added notes on JSON array serialization in result sets.
- Increased test coverage from 252 to 258 tests, ensuring all features are validated.
- Improved examples for CSV imports, changing dataset size options for clarity.
- Enhanced SQL command examples to ensure proper syntax with backticks for identifiers.
- Introduced new tests for full-text search with score, SQLScript execution, and JSON array updates.
- Fixed issues in the importer related to XML handling and clarified limitations in the code comments.
diff --git a/bindings/python/docs/api-access-methods.md b/bindings/python/docs/api-access-methods.md
@@ -153,10 +153,40 @@ try:
     for record in result["result"]:
         print(f"Name: {record['name']}")
 
+    # Optional: inspect server info (includes available languages)
+    response = requests.get(
+        f"{base_url}/api/v1/server",
+        auth=auth,
+    )
+    server_info = response.json()
+    print("Available languages:", server_info.get("languages"))
+
 finally:
     server.stop()
 ```
 
+### Token-based authentication (optional)
+
+For repeated requests, you can exchange Basic Auth for a session token and use
+`Authorization: Bearer <token>` instead of sending credentials each time:
+
+```python
+# Login to receive a token
+response = requests.post(
+    f"{base_url}/api/v1/login",
+    auth=auth,
+)
+token = response.json()["token"]
+
+# Use Bearer token for subsequent requests
+headers = {"Authorization": f"Bearer {token}"}
+response = requests.post(
+    f"{base_url}/api/v1/query/mydb",
+    headers=headers,
+    json={"language": "sql", "command": "SELECT FROM Person"}
+)
+```
+
 ## Hybrid Usage
 
 Both APIs can be used **simultaneously** on the same server:
diff --git a/bindings/python/docs/api/importer.md b/bindings/python/docs/api/importer.md
@@ -15,7 +15,7 @@ data as documents, vertices, or edges depending on your schema needs.
 
 - **CSV/TSV**: Comma or tab-separated values (recommended for bulk imports)
 - **ArcadeDB JSONL export/import**: Use `IMPORT DATABASE file://...` via SQL for full database moves (see example)
-- **XML**: Limited support via Java importer (not recommended for production use)
+- **XML**: Supports document/vertex imports via Java importer
 
 ## Module Functions
 
@@ -269,7 +269,13 @@ stats = arcadedb.import_csv(db, "data.csv", "Data", commitEvery=5000)
 The importer uses streaming parsers:
 
 - **CSV**: Line-by-line processing (very efficient)
-- **XML**: Streaming parser; keep attributes consistent across rows
+- **XML**: Streaming parser; attributes and first-level child elements are supported
+
+### XML Tips
+
+For XML imports, prefer attributes for data fields and use `objectNestLevel`
+to target the correct nesting level (for example, `<posts><row .../></posts>`
+uses `objectNestLevel=1`).
 
 ### Schema Pre-Creation
 
diff --git a/bindings/python/docs/api/results.md b/bindings/python/docs/api/results.md
@@ -299,6 +299,8 @@ for result in result_set:
 
 **Note:** The JSON includes ArcadeDB metadata like `@rid` (record ID) and `@type` (type name).
 
+**Note:** Array/list properties are serialized as JSON arrays in `to_json()`.
+
 ---
 
 ## Common Patterns
diff --git a/bindings/python/docs/development/build-architecture.md b/bindings/python/docs/development/build-architecture.md
@@ -18,7 +18,7 @@ This document describes the build architecture for creating platform-specific Py
 
 **All supported platforms:**
 
-- ✅ 252 tests passing
+- ✅ 258 tests passing
 - ✅ 31.7M JARs (83 files, identical across platforms)
 - ✅ All native runners (no QEMU emulation)
 - ✅ Reproducible builds (pinned runner versions)
diff --git a/bindings/python/docs/development/ci-setup.md b/bindings/python/docs/development/ci-setup.md
@@ -96,13 +96,13 @@ After a successful release, you should see:
 
 ### Test Results (CI run #96)
 
-All 3 platforms passing 252 tests and example scripts:
+All 3 platforms passing 258 tests and example scripts:
 
 | Platform | Wheel Size | JRE Size | Tests |
 |----------|-----------|----------|-------|
-| linux/amd64 | 115.2M | 249.0M | 252 passed ✅ |
-| linux/arm64 | 114.1M | 249.6M | 252 passed ✅ |
-| darwin/arm64 | 63.1M | 55.1M | 252 passed ✅ |
+| linux/amd64 | 115.2M | 249.0M | 258 passed ✅ |
+| linux/arm64 | 114.1M | 249.6M | 258 passed ✅ |
+| darwin/arm64 | 63.1M | 55.1M | 258 passed ✅ |
 
 **All platforms include:**
 
diff --git a/bindings/python/docs/development/testing.md b/bindings/python/docs/development/testing.md
@@ -3,9 +3,9 @@
 Comprehensive testing documentation for ArcadeDB Python bindings.
 
 !!! success "Test Coverage"
-    **252 tests** across 6 test files, 100% passing
+    **258 tests** across 20 test files, 100% passing
 
-    - **Current package**: 252 passed, 6 skipped
+    - **Current package**: 258 passed, 6 skipped
     - All ArcadeDB features working (SQL, OpenCypher, Studio)
 
 ## Quick Navigation
diff --git a/bindings/python/docs/development/testing/overview.md b/bindings/python/docs/development/testing/overview.md
@@ -5,11 +5,9 @@ The ArcadeDB Python bindings have a comprehensive test suite covering all major
 ## Quick Statistics
 
 !!! success "Test Results"
-    - **Current package**: ✅ 252 passed, 6 skipped (258 collected)
+    - **Current package**: ✅ 258 passed, 6 skipped (258 collected)
     - All features available (SQL, OpenCypher, Studio UI, Vector search)
 
-    **Total: 258 tests (252 passed, 6 skipped) + 7 examples** across all platforms
-
 ## What's Tested
 
 The test suite covers:
@@ -131,7 +129,7 @@ pytest -m "not slow"
 When all tests pass, you should see:
 
 ```
-======================== 252 passed in 9.67s =========================
+======================== 258 passed in 9.67s =========================
 ```
 
 
diff --git a/bindings/python/docs/examples/04_csv_import_documents.md b/bindings/python/docs/examples/04_csv_import_documents.md
@@ -82,7 +82,7 @@ For quick testing with the smaller dataset (124,003 records), use: `python downl
 python 04_csv_import_documents.py
 
 # Use small dataset for quick testing
-python 04_csv_import_documents.py --size small
+python 04_csv_import_documents.py --dataset movielens-small
 
 # Configure parallel threads and batch size
 python 04_csv_import_documents.py --parallel 8 --batch-size 10000
@@ -96,7 +96,7 @@ python 04_csv_import_documents.py --help
 
 **Key options:**
 
-- `--size {small,large}` - Dataset size (default: large)
+- `--dataset {movielens-small,movielens-large}` - Dataset size (default: movielens-large)
 - `--parallel PARALLEL` - Number of parallel import threads (default: auto-detect)
 - `--batch-size BATCH_SIZE` - Records per commit batch (default: 5000)
 - `--export` - Export database to JSONL after import
@@ -144,7 +144,7 @@ the data and selects optimal ArcadeDB types:
 ### Step 1: Check Dataset Availability
 
 ```python
-data_dir = Path(__file__).parent / "data" / "ml-latest-small"
+data_dir = Path(__file__).parent / "data" / "movielens-small"
 if not data_dir.exists():
     print("❌ MovieLens dataset not found!")
     print("💡 Please download the dataset first:")
@@ -166,7 +166,7 @@ need for explicit schema definition before import.
 ```python
 # Import with batch commits for performance
 import_options = {
-    "commit_every": args.batch_size,  # Batch size for commits
+   "commitEvery": args.batch_size,  # Batch size for commits
 }
 stats = arcadedb.import_csv(db, movies_csv, "Movie", **import_options)
 
@@ -493,18 +493,18 @@ cd bindings/python/examples
 python 04_csv_import_documents.py
 
 # Use small dataset for quick testing - downloads automatically if needed
-python 04_csv_import_documents.py --size small
+python 04_csv_import_documents.py --dataset movielens-small
 
 # Use large dataset explicitly
-python 04_csv_import_documents.py --size large
+python 04_csv_import_documents.py --dataset movielens-large
 
 # With custom JVM heap for large datasets
-ARCADEDB_JVM_ARGS="-Xmx8g -Xms8g" python 04_csv_import_documents.py --size large
+ARCADEDB_JVM_ARGS="-Xmx8g -Xms8g" python 04_csv_import_documents.py --dataset movielens-large
 ```
 
 **Command-line options:**
 
-- `--size {small,large}` - Dataset size to use (default: large)
+- `--dataset {movielens-small,movielens-large}` - Dataset size to use (default: movielens-large)
 - The script automatically downloads the dataset if it doesn't exist
 
 **Expected output:**
diff --git a/bindings/python/docs/examples/05_csv_import_graph.md b/bindings/python/docs/examples/05_csv_import_graph.md
@@ -51,24 +51,24 @@ pre-existing document database from Example 04.
 
 ```bash
 # Recommended: Fastest configuration (Java API, synchronous)
-python 05_csv_import_graph.py --size small --method java --no-async
+python 05_csv_import_graph.py --dataset movielens-small --method java --no-async
 
 # Compare with SQL
-python 05_csv_import_graph.py --size small --method sql
+python 05_csv_import_graph.py --dataset movielens-small --method sql
 
 # Run with export for roundtrip validation
-python 05_csv_import_graph.py --size small --method java --no-async --export
+python 05_csv_import_graph.py --dataset movielens-small --batch-size 5000 --method java --no-async --export
 
 # Comprehensive benchmark (all 6 configurations in parallel)
-./run_benchmark_05_csv_import_graph.sh small 5000 4 all_6 --export
+./run_benchmark_05_csv_import_graph.sh movielens-small 5000 4 all_6 --export
 
 # See all options
 python 05_csv_import_graph.py --help
 ```
 
 **Key options:**
 
-- `--size {small,large}` - Dataset size (default: small)
+- `--dataset {movielens-small,movielens-large}` - Dataset size (default: movielens-small)
 - `--method {java,sql}` - Creation method: 'java' (recommended) or 'sql'
 - `--no-async` - Use synchronous transactions (FASTER for embedded mode)
 - `--no-index` - Skip creating indexes (slower, for comparison)
@@ -419,26 +419,26 @@ print(f"✅ TAGGED: {tagged_count:,}")
 
 ```bash
 # Fastest configuration (recommended)
-python 05_csv_import_graph.py --size small --method java --no-async
+python 05_csv_import_graph.py --dataset movielens-small --method java --no-async
 
 # Compare with SQL
-python 05_csv_import_graph.py --size small --method sql
+python 05_csv_import_graph.py --dataset movielens-small --method sql
 
 # With export for roundtrip validation
-python 05_csv_import_graph.py --size small --method java --no-async --export
+python 05_csv_import_graph.py --dataset movielens-small --batch-size 5000 --method java --no-async --export
 ```
 
 ### Comprehensive Benchmark (All 6 Configurations)
 
 ```bash
 # Run all 6 methods in parallel
-./run_benchmark_05_csv_import_graph.sh small 5000 4 all_6
+./run_benchmark_05_csv_import_graph.sh movielens-small 5000 4 all_6
 
 # With export and roundtrip validation
-./run_benchmark_05_csv_import_graph.sh small 5000 4 all_6 --export
+./run_benchmark_05_csv_import_graph.sh movielens-small 5000 4 all_6 --export
 
 # Large dataset (takes several hours)
-./run_benchmark_05_csv_import_graph.sh large 50000 4 all_6 --export
+./run_benchmark_05_csv_import_graph.sh movielens-large 50000 4 all_6 --export
 ```
 
 **6 Configurations:**
diff --git a/bindings/python/docs/getting-started/distributions.md b/bindings/python/docs/getting-started/distributions.md
@@ -34,7 +34,7 @@ Pre-built **platform-specific** wheels are available for **3 platforms**. Sizes
 - ✅ All platforms use **platform-specific wheels** (not universal)
 - ✅ uv pip automatically selects the correct wheel for your system
 - ✅ Each platform has its own bundled JRE optimized for that architecture
-- ✅ All supported platforms tested and verified (252/252 tests passing)
+- ✅ All supported platforms tested and verified (258/258 tests passing)
 - ✅ Built on native runners (no emulation) for optimal performance
 
 ## What's Included
@@ -56,7 +56,7 @@ Pre-built **platform-specific** wheels are available for **3 platforms**. Sizes
 
 ## Test Results
 
-**252 out of 252 tests pass** on all platforms (100% success rate):
+**258 out of 258 tests pass** on all platforms (100% success rate):
 
 - ✅ All core database operations
 - ✅ SQL and OpenCypher queries
diff --git a/bindings/python/docs/guide/core/queries.md b/bindings/python/docs/guide/core/queries.md
@@ -149,6 +149,25 @@ result = db.query(
 )
 ```
 
+### SQLScript (multi-statement)
+
+Use `sqlscript` to run multiple statements in one call. When there is no
+explicit `RETURN`, the result set contains the **last executed statement**
+(including DDL such as `CREATE`/`ALTER`).
+
+```python
+script = """
+    CREATE VERTEX TYPE SqlScriptVertex;
+    INSERT INTO SqlScriptVertex SET name = 'test';
+    ALTER TYPE SqlScriptVertex ALIASES ss;
+"""
+
+result = db.command("sqlscript", script)
+last = result.first()
+assert last.get("operation") == "ALTER TYPE"
+assert last.get("typeName") == "SqlScriptVertex"
+```
+
 ### Updating Data
 
 **Prefer Pythonic API for updates:**
@@ -172,6 +191,51 @@ with db.transaction():
     """)
 ```
 
+#### Update with JSON array content
+
+ArcadeDB supports `UPDATE ... CONTENT` with JSON arrays to update multiple
+documents in one statement.
+
+```python
+with db.transaction():
+    db.command(
+        "sql",
+        """
+        INSERT INTO JsonArrayDoc CONTENT
+        [{"name":"tim"},{"name":"tom"}]
+        """,
+    )
+
+with db.transaction():
+    inserted = db.query("sql", "SELECT @rid, name FROM JsonArrayDoc").to_list()
+    update_content = ", ".join(
+        f"{{@rid:'{row['@rid']}',name:'{row['name']}',status:'updated'}}"
+        for row in inserted
+    )
+
+    result = db.command(
+        "sql",
+        f"UPDATE JsonArrayDoc CONTENT [{update_content}] RETURN AFTER",
+    )
+
+rows = result.to_list()
+assert {row["status"] for row in rows} == {"updated"}
+```
+
+#### TRUNCATE BUCKET
+
+Use `TRUNCATE BUCKET` to quickly delete all records in a bucket. This is a
+low-level operation; prefer `DELETE FROM <Type>` unless you specifically need
+bucket-level maintenance.
+
+```python
+doc_type = db.schema.create_document_type("BucketDoc", buckets=1)
+bucket_name = doc_type.getBuckets(False)[0].getName()
+
+with db.transaction():
+    db.command("sql", f"TRUNCATE BUCKET {bucket_name}")
+```
+
 ### Graph Traversal
 
 ```python
@@ -237,6 +301,26 @@ for row in result:
     print(f"{city}: {count} people, avg age {avg_age:.1f}")
 ```
 
+### Full-text search ($score)
+
+When using full-text indexes, ArcadeDB exposes a `$score` variable that you can
+select and order by.
+
+```python
+# Create full-text index
+db.schema.create_document_type("Article")
+db.schema.create_property("Article", "content", "STRING")
+db.schema.create_index("Article", ["content"], index_type="FULL_TEXT")
+
+# Query with SEARCH_FIELDS and $score
+result = db.query(
+    "sql",
+    "SELECT content, $score FROM Article WHERE SEARCH_FIELDS(['content'], 'database') = true ORDER BY $score DESC",
+)
+for row in result:
+    print(row.get("content"), row.get("$score"))
+```
+
 ### ResultSet Methods
 
 ```python
diff --git a/bindings/python/docs/guide/server.md b/bindings/python/docs/guide/server.md
diff --git a/bindings/python/docs/index.md b/bindings/python/docs/index.md
diff --git a/bindings/python/docs/java-api-coverage.md b/bindings/python/docs/java-api-coverage.md
