colcon-poetry-ros

An extension for colcon-core that adds support for Python packages that use Poetry within ROS. This extension is a replacement for Colcon's built-in setup.cfg based Python support and the Python-related bits in colcon-ros.

We use this extension with Foxy, but newer versions should work as well. Please create an issue if you see problems!

Getting Started

Start by install this extension with Pip:

pip3 install colcon-poetry-ros

Then, add a pyproject.toml in the root of your package's directory. Each package should have its own pyproject.toml file. It should look something like this:

[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "Does something cool"
authors = ["John Smith <johnny@urbanmachine.build>"]
license = "BSD-3-Clause"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.26.0"
pytest = { version = "^6.2.5", optional = true }

[tool.poetry.dev-dependencies]
black = "^21.9b0"

[tool.poetry.extras]
test = ["pytest"]

[tool.poetry.scripts]
node_a = "my_package.node_a:main"
node_b = "my_package.node_b:main"

[tool.colcon-poetry.data-files]
"share/ament_index/resource_index/packages" = ["resource/my_package"]
"share/my_package" = ["package.xml"]

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Finally, run your build like normal:

colcon build

Node Entrypoints

If you want to be able to run your nodes using ros2 run, add your node's entrypoint to the tool.poetry.scripts table. See Poetry's documentation for details.

[tool.poetry.scripts]
node_a = "my_package.node_a:main"
node_b = "my_package.node_b:main"

Defining Dependencies

Build Dependencies

This extension uses the requires field in the build-system table to source build dependencies. See the section in PEP 518 for details. This section may only be necessary if you're using a compiler like Cython that runs during package installation. Since these packages are not locked by Poetry, the version specifications in the requires field will be passed to ROS as-is.

Runtime Dependencies

Runtime dependencies are pulled from the tool.poetry.dependencies table. See Poetry's documentation for details. Dependency versions are defined by the poetry.lock file.

You can include extras by setting the POETRY_RUN_DEPENDS_EXTRAS environment variable. Multiple extras can be provided and are separated by commas. By default, no extras are included.

Test Dependencies

Poetry currently has no official way of defining test dependencies, so test dependencies are instead expected to be in an extra called "test". Dependency versions are defined by the poetry.lock file.

You can change which extras are used for test dependencies by setting the POETRY_TEST_DEPENDS_EXTRAS environment variable. Multiple extras can be provided and are separated by commas. As mentioned above, this value is set to "test" by default.

Data Files

Poetry has only limited support for including data files in an installation, and the current implementation is not flexible enough to be used with ROS. Instead, this extension consults a custom section in your pyproject.toml, called tool.colcon-poetry.data-files.

The format is intended to be identical to the data_files field used by setuptools.

All ROS projects must have, at minimum, these entries in the tool.colcon-poetry.data-files section (with {package_name} replaced with the name of your package):

[tool.colcon-poetry.data-files]
"share/ament_index/resource_index/packages" = ["resource/{package_name}"]
"share/{package_name}" = ["package.xml"]

These entries take care of adding the package index marker and package.xml file to the installation.

Testing

This extension currently supports projects based on PyTest. Run the following command to start tests:

colcon test