colcon-python-setup-py

0.2.9 · active · verified Fri Apr 17

colcon-python-setup-py is an extension for the colcon build system that enables it to properly discover, configure, and build Python packages that define their metadata using a `setup.py` file. It ensures `colcon` can correctly handle Python packages, resolve their dependencies, and integrate them into a larger workspace. The current version is 0.2.9, with active development and infrequent but stable releases, typically every 3-9 months.

Common errors

```
colcon: command not found
```
cause The `colcon-core` package, which provides the `colcon` executable, is not installed or not in your PATH.

fix Install `colcon-core`: `pip install colcon-core`.
```
Could not find a build type for the package 'your_package_name'
```
cause colcon could not detect a `setup.py` file, or there's a conflict with another build type, or the `colcon-python-setup-py` extension is not installed.

fix Verify that `colcon-python-setup-py` is installed (`pip show colcon-python-setup-py`). Ensure your package's `setup.py` file is correctly located at the root of your package directory within the `src` folder. Check for typos or incorrect file permissions.
```
ModuleNotFoundError: No module named 'your_dependency_name' during colcon build
```
cause A Python dependency required by your package is not specified in `install_requires` within your `setup.py`, or it failed to install during the colcon build process (often due to missing system dependencies or conflicts).

fix Add the missing dependency to the `install_requires` list in your `setup.py`. If it's a system dependency, ensure it's installed on your system. If the package has complex build steps, consider adding a custom `build` hook if necessary.

Warnings

gotcha This extension explicitly targets Python packages using `setup.py` for metadata. If your Python package uses `pyproject.toml` (e.g., with Poetry, Hatch, or modern setuptools build backends), this extension will not be used. colcon might try to use a different build type, or you may need another colcon extension like `colcon-python-poetry`.
Fix: Ensure your package has a `setup.py` file. If migrating to `pyproject.toml`, consider other `colcon` extensions or ensure `pyproject.toml` delegates to `setup.py` or uses a compatible build backend.
gotcha The `colcon-python-setup-py` package is an extension and requires the `colcon-core` package to be installed separately. It will not function on its own without the core `colcon` CLI tool.
Fix: Before installing or using `colcon-python-setup-py`, make sure `colcon-core` is installed: `pip install colcon-core`.
gotcha Issues within the `setup.py` file itself (e.g., incorrect `install_requires`, malformed `entry_points`, missing `find_packages()`) can lead to build failures or runtime errors. Debugging these requires understanding `setuptools`.
Fix: Carefully review your `setup.py` according to `setuptools` documentation. Use `python setup.py install --prefix /tmp/test_install` to test the `setup.py` in isolation.

Install

pip install colcon-python-setup-py Install colcon-python-setup-py

Quickstart

This quickstart demonstrates how to set up a `colcon` workspace, create a basic Python package with a `setup.py` file, and then use `colcon build` to compile and install it. The `colcon-python-setup-py` extension automatically detects the `setup.py` file and uses it to build the package.

# First, install colcon-core if you haven't already:
# pip install colcon-core

# Then, install the python setup.py extension:
# pip install colcon-python-setup-py

# 1. Create a colcon workspace and source directory
mkdir -p colcon_ws/src
cd colcon_ws/src

# 2. Create a simple Python package with setup.py
mkdir my_python_pkg
cd my_python_pkg

# Create setup.py
cat <<EOF > setup.py
from setuptools import setup, find_packages

setup(
    name='my_python_pkg',
    version='0.0.1',
    packages=find_packages(),
    install_requires=[],
    zip_safe=True,
    maintainer='Your Name',
    maintainer_email='your.email@example.com',
    description='A sample Python package for colcon.',
    license='Apache-2.0',
)
EOF

# Create a simple Python module
mkdir my_python_pkg
cat <<EOF > my_python_pkg/__init__.py
def hello_world():
    return "Hello from colcon-python-setup-py!"
EOF

# 3. Go back to the workspace root and build
cd ../..
colcon build

echo "\nBuild complete. Check 'colcon_ws/install' for the installed package."

view raw JSON →