mirror of
https://github.com/ZGCA-Forge/MsgCenterPy.git
synced 2026-02-04 05:15:14 +00:00
Update docs
This commit is contained in:
Xuwznln
@@ -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 <https://github.com/ZGCA-Forge/MsgCenterPy/blob/main/.github/CONTRIBUTING.md>`_ on GitHub.
|
||||
|
||||
Quick Links
|
||||
-----------
|
||||
|
||||
- `GitHub Repository <https://github.com/ZGCA-Forge/MsgCenterPy>`_
|
||||
- `Issue Tracker <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_
|
||||
- `Pull Requests <https://github.com/ZGCA-Forge/MsgCenterPy/pulls>`_
|
||||
- `Discussions <https://github.com/ZGCA-Forge/MsgCenterPy/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 <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
|
||||
---------------------------
|
||||
|
||||
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']}")
|
||||
|
||||
102
docs/index.rst
102
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 <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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user