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.escape_trailing_underscores(line)

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, skip_merges=False)

catkin_pkg.changelog_generator.get_forthcoming_changes(vcs_client, skip_merges=False)

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, skip_merges=False)

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, skip_merges=False)

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, skip_merges=False)

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 0x37a8800>

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)

tool_detection Module

Common functions that can be used to mark spaces, e.g. build and devel, to indicate which tools previously built the space. This allows the tools to detect cross tool talk and avoid it where appropriate.

catkin_pkg.tool_detection.get_previous_tool_used_on_the_space(space_path)

Return the tool used to build the space at the given path, or None.

Returns None if the path does not exist or if there is no built by file.

Parameters:space_path (str) – path to the space in question. Returns:str identifying the tool used to build the space or None.

catkin_pkg.tool_detection.mark_space_as_built_by(space_path, tool_name)

Place a marker file in the space at the given path, telling who built it.

The path to the marker is created if necessary.

Parameters:

• space_path (str) – path to the space which should be marked.
• tool_name (str) – name of the tool doing the marking.

Raises :

OSError, others, when trying to create the folder.

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 ‘/’