bitflicker64 opened a new pull request, #483: URL: https://github.com/apache/hugegraph-doc/pull/483
Syncs the HugeGraph Python client quick start (en and cn) with `apache/hugegraph-ai@main` at version 1.7.0. Every change below traces to a file on `main`. ## Note on the PyPI package name `hugegraph-python` on PyPI is the Apache-published distribution (latest 1.5.0, author `Apache HugeGraph Contributors <[email protected]>`). `hugegraph-python-client` on PyPI is an unrelated empty 0.1.1 placeholder with no author, license or project URLs. The repo declares the distribution as `hugegraph-python-client` 1.7.0, but nothing has shipped under that name. The install command is therefore left as `hugegraph-python` and the naming and version gap is documented on the page, rather than "fixed" into a command that does not work. | Page | Wrong | Changed to | Source | |---|---|---|---| | en + cn | `uv sync` from the repo root installs the client | `uv sync --extra python-client`; the client is a workspace member reached only through that extra | `pyproject.toml:40,93-97`, `.github/workflows/hugegraph-python-client.yml:52` | | en + cn | Requirements said only "An accessible HugeGraph Server" | HugeGraph Server 1.5.0 or later; the client raises `RuntimeError` on older servers and points at client v1.3.x | `hugegraph-python-client/src/pyhugegraph/utils/huge_config.py:66-71` | | en + cn | "Python 3.9 or later", no workspace caveat | 3.9 for the client itself, 3.10+ for the HugeGraph-AI workspace, CI on 3.10 and 3.11 | `hugegraph-python-client/pyproject.toml:27`, `pyproject.toml:27`, `.github/workflows/hugegraph-python-client.yml:22` | | en + cn | Install section stated the PyPI name with no context | Kept `hugegraph-python` (verified correct) and noted that the in-repo distribution is `hugegraph-python-client` 1.7.0 and the PyPI release lags | `hugegraph-python-client/pyproject.toml:19-20`, `hugegraph-python-client/README.md:15-16` | | en + cn | No runtime dependency list | `decorator`, `requests`, `setuptools`, `urllib3`, `rich` | `hugegraph-python-client/pyproject.toml:29-36` | | en + cn | Example passed `"127.0.0.1:8080"` positionally with no parameter reference | Full signature `PyHugeClient(url, graph, user, pwd, graphspace=None, timeout=None)` plus a parameter table, including `timeout` defaulting to `(0.5, 15.0)` | `hugegraph-python-client/src/pyhugegraph/client.py:50-59` | | en + cn | "If GraphSpace is disabled, omit `graphspace`; the default space is usually `DEFAULT`" | Actual resolution: probes `GET {url}/versions`; server < 1.5.0 raises, > 1.5.0 auto-sets `DEFAULT` and enables the mode, exactly 1.5.0 stays off, network failure stays off; plus the resulting URL prefix | `.../utils/huge_config.py:39-92`, `.../utils/huge_requests.py:113-121` | | en + cn | No list of the client's managers | Table of the 10 accessors, plus a note that `RankManager`, `RebuildManager` and `ServicesManager` ship but are not exposed | `.../client.py:61-99`, `.../api/rank.py:27`, `.../api/rebuild.py:23`, `.../api/services.py:24` | | en + cn | No schema-builder documentation | Added the fluent builders for property keys, vertex labels, edge labels and index labels | `.../api/schema_manage/property_key.py:30-180`, `vertex_label.py:28-138`, `edge_label.py:30-161`, `index_label.py:30-100` | | en + cn | Schema query section omitted `getSchema`, the single-item getters and `getRelations` | Added them, including the `Person--ActedIn-->Movie` output shape | `.../api/schema.py:65-132` | | en + cn | Update and delete section only showed `appendVertex`, `removeEdgeById`, `removeVertexById` | Added `eliminateVertex`, `appendEdge`, `eliminateEdge`, the `VertexData` and `EdgeData` fields, and the vertex-id type rules | `.../api/graph.py:50-62,140-158`, `.../structure/vertex_data.py:27-39`, `.../structure/edge_data.py:31-59`, `.../utils/id_format.py:27-47` | | en + cn | No batch write section | `addVertices` takes `(label, properties)` pairs, `addEdges` takes 6-tuples; both return id-only objects | `.../api/graph.py:41-48,122-138` | | en + cn | No paging or conditional query section | `getVertexByPage` returns `(items, next_page)`, `getVertexByCondition`, `getEdgeByPage` (direction required with `vertex_id`), `getVerticesById`, `getEdgesById` | `.../api/graph.py:70-104,166-221` | | en + cn | Gremlin section did not state alias binding or the failure mode | `exec` binds `graph` and `g` from the graph name and GraphSpace, returns `result`, raises `ResponseParseError` on a malformed payload | `.../api/gremlin.py:26,30-56` | | en + cn | No traverser section at all | Added `TraverserManager` with the snake_case methods and the POST-body variants | `.../api/traverser.py:31-250` | | en + cn | No graph variables section | `set`, `get`, `all`, `remove` | `.../api/variable.py:24-39` | | en + cn | No async task section | `list_tasks(status, limit)`, `get_task`, `cancel_task`, `delete_task` | `.../api/task.py:22-42` | | en + cn | No metrics, graphs info or version section | Nine metrics getters, `get_all_graphs` / `get_version` / `get_graph_info` / `get_graph_config` / `clear_graph_all_data`, and `version()` | `.../api/metric.py:22-57`, `.../api/graphs.py:25-62`, `.../api/version.py:22-25` | | en + cn | No auth section | `AuthManager` with graphspace-scoped users, targets, belongs and accesses, server-level groups, and the `ValueError` raised on 1.7.0+ when no graphspace resolves | `.../api/auth.py:25-209`, `.../utils/huge_router.py:134-149` | | en + cn | No mention that camelCase methods have snake_case aliases | Added a naming section noting camelCase is marked deprecated in the debug log | `.../api/common.py:85-101` | | en + cn | No error handling section | Exception table (401 to `NotAuthorizedError`, 404 to `NotFoundError`, other non-2xx to `ServerError`) plus the credential redaction behaviour | `.../utils/exceptions.py:19-76`, `.../utils/util.py:66-95,166-206` | | en + cn | Retry and timeout behaviour undocumented | 3 retries with 0.1 backoff on 500, 502 and 504 | `.../utils/huge_requests.py:36-39,63-72` | | en + cn | Development section only had the style script | Added the CI pytest invocations, the `HUGEGRAPH_*` env vars and the `hugegraph/hugegraph:1.7.0` CI image | `.github/workflows/hugegraph-python-client.yml:56,74,111-119`, `hugegraph-python-client/src/tests/client_utils.py:39-43` | | en + cn | No pointer to a runnable example | Linked `hugegraph-python-client/src/pyhugegraph/example/hugegraph_example.py` | `.../example/hugegraph_example.py:21-58` | ## Upstream defects found while reading the code Not fixed here, they belong in `apache/hugegraph-ai`. `hugegraph-python-client/README.md` is stale in ways the doc pages no longer are: - `README.md:48` calls `PyHugeClient("127.0.0.1", "8080", user=..., pwd=..., graph=..., graphspace=...)`, which raises `TypeError` against the current signature, since `graph` is the second positional parameter (`src/pyhugegraph/client.py:50-59`). - `README.md:124-160` uses `addVertex('person').property(...).create()`, `updateVertex(...)`, `deleteVertex(...)` and `deleteEdge(...)`, none of which exist on `GraphManager` (`src/pyhugegraph/api/graph.py`). ## Correction for a page this PR does not own `content/en/docs/quickstart/client/hugegraph-client.md:11` and its `cn` counterpart link the Python client to the GitHub source tree, `https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client`, while the sibling Go client link is an internal doc link. It should point at `/docs/quickstart/client/hugegraph-client-python` instead, now that this page is the fuller reference. Left for the owner of that page. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
