[Documentation] [TitleIndex] [WordIndex

API review

Proposer: Ken Conley

Present at review:

To Review

sudo pip install rospkg

API Docs

Related: REP 114 rospkg standalone library

For now, please scope ignore the rospkg.distro API (except to comment on its inclusion). Also, the 'manifest' model is still being tweaked and generally considered an internal model for now.

API changes from roslib

  1. Package API is now focused on RosPack instances instead of module-level functions like get_pkg_dir()

    • module-level functions required global cache to optimize performance, which make it hard to manipulate caching behavior. Now caching behavior is associated with each instance.
    • Overriding environment variables for module-level functions gets klunky
    • RosPack instance can be passed into higher-level libraries. For example, a rewritten rosdep can use one of these instances, which enables abstracting where package data is stored.

  2. RosPack API has been rewritten from roslib equivalent to only accept single package arguments instead of list of packages arguments.

    • Multiple package style did not provide a performance enhancement
    • Multiple package style made unpacking return values klunky, e.g. "depends = rp.get_depends([package])[package]"
  3. Standardizing on single "RosPack.get_depends(implicit=True)", "RosPack.get_rosdeps(implicit=True)" for API methods that enable querying explicit properties as well as implicit/recursive properties.

    • Previously, there was a mixture of "depend1", "rosdeps0", and other numerical means of specifying access.

    • Cleaner, simpler and more consistent API
  4. RosPack and RosStack have identical APIs for same functionality (e.g. list()) provided by same implementation. Also, underlying Manifest representation has been unified so that same Manifest object can represent either a manifest.xml or stack.xml. For example, there is no longer a separate Depend and StackDepend class; there is just now a Depend object with an additional 'type' attribute set to 'stack' or 'package'.

  5. os_detect now separates between "version" and "codename". These were previously mixed due to rosdep heritage. Now, higher-level libraries must make choice which to use

  6. os_detect: check_presence() -> is_os(). New nomenclature to be more clear that there is no validation/side-effects, just a test of the detector.

  7. OsDetect.register_default(). Constructor now gets default value from a class field of detectors. This enables dynamic registration of detectors instead of having to update OsDetect code directly.

  8. Removed Mandriva support from os_detect. Does not appear to have been used and version return value was inconsistent with other similar OSes.

What's missing

Current usage

The rospkg API thus far has been exercised in a rosdep rewrite (RosPack and os detect APIs) as well as rewrites of the ROS release toolchain (mainly rospkg.distro).

The next step will be go through code in the ROS/ros_comm stacks and being porting from the equivalent roslib APIs. That step is awaiting this review.

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

>>> rospkg.RosPack().get_rosdeps('openni_camera', False)
[u'libusb1.0', u'ps-engine']
>>> rospkg.RosPack().get_rosdeps('openni_camera', True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python2.6/dist-packages/rospkg/rospack.py", line 289, in get_rosdeps
    return self._implicit_rosdeps(package)
  File "/usr/local/lib/python2.6/dist-packages/rospkg/rospack.py", line 309, in _implicit_rosdeps
    for p in pkgs:
NameError: global name 'pkgs' is not defined

tfoote

kwc: based on your ideas, we could add a get_ros_path() as a replacement for get_ros_root() and get_ros_package_path(). get_ros_path() would return the ordered paths. I'll have to see if anything actually *needs* get_ros_root().

PeterHousel:

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Todos

Additions:

Changes:

Future work

Conclusion

Package status change mark change manifest)



2024-03-23 12:56