mirror of
https://github.com/ZGCA-Forge/MsgCenterPy.git
synced 2025-12-14 13:04:34 +00:00
Update docs
This commit is contained in:
Xuwznln
22
.github/workflows/docs.yml
vendored
22
.github/workflows/docs.yml
vendored
@@ -5,6 +5,18 @@ on:
|
|||||||
branches: [main]
|
branches: [main]
|
||||||
pull_request:
|
pull_request:
|
||||||
branches: [main]
|
branches: [main]
|
||||||
|
workflow_dispatch:
|
||||||
|
inputs:
|
||||||
|
branch:
|
||||||
|
description: "要部署文档的分支"
|
||||||
|
required: false
|
||||||
|
default: "main"
|
||||||
|
type: string
|
||||||
|
deploy_to_pages:
|
||||||
|
description: "是否部署到 GitHub Pages"
|
||||||
|
required: false
|
||||||
|
default: true
|
||||||
|
type: boolean
|
||||||
|
|
||||||
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
||||||
permissions:
|
permissions:
|
||||||
@@ -25,6 +37,8 @@ jobs:
|
|||||||
steps:
|
steps:
|
||||||
- name: Checkout
|
- name: Checkout
|
||||||
uses: actions/checkout@v4
|
uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
ref: ${{ github.event.inputs.branch || github.ref }}
|
||||||
|
|
||||||
- name: Set up Python
|
- name: Set up Python
|
||||||
uses: actions/setup-python@v5
|
uses: actions/setup-python@v5
|
||||||
@@ -42,7 +56,7 @@ jobs:
|
|||||||
- name: Setup Pages
|
- name: Setup Pages
|
||||||
id: pages
|
id: pages
|
||||||
uses: actions/configure-pages@v4
|
uses: actions/configure-pages@v4
|
||||||
if: github.ref == 'refs/heads/main'
|
if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
|
||||||
|
|
||||||
- name: Build Sphinx documentation
|
- name: Build Sphinx documentation
|
||||||
run: |
|
run: |
|
||||||
@@ -51,13 +65,13 @@ jobs:
|
|||||||
|
|
||||||
- name: Upload artifact
|
- name: Upload artifact
|
||||||
uses: actions/upload-pages-artifact@v3
|
uses: actions/upload-pages-artifact@v3
|
||||||
if: github.ref == 'refs/heads/main'
|
if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
|
||||||
with:
|
with:
|
||||||
path: docs/_build/html
|
path: docs/_build/html
|
||||||
|
|
||||||
# Deploy to GitHub Pages (only on main branch)
|
# Deploy to GitHub Pages
|
||||||
deploy:
|
deploy:
|
||||||
if: github.ref == 'refs/heads/main'
|
if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
|
||||||
environment:
|
environment:
|
||||||
name: github-pages
|
name: github-pages
|
||||||
url: ${{ steps.deployment.outputs.page_url }}
|
url: ${{ steps.deployment.outputs.page_url }}
|
||||||
|
|||||||
203
README.md
203
README.md
@@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
[](https://badge.fury.io/py/msgcenterpy)
|
[](https://badge.fury.io/py/msgcenterpy)
|
||||||
[](https://pypi.org/project/msgcenterpy/)
|
[](https://pypi.org/project/msgcenterpy/)
|
||||||
[](https://github.com/ZGCA-Forge/MsgCenterPy/actions)
|
[](https://github.com/ZGCA-Forge/MsgCenterPy/actions)
|
||||||
[](https://zgca-forge.github.io/MsgCenterPy/)
|
[](https://zgca-forge.github.io/MsgCenterPy/)
|
||||||
|
|
||||||
[](https://github.com/ZGCA-Forge/MsgCenterPy)
|
[](https://github.com/ZGCA-Forge/MsgCenterPy)
|
||||||
@@ -16,47 +16,36 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 概述
|
MsgCenterPy is a multi-format message conversion system based on a unified instance manager architecture, supporting seamless conversion between **ROS2**, **Pydantic**, **Dataclass**, **JSON**, **Dict**, **YAML**, and **JSON Schema**.
|
||||||
|
|
||||||
MsgCenterPy 是一个基于统一实例管理器架构的多格式消息转换系统，支持 **ROS2**、**Pydantic**、**Dataclass**、**JSON**、**Dict**、**YAML** 和 **JSON Schema** 之间的无缝互转。
|
### Supported Formats
|
||||||
|
|
||||||
### 支持的格式
|
| Format | Read | Write | JSON Schema | Type Constraints |
|
||||||
|
| ----------- | ---- | ----- | ----------- | ---------------- |
|
||||||
|
| ROS2 | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| JSON Schema | ✅ | ✅ | ✅ | ✅ |
|
||||||
|
| Pydantic | 🚧 | 🚧 | 🚧 | 🚧 |
|
||||||
|
| Dataclass | 🚧 | 🚧 | 🚧 | 🚧 |
|
||||||
|
| JSON | 🚧 | 🚧 | 🚧 | 🚧 |
|
||||||
|
| Dict | 🚧 | 🚧 | 🚧 | 🚧 |
|
||||||
|
| YAML | 🚧 | 🚧 | 🚧 | 🚧 |
|
||||||
|
|
||||||
| 格式 | 读取 | 写入 | JSON Schema | 类型约束 |
|
## Installation
|
||||||
| ----------- | ------ | ------ | ----------- | -------- |
|
|
||||||
| ROS2 | ✅ | ✅ | ✅ | ✅ |
|
|
||||||
| JSON Schema | ✅ | ✅ | ✅ | ✅ |
|
|
||||||
| Pydantic | 开发中 | 开发中 | 开发中 | 开发中 |
|
|
||||||
| Dataclass | 开发中 | 开发中 | 开发中 | 开发中 |
|
|
||||||
| JSON | 开发中 | 开发中 | 开发中 | 开发中 |
|
|
||||||
| Dict | 开发中 | 开发中 | 开发中 | 开发中 |
|
|
||||||
| YAML | 开发中 | 开发中 | 开发中 | 开发中 |
|
|
||||||
|
|
||||||
## 📦 安装
|
### Basic Installation
|
||||||
|
|
||||||
### 基础安装
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install msgcenterpy
|
pip install msgcenterpy
|
||||||
```
|
```
|
||||||
|
|
||||||
### 包含可选依赖
|
### With Optional Dependencies
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 安装 ROS2 支持
|
# Install ROS2 support
|
||||||
conda install
|
conda install ros-humble-ros-core ros-humble-std-msgs ros-humble-geometry-msgs -c robostack-staging
|
||||||
|
|
||||||
# 安装开发工具
|
|
||||||
pip install msgcenterpy[dev]
|
|
||||||
|
|
||||||
# 安装文档工具
|
|
||||||
pip install msgcenterpy[docs]
|
|
||||||
|
|
||||||
# 安装所有依赖
|
|
||||||
pip install msgcenterpy[all]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 从源码安装
|
### From Source
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
||||||
@@ -64,98 +53,13 @@ cd MsgCenterPy
|
|||||||
pip install -e .[dev]
|
pip install -e .[dev]
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔧 快速开始
|
## Quick Start
|
||||||
|
|
||||||
### 基础使用
|
Please visit: [https://zgca-forge.github.io/MsgCenterPy/](https://zgca-forge.github.io/MsgCenterPy/)
|
||||||
|
|
||||||
```python
|
## Development
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
|
||||||
|
|
||||||
# 从字典创建消息实例
|
### Development Environment Setup
|
||||||
data = {
|
|
||||||
"name": "sensor_001",
|
|
||||||
"readings": [1.0, 2.0, 3.0],
|
|
||||||
"active": True
|
|
||||||
}
|
|
||||||
dict_instance = MessageInstance.create(MessageType.DICT, data)
|
|
||||||
|
|
||||||
# 生成 JSON Schema
|
|
||||||
schema = dict_instance.get_json_schema()
|
|
||||||
print(schema)
|
|
||||||
```
|
|
||||||
|
|
||||||
### ROS2 消息转换
|
|
||||||
|
|
||||||
```python
|
|
||||||
from std_msgs.msg import String
|
|
||||||
from msgcenterpy.instances.ros2_instance import ROS2MessageInstance
|
|
||||||
|
|
||||||
# 创建 ROS2 消息实例
|
|
||||||
string_msg = String()
|
|
||||||
string_msg.data = "Hello ROS2"
|
|
||||||
ros2_instance = ROS2MessageInstance(string_msg)
|
|
||||||
|
|
||||||
# 转换为 JSON Schema
|
|
||||||
json_schema_instance = ros2_instance.to_json_schema()
|
|
||||||
|
|
||||||
# 获取生成的 Schema
|
|
||||||
schema = json_schema_instance.json_schema
|
|
||||||
print(schema)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 字段访问和约束
|
|
||||||
|
|
||||||
```python
|
|
||||||
# 动态字段访问
|
|
||||||
ros2_instance.data_field = "new_value"
|
|
||||||
print(ros2_instance.fields.get_field_info("data"))
|
|
||||||
|
|
||||||
# 类型约束验证
|
|
||||||
type_info = ros2_instance.fields.get_sub_type_info("data")
|
|
||||||
print(f"约束条件: {[c.type.value for c in type_info.constraints]}")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📖 文档
|
|
||||||
|
|
||||||
### 核心概念
|
|
||||||
|
|
||||||
- **MessageInstance**: 统一消息实例基类
|
|
||||||
- **TypeInfo**: 详细的字段类型信息和约束
|
|
||||||
- **FieldAccessor**: 统一字段访问接口
|
|
||||||
- **MessageCenter**: 消息类型管理和转换中心
|
|
||||||
|
|
||||||
### API 参考
|
|
||||||
|
|
||||||
详细的 API 文档请访问：[https://zgca-forge.github.io/MsgCenterPy/](https://zgca-forge.github.io/MsgCenterPy/)
|
|
||||||
|
|
||||||
### 示例代码
|
|
||||||
|
|
||||||
更多示例请查看 [`examples/`](examples/) 目录：
|
|
||||||
|
|
||||||
- [ROS2 消息转换示例](examples/ros2_example.py)
|
|
||||||
- [JSON Schema 生成示例](examples/json_schema_example.py)
|
|
||||||
- [类型约束示例](examples/type_constraints_example.py)
|
|
||||||
|
|
||||||
## 🧪 测试
|
|
||||||
|
|
||||||
### 运行测试
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 运行所有测试
|
|
||||||
python -m pytest
|
|
||||||
|
|
||||||
# 运行特定测试套件
|
|
||||||
python run_all_tests.py --type json_schema
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 生成覆盖率报告
|
|
||||||
pytest --cov=msgcenterpy --cov-report=html
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠️ 开发
|
|
||||||
|
|
||||||
### 开发环境设置
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
||||||
@@ -164,73 +68,16 @@ pip install -e .[dev]
|
|||||||
pre-commit install
|
pre-commit install
|
||||||
```
|
```
|
||||||
|
|
||||||
### 代码质量
|
For API documentation, please refer to Quick Start
|
||||||
|
|
||||||
```bash
|
## License
|
||||||
# 代码格式化
|
|
||||||
black msgcenterpy tests
|
|
||||||
isort msgcenterpy tests
|
|
||||||
|
|
||||||
# 类型检查
|
This project is licensed under Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
|
||||||
mypy msgcenterpy
|
|
||||||
|
|
||||||
# 运行测试
|
|
||||||
pytest
|
|
||||||
```
|
|
||||||
|
|
||||||
### 贡献指南
|
|
||||||
|
|
||||||
1. Fork 项目
|
|
||||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
|
||||||
3. 提交变更 (`git commit -m 'Add some AmazingFeature'`)
|
|
||||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
|
||||||
5. 创建 Pull Request
|
|
||||||
|
|
||||||
详细贡献指南请查看 [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
||||||
|
|
||||||
## 📊 开发路线图
|
|
||||||
|
|
||||||
- [x] ✅ ROS2 消息支持
|
|
||||||
- [x] ✅ JSON Schema 生成和验证
|
|
||||||
- [x] ✅ 统一字段访问器
|
|
||||||
- [x] ✅ 类型约束系统
|
|
||||||
- [ ] 🔄 Pydantic 集成
|
|
||||||
- [ ] 🔄 Dataclass 支持
|
|
||||||
- [ ] 🔄 YAML 格式支持
|
|
||||||
- [ ] 🔄 性能优化
|
|
||||||
- [ ] 🔄 插件系统
|
|
||||||
|
|
||||||
## 🤝 社区
|
|
||||||
|
|
||||||
### 支持渠道
|
|
||||||
|
|
||||||
- 💬 讨论: [GitHub Discussions](https://github.com/ZGCA-Forge/MsgCenterPy/discussions)
|
|
||||||
- 🐛 问题: [GitHub Issues](https://github.com/ZGCA-Forge/MsgCenterPy/issues)
|
|
||||||
- 📖 文档: [GitHub Pages](https://zgca-forge.github.io/MsgCenterPy/)
|
|
||||||
|
|
||||||
### 贡献者
|
|
||||||
|
|
||||||
感谢所有为 MsgCenterPy 做出贡献的开发者！
|
|
||||||
|
|
||||||
[](https://github.com/ZGCA-Forge/MsgCenterPy/graphs/contributors)
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
本项目基于 Apache-2.0 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
|
||||||
|
|
||||||
## 🙏 致谢
|
|
||||||
|
|
||||||
- [ROS2](https://ros.org/) - 机器人操作系统
|
|
||||||
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证库
|
|
||||||
- [pytest](https://pytest.org/) - 测试框架
|
|
||||||
- [jsonschema](https://python-jsonschema.readthedocs.io/) - JSON Schema 验证
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
**[⭐ 给个 Star](https://github.com/ZGCA-Forge/MsgCenterPy)** • **[🍴 Fork 项目](https://github.com/ZGCA-Forge/MsgCenterPy/fork)** • **[📖 查看文档](https://zgca-forge.github.io/MsgCenterPy/)**
|
|
||||||
|
|
||||||
Made with ❤️ by the MsgCenterPy Team
|
Made with ❤️ by the MsgCenterPy Team
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|||||||
@@ -3,98 +3,92 @@ Contributing to MsgCenterPy
|
|||||||
|
|
||||||
Thank you for your interest in contributing to MsgCenterPy! This document provides guidelines for contributing to the project.
|
Thank you for your interest in contributing to MsgCenterPy! This document provides guidelines for contributing to the project.
|
||||||
|
|
||||||
For detailed contribution guidelines, please see our `Contributing Guide <https://github.com/ZGCA-Forge/MsgCenterPy/blob/main/.github/CONTRIBUTING.md>`_ on GitHub.
|
|
||||||
|
|
||||||
Quick Links
|
Quick Links
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
- `GitHub Repository <https://github.com/ZGCA-Forge/MsgCenterPy>`_
|
- `GitHub Repository <https://github.com/ZGCA-Forge/MsgCenterPy>`_
|
||||||
- `Issue Tracker <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_
|
- `Issue Tracker <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_
|
||||||
- `Pull Requests <https://github.com/ZGCA-Forge/MsgCenterPy/pulls>`_
|
- `Pull Requests <https://github.com/ZGCA-Forge/MsgCenterPy/pulls>`_
|
||||||
- `Discussions <https://github.com/ZGCA-Forge/MsgCenterPy/discussions>`_
|
|
||||||
|
|
||||||
Development Setup
|
Development Setup
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
1. Fork the repository on GitHub
|
1. Fork the repository on GitHub
|
||||||
2. Clone your fork locally
|
2. Clone your fork locally:
|
||||||
3. Install in development mode:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
git clone https://github.com/YOUR-USERNAME/MsgCenterPy.git
|
git clone https://github.com/YOUR_USERNAME/MsgCenterPy.git
|
||||||
cd MsgCenterPy
|
cd MsgCenterPy
|
||||||
pip install -e .[dev]
|
|
||||||
|
|
||||||
4. Set up pre-commit hooks:
|
3. (Optional) If you need ROS2 support, set up ROS environment first:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
pre-commit install
|
# Create and activate conda environment with ROS2
|
||||||
|
conda create -n msgcenterpy-dev python=3.11
|
||||||
|
conda activate msgcenterpy-dev
|
||||||
|
conda install ros-humble-ros-core ros-humble-std-msgs ros-humble-geometry-msgs -c robostack-staging
|
||||||
|
|
||||||
|
4. Run the development setup script:
|
||||||
|
|
||||||
|
**Linux/macOS:**
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
./scripts/setup-dev.sh
|
||||||
|
|
||||||
|
**Windows:**
|
||||||
|
|
||||||
|
.. code-block:: powershell
|
||||||
|
|
||||||
|
.\scripts\setup-dev.ps1
|
||||||
|
|
||||||
|
The setup script will automatically:
|
||||||
|
|
||||||
|
- Install the package in development mode with all dependencies
|
||||||
|
- Set up pre-commit hooks
|
||||||
|
- Run initial code quality checks
|
||||||
|
- Display helpful commands for development
|
||||||
|
|
||||||
Code Style and Quality
|
Code Style and Quality
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
We use several tools to maintain code quality:
|
We use automated code quality checks that run via pre-commit hooks:
|
||||||
|
|
||||||
- **Black**: Code formatting
|
- **Black**: Code formatting (line length: 120)
|
||||||
- **isort**: Import sorting
|
- **isort**: Import sorting
|
||||||
|
- **flake8**: Code linting
|
||||||
- **mypy**: Type checking
|
- **mypy**: Type checking
|
||||||
- **pytest**: Testing
|
- **bandit**: Security scanning
|
||||||
|
- **prettier**: YAML/JSON formatting
|
||||||
|
|
||||||
Run quality checks:
|
These checks run automatically when you commit. You can also run them manually:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
# Format code
|
# Run all pre-commit hooks
|
||||||
black msgcenterpy tests
|
pre-commit run --all-files
|
||||||
isort msgcenterpy tests
|
|
||||||
|
|
||||||
# Type checking
|
|
||||||
mypy msgcenterpy
|
|
||||||
|
|
||||||
# Run tests
|
|
||||||
pytest
|
|
||||||
|
|
||||||
Testing
|
Testing
|
||||||
-------
|
-------
|
||||||
|
|
||||||
Please ensure all tests pass and add tests for new features:
|
**Important**: Always run tests before committing to ensure your changes work correctly.
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
# Run all tests
|
# Run all tests
|
||||||
pytest
|
pytest
|
||||||
|
|
||||||
# Run with coverage
|
# Run with verbose output
|
||||||
pytest -v
|
pytest -v
|
||||||
|
|
||||||
# Run specific test file
|
**Note**: If ROS2 is not installed, ROS-related tests will be automatically skipped. The test suite is designed to work with or without ROS2 dependencies.
|
||||||
pytest tests/test_specific_module.py
|
|
||||||
|
|
||||||
Version Management
|
Version Management
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
This project uses `bump2version` for semantic version management. The tool is included in development dependencies and automatically manages version numbers across the codebase.
|
This project uses `bump2version` for version management. It's automatically installed with dev dependencies.
|
||||||
|
|
||||||
**Setup**
|
|
||||||
|
|
||||||
bump2version is automatically installed when you install development dependencies:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
pip install -e .[dev]
|
|
||||||
|
|
||||||
**Configuration**
|
|
||||||
|
|
||||||
Version configuration is stored in `.bumpversion.cfg`:
|
|
||||||
|
|
||||||
- **Single source of truth**: `msgcenterpy/__init__.py`
|
|
||||||
- **Auto-commit**: Creates commit with version bump
|
|
||||||
- **Auto-tag**: Creates git tag for new version
|
|
||||||
- **Semantic versioning**: Follows MAJOR.MINOR.PATCH format
|
|
||||||
|
|
||||||
**Usage**
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
@@ -107,54 +101,25 @@ Version configuration is stored in `.bumpversion.cfg`:
|
|||||||
# Breaking changes (0.1.0 → 1.0.0)
|
# Breaking changes (0.1.0 → 1.0.0)
|
||||||
bump2version major
|
bump2version major
|
||||||
|
|
||||||
**Release Workflow**
|
After bumping version, push changes and tags:
|
||||||
|
|
||||||
1. Make your changes and commit them
|
|
||||||
2. Choose appropriate version bump type
|
|
||||||
3. Run bump2version command
|
|
||||||
4. Push changes and tags:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
git push && git push --tags
|
git push && git push --tags
|
||||||
|
|
||||||
**Version Bump Guidelines**
|
|
||||||
|
|
||||||
- **patch**: Bug fixes, documentation updates, internal refactoring
|
|
||||||
- **minor**: New features, backward-compatible API additions
|
|
||||||
- **major**: Breaking changes, API removals or modifications
|
|
||||||
|
|
||||||
**Notes**
|
|
||||||
|
|
||||||
- Only developers need bump2version (it's in dev dependencies only)
|
|
||||||
- Version numbers are automatically synchronized across all files
|
|
||||||
- Git working directory must be clean before version bump
|
|
||||||
- Each version bump creates a commit and git tag automatically
|
|
||||||
|
|
||||||
Submitting Changes
|
Submitting Changes
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
1. Create a new branch for your feature/fix
|
1. Create a new branch for your feature/fix
|
||||||
2. Make your changes
|
2. Make your changes and add tests
|
||||||
3. Add tests for new functionality
|
3. Run tests to ensure everything works
|
||||||
4. Ensure all tests pass
|
4. Update documentation if needed
|
||||||
5. Update documentation if needed
|
5. Submit a pull request with:
|
||||||
6. Submit a pull request
|
- Descriptive title and description
|
||||||
|
- Reference to related issues
|
||||||
Pull Request Guidelines
|
- Tests for new features
|
||||||
-----------------------
|
|
||||||
|
|
||||||
- Use descriptive titles and descriptions
|
|
||||||
- Reference related issues
|
|
||||||
- Include tests for new features
|
|
||||||
- Update documentation as needed
|
|
||||||
- Follow the existing code style
|
|
||||||
|
|
||||||
Getting Help
|
Getting Help
|
||||||
------------
|
------------
|
||||||
|
|
||||||
If you need help:
|
|
||||||
|
|
||||||
- Check existing `Issues <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_
|
- Check existing `Issues <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_
|
||||||
- Start a `Discussion <https://github.com/ZGCA-Forge/MsgCenterPy/discussions>`_
|
|
||||||
- Contact the maintainers
|
|
||||||
|
|||||||
@@ -6,220 +6,161 @@ This page contains basic usage examples to help you get started with MsgCenterPy
|
|||||||
Creating Message Instances
|
Creating Message Instances
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
Dictionary Messages
|
ROS2 Message Instances
|
||||||
~~~~~~~~~~~~~~~~~~~
|
----------------------
|
||||||
|
|
||||||
.. code-block:: python
|
Working with ROS2 Messages
|
||||||
|
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
|
||||||
|
|
||||||
# Simple dictionary
|
|
||||||
simple_data = {"name": "sensor_01", "active": True}
|
|
||||||
instance = MessageInstance.create(MessageType.DICT, simple_data)
|
|
||||||
|
|
||||||
# Access fields
|
|
||||||
name = instance.get_field("name")
|
|
||||||
print(f"Sensor name: {name}")
|
|
||||||
|
|
||||||
# Nested dictionary
|
|
||||||
nested_data = {
|
|
||||||
"device": {
|
|
||||||
"id": "dev_001",
|
|
||||||
"sensors": [
|
|
||||||
{"type": "temperature", "value": 23.5},
|
|
||||||
{"type": "humidity", "value": 65.2}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
nested_instance = MessageInstance.create(MessageType.DICT, nested_data)
|
|
||||||
|
|
||||||
JSON Schema Generation
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
# Generate JSON Schema from dictionary
|
|
||||||
schema = instance.get_json_schema()
|
|
||||||
print("Generated Schema:")
|
|
||||||
print(schema)
|
|
||||||
|
|
||||||
# Schema includes type information
|
|
||||||
assert schema["type"] == "object"
|
|
||||||
assert "name" in schema["properties"]
|
|
||||||
assert schema["properties"]["name"]["type"] == "string"
|
|
||||||
|
|
||||||
Field Access and Manipulation
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
Getting Field Values
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
# Simple field access
|
|
||||||
name = instance.get_field("name")
|
|
||||||
|
|
||||||
# Nested field access using dot notation
|
|
||||||
device_id = nested_instance.get_field("device.id")
|
|
||||||
temp_value = nested_instance.get_field("device.sensors.0.value")
|
|
||||||
|
|
||||||
Setting Field Values
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
# Set simple field
|
|
||||||
instance.set_field("name", "sensor_02")
|
|
||||||
|
|
||||||
# Set nested field
|
|
||||||
nested_instance.set_field("device.id", "dev_002")
|
|
||||||
nested_instance.set_field("device.sensors.0.value", 24.1)
|
|
||||||
|
|
||||||
Working with Field Information
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
# Get field type information
|
|
||||||
field_info = instance.fields.get_field_info("name")
|
|
||||||
print(f"Field type: {field_info.type}")
|
|
||||||
print(f"Field constraints: {field_info.constraints}")
|
|
||||||
|
|
||||||
# Check if field exists
|
|
||||||
if instance.fields.has_field("name"):
|
|
||||||
print("Field 'name' exists")
|
|
||||||
|
|
||||||
Type Constraints and Validation
|
|
||||||
-------------------------------
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from msgcenterpy.core.types import TypeConstraintError
|
|
||||||
|
|
||||||
try:
|
|
||||||
# This will raise an error if type doesn't match
|
|
||||||
instance.set_field("active", "not_a_boolean")
|
|
||||||
except TypeConstraintError as e:
|
|
||||||
print(f"Type constraint violation: {e}")
|
|
||||||
|
|
||||||
# Type conversion when possible
|
|
||||||
instance.set_field("name", 123) # Converts to string if allowed
|
|
||||||
|
|
||||||
Message Conversion
|
|
||||||
------------------
|
|
||||||
|
|
||||||
Converting Between Formats
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
# Create from dictionary
|
from msgcenterpy.instances.ros2_instance import ROS2MessageInstance
|
||||||
dict_instance = MessageInstance.create(MessageType.DICT, {"key": "value"})
|
from std_msgs.msg import String, Float64MultiArray
|
||||||
|
from geometry_msgs.msg import Point, Pose
|
||||||
|
|
||||||
# Convert to JSON Schema instance
|
# Simple String message
|
||||||
schema_instance = dict_instance.to_json_schema()
|
string_msg = String()
|
||||||
|
string_msg.data = "Hello ROS2"
|
||||||
|
ros2_instance = ROS2MessageInstance(string_msg)
|
||||||
|
|
||||||
# Get the actual schema
|
# Access and modify field
|
||||||
schema = schema_instance.json_schema
|
ros2_instance.data = "Updated message"
|
||||||
print(schema)
|
print(f"Message data: {ros2_instance.inner_data.data}")
|
||||||
|
|
||||||
Error Handling
|
# Float array message
|
||||||
--------------
|
array_msg = Float64MultiArray()
|
||||||
|
array_msg.data = [1.1, 2.2, 3.3, 4.4, 5.5]
|
||||||
|
array_instance = ROS2MessageInstance(array_msg)
|
||||||
|
|
||||||
Common Error Scenarios
|
# Complex nested message
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
pose_msg = Pose()
|
||||||
|
pose_instance = ROS2MessageInstance(pose_msg)
|
||||||
|
|
||||||
|
# Set nested fields
|
||||||
|
pose_instance.position.x = 1.5
|
||||||
|
pose_instance.position.y = 2.5
|
||||||
|
pose_instance.position.z = 3.5
|
||||||
|
|
||||||
|
# Or set entire object
|
||||||
|
new_position = Point(x=10.0, y=20.0, z=30.0)
|
||||||
|
pose_instance.position = new_position
|
||||||
|
|
||||||
|
Converting ROS2 to Python Dictionary
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from msgcenterpy.core.exceptions import FieldAccessError, TypeConstraintError
|
# Get Python dictionary representation
|
||||||
|
python_dict = ros2_instance.get_python_dict()
|
||||||
|
print(f"Dictionary: {python_dict}")
|
||||||
|
|
||||||
# Field access errors
|
# Set data from dictionary
|
||||||
try:
|
new_data = {"data": "dictionary_value"}
|
||||||
value = instance.get_field("nonexistent_field")
|
ros2_instance.set_python_dict(new_data)
|
||||||
except FieldAccessError as e:
|
|
||||||
print(f"Field not found: {e}")
|
|
||||||
|
|
||||||
# Type constraint errors
|
|
||||||
try:
|
|
||||||
instance.set_field("active", "invalid_boolean")
|
|
||||||
except TypeConstraintError as e:
|
|
||||||
print(f"Invalid type: {e}")
|
|
||||||
|
|
||||||
# Graceful handling
|
JSON Schema Message Instances
|
||||||
def safe_get_field(instance, field_name, default=None):
|
-----------------------------
|
||||||
try:
|
|
||||||
return instance.get_field(field_name)
|
|
||||||
except FieldAccessError:
|
|
||||||
return default
|
|
||||||
|
|
||||||
# Usage
|
Creating JSON Schema Instances
|
||||||
value = safe_get_field(instance, "optional_field", "default_value")
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Best Practices
|
|
||||||
--------------
|
|
||||||
|
|
||||||
1. **Always handle exceptions** when accessing fields that might not exist
|
|
||||||
2. **Use type hints** in your code for better development experience
|
|
||||||
3. **Validate data** before creating instances when working with external data
|
|
||||||
4. **Use dot notation** for nested field access instead of manual dictionary traversal
|
|
||||||
5. **Check field existence** before accessing optional fields
|
|
||||||
|
|
||||||
Complete Example
|
|
||||||
----------------
|
|
||||||
|
|
||||||
Here's a complete example that demonstrates multiple features:
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
from msgcenterpy.instances.json_schema_instance import JSONSchemaMessageInstance
|
||||||
from msgcenterpy.core.exceptions import FieldAccessError, TypeConstraintError
|
|
||||||
import json
|
|
||||||
|
|
||||||
def process_sensor_data(sensor_data):
|
# Define JSON Schema
|
||||||
"""Process sensor data with proper error handling."""
|
schema = {
|
||||||
try:
|
"type": "object",
|
||||||
# Create instance
|
"properties": {
|
||||||
instance = MessageInstance.create(MessageType.DICT, sensor_data)
|
"name": {"type": "string", "minLength": 2, "maxLength": 50},
|
||||||
|
"age": {"type": "integer", "minimum": 0, "maximum": 150},
|
||||||
# Validate required fields
|
"active": {"type": "boolean"},
|
||||||
required_fields = ["id", "type", "readings"]
|
"tags": {
|
||||||
for field in required_fields:
|
"type": "array",
|
||||||
if not instance.fields.has_field(field):
|
"items": {"type": "string"},
|
||||||
raise ValueError(f"Missing required field: {field}")
|
"minItems": 1,
|
||||||
|
"maxItems": 10
|
||||||
# Process readings
|
|
||||||
readings = instance.get_field("readings")
|
|
||||||
if isinstance(readings, list) and len(readings) > 0:
|
|
||||||
avg_reading = sum(readings) / len(readings)
|
|
||||||
instance.set_field("average", avg_reading)
|
|
||||||
|
|
||||||
# Generate schema for validation
|
|
||||||
schema = instance.get_json_schema()
|
|
||||||
|
|
||||||
# Return processed data and schema
|
|
||||||
return {
|
|
||||||
"processed_data": instance.to_dict(),
|
|
||||||
"schema": schema,
|
|
||||||
"success": True
|
|
||||||
}
|
}
|
||||||
|
},
|
||||||
except (FieldAccessError, TypeConstraintError, ValueError) as e:
|
"required": ["name"]
|
||||||
return {
|
|
||||||
"error": str(e),
|
|
||||||
"success": False
|
|
||||||
}
|
|
||||||
|
|
||||||
# Usage
|
|
||||||
sensor_data = {
|
|
||||||
"id": "temp_001",
|
|
||||||
"type": "temperature",
|
|
||||||
"readings": [23.1, 23.5, 24.0, 23.8],
|
|
||||||
"unit": "celsius"
|
|
||||||
}
|
}
|
||||||
|
|
||||||
result = process_sensor_data(sensor_data)
|
# Sample data
|
||||||
if result["success"]:
|
data = {
|
||||||
print("Processing successful!")
|
"name": "John Doe",
|
||||||
print(f"Average reading: {result['processed_data']['average']}")
|
"age": 30,
|
||||||
|
"active": True,
|
||||||
|
"tags": ["developer", "python"]
|
||||||
|
}
|
||||||
|
|
||||||
|
# Create instance
|
||||||
|
json_schema_instance = JSONSchemaMessageInstance(data, schema)
|
||||||
|
|
||||||
|
Working with JSON Schema Constraints
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
# Get field type information with constraints
|
||||||
|
name_type_info = json_schema_instance.fields.get_sub_type_info("name")
|
||||||
|
print(f"Field type: {name_type_info.standard_type}")
|
||||||
|
print(f"Min length: {name_type_info.get_constraint_value('min_length')}")
|
||||||
|
|
||||||
|
# Check validation errors
|
||||||
|
if len(json_schema_instance._validation_errors) == 0:
|
||||||
|
print("Data is valid according to schema")
|
||||||
else:
|
else:
|
||||||
print(f"Processing failed: {result['error']}")
|
print(f"Validation errors: {json_schema_instance._validation_errors}")
|
||||||
|
|
||||||
|
# Export to envelope format
|
||||||
|
envelope = json_schema_instance.export_to_envelope()
|
||||||
|
print(f"Envelope metadata: {envelope['metadata']}")
|
||||||
|
|
||||||
|
Message Type Conversion
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Converting ROS2 to JSON Schema
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
from std_msgs.msg import String
|
||||||
|
from msgcenterpy.instances.ros2_instance import ROS2MessageInstance
|
||||||
|
|
||||||
|
# Create ROS2 instance
|
||||||
|
string_msg = String()
|
||||||
|
string_msg.data = "conversion_test"
|
||||||
|
ros2_instance = ROS2MessageInstance(string_msg)
|
||||||
|
|
||||||
|
# Convert to JSON Schema instance
|
||||||
|
json_schema_instance = ros2_instance.to_json_schema()
|
||||||
|
|
||||||
|
# Verify conversion
|
||||||
|
print(f"Original data: {ros2_instance.get_python_dict()}")
|
||||||
|
print(f"Converted data: {json_schema_instance.get_python_dict()}")
|
||||||
|
print(f"Generated schema: {json_schema_instance.json_schema}")
|
||||||
|
|
||||||
|
Generate JSON Schema from ROS2 Message
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
from geometry_msgs.msg import Pose
|
||||||
|
|
||||||
|
# Create complex ROS2 message
|
||||||
|
pose_msg = Pose()
|
||||||
|
pose_msg.position.x = 5.0
|
||||||
|
pose_msg.position.y = 10.0
|
||||||
|
pose_msg.position.z = 15.0
|
||||||
|
pose_msg.orientation.w = 1.0
|
||||||
|
|
||||||
|
ros2_instance = ROS2MessageInstance(pose_msg)
|
||||||
|
|
||||||
|
# Generate JSON Schema
|
||||||
|
schema = ros2_instance.get_json_schema()
|
||||||
|
|
||||||
|
print("Generated JSON Schema:")
|
||||||
|
print(f"Type: {schema['type']}")
|
||||||
|
print(f"Properties: {list(schema['properties'].keys())}")
|
||||||
|
print(f"Position schema: {schema['properties']['position']}")
|
||||||
|
|||||||
102
docs/index.rst
102
docs/index.rst
@@ -13,37 +13,40 @@ Welcome to MsgCenterPy's Documentation!
|
|||||||
:target: https://pypi.org/project/msgcenterpy/
|
:target: https://pypi.org/project/msgcenterpy/
|
||||||
:alt: Python versions
|
:alt: Python versions
|
||||||
|
|
||||||
MsgCenterPy is a unified message conversion system based on unified instance manager architecture,
|
MsgCenterPy is a multi-format message conversion system based on a unified instance manager architecture,
|
||||||
supporting seamless conversion between **ROS2**, **Pydantic**, **Dataclass**, **JSON**, **Dict**,
|
supporting seamless conversion between **ROS2**, **Pydantic**, **Dataclass**, **JSON**, **Dict**,
|
||||||
**YAML** and **JSON Schema**.
|
**YAML** and **JSON Schema**.
|
||||||
|
|
||||||
✨ Key Features
|
📦 Installation
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
🔄 **Unified Conversion**: Supports bidirectional conversion between multiple message formats
|
Basic Installation
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
🤖 **ROS2 Integration**: Complete support for ROS2 message types and constraints
|
|
||||||
|
|
||||||
📊 **JSON Schema**: Automatic generation and validation of JSON Schema
|
|
||||||
|
|
||||||
🏗️ **Type Safety**: Strong type constraint system based on TypeInfo
|
|
||||||
|
|
||||||
🔍 **Field Access**: Unified field accessor interface
|
|
||||||
|
|
||||||
⚡ **High Performance**: Optimized conversion algorithms and caching mechanism
|
|
||||||
|
|
||||||
🧪 **Complete Testing**: 47+ test cases with >90% coverage
|
|
||||||
|
|
||||||
📦 Quick Start
|
|
||||||
--------------
|
|
||||||
|
|
||||||
Installation
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
pip install msgcenterpy
|
pip install msgcenterpy
|
||||||
|
|
||||||
|
With Optional Dependencies
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
# Install ROS2 support
|
||||||
|
conda install ros-humble-ros-core ros-humble-std-msgs ros-humble-geometry-msgs -c robostack-staging
|
||||||
|
|
||||||
|
From Source
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
||||||
|
cd MsgCenterPy
|
||||||
|
pip install -e .[dev]
|
||||||
|
|
||||||
|
🚀 Quick Start
|
||||||
|
--------------
|
||||||
|
|
||||||
Basic Usage
|
Basic Usage
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
@@ -86,33 +89,41 @@ Basic Usage
|
|||||||
- ✅
|
- ✅
|
||||||
- ✅
|
- ✅
|
||||||
* - Pydantic
|
* - Pydantic
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
* - Dataclass
|
* - Dataclass
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
* - JSON
|
* - JSON
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- ✅
|
- 🚧
|
||||||
- ⚡
|
- 🚧
|
||||||
* - Dict
|
* - Dict
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- ✅
|
- 🚧
|
||||||
- ⚡
|
- 🚧
|
||||||
* - YAML
|
* - YAML
|
||||||
- 开发中
|
- 🚧
|
||||||
- 开发中
|
- 🚧
|
||||||
- ✅
|
- 🚧
|
||||||
- ⚡
|
- 🚧
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
✅ Fully Supported | 开发中 In Development | ⚡ Basic Support
|
✅ Fully Supported | 🚧 In Development
|
||||||
|
|
||||||
|
🛠️ Development
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Development Environment Setup
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
For detailed development guidelines, please refer to the Development section.
|
||||||
|
|
||||||
📚 Documentation Contents
|
📚 Documentation Contents
|
||||||
-------------------------
|
-------------------------
|
||||||
@@ -122,7 +133,6 @@ Basic Usage
|
|||||||
:caption: User Guide
|
:caption: User Guide
|
||||||
|
|
||||||
installation
|
installation
|
||||||
quickstart
|
|
||||||
user_guide/index
|
user_guide/index
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
@@ -168,9 +178,3 @@ Indices and Tables
|
|||||||
|
|
||||||
- 📖 **Documentation**: https://zgca-forge.github.io/MsgCenterPy/
|
- 📖 **Documentation**: https://zgca-forge.github.io/MsgCenterPy/
|
||||||
- 🐛 **Issues**: https://github.com/ZGCA-Forge/MsgCenterPy/issues
|
- 🐛 **Issues**: https://github.com/ZGCA-Forge/MsgCenterPy/issues
|
||||||
- 💬 **Discussions**: https://github.com/ZGCA-Forge/MsgCenterPy/discussions
|
|
||||||
|
|
||||||
📄 License
|
|
||||||
==========
|
|
||||||
|
|
||||||
This project is licensed under the Apache-2.0 License - see the `LICENSE <https://github.com/ZGCA-Forge/MsgCenterPy/blob/main/LICENSE>`_ file for details.
|
|
||||||
|
|||||||
@@ -3,8 +3,8 @@ Installation Guide
|
|||||||
|
|
||||||
This guide will help you install MsgCenterPy in different environments.
|
This guide will help you install MsgCenterPy in different environments.
|
||||||
|
|
||||||
Quick Installation
|
Basic Installation
|
||||||
------------------
|
-------------------
|
||||||
|
|
||||||
The easiest way to install MsgCenterPy is using pip:
|
The easiest way to install MsgCenterPy is using pip:
|
||||||
|
|
||||||
@@ -18,96 +18,27 @@ Requirements
|
|||||||
- Python 3.10 or higher (Python 3.11+ recommended for optimal ROS2 compatibility)
|
- Python 3.10 or higher (Python 3.11+ recommended for optimal ROS2 compatibility)
|
||||||
- Operating System: Linux, macOS, or Windows
|
- Operating System: Linux, macOS, or Windows
|
||||||
|
|
||||||
Optional Dependencies
|
With Optional Dependencies
|
||||||
---------------------
|
--------------------------
|
||||||
|
|
||||||
ROS2 Support
|
ROS2 Support
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
To use ROS2 message conversion features:
|
To use ROS2 message conversion features, install ROS2 packages via conda:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
pip install msgcenterpy[ros2]
|
# Install ROS2 support
|
||||||
|
conda install ros-humble-ros-core ros-humble-std-msgs ros-humble-geometry-msgs -c robostack-staging
|
||||||
|
|
||||||
This will install:
|
This provides the necessary ROS2 packages for message type conversion and integration.
|
||||||
- ``rosidl-runtime-py>=0.10.0``
|
|
||||||
- ``rclpy>=3.0.0``
|
|
||||||
|
|
||||||
.. warning::
|
.. note::
|
||||||
**ROS2 Python Version Compatibility Notice**
|
**ROS2 Installation Notes**
|
||||||
|
|
||||||
While Python 3.10+ is supported by this package, ROS2 official binary distributions
|
- We recommend using conda with the robostack-staging channel for ROS2 packages
|
||||||
may have varying support across Python versions. You might need to:
|
- This approach provides better Python version compatibility
|
||||||
|
- Alternative ROS2 installation methods are also supported if you have them set up
|
||||||
- Build ROS2 from source for newer Python versions
|
|
||||||
- Use ROS2 distributions that officially support your Python version
|
|
||||||
- Consider using conda-forge ROS2 packages if available
|
|
||||||
|
|
||||||
For production environments, verify ROS2 compatibility in your specific setup.
|
|
||||||
|
|
||||||
Development Tools
|
|
||||||
~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
For development and testing:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
pip install msgcenterpy[dev]
|
|
||||||
|
|
||||||
This includes:
|
|
||||||
- ``pytest>=7.0.0``
|
|
||||||
- ``black>=22.0.0``
|
|
||||||
- ``isort>=5.0.0``
|
|
||||||
- ``mypy>=1.0.0``
|
|
||||||
- ``pre-commit>=2.20.0``
|
|
||||||
|
|
||||||
Documentation Tools
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
For building documentation:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
pip install msgcenterpy[docs]
|
|
||||||
|
|
||||||
All Dependencies
|
|
||||||
~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
To install all optional dependencies:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
pip install msgcenterpy[all]
|
|
||||||
|
|
||||||
From Source
|
|
||||||
-----------
|
|
||||||
|
|
||||||
Development Installation
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
To install from source for development:
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
git clone https://github.com/ZGCA-Forge/MsgCenterPy.git
|
|
||||||
cd MsgCenterPy
|
|
||||||
pip install -e .[dev]
|
|
||||||
|
|
||||||
This will install the package in development mode, allowing you to make changes to the source code.
|
|
||||||
|
|
||||||
Verification
|
|
||||||
------------
|
|
||||||
|
|
||||||
To verify your installation:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
import msgcenterpy
|
|
||||||
print(msgcenterpy.get_version())
|
|
||||||
print(msgcenterpy.check_dependencies())
|
|
||||||
|
|
||||||
The output should show the version number and available dependencies.
|
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
---------------
|
---------------
|
||||||
@@ -115,7 +46,7 @@ Troubleshooting
|
|||||||
Common Issues
|
Common Issues
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
1. **Python Version**: Ensure you're using Python 3.10 or higher (3.11+ recommended for optimal ROS2 compatibility)
|
1. **Python Version**: Ensure you're using Python 3.10 or higher (3.11.11 recommended for 0.6.x ROS2 compatibility)
|
||||||
2. **ROS2 Dependencies**: ROS2 support requires a proper ROS2 installation
|
2. **ROS2 Dependencies**: ROS2 support requires a proper ROS2 installation
|
||||||
3. **Virtual Environments**: Consider using virtual environments for isolation
|
3. **Virtual Environments**: Consider using virtual environments for isolation
|
||||||
|
|
||||||
|
|||||||
@@ -1,138 +0,0 @@
|
|||||||
Quick Start Guide
|
|
||||||
=================
|
|
||||||
|
|
||||||
This guide will get you up and running with MsgCenterPy in just a few minutes.
|
|
||||||
|
|
||||||
First Steps
|
|
||||||
-----------
|
|
||||||
|
|
||||||
After installation, you can start using MsgCenterPy immediately:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
|
||||||
|
|
||||||
# Create a simple message from dictionary
|
|
||||||
data = {"name": "test", "value": 42}
|
|
||||||
instance = MessageInstance.create(MessageType.DICT, data)
|
|
||||||
|
|
||||||
# Get JSON Schema
|
|
||||||
schema = instance.get_json_schema()
|
|
||||||
print(schema)
|
|
||||||
|
|
||||||
Basic Concepts
|
|
||||||
--------------
|
|
||||||
|
|
||||||
MessageInstance
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The core concept in MsgCenterPy is the ``MessageInstance``, which provides a unified interface for different message formats.
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
|
||||||
|
|
||||||
# Different ways to create instances
|
|
||||||
dict_instance = MessageInstance.create(MessageType.DICT, {"key": "value"})
|
|
||||||
|
|
||||||
# Access fields
|
|
||||||
print(dict_instance.get_field("key"))
|
|
||||||
|
|
||||||
MessageType
|
|
||||||
~~~~~~~~~~~
|
|
||||||
|
|
||||||
MsgCenterPy supports various message types:
|
|
||||||
|
|
||||||
- ``MessageType.DICT``: Python dictionaries
|
|
||||||
- ``MessageType.JSON_SCHEMA``: JSON Schema objects
|
|
||||||
- ``MessageType.ROS2``: ROS2 messages (with optional dependency)
|
|
||||||
|
|
||||||
Working with ROS2 Messages
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
If you have ROS2 installed, you can work with ROS2 messages:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from std_msgs.msg import String
|
|
||||||
from msgcenterpy.instances.ros2_instance import ROS2MessageInstance
|
|
||||||
|
|
||||||
# Create ROS2 message
|
|
||||||
msg = String()
|
|
||||||
msg.data = "Hello ROS2"
|
|
||||||
|
|
||||||
# Create instance
|
|
||||||
ros2_instance = ROS2MessageInstance(msg)
|
|
||||||
|
|
||||||
# Convert to JSON Schema
|
|
||||||
json_schema_instance = ros2_instance.to_json_schema()
|
|
||||||
print(json_schema_instance.json_schema)
|
|
||||||
|
|
||||||
JSON Schema Generation
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
One of the key features is automatic JSON Schema generation:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
from msgcenterpy import MessageInstance, MessageType
|
|
||||||
|
|
||||||
# Complex nested structure
|
|
||||||
data = {
|
|
||||||
"sensor": {
|
|
||||||
"name": "temperature_01",
|
|
||||||
"readings": [23.5, 24.1, 23.8],
|
|
||||||
"metadata": {
|
|
||||||
"unit": "celsius",
|
|
||||||
"precision": 0.1
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
instance = MessageInstance.create(MessageType.DICT, data)
|
|
||||||
schema = instance.get_json_schema()
|
|
||||||
|
|
||||||
# The schema will include type information for all nested structures
|
|
||||||
|
|
||||||
Field Access and Type Information
|
|
||||||
----------------------------------
|
|
||||||
|
|
||||||
MsgCenterPy provides detailed type information and field access:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
# Access field information
|
|
||||||
field_info = instance.fields.get_field_info("sensor.name")
|
|
||||||
print(f"Field type: {field_info.type}")
|
|
||||||
print(f"Field constraints: {field_info.constraints}")
|
|
||||||
|
|
||||||
# Dynamic field access
|
|
||||||
instance.set_field("sensor.name", "temperature_02")
|
|
||||||
value = instance.get_field("sensor.name")
|
|
||||||
|
|
||||||
Error Handling
|
|
||||||
--------------
|
|
||||||
|
|
||||||
MsgCenterPy includes comprehensive error handling:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
try:
|
|
||||||
# Invalid field access
|
|
||||||
value = instance.get_field("nonexistent.field")
|
|
||||||
except FieldAccessError as e:
|
|
||||||
print(f"Field access error: {e}")
|
|
||||||
|
|
||||||
try:
|
|
||||||
# Type constraint violation
|
|
||||||
instance.set_field("sensor.readings", "invalid")
|
|
||||||
except TypeConstraintError as e:
|
|
||||||
print(f"Type error: {e}")
|
|
||||||
|
|
||||||
Next Steps
|
|
||||||
----------
|
|
||||||
|
|
||||||
- Read the :doc:`user_guide/index` for detailed usage
|
|
||||||
- Check out :doc:`examples/basic_usage` for more examples
|
|
||||||
- Explore the :doc:`api/core` documentation
|
|
||||||
- Learn about :doc:`development/contributing` if you want to contribute
|
|
||||||
@@ -1,69 +0,0 @@
|
|||||||
# Development environment setup script for MsgCenterPy (Windows PowerShell)
|
|
||||||
|
|
||||||
Write-Host "🚀 Setting up MsgCenterPy development environment..." -ForegroundColor Green
|
|
||||||
|
|
||||||
# Check if Python is available
|
|
||||||
try {
|
|
||||||
$pythonVersion = python --version
|
|
||||||
Write-Host "✅ Found: $pythonVersion" -ForegroundColor Green
|
|
||||||
} catch {
|
|
||||||
Write-Host "❌ Error: Python 3 is required but not found in PATH." -ForegroundColor Red
|
|
||||||
Write-Host "Please install Python 3.10+ and add it to your PATH." -ForegroundColor Yellow
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Install the package in development mode
|
|
||||||
Write-Host "📦 Installing package in development mode..." -ForegroundColor Blue
|
|
||||||
pip install -e .[dev]
|
|
||||||
if ($LASTEXITCODE -ne 0) {
|
|
||||||
Write-Host "❌ Failed to install package in development mode" -ForegroundColor Red
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Install pre-commit
|
|
||||||
Write-Host "🔧 Installing pre-commit..." -ForegroundColor Blue
|
|
||||||
pip install pre-commit
|
|
||||||
if ($LASTEXITCODE -ne 0) {
|
|
||||||
Write-Host "❌ Failed to install pre-commit" -ForegroundColor Red
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Install pre-commit hooks
|
|
||||||
Write-Host "🪝 Installing pre-commit hooks..." -ForegroundColor Blue
|
|
||||||
pre-commit install
|
|
||||||
if ($LASTEXITCODE -ne 0) {
|
|
||||||
Write-Host "❌ Failed to install pre-commit hooks" -ForegroundColor Red
|
|
||||||
exit 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Install pre-commit hooks for commit-msg (optional)
|
|
||||||
Write-Host "📝 Installing commit-msg hooks..." -ForegroundColor Blue
|
|
||||||
pre-commit install --hook-type commit-msg
|
|
||||||
if ($LASTEXITCODE -ne 0) {
|
|
||||||
Write-Host "⚠️ commit-msg hooks installation failed (optional)" -ForegroundColor Yellow
|
|
||||||
}
|
|
||||||
|
|
||||||
# Run pre-commit on all files to check setup
|
|
||||||
Write-Host "🔍 Running pre-commit on all files to verify setup..." -ForegroundColor Blue
|
|
||||||
pre-commit run --all-files
|
|
||||||
if ($LASTEXITCODE -eq 0) {
|
|
||||||
Write-Host "✅ Pre-commit setup completed successfully!" -ForegroundColor Green
|
|
||||||
Write-Host ""
|
|
||||||
Write-Host "🎉 You're all set! Pre-commit will now run automatically on every commit." -ForegroundColor Green
|
|
||||||
Write-Host ""
|
|
||||||
Write-Host "📋 Quick commands:" -ForegroundColor Cyan
|
|
||||||
Write-Host " • Run all hooks manually: pre-commit run --all-files" -ForegroundColor White
|
|
||||||
Write-Host " • Update hook versions: pre-commit autoupdate" -ForegroundColor White
|
|
||||||
Write-Host " • Skip hooks for one commit: git commit --no-verify" -ForegroundColor White
|
|
||||||
Write-Host " • Run tests: pytest" -ForegroundColor White
|
|
||||||
Write-Host " • Type checking: mypy msgcenterpy" -ForegroundColor White
|
|
||||||
} else {
|
|
||||||
Write-Host "⚠️ Pre-commit found some issues. Please fix them and run 'pre-commit run --all-files' again." -ForegroundColor Yellow
|
|
||||||
Write-Host "💡 Or use 'pre-commit run --all-files --show-diff-on-failure' to see what needs to be fixed." -ForegroundColor Yellow
|
|
||||||
}
|
|
||||||
|
|
||||||
Write-Host ""
|
|
||||||
Write-Host "🔗 Integration with CI:" -ForegroundColor Cyan
|
|
||||||
Write-Host " • CI will run the same pre-commit hooks" -ForegroundColor White
|
|
||||||
Write-Host " • If you skip pre-commit locally, CI will catch the issues" -ForegroundColor White
|
|
||||||
Write-Host " • Best practice: Always let pre-commit fix issues before committing" -ForegroundColor White
|
|
||||||
52
setup-dev.sh
52
setup-dev.sh
@@ -1,52 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# Development environment setup script for MsgCenterPy
|
|
||||||
|
|
||||||
set -e # Exit on any error
|
|
||||||
|
|
||||||
echo "🚀 Setting up MsgCenterPy development environment..."
|
|
||||||
|
|
||||||
# Check if Python is available
|
|
||||||
if ! command -v python3 &> /dev/null; then
|
|
||||||
echo "❌ Error: Python 3 is required but not installed."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Install the package in development mode
|
|
||||||
echo "📦 Installing package in development mode..."
|
|
||||||
pip install -e .[dev]
|
|
||||||
|
|
||||||
# Install pre-commit
|
|
||||||
echo "🔧 Installing pre-commit..."
|
|
||||||
pip install pre-commit
|
|
||||||
|
|
||||||
# Install pre-commit hooks
|
|
||||||
echo "🪝 Installing pre-commit hooks..."
|
|
||||||
pre-commit install
|
|
||||||
|
|
||||||
# Install pre-commit hooks for commit-msg (optional)
|
|
||||||
echo "📝 Installing commit-msg hooks..."
|
|
||||||
pre-commit install --hook-type commit-msg || echo "⚠️ commit-msg hooks installation failed (optional)"
|
|
||||||
|
|
||||||
# Run pre-commit on all files to check setup
|
|
||||||
echo "🔍 Running pre-commit on all files to verify setup..."
|
|
||||||
if pre-commit run --all-files; then
|
|
||||||
echo "✅ Pre-commit setup completed successfully!"
|
|
||||||
echo ""
|
|
||||||
echo "🎉 You're all set! Pre-commit will now run automatically on every commit."
|
|
||||||
echo ""
|
|
||||||
echo "📋 Quick commands:"
|
|
||||||
echo " • Run all hooks manually: pre-commit run --all-files"
|
|
||||||
echo " • Update hook versions: pre-commit autoupdate"
|
|
||||||
echo " • Skip hooks for one commit: git commit --no-verify"
|
|
||||||
echo " • Run tests: pytest"
|
|
||||||
echo " • Type checking: mypy msgcenterpy"
|
|
||||||
else
|
|
||||||
echo "⚠️ Pre-commit found some issues. Please fix them and run 'pre-commit run --all-files' again."
|
|
||||||
echo "💡 Or use 'pre-commit run --all-files --show-diff-on-failure' to see what needs to be fixed."
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
echo "🔗 Integration with CI:"
|
|
||||||
echo " • CI will run the same pre-commit hooks"
|
|
||||||
echo " • If you skip pre-commit locally, CI will catch the issues"
|
|
||||||
echo " • Best practice: Always let pre-commit fix issues before committing"
|
|
||||||
Reference in New Issue
Block a user