# colcon-poetry-ros
An extension for [colcon-core][colcon-core] that adds support for Python
packages that use [Poetry][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][colcon-ros].
We use this extension with Humble, but other versions should work as well.
Please create an issue if you see problems!
[colcon-core]: https://github.com/colcon/colcon-core
[poetry]: https://python-poetry.org/
[colcon-ros]: https://github.com/colcon/colcon-ros
## Getting Started
1. [Install Poetry][installing poetry] and the
[Poetry Bundle plugin][installing poetry bundle], if you haven't already.
2. Install this extension with Pip:
```bash
pip3 install colcon-poetry-ros
```
3. 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:
```toml
[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"
[tool.poetry.scripts]
node_a = "my_package.node_a:main"
node_b = "my_package.node_b:main"
[tool.colcon-poetry-ros.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"
```
4. Install your packages' Python dependencies using a script included with
this plugin:
```bash
python3 -m colcon_poetry_ros.dependencies.install --base-paths <path to your nodes>
```
5. Finally, run your build like normal:
```bash
colcon build
```
## Testing
This extension currently supports projects based on PyTest. Run the following
command to start tests:
```bash
colcon test
```
## 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][poetry-scripts] for details.
```toml
[tool.poetry.scripts]
node_a = "my_package.node_a:main"
node_b = "my_package.node_b:main"
```
[poetry-scripts]: https://python-poetry.org/docs/pyproject/#scripts
## 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-ros.data-files`.
The format is intended to be mostly identical to the `data_files` field used
by [setuptools][setuptools-data-files]. The main differences are that copying
entire directories is supported, and globbing is not yet implemented.
All ROS packages must have, at minimum, these entries in the
`tool.colcon-poetry-ros.data-files` section (with `{package_name}` replaced
with the name of your package):
```toml
[tool.colcon-poetry-ros.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.
[setuptools-data-files]: https://setuptools.pypa.io/en/latest/userguide/datafiles.html
## Python Dependency Details
Poetry dependencies are not installed as part of the build process, so they
must be installed using a separate tool that's included in this package.
```bash
python3 -m colcon_poetry_ros.dependencies.install --base-paths <path to your nodes>
```
This command creates a virtual environment within Colcon's base install
directory, then installs each package's dependencies in that virtual
environment.
If you customize `colcon build` with the `--install-base` or `--merge-install`
flags, make sure to provide those to this tool as well.
We split dependency installation out of `colcon build` to make development
iterations faster. Third-party dependencies change less frequency than first
party code, so it's often a waste of time to resolve dependencies on every
iteration. This is especially elegant in container-based workflows, an example
of which can be found in the `examples/` directory.
## Communicating Package Dependencies to Colcon
Colcon can be given information on dependencies between packages, which
affects build order and can be displayed in tools like `colcon graph`. These
dependencies can be explicitly defined in the `pyproject.toml` under a custom
section called `tool.colcon-poetry-ros.dependencies`.
```toml
[tool.colcon-poetry-ros.dependencies]
depend = ["foo_package"] # This will add to both `build_depend` and `exec_depend` following `package.xml` standards
build_depend = ["bar_package"]
exec_depend = ["baz_package"]
test_depend = ["qux_package"]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/UrbanMachine/colcon-poetry-ros",
"name": "colcon-poetry-ros",
"maintainer": "Urban Machine",
"docs_url": null,
"requires_python": null,
"maintainer_email": "info@urbanmachine.build",
"keywords": "colcon",
"author": "Urban Machine",
"author_email": "info@urbanmachine.build",
"download_url": "https://files.pythonhosted.org/packages/c4/39/41ebb8e0615ec67181cbd404252e64332bb9449f65b79aac9898f18038a1/colcon_poetry_ros-0.9.0.tar.gz",
"platform": null,
"description": "# colcon-poetry-ros\n\nAn extension for [colcon-core][colcon-core] that adds support for Python\npackages that use [Poetry][poetry] within ROS. This extension is a replacement\nfor Colcon's built-in `setup.cfg` based Python support and the Python-related\nbits in [colcon-ros][colcon-ros].\n\nWe use this extension with Humble, but other versions should work as well.\nPlease create an issue if you see problems!\n\n[colcon-core]: https://github.com/colcon/colcon-core\n[poetry]: https://python-poetry.org/\n[colcon-ros]: https://github.com/colcon/colcon-ros\n\n## Getting Started\n\n1. [Install Poetry][installing poetry] and the\n [Poetry Bundle plugin][installing poetry bundle], if you haven't already.\n\n2. Install this extension with Pip:\n\n ```bash\n pip3 install colcon-poetry-ros\n ```\n\n3. Add a `pyproject.toml` in the root of your package's directory. Each\n package should have its own `pyproject.toml` file. It should look something\n like this:\n\n ```toml\n [tool.poetry]\n name = \"my_package\"\n version = \"0.1.0\"\n description = \"Does something cool\"\n authors = [\"John Smith <johnny@urbanmachine.build>\"]\n license = \"BSD-3-Clause\"\n\n [tool.poetry.dependencies]\n python = \"^3.8\"\n\n [tool.poetry.scripts]\n node_a = \"my_package.node_a:main\"\n node_b = \"my_package.node_b:main\"\n\n [tool.colcon-poetry-ros.data-files]\n \"share/ament_index/resource_index/packages\" = [\"resource/my_package\"]\n \"share/my_package\" = [\"package.xml\"]\n\n [build-system]\n requires = [\"poetry-core>=1.0.0\"]\n build-backend = \"poetry.core.masonry.api\"\n ```\n\n4. Install your packages' Python dependencies using a script included with\n this plugin:\n\n ```bash\n python3 -m colcon_poetry_ros.dependencies.install --base-paths <path to your nodes>\n ```\n\n5. Finally, run your build like normal:\n\n ```bash\n colcon build\n ```\n\n## Testing\n\nThis extension currently supports projects based on PyTest. Run the following\ncommand to start tests:\n\n```bash\ncolcon test\n```\n\n## Node Entrypoints\n\nIf you want to be able to run your nodes using `ros2 run`, add your node's\nentrypoint to the `tool.poetry.scripts` table. See\n[Poetry's documentation][poetry-scripts] for details.\n\n```toml\n[tool.poetry.scripts]\nnode_a = \"my_package.node_a:main\"\nnode_b = \"my_package.node_b:main\"\n```\n\n[poetry-scripts]: https://python-poetry.org/docs/pyproject/#scripts\n\n## Data Files\n\nPoetry has only limited support for including data files in an installation,\nand the current implementation is not flexible enough to be used with ROS.\nInstead, this extension consults a custom section in your `pyproject.toml`,\ncalled `tool.colcon-poetry-ros.data-files`.\n\nThe format is intended to be mostly identical to the `data_files` field used\nby [setuptools][setuptools-data-files]. The main differences are that copying\nentire directories is supported, and globbing is not yet implemented.\n\nAll ROS packages must have, at minimum, these entries in the\n`tool.colcon-poetry-ros.data-files` section (with `{package_name}` replaced\nwith the name of your package):\n\n```toml\n[tool.colcon-poetry-ros.data-files]\n\"share/ament_index/resource_index/packages\" = [\"resource/{package_name}\"]\n\"share/{package_name}\" = [\"package.xml\"]\n```\n\nThese entries take care of adding the package index marker and `package.xml`\nfile to the installation.\n\n[setuptools-data-files]: https://setuptools.pypa.io/en/latest/userguide/datafiles.html\n\n## Python Dependency Details\n\nPoetry dependencies are not installed as part of the build process, so they\nmust be installed using a separate tool that's included in this package.\n\n```bash\npython3 -m colcon_poetry_ros.dependencies.install --base-paths <path to your nodes>\n```\n\nThis command creates a virtual environment within Colcon's base install\ndirectory, then installs each package's dependencies in that virtual\nenvironment.\n\nIf you customize `colcon build` with the `--install-base` or `--merge-install`\nflags, make sure to provide those to this tool as well.\n\nWe split dependency installation out of `colcon build` to make development\niterations faster. Third-party dependencies change less frequency than first\nparty code, so it's often a waste of time to resolve dependencies on every\niteration. This is especially elegant in container-based workflows, an example\nof which can be found in the `examples/` directory.\n\n## Communicating Package Dependencies to Colcon\n\nColcon can be given information on dependencies between packages, which\naffects build order and can be displayed in tools like `colcon graph`. These\ndependencies can be explicitly defined in the `pyproject.toml` under a custom\nsection called `tool.colcon-poetry-ros.dependencies`.\n\n```toml\n[tool.colcon-poetry-ros.dependencies]\ndepend = [\"foo_package\"] # This will add to both `build_depend` and `exec_depend` following `package.xml` standards\nbuild_depend = [\"bar_package\"]\nexec_depend = [\"baz_package\"]\ntest_depend = [\"qux_package\"]\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Colcon extension providing support for Python projects that use Poetry",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/UrbanMachine/colcon-poetry-ros"
},
"split_keywords": [
"colcon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "843437c0e11b0963700fee9527f8836f1fca305196a35af3ff62b99b3c23a1ce",
"md5": "6951a046d890492d167919e308cb9a1d",
"sha256": "e6dbf51e440f34efb59a90503f6bb67556d0109720a653a0001339e058eb1127"
},
"downloads": -1,
"filename": "colcon_poetry_ros-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6951a046d890492d167919e308cb9a1d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16412,
"upload_time": "2024-11-12T00:48:10",
"upload_time_iso_8601": "2024-11-12T00:48:10.264402Z",
"url": "https://files.pythonhosted.org/packages/84/34/37c0e11b0963700fee9527f8836f1fca305196a35af3ff62b99b3c23a1ce/colcon_poetry_ros-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c43941ebb8e0615ec67181cbd404252e64332bb9449f65b79aac9898f18038a1",
"md5": "295b1b15ba7c91ea9680644e182fb09d",
"sha256": "8821ff6f17dbf5e349d33210d8603cda515a54b656f7d22ec88a7403f7f79366"
},
"downloads": -1,
"filename": "colcon_poetry_ros-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "295b1b15ba7c91ea9680644e182fb09d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14498,
"upload_time": "2024-11-12T00:48:11",
"upload_time_iso_8601": "2024-11-12T00:48:11.847586Z",
"url": "https://files.pythonhosted.org/packages/c4/39/41ebb8e0615ec67181cbd404252e64332bb9449f65b79aac9898f18038a1/colcon_poetry_ros-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 00:48:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "UrbanMachine",
"github_project": "colcon-poetry-ros",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "colcon-poetry-ros"
}
JSON
