Skip to content

doc(ai): sync hugegraph-python-client with main - #483

Open
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/ai-hugegraph-python-client
Open

doc(ai): sync hugegraph-python-client with main#483
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/ai-hugegraph-python-client

Conversation

@bitflicker64

Copy link
Copy Markdown
Contributor

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 <dev@hugegraph.apache.org>). 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.

Verify install command against packaging metadata, correct the
PyHugeClient signature and workspace sync command, document the
1.5.0 server floor and GraphSpace resolution, and add the manager,
traverser, task, variable, metrics, auth and error-handling sections
the pages were missing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant