open_pub/MsgCenterPy
1
0
Fork 0
mirror of https://github.com/ZGCA-Forge/MsgCenterPy.git synced 2026-02-04 05:15:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

init version

Browse Source
This commit is contained in:
Xuwznln
2025-09-02 16:39:44 +08:00
commit 94f0c112e5
41 changed files with 6004 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/Makefile Normal file
View File

@@ -0,0 +1,64 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Custom targets for common operations
clean:
@echo "Cleaning build directory..."
rm -rf $(BUILDDIR)/*
html:
@echo "Building HTML documentation..."
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
livehtml:
@echo "Starting live HTML build..."
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
linkcheck:
@echo "Checking external links..."
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) $(O)
@echo
@echo "Link check complete; look for any errors in the above output."
doctest:
@echo "Running doctests..."
@$(SPHINXBUILD) -b doctest "$(SOURCEDIR)" "$(BUILDDIR)/doctest" $(SPHINXOPTS) $(O)
@echo "doctest finished; look at the results in $(BUILDDIR)/doctest."
coverage:
@echo "Checking documentation coverage..."
@$(SPHINXBUILD) -b coverage "$(SOURCEDIR)" "$(BUILDDIR)/coverage" $(SPHINXOPTS) $(O)
@echo "Coverage finished; see $(BUILDDIR)/coverage/python.txt."
latexpdf:
@echo "Building LaTeX files and running them through pdflatex..."
@$(SPHINXBUILD) -b latex "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(SPHINXOPTS) $(O)
@echo "Running LaTeX files through pdflatex..."
@make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
epub:
@echo "Building EPUB documentation..."
@$(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)/epub" $(SPHINXOPTS) $(O)
@echo
@echo "Build finished. The EPUB file is in $(BUILDDIR)/epub."

60
docs/api/core.rst Normal file
View File

@@ -0,0 +1,60 @@
Core API Reference
==================
This section documents the core components of MsgCenterPy.
MessageInstance
---------------
.. autoclass:: msgcenterpy.core.message_instance.MessageInstance
:members:
:undoc-members:
:show-inheritance:
MessageType
-----------
.. autoclass:: msgcenterpy.core.types.MessageType
:members:
:undoc-members:
:show-inheritance:
TypeInfo
--------
.. autoclass:: msgcenterpy.core.type_info.TypeInfo
:members:
:undoc-members:
:show-inheritance:
FieldAccessor
-------------
.. autoclass:: msgcenterpy.core.field_accessor.FieldAccessor
:members:
:undoc-members:
:show-inheritance:
MessageCenter
-------------
.. autoclass:: msgcenterpy.core.message_center.MessageCenter
:members:
:undoc-members:
:show-inheritance:
TypeConverter
-------------
.. autoclass:: msgcenterpy.core.type_converter.TypeConverter
:members:
:undoc-members:
:show-inheritance:
Envelopes
---------
.. automodule:: msgcenterpy.core.envelope
:members:
:undoc-members:
:show-inheritance:

135
docs/conf.py Normal file
View File

@@ -0,0 +1,135 @@
"""Configuration file for the Sphinx documentation builder.
For the full list of built-in configuration values, see the documentation:
https://www.sphinx-doc.org/en/master/usage/configuration.html
"""
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import os
import sys
sys.path.insert(0, os.path.abspath(".."))
# Import version from package
try:
from msgcenterpy import __version__
version = __version__
except ImportError:
version = "0.0.1" # fallback
project = "MsgCenterPy"
copyright = "2025, MsgCenterPy Team"
author = "MsgCenterPy Team"
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.mathjax",
"myst_parser",
]
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
language = "en"
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "sphinx_rtd_theme"
html_static_path = ["_static"]
# -- Extension configuration -------------------------------------------------
# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
# Autodoc settings
autodoc_default_options = {
"members": True,
"member-order": "bysource",
"special-members": "__init__",
"undoc-members": True,
"exclude-members": "__weakref__",
}
# Intersphinx mapping
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"numpy": ("https://numpy.org/doc/stable", None),
"pydantic": ("https://docs.pydantic.dev", None),
}
# MyST parser settings
myst_enable_extensions = [
"deflist",
"tasklist",
"dollarmath",
"amsmath",
"colon_fence",
"attrs_inline",
]
# Todo settings
todo_include_todos = True
# HTML theme options
html_theme_options = {
"canonical_url": "",
"analytics_id": "", # Provided by Google in your dashboard
"logo_only": False,
"display_version": True,
"prev_next_buttons_location": "bottom",
"style_external_links": False,
"vcs_pageview_mode": "",
"style_nav_header_background": "#2980B9",
# Toc options
"collapse_navigation": True,
"sticky_navigation": True,
"navigation_depth": 4,
"includehidden": True,
"titles_only": False,
}
# Custom sidebar
html_sidebars = {
"**": [
"about.html",
"navigation.html",
"relations.html",
"searchbox.html",
"donate.html",
]
}
# -- Custom CSS and JS -------------------------------------------------------
html_css_files = ["custom.css"]
# GitHub URL
html_context = {
"display_github": True, # Integrate GitHub
"github_user": "ZGCA-Forge", # Username
"github_repo": "MsgCenterPy", # Repo name
"github_version": "main", # Version
"conf_py_path": "/docs/", # Path in the checkout to the docs root
}

160
docs/development/contributing.rst Normal file
View File

@@ -0,0 +1,160 @@
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:
.. code-block:: bash
git clone https://github.com/YOUR-USERNAME/MsgCenterPy.git
cd MsgCenterPy
pip install -e .[dev]
4. Set up pre-commit hooks:
.. code-block:: bash
pre-commit install
Code Style and Quality
----------------------
We use several tools to maintain code quality:
- **Black**: Code formatting
- **isort**: Import sorting
- **mypy**: Type checking
- **pytest**: Testing
Run quality checks:
.. code-block:: bash
# Format code
black msgcenterpy tests
isort msgcenterpy tests
# Type checking
mypy msgcenterpy
# Run tests
pytest
Testing
-------
Please ensure all tests pass and add tests for new features:
.. code-block:: bash
# Run all tests
pytest
# Run with coverage
pytest -v
# Run specific test file
pytest tests/test_specific_module.py
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**
.. code-block:: bash
# Bug fixes (0.0.1 → 0.0.2)
bump2version patch
# New features (0.0.2 → 0.1.0)
bump2version minor
# 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:
.. 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
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

225
docs/examples/basic_usage.rst Normal file
View File

@@ -0,0 +1,225 @@
Basic Usage Examples
====================
This page contains basic usage examples to help you get started with MsgCenterPy.
Creating Message Instances
---------------------------
Dictionary Messages
~~~~~~~~~~~~~~~~~~~
.. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
# Create from dictionary
dict_instance = MessageInstance.create(MessageType.DICT, {"key": "value"})
# Convert to JSON Schema instance
schema_instance = dict_instance.to_json_schema()
# Get the actual schema
schema = schema_instance.json_schema
print(schema)
Error Handling
--------------
Common Error Scenarios
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
from msgcenterpy.core.exceptions import FieldAccessError, TypeConstraintError
# Field access errors
try:
value = instance.get_field("nonexistent_field")
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
def safe_get_field(instance, field_name, default=None):
try:
return instance.get_field(field_name)
except FieldAccessError:
return default
# 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:
.. code-block:: python
from msgcenterpy import MessageInstance, MessageType
from msgcenterpy.core.exceptions import FieldAccessError, TypeConstraintError
import json
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
}
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"
}
result = process_sensor_data(sensor_data)
if result["success"]:
print("Processing successful!")
print(f"Average reading: {result['processed_data']['average']}")
else:
print(f"Processing failed: {result['error']}")

176
docs/index.rst Normal file
View File

@@ -0,0 +1,176 @@
Welcome to MsgCenterPy's Documentation!
========================================
.. image:: https://img.shields.io/badge/license-Apache--2.0-blue.svg
:target: https://github.com/ZGCA-Forge/MsgCenterPy/blob/main/LICENSE
:alt: License
.. image:: https://img.shields.io/pypi/v/msgcenterpy.svg
:target: https://pypi.org/project/msgcenterpy/
:alt: PyPI version
.. image:: https://img.shields.io/pypi/pyversions/msgcenterpy.svg
:target: https://pypi.org/project/msgcenterpy/
:alt: Python versions
MsgCenterPy is a unified message conversion system based on unified instance manager architecture,
supporting seamless conversion between **ROS2**, **Pydantic**, **Dataclass**, **JSON**, **Dict**,
**YAML** and **JSON Schema**.
✨ Key Features
---------------
🔄 **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
~~~~~~~~~~~~
.. code-block:: bash
pip install msgcenterpy
Basic Usage
~~~~~~~~~~~
.. code-block:: python
from msgcenterpy import MessageInstance, MessageType
# Create message instance from dictionary
data = {
"name": "sensor_001",
"readings": [1.0, 2.0, 3.0],
"active": True
}
dict_instance = MessageInstance.create(MessageType.DICT, data)
# Generate JSON Schema
schema = dict_instance.get_json_schema()
print(schema)
🎯 Supported Formats
--------------------
.. list-table::
:header-rows: 1
:widths: 20 20 20 20 20
* - Format
- Read
- Write
- JSON Schema
- Type Constraints
* - ROS2
- ✅
- ✅
- ✅
- ✅
* - JSON Schema
- ✅
- ✅
- ✅
- ✅
* - Pydantic
- 开发中
- 开发中
- 开发中
- 开发中
* - Dataclass
- 开发中
- 开发中
- 开发中
- 开发中
* - JSON
- 开发中
- 开发中
- ✅
- ⚡
* - Dict
- 开发中
- 开发中
- ✅
- ⚡
* - YAML
- 开发中
- 开发中
- ✅
- ⚡
.. note::
✅ Fully Supported | 开发中 In Development | ⚡ Basic Support
📚 Documentation Contents
-------------------------
.. toctree::
:maxdepth: 2
:caption: User Guide
installation
quickstart
user_guide/index
.. toctree::
:maxdepth: 2
:caption: Examples
examples/basic_usage
examples/ros2_examples
examples/json_schema_examples
.. toctree::
:maxdepth: 2
:caption: API Reference
api/core
api/instances
api/utils
.. toctree::
:maxdepth: 1
:caption: Development
development/contributing
development/testing
development/changelog
.. toctree::
:maxdepth: 1
:caption: Community
community/support
community/faq
Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
🤝 Community & Support
======================
- 📖 **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.

122
docs/installation.rst Normal file
View File

@@ -0,0 +1,122 @@
Installation Guide
==================
This guide will help you install MsgCenterPy in different environments.
Quick Installation
------------------
The easiest way to install MsgCenterPy is using pip:
.. code-block:: bash
pip install msgcenterpy
Requirements
------------
- Python 3.10 or higher (Python 3.11+ recommended for optimal ROS2 compatibility)
- Operating System: Linux, macOS, or Windows
Optional Dependencies
---------------------
ROS2 Support
~~~~~~~~~~~~
To use ROS2 message conversion features:
.. code-block:: bash
pip install msgcenterpy[ros2]
This will install:
- ``rosidl-runtime-py>=0.10.0``
- ``rclpy>=3.0.0``
.. warning::
**ROS2 Python Version Compatibility Notice**
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.
Troubleshooting
---------------
Common Issues
~~~~~~~~~~~~~
1. **Python Version**: Ensure you're using Python 3.10 or higher (3.11+ recommended for optimal ROS2 compatibility)
2. **ROS2 Dependencies**: ROS2 support requires a proper ROS2 installation
3. **Virtual Environments**: Consider using virtual environments for isolation
If you encounter any issues, please check the `GitHub Issues <https://github.com/ZGCA-Forge/MsgCenterPy/issues>`_ page.

138
docs/quickstart.rst Normal file
View File

@@ -0,0 +1,138 @@
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

14
docs/requirements.txt Normal file
View File

@@ -0,0 +1,14 @@
# Documentation build requirements
sphinx>=5.0.0
sphinx_rtd_theme>=1.0.0
myst-parser>=0.18.0
# For autodoc generation
sphinx-autodoc-typehints>=1.19.0
# Additional Sphinx extensions
sphinx-copybutton>=0.5.0
sphinx-tabs>=3.4.0
# For parsing project dependencies
packaging>=21.0