rosdep2 Python API

Experimental: the rosdep2 Python library is still unstable.

The rosdep Python module supports both the rosdep command-line tool as well as libraries that wish to use rosdep data files to resolve dependencies.

As a developer, you may wish to extend rosdep to add new OS platforms or package managers. Platforms are specified by registering information on the InstallerContext. Package managers generally extend the PackageManagerInstaller implementation.

The rospkg library is used for OS detection.

Please consult the Developers Guide for more information on developing with the Python API.

Exceptions

class rosdep2.InvalidData(message, origin=None)

Data is not in valid rosdep format.

Database Model

class rosdep2.RosdepDatabase

Stores loaded rosdep data for multiple views.

get_view_data(view_name)

Returns:

RosdepDatabaseEntry of given view.

Raises:

KeyError if no entry for view_name

get_view_dependencies(view_name)

Raises:

KeyError if view_name is not an entry, or if all of view’s dependencies have not been properly loaded.

get_view_names()

Returns:

list of view names that are loaded into this database.

is_loaded(view_name)

Parameters:

view_name – name of view to check, str

Returns:

True if view_name has been loaded into this database.

mark_loaded(view_name)

If view is not already loaded, this will mark it as such. This in effect sets the data for the view to be empty.

Parameters:

view_name – name of view to mark as loaded

set_view_data(view_name, rosdep_data, view_dependencies, origin)

Set data associated with view. This will create a new RosdepDatabaseEntry.

Parameters:

• rosdep_data – rosdep data map to associated with view. This will be copied.

• origin – origin of view data, e.g. filepath of rosdep.yaml

class rosdep2.RosdepDatabaseEntry(rosdep_data, view_dependencies, origin)

Stores rosdep data and metadata for a single view.

View Model

class rosdep2.RosdepDefinition(rosdep_key, data, origin='<dynamic>')

Single rosdep dependency definition. This data is stored as the raw dictionary definition for the dependency.

See REP 111, ‘Multiple Package Manager Support for Rosdep’ for a discussion of this raw format.

get_rule_for_platform(os_name, os_version, installer_keys, default_installer_key)

Get installer_key and rule for the specified rule. See REP 111 for precedence rules.

Parameters:

• os_name – OS name to get rule for

• os_version – OS version to get rule for

• installer_keys – Keys of installers for platform, [str]

• default_installer_key – Default installer key for platform, [str]

Returns:

(installer_key, rosdep_args_dict), (str, dict)

Raises:

ResolutionError If no rule is available

Raises:

InvalidData If rule data is not valid

reverse_merge(new_data, origin='<dynamic>', verbose=False)

Merge two definitions together, with existing rules taking precendence. Definitions are merged at the os_name level, meaning that if two rules exist with the same os_name, the first one wins.

Parameters:

• data – raw rosdep data for a single rosdep dependency, dict

• origin – string that indicates where this new data comes from (e.g. filename)

class rosdep2.RosdepView(name)

View of RosdepDatabase. Unlike RosdepDatabase, which stores RosdepDatabaseEntry data for all stacks, a view merges entries for a particular stack. This view can then be queried to lookup and resolve individual rosdep dependencies.

keys()

Returns:

list of rosdep names in this view

lookup(rosdep_name)

Returns:

RosdepDefinition

Raises:

KeyError If rosdep_name is not declared

merge(update_entry, override=False, verbose=False)

Merge rosdep database update into main database. Merge rules are first entry to declare a key wins. There are no conflicts. This rule logic is modelled after the apt sources list.

Parameters:

override – Ignore first-one-wins rules and instead always use rules from update_entry

class rosdep2.RosdepLookup(rosdep_db, loader)

Lookup rosdep definitions. Provides API for most non-install-related commands for rosdep.

RosdepLookup caches data as it is loaded, so changes made on the filesystem will not be reflected if the rosdep information has already been loaded.

static create_from_rospkg(rospack=None, rosstack=None, sources_loader=None, verbose=False, dependency_types=None)

Create RosdepLookup based on current ROS package environment.

Parameters:

• rospack – (optional) Override rospkg.RosPack instance used to crawl ROS packages.

• rosstack – (optional) Override rospkg.RosStack instance used to crawl ROS stacks.

• sources_loader – (optional) Override SourcesLoader used for managing sources.list data sources.

• dependency_types – (optional) List of dependency types. Allowed: {‘build’, ‘buildtool’, ‘build_export’, ‘buildtool_export’, ‘exec’, ‘test’, ‘doc’}

create_rosdep_view(view_name, view_keys, verbose=False)

Parameters:

• view_name – name of view to create

• view_keys – order list of view names to merge, first one wins

• verbose – print debugging output

get_errors()

Retrieve error state for API calls that do not directly report error state. This is the case for APIs like RosdepLookup.where_defined() that are meant to be fault-tolerant to single-stack failures.

Returns:

List of exceptions, [Exception]

get_resources_that_need(rosdep_name)

Parameters:

rosdep_name – name of rosdep dependency

Returns:

list of package names that require rosdep, [str]

get_rosdep_view(view_key, verbose=False)

Get a RosdepView associated with view_key. Views can be queries to resolve rosdep keys to definitions.

Parameters:

view_key – Name of rosdep view (e.g. ROS stack name), str

Raises:

RosdepConflict if view cannot be created due to conflict rosdep definitions.

Raises:

rospkg.ResourceNotFound if view_key cannot be located

Raises:

RosdepInternalError

get_rosdep_view_for_resource(resource_name, verbose=False)

Get a RosdepView for a specific ROS resource resource_name. Views can be queries to resolve rosdep keys to definitions.

Parameters:

resource_name – Name of ROS resource (e.g. stack, package) to create view for, str.

Returns:

RosdepView for specific ROS resource resource_name, or None if no view is associated with this resource.

Raises:

RosdepConflict if view cannot be created due to conflict rosdep definitions.

Raises:

rospkg.ResourceNotFound if view_key cannot be located

Raises:

RosdepInternalError

get_rosdeps(resource_name, implicit=True)

Get rosdeps that resource_name (e.g. package) requires.

Parameters:

implicit – If True, include implicit rosdep dependencies. Default: True.

Returns:

list of rosdep names, [str]

get_views_that_define(rosdep_name)

Locate all views that directly define rosdep_name. A side-effect of this method is that all available rosdep files in the configuration will be loaded into memory.

Error state from single-stack failures (e.g. InvalidData, ResourceNotFound) are not propagated. Caller must check RosdepLookup.get_errors() to check for single-stack error state. Error state does not reset – it accumulates.

Parameters:

rosdep_name – name of rosdep to lookup

Returns:

list of (stack_name, origin) where rosdep is defined.

Raises:

RosdepInternalError

resolve(rosdep_key, resource_name, installer_context)

Resolve a RosdepDefinition for a particular os/version spec.

Parameters:

• resource_name – resource (e.g. ROS package) to resolve key within

• rosdep_key – rosdep key to resolve

• os_name – OS name to use for resolution

• os_version – OS name to use for resolution

Returns:

(installer_key, resolution, dependencies), (str, [opaque], [str]). resolution are the system dependencies for the specified installer. The value is an opaque list and meant to be interpreted by the installer. dependencies is a list of rosdep keys that the definition depends on.

Raises:

ResolutionError If rosdep_key cannot be resolved for resource_name in installer_context

Raises:

rospkg.ResourceNotFound if resource_name cannot be located

resolve_all(resources, installer_context, implicit=False)

Resolve all the rosdep dependencies for resources using installer_context.

Parameters:

• resources – list of resources (e.g. packages), [str]

• installer_context – InstallerContext

• implicit – Install implicit (recursive) dependencies of resources. Default False.

Returns:

(resolutions, errors), ([(str, [str])], {str: ResolutionError}). resolutions provides an ordered list of resolution tuples. A resolution tuple’s first element is the installer key (e.g.: apt or homebrew) and the second element is a list of opaque resolution values for that installer. errors maps package names to an ResolutionError or KeyError exception.

Raises:

RosdepInternalError if unexpected error in constructing dependency graph

Raises:

InvalidData if a cycle occurs in constructing dependency graph

Loaders

class rosdep2.RosdepLoader

Base API for loading rosdep information by package or stack name.

get_rosdeps(resource_name, implicit=True)

Raises:

rospkg.ResourceNotFound if resource_name cannot be found.

get_view_key(resource_name)

Map resource_name to a view key. In rospkg, this maps a ROS package name to a ROS stack name. If resource_name is a ROS stack name, it returns the ROS stack name.

Returns:

Name of view that resource_name is in, None if no associated view.

Raises:

rospkg.ResourceNotFound if resource_name cannot be found.

load_rosdep_yaml(yaml_contents, origin)

Utility routine for unmarshalling rosdep data encoded as YAML.

Parameters:

origin – origin of yaml contents (for error messages)

Raises:

yaml.YAMLError

load_view(view_name, rosdep_db, verbose=False)

Load view data into rosdep_db. If the view has already been loaded into rosdep_db, this method does nothing.

Parameters:

• view_name – name of ROS stack to load, str

• rosdep_db – database to load stack data into, RosdepDatabase

Raises:

InvalidData

Raises:

rospkg.ResourceNotFound if view cannot be located

class rosdep2.RosPkgLoader(rospack=None, rosstack=None, underlay_key=None, dependency_types=[])

get_loadable_resources()

‘Resources’ map to ROS packages names.

get_loadable_views()

‘Views’ map to ROS stack names.

get_rosdeps(resource_name, implicit=True)

If resource_name is a stack, returns an empty list.

Raises:

rospkg.ResourceNotFound if resource_name cannot be found.

get_view_key(resource_name)

Map resource_name to a view key. In rospkg, this maps the DEFAULT_VIEW_KEY if resource_name exists.

Raises:

rospkg.ResourceNotFound

load_view(view_name, rosdep_db, verbose=False)

Load view data into rosdep_db. If the view has already been loaded into rosdep_db, this method does nothing. If view has no rosdep data, it will be initialized with an empty data map.

Raises:

InvalidData if view rosdep.yaml is invalid

Raises:

rospkg.ResourceNotFound if view cannot be located

Returns:

True if view was loaded. False if view was already loaded.

Installers

class rosdep2.InstallerContext(os_detect=None)

InstallerContext manages the context of execution for rosdep as it relates to the installers, OS detectors, and other extensible APIs.

add_os_installer_key(os_key, installer_key)

Register an installer for the specified OS. This will fail with a KeyError if no Installer can be found with the associated installer_key.

Parameters:

• os_key – Key for OS

• installer_key – Key for installer to add to OS

Raises:

KeyError: if installer for installer_key is not set.

get_default_os_installer_key(os_key)

Get the default OS installer key to use for OS, or None if there is no default.

Parameters:

os_key – Key for OS

Returns:

Installer

Raises:

KeyError: if no information for OS os_key is registered.

get_installer(installer_key)

Returns:

Installer class associated with installer_key.

Raises:

KeyError If not associated installer

Raises:

InstallFailed If installer cannot produce an install command (e.g. if installer is not installed)

get_installer_keys()

Returns:

list of registered installer keys

get_os_detect()

Returns os_detect:

OsDetect instance used for detecting platforms.

get_os_installer_keys(os_key)

Get list of installer keys registered for the specified OS. These keys can be resolved by calling InstallerContext.get_installer().

Parameters:

os_key – Key for OS

Raises:

KeyError: if no information for OS os_key is registered.

get_os_keys()

Returns:

list of OS keys that have registered with this context, [str]

get_os_name_and_version()

Get the OS name and version key to use for resolution and installation. This will be the detected OS name/version unless InstallerContext.set_os_override() has been called.

Returns:

(os_name, os_version), (str, str)

set_default_os_installer_key(os_key, installer_key)

Set the default OS installer to use for OS. InstallerContext.add_os_installer() must have previously been called with the same arguments.

Parameters:

• os_key – Key for OS

• installer_key – Key for installer to add to OS

Raises:

KeyError: if installer for installer_key is not set or if OS for os_key has no associated installers.

set_installer(installer_key, installer)

Set the installer to use for installer_key. This will replace any existing installer associated with the key. installer_key should be the same key used for the rosdep.yaml package manager key. If installer is None, this will delete any existing associated installer from this context.

Parameters:

• installer_key – key/name to associate with installer, str

• installer – Installer implementation, class.

Raises:

TypeError if installer is not a subclass of Installer

set_os_override(os_name, os_version)

Override the OS detector with os_name and os_version. See InstallerContext.detect_os().

Parameters:

• os_name – OS name value to use, str

• os_version – OS version value to use, str

class rosdep2.Installer

The Installer API is designed around opaque resolved parameters. These parameters can be any type of sequence object, but they must obey set arithmetic. They should also implement __str__() methods so they can be pretty printed.

get_depends(rosdep_args)

Returns:

list of dependencies on other rosdep keys. Only necessary if the package manager doesn’t handle dependencies.

get_install_command(resolved, interactive=True, reinstall=False, quiet=False)

Parameters:

• resolved – list of resolved installation items, [opaque]

• interactive – If False, disable interactive prompts, e.g. Pass through -y or equivalant to package manager.

• reinstall – If True, install everything even if already installed

is_installed(resolved_item)

Parameters:

resolved – resolved installation item. NOTE: this is a single item, not a list of items like the other APIs, opaque.

Returns:

True if all of the resolved items are installed on the local system

resolve(rosdep_args_dict)

Parameters:

rosdep_args_dict – argument dictionary to the rosdep rule for this package manager

Returns:

[resolutions]. resolved objects should be printable to a user, but are otherwise opaque.

unique(*resolved_rules)

Combine the resolved rules into a unique list. This is meant to combine the results of multiple calls to PackageManagerInstaller.resolve().

Example:

resolved1 = installer.resolve(args1)
resolved2 = installer.resolve(args2)
resolved = installer.unique(resolved1, resolved2)

Parameters:

resolved_rules – resolved arguments. Resolved arguments must all be from this Installer instance.

class rosdep2.PackageManagerInstaller(detect_fn, supports_depends=False)

General form of a package manager Installer implementation that assumes:

• installer rosdep args spec is a list of package names stored with the key “packages”

• a detect function exists that can return a list of packages that are installed

Also, if supports_depends is set to True:

• installer rosdep args spec can also include dependency specification with the key “depends”

elevate_priv(cmd)

Prepend self.sudo_command to the command if self.as_root is True.

Parameters:

cmd (list) – list of strings comprising the command

Returns:

a list of commands

get_depends(rosdep_args)

Returns:

list of dependencies on other rosdep keys. Only necessary if the package manager doesn’t handle dependencies.

get_install_command(resolved, interactive=True, reinstall=False, quiet=False)

Parameters:

• resolved – list of resolved installation items, [opaque]

• interactive – If False, disable interactive prompts, e.g. Pass through -y or equivalant to package manager.

• reinstall – If True, install everything even if already installed

get_packages_to_install(resolved, reinstall=False)

Return a list of packages (out of resolved) that still need to get installed.

get_version_strings()

Return a list of version information strings.

Where each string is of the form “<installer> <version string>”. For example, [“apt-get x.y.z”] or [“pip x.y.z”, “setuptools x.y.z”].

is_installed(resolved_item)

Check if a given package was installed.

resolve(rosdep_args)

See Installer.resolve()

unique(*resolved_rules)

See Installer.unique()

Indices and tables

• Index

• Module Index

• Search Page