With catkin

The loader method of accessing Python code in ROS is obsolete if you are using catkin. When using catkin, the Python code for all packages will be on the PYTHONPATH after sourcing the setup file for your workspace.

With rosbuild

roslib is the only ROS Python package you can automatically assume to be importable other than your local files. If your Python package has dependencies, you must include the following header at the top:

import roslib
roslib.load_manifest('your_package_name')

roslib.load_manifest looks at your manifest.xml and places your dependencies on your Python path. DO NOT use multiple load_manifest calls. If you need multiple calls, it's probably because you're missing the correct dependencies in your manifest.

With catkin

When using catkin you can organize your Python code in any way that you like, but you must inform Python's setuptools where your code is located by creating a setup.py file. The recommended layout is to put all of your package's importable Python code in the src folder of your package and in a "Python package" with the same name as your package. In this case a "Python package" is a folder which contains a __init__.py file, indicating that the folder contains additional Python packages and modules.

Here is the recommended layout of an example catkin package called my_package which contains Python code:

my_package
├── CMakeLists.txt
├── package.xml
├── setup.py
└── src
    └── my_package
        ├── __init__.py
        ├── a_nested_python_package
        │   └── __init__.py
        └── a_python_module.py

In this example there is a root Python package in the src folder called my_package, which follows the recommendation. This root Python package then contains a Python module called a_python_module and a nested Python package called a_nested_python_package.

In this example the setup.py will use the convenience function generate_distutils_setup, which is provided by catkin, in order to extract information like the version and description from the package's manifest file, i.e. the package.xml:

from distutils.core import setup
from catkin_pkg.python_setup import generate_distutils_setup

d = generate_distutils_setup(
    packages=['my_package', 'my_package.a_nested_python_package'],
    package_dir={'': 'src'},
)

setup(**d)

Note that the packages parameter points to all Python packages which should be installed, even the nested one. Also note the package_dir parameter indicates that all aforementioned packages are located in the src folder by using the empty string as a key. This standard boiler plate configuration for Python packages allows you to place your Python code anywhere you like within your package and follows the Python setuptools conventions.

If your package contains messages or services then they will generate code into a Python package called msgs or srvs in the root of your package's "Python package", e.g. my_package/msgs or my_package/srvs. Though this generated code does not go into your package's source code, it does get merged with your package's Python source when getting installed. This is a new mechanism introduced with catkin because catkin installs into a FHS [5] layout, whereas rosbuild did not have an install step.

Your package shares a global PYTHONPATH namespace with other packages (system Python packages as well as ROS packages with Python code), so be considerate when creating Python packages at the root of your package's src folder as they can collide with others.

catkin_install_python(PROGRAMS nodes/my_node
  DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

from distutils.core import setup
from catkin_pkg.python_setup import generate_distutils_setup

d = generate_distutils_setup(
    scripts=['scripts/my_script'],
    ...
)

setup(**d)

With rosbuild

All python code must be placed within a module namespace. ROS exports your Python source directory to be on the path of any of your dependents (packages which depend on you), so it is important not to accidentally clobber someone else's import. We strongly recommend that this module name be the same as your ROS package name.

There are two recommended code layouts:

Small modules with no msg/srvs:

packagename
 |- nodes/
    |- ROS node executable files
 |- src/
    |- packagename.py
 |- scripts/
    |- non-exported python files

Module with msgs/srvs:

packagename
 |- nodes/
    |- ROS node executable files
 |- src/
    |- packagename/
      |- __init__.py
      |- yourfiles.py
 |- scripts/
    |- non-exported python files

We distinguish between "nodes" and "scripts" for clarity to users. Nodes are executable Python files that conform to the ROS node API. Scripts are executable Python files that do not conform to the ROS node API.

If you don't know what an __init__.py file is, we recommend that you read What is init py used for??

The more complicated layout for msg/srv files is required as the Python msg/srv generators will need to generate files into your package's namespace.

In the rare case that you can't place your source code in src/ (e.g. thirdparty code), you can override the Python export path of your package by editing your manifest.