While documentation is sparse, you can usually get useful information from the function/macro documentations.
Did you try looking at the content of the ament_cmake_python package?
At a glance it contains only 2 macro definitions which name and docblocs are pretty explicit.
ament_python_install_module to install python modulesament_python_install_package to install python packages
I know that [...] (for now) users can not mix ament_cmake with ament_python in the same package.
grep -rl "ament_python_install_package(" | sort -u | grep CMakeLists.txt | wc -l
41
It appears that 41 packages in the [ros2.repos](https://github.com/ros2/ros2/blob/0a62b2cd2210b06be7570c00922cd2f3d6609e31/ros2.repos) file do install python packages from ament_cmake packages. There may be restrictions or good reasons not to mix ament_cmake and python packages but it looks like in some cases it is doable and done.
Edit:
An example of package using it is rqt_plot
Are the Python packages installed here are:
- PyPi packages and whls only
- ros2 packages with setup.py (including the current one that the
CMake is building)
- both of the above
My understanding from reading the docblock is that it installs the python package you point to and any sub-package in that same directory (sub-directories containing an __init__.py).
It does not require any setup.py, just the presence of an __init__.py file
So I expect it to install noting outside that directory, no other ROS 2 packages and no Pypi packages, only recursive subpackages
