catkin_pkg package¶
Subpackages¶
- catkin_pkg.cli package
Submodules¶
catkin_pkg.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)[source]¶
Bases:
object
Represent a bulleted list of text.
- class catkin_pkg.changelog.Changelog(package_name=None)[source]¶
Bases:
object
Represents a REP-0132 changelog.
- add_version_section(version, date, contents)[source]¶
Add a version section.
- Parameters:
version –
str
version as a stringdate –
datetime.datetime
version datecontents –
list(list([str|Reference]))`
contents as a list of lists which contain a combination ofstr
andReference
objects
- Returns:
None
- foreach_version(reverse=False)[source]¶
Create 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)[source]¶
Return changelog content for a given version.
- Parameters:
version –
str
version- Returns:
list(list([str|Reference]))
content expanded
- property package_name¶
- property rst¶
- exception catkin_pkg.changelog.DuplicateVersionsException(version)[source]¶
Bases:
Exception
Raised when more than one section per version is given.
- exception catkin_pkg.changelog.InvalidSectionTitle(title)[source]¶
Bases:
Exception
raised on non REP-0132 section titles.
- class catkin_pkg.changelog.MixedText(texts=[])[source]¶
Bases:
object
Represents text mixed with references and nested bullets.
- class catkin_pkg.changelog.Reference(text, link)[source]¶
Bases:
object
Represents a piece of text with an associated link.
- class catkin_pkg.changelog.Transition[source]¶
Bases:
object
Represents a trasition element from ReST.
- catkin_pkg.changelog.bullet_list_class_from_docutils(bullet_list, bullet_type=None)[source]¶
Process elements of bullet list into an encapsulating class.
- Parameters:
bullet_list –
docutils.nodes.bullet_list
list to be processedbullet_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)[source]¶
Changelog factory, which reads a changelog file into a class.
- Parameters:
path –
str
the path of the changelog including or excluding the filename CHANGELOG.rstpackage_name –
str
the package name
- Returns:
Changelog
changelog class or None if file was not readable
- catkin_pkg.changelog.mixed_text_from_docutils(node)[source]¶
Take 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)[source]¶
Changelog factory, which converts the raw ReST into a class.
- Parameters:
changelog –
Changelog
changelog to be populatedrst –
str
raw ReST changelog
- Returns:
Changelog
changelog that was populated
- catkin_pkg.changelog.processes_changelog_children(changelog, children)[source]¶
Process 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 populatedsection –
docutils.nodes.section
section to be processed
- Returns:
Changelog
changelog that was populated
catkin_pkg.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.generate_changelog_file(pkg_name, tag2log_entries, vcs_client=None, skip_contributors=False)[source]¶
- catkin_pkg.changelog_generator.generate_changelogs(base_path, packages, tag2log_entries, logger=None, vcs_client=None, skip_contributors=False)[source]¶
- catkin_pkg.changelog_generator.generate_version_block(version, timestamp, log_entries, vcs_client=None, skip_contributors=False)[source]¶
- catkin_pkg.changelog_generator.generate_version_content(log_entries, vcs_client=None, skip_contributors=False)[source]¶
- catkin_pkg.changelog_generator.get_all_changes(vcs_client, skip_merges=False, only_merges=False)[source]¶
- catkin_pkg.changelog_generator.get_forthcoming_changes(vcs_client, skip_merges=False, only_merges=False)[source]¶
- catkin_pkg.changelog_generator.update_changelog_file(data, tag2log_entries, vcs_client=None, skip_contributors=False)[source]¶
catkin_pkg.changelog_generator_vcs module¶
Extract log information from repositories.
- class catkin_pkg.changelog_generator_vcs.GitClient(path)[source]¶
Bases:
VcsClientBase
- type = 'git'¶
- class catkin_pkg.changelog_generator_vcs.HgClient(path)[source]¶
Bases:
VcsClientBase
- type = 'hg'¶
- class catkin_pkg.changelog_generator_vcs.LogEntry(msg, affected_paths, author)[source]¶
Bases:
object
catkin_pkg.cmake module¶
- catkin_pkg.cmake.configure_file(template_file, environment)[source]¶
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)[source]¶
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.condition module¶
catkin_pkg.group_dependency module¶
- class catkin_pkg.group_dependency.GroupDependency(name, condition=None, members=None)[source]¶
Bases:
object
- condition¶
- evaluate_condition(context)[source]¶
Evaluate the condition.
The result is also stored in the member variable evaluated_condition.
- Parameters:
context – A dictionary with key value pairs to replace variables starting with $ in the condition.
- Returns:
True if the condition evaluates to True, else False
- Raises:
ValueError
if the condition fails to parse
- evaluated_condition¶
- members¶
- name¶
catkin_pkg.group_membership module¶
- class catkin_pkg.group_membership.GroupMembership(name, condition=None)[source]¶
Bases:
object
- condition¶
- evaluate_condition(context)[source]¶
Evaluate the condition.
The result is also stored in the member variable evaluated_condition.
- Parameters:
context – A dictionary with key value pairs to replace variables starting with $ in the condition.
- Returns:
True if the condition evaluates to True, else False
- Raises:
ValueError
if the condition fails to parse
- evaluated_condition¶
- name¶
catkin_pkg.metapackage module¶
Checks metapackages for compliance with REP-0127.
Reference: http://ros.org/reps/rep-0127.html#metapackage
- catkin_pkg.metapackage.get_cmakelists_txt(path)[source]¶
Fetch 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)[source]¶
Return 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)[source]¶
Return 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)[source]¶
Return 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)[source]¶
Validate 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
catkin_pkg.package module¶
Library for parsing package.xml and providing an object representation.
- class catkin_pkg.package.Dependency(name, **kwargs)[source]¶
Bases:
object
- condition¶
- evaluate_condition(context)[source]¶
Evaluate the condition.
The result is also stored in the member variable evaluated_condition.
- Parameters:
context – A dictionary with key value pairs to replace variables starting with $ in the condition.
- Returns:
True if the condition evaluates to True, else False
- Raises:
ValueError
if the condition fails to parse
- evaluated_condition¶
- name¶
- version_eq¶
- version_gt¶
- version_gte¶
- version_lt¶
- version_lte¶
- class catkin_pkg.package.Export(tagname, content=None)[source]¶
Bases:
object
- attributes¶
- content¶
- evaluate_condition(context)[source]¶
Evaluate the condition.
The result is also stored in the member variable evaluated_condition.
- Parameters:
context – A dictionary with key value pairs to replace variables starting with $ in the condition.
- Returns:
True if the condition evaluates to True, else False
- Raises:
ValueError
if the condition fails to parse
- evaluated_condition¶
- tagname¶
- class catkin_pkg.package.Package(filename=None, **kwargs)[source]¶
Bases:
object
Object representation of a package manifest file.
- authors¶
- build_depends¶
- build_export_depends¶
- buildtool_depends¶
- buildtool_export_depends¶
- conflicts¶
- description¶
- doc_depends¶
- evaluate_conditions(context)[source]¶
Evaluate the conditions of all dependencies and memberships.
- Parameters:
context – A dictionary with key value pairs to replace variables starting with $ in the condition.
- Raises:
ValueError
if any condition fails to parse
- exec_depends¶
- exports¶
- filename¶
- get_build_type()[source]¶
Return value of export/build_type element, or ‘catkin’ if unspecified.
- Returns:
package build type
- Return type:
str
- Raises:
- get_unconditional_build_types()[source]¶
Return values of export/build_type elements without conditional filtering, or [‘catkin’] if unspecified.
- Returns:
package build types
- Return type:
List[str]
- group_depends¶
- has_buildtool_depend_on_catkin()[source]¶
Return 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()[source]¶
Return 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()[source]¶
Return True if this pacakge is a metapackage, otherwise False.
- Returns:
True if metapackage, else False
- Return type:
bool
- licenses¶
- maintainers¶
- member_of_groups¶
- name¶
- package_format¶
- plaintext_description¶
- replaces¶
- test_depends¶
- urls¶
- validate(warnings=None)[source]¶
Make sure all standards for packages are met.
- Parameters:
package – Package to check
warnings – Print warnings if None or return them in the given list
- Raises:
InvalidPackage – in case validation fails
- version¶
- version_compatibility¶
- catkin_pkg.package.has_ros_schema_reference(path)[source]¶
Check if the XML file contains a processing instruction referencing a ROS package manifest schema.
- Parameters:
path (str) – The path of the package.xml file, it may or may not include the filename
- Returns:
True if it contains the known reference, else False
- Return type:
bool
- Raises:
IOError
- catkin_pkg.package.has_ros_schema_reference_string(data)[source]¶
Check if the XML data contains a processing instruction referencing a ROS package manifest schema.
- Parameters:
data (str) – package.xml contents
- Returns:
True if it contains the known reference, else False
- Return type:
bool
- catkin_pkg.package.package_exists_at(path)[source]¶
Check 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)[source]¶
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:
- Raises:
IOError
- catkin_pkg.package.parse_package_string(data, filename=None, warnings=None)[source]¶
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:
catkin_pkg.package_templates module¶
- class catkin_pkg.package_templates.CatkinTemplate(template)[source]¶
Bases:
Template
subclass to use @ instead of $ as markers.
- delimiter = '@'¶
- escape = '@'¶
- pattern = re.compile('\n @(?:\n (?P<escaped>@) | # Escape sequence of two delimiters\n (?P<named>(?a:[_a-z][_a-z0-9]*)) | # delimiter and a Python identifier\n , re.IGNORECASE|re.VERBOSE)¶
- class catkin_pkg.package_templates.PackageTemplate(catkin_deps=None, system_deps=None, boost_comps=None, **kwargs)[source]¶
Bases:
Package
- authors¶
- build_depends¶
- build_export_depends¶
- buildtool_depends¶
- buildtool_export_depends¶
- conflicts¶
- description¶
- doc_depends¶
- exec_depends¶
- exports¶
- filename¶
- group_depends¶
- licenses¶
- maintainers¶
- member_of_groups¶
- name¶
- package_format¶
- plaintext_description¶
- replaces¶
- test_depends¶
- urls¶
- version¶
- version_compatibility¶
- catkin_pkg.package_templates.create_cmakelists(package_template, rosdistro, meta=False)[source]¶
Create CMake file contents from the template.
- 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)[source]¶
Create 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_version module¶
- catkin_pkg.package_version.bump_version(version, bump='patch')[source]¶
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
- Return type:
str
- Raises:
ValueError – if the version string is not in the format x.y.z
- catkin_pkg.package_version.update_versions(packages, new_version)[source]¶
Bulk replace of version: searches for package.xml and setup.py files directly in given folders and replaces version tag within.
- Parameters:
packages (dict) – dict from folder names to package xml objects in those folders
new_version (str) – version string “int.int.int”
- Raises:
RuntimeError – if any one package.xml cannot be updated
catkin_pkg.packages module¶
Library to find packages in the filesystem.
- catkin_pkg.packages.find_package_paths(basepath, exclude_paths=None, exclude_subspaces=False, ignore_markers={'AMENT_IGNORE', 'CATKIN_IGNORE', 'COLCON_IGNORE'})[source]¶
Crawls the filesystem to find package manifest files.
When a subfolder contains either of the files mentioned in
ignore_markers
it is ignored. By default, these are: -AMENT_IGNORE
-CATKIN_IGNORE
-COLCON_IGNORE
- 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
ignore_markers – Names of files that indicate that a folder should be ignored,
set
- 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, ignore_markers={'AMENT_IGNORE', 'CATKIN_IGNORE', 'COLCON_IGNORE'})[source]¶
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,
bool
ignore_markers – Names of files that indicate that a folder should be ignored,
set
- Returns:
A dict mapping relative paths to
Package
objectsdict
- 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, ignore_markers={'AMENT_IGNORE', 'CATKIN_IGNORE', 'COLCON_IGNORE'})[source]¶
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
ignore_markers – Names of files that indicate that a folder should be ignored,
set
- Returns:
A dict mapping relative paths to
Package
objectsdict
catkin_pkg.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)[source]¶
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 and has no newlines. If it does “description” contains the truncated text while “long_description” 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.rospack module¶
API provided for rospack to reorder include/library paths according to the chained workspaces.
catkin_pkg.terminal_color module¶
Module to enable color terminal output.
- class catkin_pkg.terminal_color.ColorTemplate(template)[source]¶
Bases:
Template
- delimiter = '@'¶
- pattern = re.compile('\n @(?:\n (?P<escaped>@) | # Escape sequence of two delimiters\n (?P<named>(?a:[_a-z][_a-z0-9]*)) | # delimiter and a Python identifier\n , re.IGNORECASE|re.VERBOSE)¶
- catkin_pkg.terminal_color.disable_ANSI_colors()[source]¶
Set all the ANSI escape sequences to empty strings, effectively disabling console colors.
catkin_pkg.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)[source]¶
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)[source]¶
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.
catkin_pkg.topological_order module¶
- catkin_pkg.topological_order.topological_order(root_dir, whitelisted=None, blacklisted=None, underlay_workspaces=None)[source]¶
Crawls the filesystem to find packages and uses their dependencies to return a topologically order list.
When a circular dependency is detected, the last item in the returned list is a tuple with None and a string giving a superset of the guilty packages.
- 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)[source]¶
Topologically orders packages.
evaluate_conditions() will be called for each package.
If group dependencies haven’t determined their members yet extract_group_members() will be called for each group dependency to do so.
First returning packages which have message generators and then the rest based on direct build-/buildtool_depends and indirect recursive run_depends.
When a circular dependency is detected, the last item in the returned list is a tuple with None and a string giving a superset of the guilty packages.
- Parameters:
packages – A dict mapping relative paths to
Package
objectsdict
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
objectsdict
- Returns:
A list of tuples containing the relative path and a
Package
object,list
catkin_pkg.workspace_vcs module¶
catkin_pkg.workspaces module¶
Library to provided logic for chained workspaces.
- catkin_pkg.workspaces.ensure_workspace_marker(base_path)[source]¶
Create workspace marker file at path if not existing.
- Parameters:
path – target folder
- catkin_pkg.workspaces.get_spaces(paths=None)[source]¶
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 ‘/’
Module contents¶
Library for retrieving information about catkin packages.