PythonRobotics - Moses Yebei

The Problem

Students and researchers need ready‑to‑run Python implementations of core robotics algorithms (localization, mapping, SLAM, path planning, control). Existing textbooks often omit runnable code or provide fragmented snippets, forcing users to re‑implement the logic and waste time on debugging.

What This Does

The repository supplies self‑contained Python scripts that demonstrate a full spectrum of classic algorithms. The PathPlanning/ folder (92 files) hosts A*, D*, RRT*, Hybrid A*, and Frenet‑optimal planners; SLAM/ and Localization/ implement EKF, FastSLAM, particle filters, and ICP. 3‑D drone trajectory following lives in AerialNavigation/drone_3d_trajectory_following/ and arm‑navigation examples under ArmNavigation/.

Key entry points are:

PathPlanning/DStar/dstar.py – defines run() (line 159) that builds a grid map, invokes the D* planner, and visualises the result.
AerialNavigation/drone_3d_trajectory_following/drone_3d_trajectory_following.py – main() (line 192) creates a Quadrotor instance, runs a simulation loop, and calls the generic plot() helper (77 callers).

All algorithms share utility modules utils/angle.py (26 importers) and utils/plot.py (8 importers), which centralise geometry calculations and Matplotlib visualisation.

How It Is Wired

Execution starts in a concrete script, e.g. PathPlanning/DStar/dstar.py → run(). run() constructs a map, calls DStar class methods (cost, set_state) and then invokes plot() from utils/plot.py. The call graph shows plot is the most frequently called internal function (77 distinct callers), giving it the widest blast radius; any change here ripples through most planners and visualisations.

main in the drone example follows a similar pattern:

Instantiate Quadrotor (AerialNavigation/.../Quadrotor.py).
Loop over time steps, calling calculate_position, calculate_velocity, and calculate_acceleration.
Each step ends with plot to render the trajectory.

The internal call graph records 1 607 intra‑repo call edges; notable hot spots are flatten (16 callers) and Node (24 callers) used by the Time‑Based Path Planning submodule. No circular import cycles were detected, but utils/angle.py is a hub (26 importers), so stability there is critical. Deep nesting (max indentation depth 6) appears in PathPlanning/TimeBasedPathPlanning/GridWithDynamicObstacles.py, utils/plot.py, and MissionPlanning/StateMachine/state_machine.py, making those files harder to modify safely.

External interaction is limited to five functions that launch shell commands; the code otherwise stays in‑process and writes only image files for visualisation (e.g., PathPlanning/SpiralSpanningTreeCPP/map/*.png).

How To Use It

# Clone the exact upstream repository
git clone https://github.com/moses-y/PythonRobotics.git
cd PythonRobotics

# Install the declared Python deps (no lockfile, so versions may vary)
pip install -r requirements/requirements.txt

To run a planner:

python PathPlanning/DStar/dstar.py        # executes run() → visualises D* path

To simulate the drone demo:

python AerialNavigation/drone_3d_trajectory_following/drone_3d_trajectory_following.py

The docs/Makefile can build the Sphinx documentation (make -C docs html) if you need the textbook‑style narrative.

Real‑World Use

A robotics research team can import a planner directly, e.g.:

from PathPlanning.RRTStar.rrt_star import RRTStar
planner = RRTStar(start, goal, obstacle_map)
path = planner.plan()

The returned path can feed a ROS node’s trajectory controller without further modification, because the data structures are plain Python lists of (x, y) tuples.

Code Health & Issues

Measured findings (static analysis)

HIGH – Hub module: utils/angle.py (26 importers). Keep API stable; extract volatile logic.
HIGH – Deep nesting: observed in PathPlanning/TimeBasedPathPlanning/GridWithDynamicObstacles.py, utils/plot.py, MissionPlanning/StateMachine/state_machine.py. Refactor to early returns.
HIGH – Duplicated code: similar 6‑line blocks across multiple ArmNavigation/ files. Consolidate into shared helpers.

Code‑health audit (GitHub Actions)

HIGH – Pin third‑party actions to commit SHA (.github/workflows/*).
HIGH – CI does not run the test suite; add a pytest step.
MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN (.github/workflows/Linux_CI.yml).
MEDIUM – Add a dependency‑vulnerability scan (e.g., dependency-review-action).
MEDIUM – Set persist-credentials: false on checkout to avoid credential leakage.
LOW – Set timeout-minutes on workflow jobs to prevent hangs.

No Dockerfile, no lockfile, and the repository relies on a single requirements.txt, which limits reproducibility.

The Bottom Line

The repo delivers a breadth of well‑organised, runnable robotics algorithms useful for education and rapid prototyping. Its primary limitation is operational hygiene: CI does not execute tests, and dependency management lacks lockfiles and pinned actions, which raises reproducibility and security concerns. Teams comfortable managing their own CI pipeline will find the code valuable; others should first address the health issues before adopting it in production.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

514 files

Python257
reStructuredText94
YAML13
Markdown8
CSS1
HTML1

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests 92 modules"] g1["PathPlanning 83 modules"] g2["SLAM 15 modules"] g3["Mapping 15 modules"] g4["ArmNavigation 12 modules"] g5["PathTracking 12 modules"] g6["Localization 8 modules"] g0 -->|23| g1 g5 -->|4| g1 g0 -->|3| g5 g1 -->|2| g3 g0 -->|1| g3

Module dependencies

The 10 most depended-upon modules of 257, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_utils_angle["angle"] n1_ing_GridWithDynamicObstacles["GridWithDynamicObstacles"] n2_utils_plot["plot"] n3_g_TimeBasedPathPlanning_Node["Node"] n4_asedPathPlanning_BaseClasses["BaseClasses"] n5_lanning_CubicSpline___init__["__init__"] n6_meBasedPathPlanning_Plotting["Plotting"] n7_ng_grid_map_lib_grid_map_lib["grid_map_lib"] n8_PathPlanning_RRT___init__["__init__"] n9_meBasedPathPlanning___init__["__init__"] n4_asedPathPlanning_BaseClasses --> n1_ing_GridWithDynamicObstacles n4_asedPathPlanning_BaseClasses --> n3_g_TimeBasedPathPlanning_Node n1_ing_GridWithDynamicObstacles --> n3_g_TimeBasedPathPlanning_Node n6_meBasedPathPlanning_Plotting --> n1_ing_GridWithDynamicObstacles n6_meBasedPathPlanning_Plotting --> n4_asedPathPlanning_BaseClasses n6_meBasedPathPlanning_Plotting --> n3_g_TimeBasedPathPlanning_Node n2_utils_plot --> n0_utils_angle

Dependencies

1 of 9 declared dependencies are a major version behind. Resolved 9 of 9 against the registry.

Package	Declared	Latest	Behind
`mypy`	== 1.19.1	2.3.1	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds requirements/requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

larsoner/circleci-artifacts-redirector-action@v1.3.1, sphinx-notes/pages@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh2 occurrences

pytest@9.0.2 CVE-2025-71176 (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Make CI invoke the test suite it hashigh96 occurrences

.github/workflows

96 test files, no test command in the 4 workflows read

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/Linux_CI.yml

3 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/Linux_CI.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/Linux_CI.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.