catkin_pkg package¶
Subpackages¶
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 string - date –
datetime.datetime
version date - contents –
list(list([str|Reference]))`
contents as a list of lists which contain a combination ofstr
andReference
objects
Returns: None
- version –
-
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 reversedReturns: generator
for iterating over versions, dates and content
-
get_content_of_version
(version)[source]¶ Return changelog content for a given version.
Parameters: version – str
versionReturns: list(list([str|Reference]))
content expanded
-
package_name
¶
-
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 processed - bullet_type –
str
either ‘bullet’ or ‘enumerated’
Returns: BulletList
object representing a docutils bullet_list- 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.rst - package_name –
str
the package name
Returns: Changelog
changelog class or None if file was not readable- path –
-
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-ishReturns: 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 populated - rst –
str
raw ReST changelog
Returns: Changelog
changelog that was populated- changelog –
-
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 populated - section –
docutils.nodes.section
section to be processed
Returns: Changelog
changelog that was populated- changelog –
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:
catkin_pkg.changelog_generator_vcs.VcsClientBase
-
type
= 'git'¶
-
-
class
catkin_pkg.changelog_generator_vcs.
HgClient
(path)[source]¶ Bases:
catkin_pkg.changelog_generator_vcs.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
- template_file – path to the template,
-
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
- template – the template,
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.
-
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: InvalidPackage
-
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
¶
-
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 fieldsRaises: 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: - data – package.xml contents,
catkin_pkg.package_templates module¶
-
class
catkin_pkg.package_templates.
CatkinTemplate
(template)[source]¶ Bases:
string.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 {(?P<braced>(?a:[_a-z][_a-z0-9]*)), re.IGNORECASE|re.VERBOSE)¶
-
-
class
catkin_pkg.package_templates.
PackageTemplate
(catkin_deps=None, system_deps=None, boost_comps=None, **kwargs)[source]¶ Bases:
catkin_pkg.package.Package
-
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
(paths, new_version)[source]¶ Bulk replace of version: searches for package.xml files directly in given folders and replaces version tag within.
Parameters: - paths (list) – folder names
- 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)[source]¶ Crawls the filesystem to find package manifest files.
When a subfolder contains either of the following files it is ignored: -
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
Returns: A list of relative paths containing package manifest files
list
- basepath – The path to search in,
-
catkin_pkg.packages.
find_packages
(basepath, exclude_paths=None, exclude_subspaces=False, warnings=None)[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
Returns: A dict mapping relative paths to
Package
objectsdict
Raises: :exc:RuntimeError` If multiple packages have the same name
- basepath – The path to search in,
-
catkin_pkg.packages.
find_packages_allowing_duplicates
(basepath, exclude_paths=None, exclude_subspaces=False, warnings=None)[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
Returns: A dict mapping relative paths to
Package
objectsdict
- basepath – The path to search in,
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. 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.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:
string.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 {(?P<braced>(?a:[_a-z][_a-z0-9]*)), 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
- root_dir – The path to search in,
-
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
- packages – A dict mapping relative paths to
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.