Skip to main content

Python API AI Assistant Guidelines

Package Overview​

This is moveit_pro_py — a pybind11-based Python API wrapping MoveIt Pro's C++ libraries (kinematics, planning, task construction). The public API is dynamically generated during build via scripts/generate_package.py.

Architecture​

  • C++ bindings live in src/ and include/ — pybind11 modules organized by domain (kinematics/, planners/, tasks/).
  • Python wrappers in moveit_pro/_wrappers/ add Pythonic error handling on top of raw bindings.
  • __init__.py is auto-generated during CMake build by scripts/generate_package.py. Do not edit it directly — modify the extras dict in the generator script instead.
  • bind_util/eigen.hpp handles numpy ↔ Eigen::Isometry3d conversion with validation.
  • bind_util/exception.hpp defines MessageError for propagating tl::expected errors to Python.

Build & Test​

  • Build system: ament_cmake + pybind11 (not setuptools). See CMakeLists.txt.
  • Tests use pytest via ament_cmake_pytest. Run with /run-all-tests or pytest tests/.
  • Test fixtures (URDF/SRDF) are in tests/fixtures/.
  • conftest.py provides setup_robot and license validation fixtures.

Test Scope​

  • Scope Python tests to the binding, not the wrapped library. The C++ packages already test their own rules and error paths; do not duplicate that coverage from Python.
  • For a bound function, test what the binding adds: argument marshaling, defaults, and that tl::expected errors surface as MessageError. A single error-path test per bound function is enough to prove the plumbing, not one per C++ validation rule.
  • Round-trip tests on bound properties (set from Python, read back) are binding tests and belong here. Behavioral coverage of the underlying algorithm belongs in the C++ package's tests.

Adding New Bindings​

  1. Add C++ binding code in src/<domain>/ with a header in include/<domain>/.
  2. Register the binding function in src/moveit_pro_py.cpp (submodule pattern).
  3. Export public symbols by adding entries to extras in scripts/generate_package.py.
  4. Add tests in tests/test_<feature>.py.

Conventions​

  • The examples/ folder contains documented examples of how to use the Python API. Keep examples up to date when changing the public API.
  • Examples that use the MoveIt Pro runtime (e.g., planning, kinematics, task construction) must call moveit_pro.init() / moveit_pro.shutdown() for license validation and cleanup. Initialize ROS 2 only as needed: use rclpy.init() / rclpy.shutdown() in rclpy-based examples, and additionally rclcpp.init() / rclcpp.shutdown() only in examples that use rclcpp-backed components.
  • User-facing documentation is in README_PUBLIC.md — update it when adding or changing public API.
  • Python wrappers should raise descriptive exceptions (e.g., PartialPathError) rather than returning error tuples.

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.9.8.