feat: one Vertex class; Graph(directed=...) chooses the kind of graph

[petercorke]

Summary

There is one vertex class, Vertex, and Graph(directed=...) chooses the kind of graph.

UVertex and DVertex differed only in four private methods that recorded an edge at its ends, and that is the graph's decision, not the vertex's: a vertex has no direction of its own. Having the kind in both the graph and its vertices meant keeping them consistent, with checks (add_vertex's kind test, vertex_class's kind test) whose only job was to refuse the combinations the design allowed to be written.

• The hooks _attach, _detach, _incoming and _endpoints_match move to the graph kinds: UGraph records an edge at both ends, DGraph as leaving its start and entering its end. Vertex.connect calls the graph's hook.
• UVertex and DVertex remain as deprecated names for Vertex (module __getattr__, DeprecationWarning), so existing code that subclasses or constructs them runs. They are not in __all__.
• Graph is concrete: Graph(directed=True) is a DGraph and Graph() a UGraph, so the kind can be a variable; Graph.Adjacency and Graph.Dict take directed= the same way. UGraph(directed=True) is a ValueError. isinstance, the hooks and pickling see the honest subclass.
• Graph.directed reports the kind, replacing the isinstance tests in Adjacency, iscyclic, incidence, validate, the exporters and Edge.__str__.
• vertex_class need only be a subclass of Vertex.

Behaviour changes (1.0)

• A bare Vertex, which could not join any graph, now can; there is no longer a wrong-kind vertex for add_vertex to refuse.
• An Edge between standalone vertices has no kind to show, so its str uses --, not ->.
• Vertex no longer has _attach / _detach; code overriding those on a vertex moves the override to a UGraph / DGraph subclass (see test_vertex_hook.py::TestHookIsTheExtensionPoint).

Downstream

Checked against this branch with the deprecated aliases: MVTB's bundle-adjust tests (4) and RTB's mobile and planner tests (21) pass. RTB's PoseGraph / LatticePlanner and MVTB's ViewPoint / Landmark should change UVertex / DVertex to Vertex; they get a DeprecationWarning until then.

Tests

The hook tests exercise the graph hooks. New tests/test_unified_graph.py (28 tests): the dispatch, directed and its contradictions, one vertex class serving both kinds, the deprecated names (warn, subclass, not advertised, not in __all__), the kind-aware constructors, copy and pickle keeping the kind, the edge arrow.

Docs

Only what the new API makes wrong, or runnable with a warning, is changed (examples, policy.rst, README, the two removed vertex pages). The full documentation and diagram pass follows.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 48 complexity · -2 duplication

Metric	Results
Complexity	48
Duplication	-2

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[codecov]

Codecov Report

❌ Patch coverage is 97.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.27%. Comparing base (c57db9a) to head (0182c19).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/pgraph/PGraph.py	97.22%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #47      +/-   ##
==========================================
+ Coverage   94.79%   95.27%   +0.48%     
==========================================
  Files           3        3              
  Lines        1249     1271      +22     
==========================================
+ Hits         1184     1211      +27     
+ Misses         65       60       -5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.