refactor: connect() defined once, vertex kinds supply an _attach hook

[petercorke]

Summary

UVertex.connect() and DVertex.connect() were the same few lines (call super().connect(), then append the edge to one or two edge lists) differing only in that last line, and each repeated the full signature and docstring. A new vertex kind had to know to call super() first, and the edge rules had to be documented three times.

connect() is now defined once, on BaseVertex, and the vertex kinds supply a single bookkeeping hook, _attach (Template Method):

class BaseVertex:
    def connect(self, dest, edge=None, cost=None, data=None) -> Edge:
        ...validate, bind the edge's endpoints, register it with the graph...
        self._attach(e, dest)      # the one thing that differs
        return e

class UVertex(BaseVertex):
    def _attach(self, edge, dest):
        self._edgelist.append(edge); dest._edgelist.append(edge)   # both ends

class DVertex(BaseVertex):
    def _attach(self, edge, dest):
        self._edgelist.append(edge)                                # source only

Why not make connect() itself abstract

BaseVertex is documented as constructible (policy.rst), and a bare BaseVertex can never join a graph anyway (connect() raises ValueError, add_vertex() raises TypeError), so abstractness would break the documented behavior and prevent nothing. The hook is what varies, so the hook is what a subclass supplies; the base one raises NotImplementedError.

Behavior

None. Signature, return value, exceptions and edge-list contents are unchanged, add_edge() and Edge.connect() both still go through connect(), and the full existing suite passes untouched.

Docs

The "unlike the directed counterpart" text and the per-kind example moved from the removed overrides to the UVertex/DVertex class docstrings, and BaseVertex.connect gains one note stating who holds the edge and the endpoint rule for each kind.

Tests

tests/test_vertex_hook.py, 18 tests: connect is defined once (UVertex.connect is BaseVertex.connect), the hook is called exactly once and after the edge is registered, nothing is attached when validation refuses (wrong graph, wrong endpoints, ungraphed), self-loops are held twice by an undirected and once by a directed vertex, a bare BaseVertex is still constructible but cannot connect or be added, and a user vertex kind can change the bookkeeping by overriding only _attach. Suite: 233 passing, mypy clean.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 21 complexity · 0 duplication

Metric	Results
Complexity	21
Duplication	0

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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.54%. Comparing base (d22408d) to head (66aff65).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #35      +/-   ##
==========================================
+ Coverage   93.27%   93.54%   +0.27%     
==========================================
  Files           3        3              
  Lines        1055     1054       -1     
==========================================
+ Hits          984      986       +2     
+ Misses         71       68       -3     

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