catkin_pkg Package

catkin_pkg Package

Library for retrieving information about catkin packages.

changelog Module

Processes ROS changelogs so that they can be used in binary packaging.

The Changelog format is described in REP-0132:

http://ros.org/reps/rep-0132.html

class catkin_pkg.changelog.BulletList(bullets=None, bullet_type=None)

Bases: object

Represents a bulleted list of text

as_rst()

as_txt(indent=u'', use_hyphen_bullet=False)

bullet_generator(bullet)

class catkin_pkg.changelog.Changelog(package_name=None)

Bases: object

Represents a REP-0132 changelog

add_version_section(version, date, contents)

Adds a version section

Parameters:

• version – str version as a string
• date – datetime.datetime version date
• contents – list(list([str|Reference]))` contents as a list of lists which contain a combination of str and Reference objects

Returns:

None

foreach_version(reverse=False)

Creates a generator for iterating over the versions, dates and content

Versions are stored and iterated in order.

Parameters:reverse – bool if True then the iteration is reversed Returns:generator for iterating over versions, dates and content

get_content_of_version(version)

Returns changelog content for a given version

Parameters:version – str version Returns:list(list([str|Reference])) content expanded

get_date_of_version(version)

Returns date of a given version as a datetime.datetime

package_name

rst

exception catkin_pkg.changelog.DuplicateVersionsException(version)

Bases: exceptions.Exception

Raised when more than one section per version is given

exception catkin_pkg.changelog.InvalidSectionTitle(title)

Bases: exceptions.Exception

raised on non REP-0132 section titles

class catkin_pkg.changelog.MixedText(texts=[])

Bases: object

Represents text mixed with references and nested bullets

to_txt(bullet_indent=u' ')

class catkin_pkg.changelog.Reference(text, link)

Bases: object

Represents a piece of text with an associated link

as_rst()

Self as rst (unicode)

as_txt()

Self formatted for plain text (unicode)

class catkin_pkg.changelog.Transition

Bases: object

Represents a trasition element from ReST

catkin_pkg.changelog.bullet_list_class_from_docutils(bullet_list, bullet_type=None)

Processes elements of bullet list into an encapsulating class

Parameters:

• bullet_list – docutils.nodes.bullet_list list to be processed
• bullet_type – str either ‘bullet’ or ‘enumerated’

Returns:

BulletList object representing a docutils bullet_list

catkin_pkg.changelog.get_changelog_from_path(path, package_name=None)

Changelog factory, which reads a changelog file into a class

Parameters:

• path – str the path of the changelog including or excluding the filename CHANGELOG.rst
• package_name – str the package name

Returns:

Changelog changelog class or None if file was not readable

catkin_pkg.changelog.mixed_text_from_docutils(node)

Takes most Text-ish docutils objects and converts them to MixedText

Parameters:node – docutils.nodes.{paragraph, list_item, ...} text-ish Returns:MixedText representing the given docutils object

catkin_pkg.changelog.populate_changelog_from_rst(changelog, rst)

Changelog factory, which converts the raw ReST into a class

Parameters:

• changelog – Changelog changelog to be populated
• rst – str raw ReST changelog

Returns:

Changelog changelog that was populated

catkin_pkg.changelog.processes_changelog_children(changelog, children)

Processes docutils children into a REP-0132 changelog instance. Recurse into sections, check (sub-)titles if they are valid versions.

Parameters:

• changelog – Changelog changelog to be populated
• section – docutils.nodes.section section to be processed

Returns:

Changelog changelog that was populated

catkin_pkg.changelog.reference_from_docutils(reference)

Turns a reference element into a Reference

Parameters:reference – docutils.nodes.reference reference element Returns:Reference simpler object representing the reference

catkin_pkg.changelog.version_and_date_from_title(title)

Splits a section title into version and date if possible.

Parameters:title – str raw section title to be processed Returns:(str, datetime.datetime) Raises :InvalidSectionTitle for non REP-0132 section titles

changelog_generator Module

Generate/update ROS changelog files.

The Changelog format is described in REP-0132:

http://ros.org/reps/rep-0132.html

catkin_pkg.changelog_generator.filter_package_changes(tag2log_entries, pkg_path)

catkin_pkg.changelog_generator.generate_changelog_file(pkg_name, tag2log_entries, vcs_client=None, skip_contributors=False)

catkin_pkg.changelog_generator.generate_changelogs(base_path, packages, tag2log_entries, logger=None, vcs_client=None, skip_contributors=False)

catkin_pkg.changelog_generator.generate_package_headline(pkg_name)

catkin_pkg.changelog_generator.generate_version_block(version, timestamp, log_entries, vcs_client=None, skip_contributors=False)

catkin_pkg.changelog_generator.generate_version_content(log_entries, vcs_client=None, skip_contributors=False)

catkin_pkg.changelog_generator.generate_version_headline(version, timestamp)

catkin_pkg.changelog_generator.get_all_changes(vcs_client)

catkin_pkg.changelog_generator.get_forthcoming_changes(vcs_client)

catkin_pkg.changelog_generator.get_version_headline(version, timestamp)

catkin_pkg.changelog_generator.get_version_section_match(data, version)

catkin_pkg.changelog_generator.get_version_section_pattern(version)

catkin_pkg.changelog_generator.prepend_version_content(data, version, content)

catkin_pkg.changelog_generator.replace_repository_references(line, vcs_client=None)

catkin_pkg.changelog_generator.sorted_tags(tags)

catkin_pkg.changelog_generator.update_changelog_file(data, tag2log_entries, vcs_client=None, skip_contributors=False)

catkin_pkg.changelog_generator.update_changelogs(base_path, packages, tag2log_entries, logger=None, vcs_client=None, skip_contributors=False)

changelog_generator_vcs Module

Extract log information from repositories.

class catkin_pkg.changelog_generator_vcs.GitClient(path)

Bases: catkin_pkg.changelog_generator_vcs.VcsClientBase

get_latest_tag_name()

get_log_entries(from_tag, to_tag)

get_tags()

replace_repository_references(line)

type = 'git'

class catkin_pkg.changelog_generator_vcs.HgClient(path)

Bases: catkin_pkg.changelog_generator_vcs.VcsClientBase

get_latest_tag_name()

get_log_entries(from_tag, to_tag)

get_tags()

type = 'hg'

class catkin_pkg.changelog_generator_vcs.LogEntry(msg, affected_paths, author)

Bases: object

affects_path(path)

class catkin_pkg.changelog_generator_vcs.Tag(name, timestamp=None)

Bases: object

class catkin_pkg.changelog_generator_vcs.VcsClientBase(path)

Bases: object

get_latest_tag_name()

get_log_entries(from_tag, to_tag)

get_tags()

replace_repository_references(line)

catkin_pkg.changelog_generator_vcs.get_vcs_client(base_path)

cmake Module

catkin_pkg.cmake.configure_file(template_file, environment)

Evaluate a .in template file used in CMake with configure_file().

Parameters:

• template_file – path to the template, str
• environment – dictionary of placeholders to substitute, dict

Returns:

string with evaluates template

Raises :

KeyError for placeholders in the template which are not in the environment

catkin_pkg.cmake.configure_string(template, environment)

Substitute variables enclosed by @ characters.

Parameters:

• template – the template, str
• environment – dictionary of placeholders to substitute, dict

Returns:

string with evaluates template

Raises :

KeyError for placeholders in the template which are not in the environment

catkin_pkg.cmake.get_metapackage_cmake_template_path()

Returns the location of the metapackage CMakeLists.txt CMake template.

Returns:str location of the metapackage CMakeLists.txt CMake template

metapackage Module

Checks metapackages for compliance with REP-0127:

http://ros.org/reps/rep-0127.html#metapackage

exception catkin_pkg.metapackage.InvalidMetapackage(msg, path, package)

Bases: exceptions.Exception

catkin_pkg.metapackage.get_cmakelists_txt(path)

Fetches the CMakeLists.txt from a given path

Parameters:path (str) – path to the folder containing the CMakeLists.txt Returns:contents of CMakeLists.txt file in given path Return type:str Raises OSError:if there is no CMakeLists.txt in given path

catkin_pkg.metapackage.get_expected_cmakelists_txt(metapackage_name)

Returns the expected boilerplate CMakeLists.txt file for a metapackage

Parameters:metapackage_name (str) – name of the metapackage Returns:expected CMakeLists.txt file Return type:str

catkin_pkg.metapackage.has_cmakelists_txt(path)

Returns True if the given path contains a CMakeLists.txt, otherwise False

Parameters:path (str) – path to folder potentially containing CMakeLists.txt Returns:True if path contains CMakeLists.txt, else False Return type:bool

catkin_pkg.metapackage.has_valid_cmakelists_txt(path, metapackage_name)

Returns True if the given path contains a valid CMakeLists.txt, otherwise False

A valid CMakeLists.txt for a metapackage is defined by REP-0127

Parameters:

• path (str) – path to folder containing CMakeLists.txt
• metapackage_name (str) – name of the metapackage being tested

Returns:

True if the path contains a valid CMakeLists.txt, else False

Return type:

bool

Raises OSError:

if there is no CMakeLists.txt in given path

catkin_pkg.metapackage.validate_metapackage(path, package)

Validates the given package (catkin_pkg.package.Package) as a metapackage

This validates the metapackage against the definition from REP-0127

Parameters:

• path (str) – directory of the package being checked
• package (catkin_pkg.package.Package) – package to be validated

Raises:

• InvalidMetapackage – if package is not a valid metapackage
• OSError – if there is not package.xml at the given path

package Module

Library for parsing package.xml and providing an object representation.

class catkin_pkg.package.Dependency(name, **kwargs)

Bases: object

name

version_eq

version_gt

version_gte

version_lt

version_lte

class catkin_pkg.package.Export(tagname, content=None)

Bases: object

attributes

content

tagname

exception catkin_pkg.package.InvalidPackage

Bases: exceptions.Exception

class catkin_pkg.package.Package(filename=None, **kwargs)

Bases: object

Object representation of a package manifest file

authors

build_depends

build_export_depends

buildtool_depends

buildtool_export_depends

conflicts

description

doc_depends

exec_depends

exports

filename

has_buildtool_depend_on_catkin()

Returns True if this Package buildtool depends on catkin, otherwise False

Returns:True if the given package buildtool depends on catkin Return type:bool

has_invalid_metapackage_dependencies()

Returns True if this package has invalid dependencies for a metapackage

This is defined by REP-0127 as any non-run_depends dependencies other then a buildtool_depend on catkin.

Returns:True if the given package has any invalid dependencies, otherwise False Return type:bool

is_metapackage()

Returns True if this pacakge is a metapackage, otherwise False

Returns:True if metapackage, else False Return type:bool

licenses

maintainers

name

package_format

replaces

test_depends

urls

validate(warnings=None)

makes sure all standards for packages are met :param package: Package to check :param warnings: Print warnings if None or return them in the given list :raises InvalidPackage: in case validation fails

version

version_abi

class catkin_pkg.package.Person(name, email=None)

Bases: object

email

name

validate()

class catkin_pkg.package.Url(url, type_=None)

Bases: object

type

url

catkin_pkg.package.package_exists_at(path)

Checks that a package exists at the given path

Parameters:path (str) – path to a package Returns:True if package exists in given path, else False Return type:bool

catkin_pkg.package.parse_package(path, warnings=None)

Parse package manifest.

Parameters:

• path – The path of the package.xml file, it may or may not include the filename
• warnings – Print warnings if None or return them in the given list

Returns:

return Package instance, populated with parsed fields

Raises :

InvalidPackage

Raises :

IOError

catkin_pkg.package.parse_package_for_distutils(path=None)

catkin_pkg.package.parse_package_string(data, filename=None, warnings=None)

Parse package.xml string contents.

Parameters:

• data – package.xml contents, str
• filename – full file path for debugging, str
• warnings – Print warnings if None or return them in the given list

Returns:

return parsed Package

Raises :

InvalidPackage

package_templates Module

class catkin_pkg.package_templates.CatkinTemplate(template)

Bases: string.Template

subclass to use @ instead of $ as markers

delimiter = '@'

escape = '@'

pattern = <_sre.SRE_Pattern object at 0x21fec40>

class catkin_pkg.package_templates.PackageTemplate(catkin_deps=None, system_deps=None, boost_comps=None, **kwargs)

Bases: catkin_pkg.package.Package

catkin_pkg.package_templates.create_cmakelists(package_template, rosdistro, meta=False)

Parameters:package_template – contains the required information Returns:file contents as string

catkin_pkg.package_templates.create_package_files(target_path, package_template, rosdistro, newfiles=None, meta=False)

creates several files from templates to start a new package.

Parameters:

• target_path – parent folder where to create the package
• package_template – contains the required information
• rosdistro – name of the distro to look up respective template
• newfiles – dict {filepath: contents} for additional files to write

catkin_pkg.package_templates.create_package_xml(package_template, rosdistro, meta=False)

Parameters:package_template – contains the required information Returns:file contents as string

catkin_pkg.package_templates.read_template_file(filename, rosdistro)

package_version Module

catkin_pkg.package_version.bump_version(version, bump='patch')

Increases version number.

Parameters:

• version – str, must be in version format “int.int.int”
• bump – str, one of ‘patch, minor, major’

Returns:

version with the given part increased, and all inferior parts reset to 0

Raises ValueError:  

if the version string is not in the format x.y.z

packages Module

Library to find packages in the filesystem.

catkin_pkg.packages.find_package_paths(basepath, exclude_paths=None, exclude_subspaces=False)

Crawls the filesystem to find package manifest files.

When a subfolder contains a file CATKIN_IGNORE it is ignored.

Parameters:

• basepath – The path to search in, str
• exclude_paths – A list of paths which should not be searched, list
• exclude_subspaces – The flag is subfolders containing a .catkin file should not be searched, bool

Returns:

A list of relative paths containing package manifest files list

catkin_pkg.packages.find_packages(basepath, exclude_paths=None, exclude_subspaces=False, warnings=None)

Crawls the filesystem to find package manifest files and parses them.

Parameters:

• basepath – The path to search in, str
• exclude_paths – A list of paths which should not be searched, list
• exclude_subspaces – The flag is subfolders containing a .catkin file should not be searched, bool
• warnings – Print warnings if None or return them in the given list

Returns:

A dict mapping relative paths to Package objects dict

Raises :

:exc:RuntimeError` If multiple packages have the same name

catkin_pkg.packages.find_packages_allowing_duplicates(basepath, exclude_paths=None, exclude_subspaces=False, warnings=None)

Crawls the filesystem to find package manifest files and parses them.

Parameters:

• basepath – The path to search in, str
• exclude_paths – A list of paths which should not be searched, list
• exclude_subspaces – The flag is subfolders containing a .catkin file should not be searched, bool
• warnings – Print warnings if None or return them in the given list

Returns:

A dict mapping relative paths to Package objects dict

catkin_pkg.packages.verify_equal_package_versions(packages)

Verifies that all packages have the same version number.

Parameters:packages – The list of Package objects, list Returns:The version number Raises ::exc:RuntimeError` If the version is not equal in all packages

python_setup Module

Library for providing the relevant information from the package manifest for the Python setup.py file.

catkin_pkg.python_setup.generate_distutils_setup(package_xml_path='.', **kwargs)

Extract the information relevant for distutils from the package manifest. The following keys will be set:

The “name” and “version” are taken from the eponymous tags.

A single maintainer will set the keys “maintainer” and “maintainer_email” while multiple maintainers are merged into the “maintainer” fields (including their emails). Authors are handled likewise.

The first URL of type “website” (or without a type) is used for the “url” field.

The “description” is taken from the eponymous tag if it does not exceed 200 characters. If it does “description” contains the truncated text while “description_long” contains the complete.

All licenses are merged into the “license” field.

Parameters:kwargs – All keyword arguments are passed through. The above mentioned keys are verified to be identical if passed as a keyword argument Returns:return dict populated with parsed fields and passed keyword arguments Raises :InvalidPackage Raises :IOError

catkin_pkg.python_setup.get_global_bin_destination()

catkin_pkg.python_setup.get_global_etc_destination()

catkin_pkg.python_setup.get_global_include_destination()

catkin_pkg.python_setup.get_global_lib_destination()

catkin_pkg.python_setup.get_global_libexec_destination()

catkin_pkg.python_setup.get_global_python_destination()

catkin_pkg.python_setup.get_global_share_destination()

catkin_pkg.python_setup.get_package_bin_destination(pkgname)

catkin_pkg.python_setup.get_package_etc_destination(pkgname)

catkin_pkg.python_setup.get_package_include_destination(pkgname)

catkin_pkg.python_setup.get_package_lib_destination(_pkgname)

catkin_pkg.python_setup.get_package_python_destination(pkgname)

catkin_pkg.python_setup.get_package_share_destination(pkgname)

rospack Module

API provided for rospack to reorder include/library paths according to the chained workspaces

catkin_pkg.rospack.reorder_paths(paths)

topological_order Module

catkin_pkg.topological_order.topological_order(root_dir, whitelisted=None, blacklisted=None, underlay_workspaces=None)

Crawls the filesystem to find packages and uses their dependencies to return a topologically order list.

Parameters:

• root_dir – The path to search in, str
• whitelisted – A list of whitelisted package names, list
• blacklisted – A list of blacklisted package names, list
• underlay_workspaces – A list of underlay workspaces of packages which might provide dependencies in case of partial workspaces, list

Returns:

A list of tuples containing the relative path and a Package object, list

catkin_pkg.topological_order.topological_order_packages(packages, whitelisted=None, blacklisted=None, underlay_packages=None)

Topologically orders packages. First returning packages which have message generators and then the rest based on direct build-/buildtool_depends and indirect recursive run_depends.

Parameters:

• packages – A dict mapping relative paths to Package objects dict
• whitelisted – A list of whitelisted package names, list
• blacklisted – A list of blacklisted package names, list
• underlay_packages – A dict mapping relative paths to Package objects dict

Returns:

A list of tuples containing the relative path and a Package object, list

workspaces Module

Library to provided logic for chained workspaces

catkin_pkg.workspaces.ensure_workspace_marker(base_path)

creates workspace marker file at path if not existing

Parameters:path – target folder

catkin_pkg.workspaces.get_spaces(paths=None)

Return a list of spaces based on the CMAKE_PREFIX_PATH or passed in list of workspaces. It resolves the source space for each devel space and ignores non-catkin paths. :param paths_to_order: list of paths :param prefix_paths: list of prefixes, must not end with ‘/’

catkin_pkg.workspaces.order_paths(paths_to_order, prefix_paths)

Return a list containing all items of paths_to_order ordered by list of prefix_paths, compared as strings :param paths_to_order: list of paths :param prefix_paths: list of prefixes, must not end with ‘/’