Enhance documentation and tests for ArcadeDB Python bindings

- 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.

Author: tae898

bindings/python/README.md

@@ -2,7 +2,7 @@
 
 Native Python bindings for ArcadeDB - the multi-model database that supports Graph, Document, Key/Value, Search Engine, Time Series, and Vector models.
 
-**Status**: ✅ Production Ready | **Tests**: 252 Passing | **Platforms**: 3 Supported
+**Status**: ✅ Production Ready | **Tests**: 258 Passing | **Platforms**: 3 Supported
 
 ---
 
@@ -91,7 +91,7 @@ Import: `import arcadedb_embedded as arcadedb`
 
 ## 🧪 Testing
 
-**Status**: 252 tests + example scripts passing on all 3 platforms
+**Status**: 258 tests + example scripts passing on all 3 platforms
 
 ```bash
 # Run all tests

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:

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
 

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

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)

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:**
 

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

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 =========================
 ```
 
 

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:**

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:**