diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f91f110..d9df9fe 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,6 +5,18 @@ on: branches: [main] pull_request: 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 permissions: @@ -25,6 +37,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + ref: ${{ github.event.inputs.branch || github.ref }} - name: Set up Python uses: actions/setup-python@v5 @@ -42,7 +56,7 @@ jobs: - name: Setup Pages id: pages 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 run: | @@ -51,13 +65,13 @@ jobs: - name: Upload artifact 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: path: docs/_build/html - # Deploy to GitHub Pages (only on main branch) + # Deploy to GitHub Pages 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: name: github-pages url: ${{ steps.deployment.outputs.page_url }} diff --git a/README.md b/README.md index e1615b1..2155900 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![PyPI version](https://badge.fury.io/py/msgcenterpy.svg)](https://badge.fury.io/py/msgcenterpy) [![Python versions](https://img.shields.io/pypi/pyversions/msgcenterpy.svg)](https://pypi.org/project/msgcenterpy/) -[![Build Status](https://github.com/ZGCA-Forge/MsgCenterPy/workflows/CI/badge.svg)](https://github.com/ZGCA-Forge/MsgCenterPy/actions) +[![Build Status](https://github.com/ZGCA-Forge/MsgCenterPy/actions/workflows/ci.yml/badge.svg)](https://github.com/ZGCA-Forge/MsgCenterPy/actions) [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-brightgreen)](https://zgca-forge.github.io/MsgCenterPy/) [![GitHub stars](https://img.shields.io/github/stars/ZGCA-Forge/MsgCenterPy.svg?style=social&label=Star)](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 | 类型约束 | -| ----------- | ------ | ------ | ----------- | -------- | -| ROS2 | ✅ | ✅ | ✅ | ✅ | -| JSON Schema | ✅ | ✅ | ✅ | ✅ | -| Pydantic | 开发中 | 开发中 | 开发中 | 开发中 | -| Dataclass | 开发中 | 开发中 | 开发中 | 开发中 | -| JSON | 开发中 | 开发中 | 开发中 | 开发中 | -| Dict | 开发中 | 开发中 | 开发中 | 开发中 | -| YAML | 开发中 | 开发中 | 开发中 | 开发中 | +## Installation -## 📦 安装 - -### 基础安装 +### Basic Installation ```bash pip install msgcenterpy ``` -### 包含可选依赖 +### With Optional Dependencies ```bash -# 安装 ROS2 支持 -conda install - -# 安装开发工具 -pip install msgcenterpy[dev] - -# 安装文档工具 -pip install msgcenterpy[docs] - -# 安装所有依赖 -pip install msgcenterpy[all] +# Install ROS2 support +conda install ros-humble-ros-core ros-humble-std-msgs ros-humble-geometry-msgs -c robostack-staging ``` -### 从源码安装 +### From Source ```bash git clone https://github.com/ZGCA-Forge/MsgCenterPy.git @@ -64,98 +53,13 @@ cd MsgCenterPy pip install -e .[dev] ``` -## 🔧 快速开始 +## Quick Start -### 基础使用 +Please visit: [https://zgca-forge.github.io/MsgCenterPy/](https://zgca-forge.github.io/MsgCenterPy/) -```python -from msgcenterpy import MessageInstance, MessageType +## Development -# 从字典创建消息实例 -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 -``` - -## 🛠️ 开发 - -### 开发环境设置 +### Development Environment Setup ```bash git clone https://github.com/ZGCA-Forge/MsgCenterPy.git @@ -164,73 +68,16 @@ pip install -e .[dev] pre-commit install ``` -### 代码质量 +For API documentation, please refer to Quick Start -```bash -# 代码格式化 -black msgcenterpy tests -isort msgcenterpy tests +## License -# 类型检查 -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 做出贡献的开发者！ - -[![Contributors](https://contrib.rocks/image?repo=ZGCA-Forge/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 验证 +This project is licensed under Apache-2.0 License - see the [LICENSE](LICENSE) file for details. ---
-**[⭐ 给个 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
diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst index a18bf83..c13412d 100644 --- a/docs/development/contributing.rst +++ b/docs/development/contributing.rst @@ -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. -For detailed contribution guidelines, please see our `Contributing Guide `_ on GitHub. - Quick Links ----------- - `GitHub Repository `_ - `Issue Tracker `_ - `Pull Requests `_ -- `Discussions `_ Development Setup ----------------- 1. Fork the repository on GitHub -2. Clone your fork locally -3. Install in development mode: +2. Clone your fork locally: .. code-block:: bash - git clone https://github.com/YOUR-USERNAME/MsgCenterPy.git + git clone https://github.com/YOUR_USERNAME/MsgCenterPy.git 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 - 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 ---------------------- -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 +- **flake8**: Code linting - **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 - # Format code - black msgcenterpy tests - isort msgcenterpy tests - - # Type checking - mypy msgcenterpy - - # Run tests - pytest + # Run all pre-commit hooks + pre-commit run --all-files 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 # Run all tests pytest - # Run with coverage + # Run with verbose output pytest -v - # Run specific test file - pytest tests/test_specific_module.py +**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. 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. - -**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** +This project uses `bump2version` for version management. It's automatically installed with dev dependencies. .. code-block:: bash @@ -107,54 +101,25 @@ Version configuration is stored in `.bumpversion.cfg`: # Breaking changes (0.1.0 → 1.0.0) bump2version major -**Release Workflow** - -1. Make your changes and commit them -2. Choose appropriate version bump type -3. Run bump2version command -4. Push changes and tags: +After bumping version, push changes and tags: .. code-block:: bash 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 ------------------ 1. Create a new branch for your feature/fix -2. Make your changes -3. Add tests for new functionality -4. Ensure all tests pass -5. Update documentation if needed -6. Submit a pull request - -Pull Request Guidelines ------------------------ - -- Use descriptive titles and descriptions -- Reference related issues -- Include tests for new features -- Update documentation as needed -- Follow the existing code style +2. Make your changes and add tests +3. Run tests to ensure everything works +4. Update documentation if needed +5. Submit a pull request with: + - Descriptive title and description + - Reference to related issues + - Tests for new features Getting Help ------------ -If you need help: - - Check existing `Issues `_ -- Start a `Discussion `_ -- Contact the maintainers diff --git a/docs/examples/basic_usage.rst b/docs/examples/basic_usage.rst index 20f9300..f852cea 100644 --- a/docs/examples/basic_usage.rst +++ b/docs/examples/basic_usage.rst @@ -6,220 +6,161 @@ This page contains basic usage examples to help you get started with MsgCenterPy Creating Message Instances --------------------------- -Dictionary Messages -~~~~~~~~~~~~~~~~~~~ +ROS2 Message Instances +---------------------- -.. code-block:: python - - 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 +Working with ROS2 Messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python - # Create from dictionary - dict_instance = MessageInstance.create(MessageType.DICT, {"key": "value"}) + from msgcenterpy.instances.ros2_instance import ROS2MessageInstance + from std_msgs.msg import String, Float64MultiArray + from geometry_msgs.msg import Point, Pose - # Convert to JSON Schema instance - schema_instance = dict_instance.to_json_schema() + # Simple String message + string_msg = String() + string_msg.data = "Hello ROS2" + ros2_instance = ROS2MessageInstance(string_msg) - # Get the actual schema - schema = schema_instance.json_schema - print(schema) + # Access and modify field + ros2_instance.data = "Updated message" + 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 - 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 - try: - value = instance.get_field("nonexistent_field") - except FieldAccessError as e: - print(f"Field not found: {e}") + # Set data from dictionary + new_data = {"data": "dictionary_value"} + ros2_instance.set_python_dict(new_data) - # Type constraint errors - try: - instance.set_field("active", "invalid_boolean") - except TypeConstraintError as e: - print(f"Invalid type: {e}") - # Graceful handling - def safe_get_field(instance, field_name, default=None): - try: - return instance.get_field(field_name) - except FieldAccessError: - return default +JSON Schema Message Instances +----------------------------- - # Usage - 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: +Creating JSON Schema Instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python - from msgcenterpy import MessageInstance, MessageType - from msgcenterpy.core.exceptions import FieldAccessError, TypeConstraintError - import json + from msgcenterpy.instances.json_schema_instance import JSONSchemaMessageInstance - def process_sensor_data(sensor_data): - """Process sensor data with proper error handling.""" - try: - # Create instance - instance = MessageInstance.create(MessageType.DICT, sensor_data) - - # Validate required fields - required_fields = ["id", "type", "readings"] - for field in required_fields: - if not instance.fields.has_field(field): - raise ValueError(f"Missing required field: {field}") - - # 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 + # Define JSON Schema + schema = { + "type": "object", + "properties": { + "name": {"type": "string", "minLength": 2, "maxLength": 50}, + "age": {"type": "integer", "minimum": 0, "maximum": 150}, + "active": {"type": "boolean"}, + "tags": { + "type": "array", + "items": {"type": "string"}, + "minItems": 1, + "maxItems": 10 } - - except (FieldAccessError, TypeConstraintError, ValueError) as e: - 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" + }, + "required": ["name"] } - result = process_sensor_data(sensor_data) - if result["success"]: - print("Processing successful!") - print(f"Average reading: {result['processed_data']['average']}") + # Sample data + data = { + "name": "John Doe", + "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: - 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']}") diff --git a/docs/index.rst b/docs/index.rst index c0a4a12..d1a801c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,37 +13,40 @@ Welcome to MsgCenterPy's Documentation! :target: https://pypi.org/project/msgcenterpy/ :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**, **YAML** and **JSON Schema**. -✨ Key Features +📦 Installation --------------- -🔄 **Unified Conversion**: Supports bidirectional conversion between multiple message formats - -🤖 **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 -~~~~~~~~~~~~ +Basic Installation +~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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 ~~~~~~~~~~~ @@ -86,33 +89,41 @@ Basic Usage - ✅ - ✅ * - Pydantic - - 开发中 - - 开发中 - - 开发中 - - 开发中 + - 🚧 + - 🚧 + - 🚧 + - 🚧 * - Dataclass - - 开发中 - - 开发中 - - 开发中 - - 开发中 + - 🚧 + - 🚧 + - 🚧 + - 🚧 * - JSON - - 开发中 - - 开发中 - - ✅ - - ⚡ + - 🚧 + - 🚧 + - 🚧 + - 🚧 * - Dict - - 开发中 - - 开发中 - - ✅ - - ⚡ + - 🚧 + - 🚧 + - 🚧 + - 🚧 * - YAML - - 开发中 - - 开发中 - - ✅ - - ⚡ + - 🚧 + - 🚧 + - 🚧 + - 🚧 .. 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 ------------------------- @@ -122,7 +133,6 @@ Basic Usage :caption: User Guide installation - quickstart user_guide/index .. toctree:: @@ -168,9 +178,3 @@ Indices and Tables - 📖 **Documentation**: https://zgca-forge.github.io/MsgCenterPy/ - 🐛 **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 `_ file for details. diff --git a/docs/installation.rst b/docs/installation.rst index c3f8fd0..2848c15 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -3,8 +3,8 @@ Installation Guide This guide will help you install MsgCenterPy in different environments. -Quick Installation ------------------- +Basic Installation +------------------- 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) - Operating System: Linux, macOS, or Windows -Optional Dependencies ---------------------- +With Optional Dependencies +-------------------------- ROS2 Support ~~~~~~~~~~~~ -To use ROS2 message conversion features: +To use ROS2 message conversion features, install ROS2 packages via conda: .. 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: -- ``rosidl-runtime-py>=0.10.0`` -- ``rclpy>=3.0.0`` +This provides the necessary ROS2 packages for message type conversion and integration. -.. warning:: - **ROS2 Python Version Compatibility Notice** +.. note:: + **ROS2 Installation Notes** - While Python 3.10+ is supported by this package, ROS2 official binary distributions - may have varying support across Python versions. You might need to: - - - 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. + - We recommend using conda with the robostack-staging channel for ROS2 packages + - This approach provides better Python version compatibility + - Alternative ROS2 installation methods are also supported if you have them set up Troubleshooting --------------- @@ -115,7 +46,7 @@ Troubleshooting 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 3. **Virtual Environments**: Consider using virtual environments for isolation diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index 0358981..0000000 --- a/docs/quickstart.rst +++ /dev/null @@ -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 diff --git a/setup-dev.ps1 b/setup-dev.ps1 deleted file mode 100644 index dac7bdd..0000000 --- a/setup-dev.ps1 +++ /dev/null @@ -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 diff --git a/setup-dev.sh b/setup-dev.sh deleted file mode 100644 index 18717e8..0000000 --- a/setup-dev.sh +++ /dev/null @@ -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"