fix: update references from Cypher to OpenCypher in documentation and examples

Author: tae898

bindings/python/docs/api/async_executor.md

@@ -332,7 +332,7 @@ Execute async query.
 
 **Parameters:**
 
-- `language` (str): Query language ("sql", "cypher", etc.)
+- `language` (str): Query language ("sql", "opencypher", etc.)
 - `query` (str): Query string
 - `callback` (Callable): Callback for query results
 - `**params`: Query parameters

bindings/python/docs/api/results.md

@@ -658,14 +658,14 @@ import arcadedb_embedded as arcadedb
 
 db = arcadedb.open_database("./graph_db")
 
-# Cypher queries also return ResultSet
+# OpenCypher queries also return ResultSet
 cypher_query = """
     MATCH (p:Person)-[:WORKS_AT]->(c:Company)
     WHERE c.name = 'TechCorp'
     RETURN p.name AS employee, p.role AS position
 """
 
-result_set = db.query("cypher", cypher_query)
+result_set = db.query("opencypher", cypher_query)
 
 print("TechCorp Employees:")
 for result in result_set:

bindings/python/docs/examples/21_server_mode_http_access.md

@@ -44,8 +44,10 @@ python3 21_server_mode_http_access.py --http-port 2491 --server-root ./my_test_d
   remote client wrapper or a new dependency.
 - Database creation still happens through the existing server-managed Java API,
   because that is the supported path already used in the test suite.
-- The example binds to `127.0.0.1:2481` by default to reduce clashes with any
-  separately running local ArcadeDB server on the usual `2480` port.
+- The example prefers `127.0.0.1:2481` by default to reduce clashes with any
+  separately running local ArcadeDB server on the usual `2480` port. If that
+  port is already in use, the script automatically falls back to a free local
+  port and prints the chosen value.
 - By default the example exits as soon as the scripted verification steps finish,
   which shuts the server down immediately. Use `--wait-for-enter` if you want time
   to open Studio and inspect the database before shutdown.

bindings/python/docs/java-api-coverage.md

@@ -198,7 +198,7 @@ This approach is actually **cleaner and more maintainable** than direct API expo
 ```python
 # Python way (clean):
 db.command("sql", "CREATE INDEX ON User (email) UNIQUE")
-db.query("cypher", "MATCH (a)-[:FOLLOWS]->(b) RETURN b")
+db.query("opencypher", "MATCH (a)-[:FOLLOWS]->(b) RETURN b")
 
 # vs. hypothetical direct API (complex):
 schema = db.getSchema()

bindings/python/examples/21_server_mode_http_access.py

@@ -27,6 +27,7 @@
 import base64
 import json
 import shutil
+import socket
 import time
 from pathlib import Path
 from urllib.error import HTTPError, URLError
@@ -110,6 +111,32 @@ def reset_server_root(server_root: Path) -> None:
     server_root.parent.mkdir(parents=True, exist_ok=True)
 
 
+def choose_http_port(host: str, requested_port: int) -> tuple[int, bool]:
+    """Return a usable HTTP port for the example.
+
+    Tries the requested port first. If it is unavailable, fall back to an
+    ephemeral free port chosen by the OS.
+    """
+
+    def _can_bind(port: int) -> bool:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+            except OSError:
+                return False
+        return True
+
+    if requested_port > 0 and _can_bind(requested_port):
+        return requested_port, False
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((host, 0))
+        fallback_port = int(sock.getsockname()[1])
+
+    return fallback_port, True
+
+
 def basic_auth_header(username: str, password: str) -> dict[str, str]:
     token = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
     return {"Authorization": f"Basic {token}"}
@@ -186,7 +213,9 @@ def main() -> int:
     server_root = Path(args.server_root)
     reset_server_root(server_root)
 
-    base_url = f"http://{args.host}:{args.http_port}"
+    http_port, used_fallback_port = choose_http_port(args.host, args.http_port)
+
+    base_url = f"http://{args.host}:{http_port}"
     basic_headers = basic_auth_header("root", ROOT_PASSWORD)
 
     print("=" * 72)
@@ -197,14 +226,19 @@ def main() -> int:
     print(f"Server root: {server_root}")
     print(f"Database name: {args.db_name}")
     print(f"Base URL: {base_url}")
+    if used_fallback_port:
+        print(
+            f"Requested HTTP port {args.http_port} was unavailable; "
+            f"using {http_port} instead."
+        )
     print()
 
     with arcadedb.create_server(
         str(server_root),
         root_password=ROOT_PASSWORD,
         config={
             "host": args.host,
-            "http_port": args.http_port,
+            "http_port": http_port,
             "mode": "development",
         },
     ) as server:

bindings/python/examples/scripts/internal_vector_http_latency_probe.py

@@ -28,6 +28,7 @@
 import json
 import os
 import random
+import socket
 import tempfile
 import time
 from contextlib import contextmanager
@@ -140,6 +141,32 @@ def require(condition: bool, message: str) -> None:
         raise SystemExit(message)
 
 
+def choose_http_port(host: str, requested_port: int) -> tuple[int, bool]:
+    """Return a usable HTTP port for the probe.
+
+    Tries the requested port first. If it is unavailable, fall back to an
+    ephemeral free port chosen by the OS.
+    """
+
+    def _can_bind(port: int) -> bool:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+            except OSError:
+                return False
+        return True
+
+    if requested_port > 0 and _can_bind(requested_port):
+        return requested_port, False
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((host, 0))
+        fallback_port = int(sock.getsockname()[1])
+
+    return fallback_port, True
+
+
 @contextmanager
 def prepare_server_root(
     db_path: Path,
@@ -442,7 +469,8 @@ def main() -> int:
     db_path = Path(args.db_path).resolve()
     require(db_path.is_dir(), f"Database path not found or not a directory: {db_path}")
     index_name = f"{args.type_name}[{args.vector_field}]"
-    base_url = f"http://{args.host}:{args.http_port}"
+    http_port, used_fallback_port = choose_http_port(args.host, args.http_port)
+    base_url = f"http://{args.host}:{http_port}"
 
     sql_forms = [args.sql_form] if args.sql_form != "both" else ["raw", "expand"]
 
@@ -456,7 +484,7 @@ def main() -> int:
             "root_password": args.root_password,
             "config": {
                 "host": args.host,
-                "http_port": args.http_port,
+                "http_port": http_port,
                 "mode": "development",
             },
         }
@@ -472,6 +500,8 @@ def main() -> int:
         print(f"wrapper_root:  {using_wrapper_root}")
         print(f"index_name:    {index_name}")
         print(f"base_url:      {base_url}")
+        if used_fallback_port:
+            print(f"requested_port:{args.http_port} unavailable, using {http_port}")
         print(f"k:             {args.k}")
         print(f"ef_search:     {args.ef_search}")
         print(f"warmup_runs:   {args.warmup_runs}")

bindings/python/src/arcadedb_embedded/async_executor.py

@@ -376,7 +376,7 @@ def query(
         Execute async query with callback for each result.
 
         Args:
-            language: Query language ("sql", "cypher", etc.)
+            language: Query language ("sql", "opencypher", etc.)
             query_text: Query string
             callback: Result callback, receives each ResultSet row
             **params: Query parameters
@@ -425,7 +425,7 @@ def command(
         Execute async command with optional callback.
 
         Args:
-            language: Command language ("sql", "cypher", etc.)
+            language: Command language ("sql", "opencypher", etc.)
             command_text: Command string
             callback: Optional result callback
             **params: Command parameters