Skip to content

rename: Path -> Polyline, avoids clashing with pathlib.Path - #42

Merged
petercorke merged 1 commit into
jhavl:mainfrom
petercorke:rename/path-to-polyline
Aug 9, 2026
Merged

rename: Path -> Polyline, avoids clashing with pathlib.Path#42
petercorke merged 1 commit into
jhavl:mainfrom
petercorke:rename/path-to-polyline

Conversation

@petercorke

Copy link
Copy Markdown
Collaborator

Summary

  • Path is renamed to Polyline -- it's a heavily overloaded name
    (pathlib.Path, matplotlib.path.Path, os.path) and RTB in particular
    imports pathlib.Path pervasively, so any RTB code that also wants this
    shape needs an import alias just to avoid shadowing. The class's own
    docstring already called itself "a polyline through a sequence of
    waypoints", so Polyline is the more accurate name too, not just a
    workaround.
  • Path has been in a released version since 1.3.0 (currently on PyPI),
    so it's kept as a deprecated alias rather than removed outright -- same
    pattern as Box -> Cuboid: a subclass that raises FutureWarning in
    __init__ then delegates to super().
  • The wire-protocol string (stype="path") is left unchanged -- it's an
    internal renderer identifier, not the Python API surface causing the
    clash, and touching it would need a synchronized change on the Swift
    side for no real benefit.
  • Docs (api.rst) and tests updated to match; Polyline gets the primary
    entry, Path still gets its own (deprecated) autoclass entry, same
    treatment as Box gets today.

Test plan

  • pytest tests/test_Shape.py tests/test_collision.py -- 170 passed
  • New test_Path_warns_and_is_a_polyline covers the deprecation:
    warns FutureWarning, isinstance(x, Polyline) holds, behaviour
    unchanged
  • repr() correctly distinguishes Path(...) from Polyline(...),
    matching existing Box/Cuboid behaviour
  • docs && make html -- clean, no new warnings introduced (33
    pre-existing, unrelated SceneNode duplicate-description warnings)
  • Grepped Swift and RTB for direct spatialgeometry.Path/gm.Path
    usage -- none found, so nothing external breaks even without the
    deprecation shim; the shim covers any WIP code not yet checked in

🤖 Generated with Claude Code

Path is an extremely overloaded name (pathlib.Path, matplotlib.path.Path,
os.path) -- RTB in particular imports pathlib.Path pervasively, so any RTB
code that also wants spatialgeometry's polyline shape needs an import
alias just to avoid shadowing. The class's own docstring already called
itself "a polyline through a sequence of waypoints", so Polyline is the
more accurate name too, not just a workaround.

Path has been in a released version since 1.3.0 (currently on PyPI), so
kept as a deprecated alias -- same pattern as Box -> Cuboid: a subclass
that warns FutureWarning in __init__ then delegates to super().

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@petercorke
petercorke merged commit c46729b into jhavl:main Aug 9, 2026
15 checks passed
petercorke added a commit to jhavl/swift that referenced this pull request Aug 9, 2026
spatialgeometry renamed the Python class Path -> Polyline (avoids
clashing with pathlib.Path -- jhavl/spatialgeometry#42), keeping Path
as a deprecated (FutureWarning) alias. Migrates swift's one direct
reference (test_protocol.py). The wire-protocol stype string
deliberately stays "path" -- changing that too would be a breaking
protocol change for a rename that's purely cosmetic on the Python
side -- so shapes.js needed comments explaining the naming disparity,
not a code change.
petercorke added a commit to jhavl/swift that referenced this pull request Aug 16, 2026
pytest tests/ -v (CI's invocation) doesn't add the repo root to
sys.path, so tests/test_lights.py's `from tests.test_protocol import
...` has failed at collection on every run since it landed on
2026-08-07/09 -- every PR since (#113-#122) inherited this, unrelated
to what any of them actually changed. Add pythonpath = ["."] to
pytest's ini options, matching what `python -m pytest` already does
implicitly.

With collection fixed, one real failure surfaces: tests/test_protocol.py
constructs sg.Polyline(...), but spatialgeometry's Path->Polyline
rename (jhavl/spatialgeometry#42) merged to its main branch after the
last PyPI release (1.3.0), so plain `pip install spatialgeometry` in CI
doesn't have it yet. Pin CI to spatialgeometry@main, mirroring the
existing roboticstoolbox-python workaround in the same workflow.
Verified against SG's current main: swift's full 99-test suite passes,
and Path is kept as a working deprecated alias (FutureWarning only), so
this isn't a breaking change for swift.
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