init: ROS2 learning suite

2026-08-03 18:09:35 +08:00
commit 5ef38ab508
95 changed files with 13322 additions and 0 deletions
@@ -0,0 +1,107 @@
+# =============================================================================
+# pyproject.toml —— 标准 PEP 621 项目元数据(workspace 模式)。
+#
+# 设计取舍:
+#   - ROS2 实际构建/运行仍走 colcon + ament_python(ROS2 官方工具链);
+#   - 本文件提供 *额外* 的标准 Python 入口,让本机 IDE / 类型检查 /
+#     pytest / ruff 能识别为 Python 项目,且不污染系统 Python。
+#   - 真正运行 ROS2 节点时,需要在容器内 / WSL 内 source /opt/ros/humble/setup.bash,
+#     因为 rclpy / sensor_msgs 等只有 apt 上的发行版,Windows 无 wheels。
+#
+# venv 工作流:
+#   本机: ./tools/setup_venv.sh  (Linux/WSL) 或 ./tools/setup_venv.ps1 (Windows)
+#   进入开发: source .venv/bin/activate  (Linux) 或 .venv\Scripts\Activate.ps1 (Win)
+#   pytest:    pytest src/py_pubsub/test                  # 纯逻辑测试
+#   全套测试:  colcon test (在 Docker 容器内)            # 真 ROS2 测试
+# =============================================================================
+
+[build-system]
+# 不用 setuptools 实际构建,只是给 IDE 一个工具入口。
+# 各 ROS2 ament_python 包各自的 setup.py 由 colcon 调用。
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ros2-learning-suite"
+version = "0.1.0"
+description = "ROS2 Humble 全栈实战:Topics/Services/Actions/TF2/URDF/Vision(具身智能入门)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "xs", email = "dev@example.com" }]
+keywords = ["ros2", "humble", "robotics", "embodied-ai", "vla", "tf2", "urdf"]
+
+# 标准 Python 依赖(运行时不强制,运行时 ROS2 客户端库来自 apt)。
+dependencies = [
+  # 测试/工具依赖见 requirements-dev.txt;这里只列运行相关的纯 Python 库。
+  "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+# pip install -e .[dev] 装开发工具
+dev = [
+  "pytest>=7",
+  "pytest-cov>=4",
+  "pytest-timeout>=2",
+  "mypy>=1.5",
+  "ruff>=0.1",
+  "black>=23",
+  "flake8>=6",
+  "types-setuptools",
+]
+# pip install -e .[vision] 装视觉相关
+vision = [
+  "opencv-python-headless>=4.7",
+]
+
+[project.urls]
+Documentation = "https://docs.ros.org/en/humble/"
+Source = "https://github.com/ros2"
+
+[tool.setuptools]
+# 不让 setuptools 试图打包本根目录——各子包由 ament_python 单独构建。
+py-modules = []
+
+# ---------------- pytest 配置 ----------------
+[tool.pytest.ini_options]
+# 让 pytest 自动找到 src/ 下所有 test_*.py / *_test.py
+testpaths = ["src"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+  "-ra",
+  "--strict-markers",
+  "--tb=short",
+]
+# 标记:需要 ROS2 环境(容器内跑),用 pytest -m "not ros" 在本机只跑纯逻辑测试
+markers = [
+  "ros: 需要 ROS2 运行环境(rclpy / sensor_msgs / tf2)",
+  "inproc: 同进程内 spin 跑得通,不依赖外部 ROS daemon",
+]
+
+# ---------------- ruff 配置(快速 lint) ----------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = [".venv", "build", "install", "log", "src/*/build"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4"]
+ignore = ["E501", "B008"]  # 容忍长行 / 函数调用默认值
+
+[tool.ruff.lint.per-file-ignores]
+"src/**/test_*.py" = ["B011"]  # 测试允许 assert False
+
+# ---------------- mypy 配置(静态类型检查) ----------------
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true     # rclpy / sensor_msgs 在 venv 里看不到
+warn_unused_ignores = true
+no_implicit_optional = true
+
+# ---------------- black 配置 ----------------
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+extend-exclude = '((\\.venv|build|install|log)/)'