# Подробнее о ament\_python
**`ament_python`** — это инструмент сборки и управления зависимостями для Python-пакетов в ROS 2. Он является частью системы **Ament**, которая пришла на смену `catkin` из ROS 1. `ament_python` упрощает создание, установку и распространение Python-пакетов, интегрируя их с экосистемой ROS 2. Рассмотрим его ключевые аспекты.
***
#### **1. Основные компоненты Python-пакета**
Для создания ROS 2 Python-пакета с использованием `ament_python` требуется следующая структура:
```
my_py_pkg/
├── package.xml # Метаданные и зависимости
├── setup.py # Конфигурация пакета (установка, entry points)
├── setup.cfg # Настройки для setuptools
├── my_py_pkg/ # Исходный код
│ ├── __init__.py
│ └── nodes/
│ ├── __init__.py
│ └── my_node.py # Пример ROS 2 узла
└── resource/ # Ресурсы (необязательно)
└── my_py_pkg
```
**Файлы:**
* **`package.xml`**\
Содержит метаданные пакета и зависимости. Пример:
```xml
my_py_pkg
0.0.1
Мой Python-пакет для ROS 2
Your Name
Apache-2.0
rclpy
std_msgs
ament_python
```
* **`setup.py`**\
Определяет, как пакет устанавливается. Здесь указываются entry points для ROS 2 узлов:
```python
from setuptools import setup
setup(
name='my_py_pkg',
version='0.0.1',
packages=['my_py_pkg', 'my_py_pkg.nodes'],
data_files=[
('share/ament_index/resource_index/packages', ['resource/my_py_pkg']),
('share/my_py_pkg', ['package.xml']),
],
install_requires=['setuptools'],
zip_safe=True,
author='Your Name',
author_email='you@email.com',
entry_points={
'console_scripts': [
'my_node = my_py_pkg.nodes.my_node:main', # Регистрация узла
],
},
)
```
* **`setup.cfg`**\
Настраивает поведение `setuptools`:
```
[develop]
script_dir=$base/lib/python3.8/site-packages
[install]
install_scripts=$base/lib/python3.8/site-packages
```
***
#### **2. Сборка и установка**
Для сборки Python-пакета используется `colcon`:
```bash
colcon build --packages-select my_py_pkg --symlink-install
```
* **`--symlink-install`** — создает символические ссылки вместо копирования файлов, что позволяет вносить изменения в Python-код без пересборки.
После сборки пакет активируется через:
```bash
source install/local_setup.bash
```
***
#### **3. Особенности `ament_python`**
**a. Entry Points (исполняемые узлы)**
* В `setup.py` через `entry_points` регистрируются ROS 2 узлы как консольные скрипты.
* При установке пакета скрипты автоматически помещаются в `install/lib/my_py_pkg`, и их можно запускать как обычные команды:
```bash
ros2 run my_py_pkg my_node
```
**b. Ресурсы и данные**
* Файлы в директории `resource/` (например, конфиги, launch-файлы) копируются в `install/share/my_py_pkg`.
* Для доступа к ресурсам из кода используйте:
```python
from ament_index_python.packages import get_package_share_directory
pkg_path = get_package_share_directory('my_py_pkg')
```
**c. Зависимости**
* В `package.xml` указываются зависимости:
* `` — зависимости времени сборки и выполнения (например, `rclpy`).
* `` — только для выполнения (например, `ament_python`).
* `` — для тестирования (например, `pytest`).
***
#### **4. Тестирование**
`ament_python` поддерживает тестирование через `pytest`. Пример:
```python
# tests/test_my_node.py
def test_my_node():
assert True # Простейший тест
```
Для запуска тестов:
```bash
colcon test --packages-select my_py_pkg
```
Результаты тестов можно просмотреть через:
```bash
colcon test-result --all --verbose
```
***
#### **5. Отличия от `ament_cmake`**
* **Для C++**: `ament_cmake` использует CMake для сборки, требует `CMakeLists.txt`.
* **Для Python**: `ament_python` полагается на `setuptools` и не требует CMake.
* **Гибридные пакеты**: Если пакет содержит и C++, и Python код, можно использовать оба инструмента, но это усложняет конфигурацию.
***
#### **6. Лучшие практики**
1. **Используйте виртуальные окружения** для изоляции Python-зависимостей.
2. **Документируйте entry points** в `README.md`, чтобы другие разработчики знали, как запускать узлы.
3. **Избегайте глобальных путей** — используйте `get_package_share_directory`.
4. **Выносите общий код** в отдельные модули (например, `my_py_pkg/utils`).
***
#### **7. Пример узла на Python**
```python
# my_py_pkg/nodes/my_node.py
import rclpy
from rclpy.node import Node
class MyNode(Node):
def __init__(self):
super().__init__('my_node')
self.get_logger().info('Hello from ament_python!')
def main(args=None):
rclpy.init(args=args)
node = MyNode()
rclpy.spin(node)
rclpy.shutdown()
if __name__ == '__main__':
main()
```
***
#### **Итог**
`ament_python` — это мощный инструмент для работы с Python-пакетами в ROS 2. Он позволяет:
* Быстро создавать узлы и скрипты через `entry_points`.
* Интегрироваться с системой сборки `colcon`.
* Управлять зависимостями и ресурсами.
* Тестировать код с помощью `pytest`.
Используйте его для разработки легковесных компонентов ROS 2, где Python предпочтительнее C++. Для сложных проектов с высокими требованиями к производительности лучше подойдет `ament_cmake`.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://alice-and-alex-docs.gitbook.io/alice_and_alex_docs/ros2-development/podrobnee-o-ament_python.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.