Abstract: This will be a fire to go blog. It is really not hard to do this but ROS wiki did a good job in making it hard. Let me guide you through it.

There are only TWO things you can do

First of all, you need to understand what you can do and then what you need to do. Its really simply, there are two things you can do:

1. Export a python module to a new package in the ROS global namespace
2. Export a executable file to a new pacakge in the ROS global namespace

ROS wiki did a bad thing when explaning them together. Another confusion is the executable can be any file type but you need to make them executable.

How to export the Python module (class)

Let's say you already build a package called robot_helper. And you have a python file inside the api folder. Here is what it looks like:

robot_helper
├── api
│   ├── api.py
│   ├── api2.py
│   ├── my_test_exe
│   └── __init__.py
├── scripts
│   ├── manager.py
├── package.xml
├── CMakeLists.txt
├── setup.py

#And inside the api.py, you have some class
class MY_API():
    def __init__(self):

#And inside the api2.py, you have some class
class MY_API2():
    def __init__(self):

And what you need to do:

1. create an empty file __init__.py inside the api folder.
2. create setup.py
3. add this line in CMakeLists.txt after the find_package

## Uncomment if the package has a setup.py
catkin_python_setup()

4. open setup.py and add this:

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

setup_args = generate_distutils_setup(
    packages=['my_api'],
	package_dir={'': 'api'}
)

setup(**setup_args)

5. You are done. catkin_make and you may need to source the devel/setup.bash to make it affect.

Behind the sense

1. catkin_python_setup() makes the ROS run setup.py.
2. __init__.py expose the folder content to setup.py, you can put __init__.py in the package root if you feel safe to do so.
3. packages=['my_python_stuff'] this tells ROS to find some python packages, which does NOT matter with your python module, don't mess up.
4. package_dir={'': 'api'} tells ROS to put all python file from (./api) into a gloabl python environment.

And finally you can start importing this python module in other packages like

from api import MY_API
from api2 import MY_API2

Somehow, you need to keep the package name matches your python file name, otherwise it won't find the package from the filename import the Class Name.

Install the executable

If you look around, you will find this in CMakeLists:

## this is used only when you have a script and want to make is an executable
# catkin_install_python(PROGRAMS api/my_test_exe
#   DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

The my_test_exe is actually the file you created and made +x to it.
This my_test_exe is available inside the CMakeList Project name that is:

rosrun robot_helper my_test_exe

Which I think make sense but is 100% confusing for beginers!

I hope you enjoin this blog, feel free to contact me if you have any ideas.