cydr 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. cydr-0.1.0/LICENCE +21 -0
  2. cydr-0.1.0/MANIFEST.in +2 -0
  3. cydr-0.1.0/PKG-INFO +228 -0
  4. cydr-0.1.0/README.md +194 -0
  5. cydr-0.1.0/cydr/__init__.py +28 -0
  6. cydr-0.1.0/cydr/_every_supported_cython.pxd +471 -0
  7. cydr-0.1.0/cydr/_every_supported_cython.pyx +1820 -0
  8. cydr-0.1.0/cydr/_message_ops.py +220 -0
  9. cydr-0.1.0/cydr/_runtime.py +772 -0
  10. cydr-0.1.0/cydr/_warmup.py +63 -0
  11. cydr-0.1.0/cydr/cython_generator.py +724 -0
  12. cydr-0.1.0/cydr/idl.py +65 -0
  13. cydr-0.1.0/cydr/py.typed +1 -0
  14. cydr-0.1.0/cydr/schema_types.py +204 -0
  15. cydr-0.1.0/cydr/structs.py +216 -0
  16. cydr-0.1.0/cydr/types.py +83 -0
  17. cydr-0.1.0/cydr.egg-info/PKG-INFO +228 -0
  18. cydr-0.1.0/cydr.egg-info/SOURCES.txt +21 -0
  19. cydr-0.1.0/cydr.egg-info/dependency_links.txt +1 -0
  20. cydr-0.1.0/cydr.egg-info/requires.txt +7 -0
  21. cydr-0.1.0/cydr.egg-info/top_level.txt +1 -0
  22. cydr-0.1.0/pyproject.toml +60 -0
  23. cydr-0.1.0/setup.cfg +4 -0
cydr-0.1.0/LICENCE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Elian NEPPEL
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
cydr-0.1.0/MANIFEST.in ADDED
@@ -0,0 +1,2 @@
1
+ include README.md
2
+ recursive-include cydr *.pxd *.pyx py.typed
cydr-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,228 @@
1
+ Metadata-Version: 2.4
2
+ Name: cydr
3
+ Version: 0.1.0
4
+ Summary: A fast, pythonic, focused XCDR1 serializer/deserializer for Python with a schema API and just-in-time compilation.
5
+ Author-email: Elian NEPPEL <elian.dev@posteo.com>
6
+ License-Expression: MIT
7
+ Keywords: cdr,xcdr,cython,codec,serialization
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Operating System :: Microsoft :: Windows
11
+ Classifier: Operating System :: MacOS
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Programming Language :: Cython
20
+ Classifier: Topic :: Software Development :: Code Generators
21
+ Classifier: Topic :: System :: Networking
22
+ Classifier: Topic :: Scientific/Engineering
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.10
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENCE
27
+ Requires-Dist: Cython<4,>=3.0
28
+ Requires-Dist: msgspec<1,>=0.20.0
29
+ Requires-Dist: numpy<3,>=1.26
30
+ Requires-Dist: np2typing<3,>=2.6.3
31
+ Provides-Extra: dev
32
+ Requires-Dist: cyclonedds-idl<0.2,>=0.1.0; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+ # `cydr` Cython CDR
36
+
37
+ | Requirements | Compatibility | Tests Matrix |
38
+ |---|:---|:---:|
39
+ | [![python](https://img.shields.io/badge/Python-3.10--3.14-%20blue?logo=python&logoColor=white)](./pyproject.toml) <br> [![numpy](https://img.shields.io/badge/NumPy-1.26%20%7C%202.x-%20blue?logo=numpy&logoColor=white)](./pixi.toml) <br> [![mit](https://img.shields.io/badge/License-MIT-gold)](https://opensource.org/license/mit) | [![linux](https://img.shields.io/badge/OS-Linux-black?logo=linux&logoColor=white)](./pixi.toml) <br> [![windows](https://img.shields.io/badge/OS-Windows-black?logo=windows)](./pixi.toml) <br> [![macos](https://img.shields.io/badge/OS-macOS-black?logo=apple)](./pixi.toml) <br> [![xcdr1](https://img.shields.io/badge/Wire-XCDR1-blue)](./README.md#runtime-conventions) | Python: `3.10`, `3.11`, `3.12`, `3.13`, `3.14` <br> NumPy: `1.26`, `2.x`<br> [![Tests](https://github.com/2lian/cydr/actions/workflows/tests.yml/badge.svg)](https://github.com/2lian/cydr/actions/workflows/tests.yml)|
40
+
41
+ `cydr` is a fast, pythonic, focused `XCDR1` serializer/deserializer for Python with a schema API and just-in-time compilation. After defining your message schema with a Python class, `cydr` generates a Cython codec and compiles it down to C unlocking sub-microsecond operations.
42
+
43
+ > [!NOTE]
44
+ > A working C compiler toolchain is required at runtime.
45
+
46
+ Priorities:
47
+
48
+ 1. SPEED
49
+ 2. Pythonic-style
50
+ 3. JIT compilation
51
+
52
+ Runnable examples:
53
+
54
+ - [`examples/roundtrip_custom_message.py`](examples/roundtrip_custom_message.py) for the minimal low-level nested-dict interface
55
+ - [`examples/roundtrip_xcdrstruct_message.py`](examples/roundtrip_xcdrstruct_message.py) for the higher-level `XcdrStruct` interface based on [`msgspec`](https://github.com/jcrist/msgspec)
56
+
57
+ > [!WARNING]
58
+ > `cydr` prioritizes speed and therefore supports only a focused subset of XCDR1: little-endian XCDR1, plain nested structs, and fixed arrays / sequences of scalars and strings.
59
+ >
60
+ > To stay fast, `cydr` is exclusively based on numpy and opinionated about runtime types. In particular, schema `string` means UTF-8 `bytes` at runtime, not Python `str`.
61
+ >
62
+ > Constraints:
63
+ > - `string` fields are `bytes`, and string arrays / sequences are NumPy arrays with `np.bytes_` dtype. However this datastructure is not optimal for all applications, hence:
64
+ > - You can alternatively pass `list[bytes]` for encoding.
65
+ > - You can alternatively decode into `list[bytes]` or raw C representation.
66
+ > - Arrays and sequences must be 1D NumPy arrays with the matching dtype
67
+ > - Collections of strings are much slower than numeric arrays, thus large arrays / sequences of strings should be avoided if speed matters. One long `string` entry is fine.
68
+ > - Collections of schemas are not supported, only collections of primitive types.
69
+ > - Enums, unions, optionals, bounded strings, `char` / `wchar`, XCDR2 mutable or appendable encodings, and big-endian targets are not supported
70
+ >
71
+ > If you need anything outside this subset, use `cyclonedds_idl` directly. Contributions to extend our subset are however welcome!
72
+
73
+ ## Benchmarks
74
+
75
+ Those benchmarks were performed on `JointState` messages containing 3 sequence of floats, 1 sequence of strings, one nested `Header` (containing a string, and another nested `Time` with 2 integers). The `Count` row of table idicates the length of the 4 sequences.
76
+
77
+ #### Serialize
78
+
79
+ | Case | Count | Bytes | Implementation | Median | Speedup |
80
+ |---|---:|---:|---|---:|---:|
81
+ | small | 8 | 372 | `cydr_dict` | `2.22 μs` | `6.53x` |
82
+ | small | 8 | 372 | `cydr_struct` | `1.99 μs` | `7.05x` |
83
+ | small | 8 | 372 | `cyclonedds_idl` | `14.01 μs` | `1.00x` |
84
+ | large | 10000 | 400052 | `cydr_dict` | `55.07 μs` | `164.55x` |
85
+ | large | 10000 | 400052 | `cydr_struct` | `54.70 μs` | `164.57x` |
86
+ | large | 10000 | 400052 | `cyclonedds_idl` | `8993.45 μs` | `1.00x` |
87
+
88
+ #### Deserialize
89
+
90
+ | Case | Count | Bytes | Implementation | Median | Speedup |
91
+ |---|---:|---:|---|---:|---:|
92
+ | small | 8 | 372 | `cydr_dict` | `3.67 μs` | `4.21x` |
93
+ | small | 8 | 372 | `cydr_struct` | `2.84 μs` | `5.25x` |
94
+ | small | 8 | 372 | `cyclonedds_idl` | `14.80 μs` | `1.00x` |
95
+ | large | 10000 | 400052 | `cydr_dict` | `46.63 μs` | `170.36x` |
96
+ | large | 10000 | 400052 | `cydr_struct` | `41.01 μs` | `172.04x` |
97
+ | large | 10000 | 400052 | `cyclonedds_idl` | `7055.84 μs` | `1.00x` |
98
+
99
+ ## Quick Start
100
+
101
+ ```python
102
+ from typing import Any
103
+ import msgspec
104
+ import numpy as np
105
+ from nptyping import Bytes, Float64, NDArray
106
+
107
+ from cydr.idl import XcdrStruct
108
+ from cydr.types import int32, string, uint32
109
+
110
+ # Define adn use your message schema using a simple python class
111
+ # Type hints (`: int32` / `: uint32`) describe the cdr type of the field
112
+ class Time(XcdrStruct):
113
+ sec: int32 = np.int32(0)
114
+ nanosec: uint32 = np.uint32(0)
115
+
116
+ # Create more schemas using one you previously created
117
+ class Header(XcdrStruct):
118
+ stamp: Time = msgspec.field(default_factory=Stamp)
119
+ frame_id: string = b""
120
+
121
+ # And also define collections (arrays of set/varialbe length) using numpy and nptyping
122
+ class JointState(XcdrStruct):
123
+ header: Header = msgspec.field(default_factory=Header)
124
+ name: NDArray[Any, Bytes] = msgspec.field(
125
+ default_factory=lambda: np.array([], dtype=np.bytes_)
126
+ )
127
+ position: NDArray[Any, Float64] = msgspec.field(
128
+ default_factory=lambda: np.array([], dtype=np.float64)
129
+ )
130
+ velocity: NDArray[Any, Float64] = msgspec.field(
131
+ default_factory=lambda: np.array([], dtype=np.float64)
132
+ )
133
+ effort: NDArray[Any, Float64] = msgspec.field(
134
+ default_factory=lambda: np.array([], dtype=np.float64)
135
+ )
136
+
137
+ # Optional: forces caching and compilation of the schema
138
+ JointState.brew()
139
+
140
+ # Instatiate a message with its nested components and arrays
141
+ message = JointState(
142
+ header=Header(
143
+ stamp=Stamp(sec=np.int32(10), nanosec=np.uint32(123)),
144
+ frame_id=b"map",
145
+ ),
146
+ name=np.array([b"joint_a", b"joint_b"], dtype=np.bytes_),
147
+ position=np.array([1.0, 2.0], dtype=np.float64),
148
+ )
149
+
150
+ # Encode / Decode
151
+ payload = message.serialize()
152
+ decoded = JointState.deserialize(payload)
153
+ ```
154
+
155
+ ## Schema Types
156
+ - **WIRE** -> **Python**
157
+
158
+ #### Primitive types
159
+ - `boolean` -> `np.bool_`
160
+ - `byte`, `uint8` -> `np.uint8`
161
+ - `int8` -> `np.int8`
162
+ - `int16` -> `np.int16`
163
+ - `uint16` -> `np.uint16`
164
+ - `int32` -> `np.int32`
165
+ - `uint32` -> `np.uint32`
166
+ - `int64` -> `np.int64`
167
+ - `uint64` -> `np.uint64`
168
+ - `float32` -> `np.float32`
169
+ - `float64` -> `np.float64`
170
+ - `string` -> UTF-8 `bytes`
171
+
172
+ #### Collection types
173
+ - `Sequence[Primitive]` -> `NDArray[Any, dtype]` defines a variable-length 1D collection of one primitive dtype.
174
+ - `Array[n, Primitive]` -> `NDArray[Shape["n"], dtype]` defines a fixed-length 1D collection of one primitive dtype.
175
+ - `Sequence[string]` -> `NDArray[Any, Bytes]` Represent a collection of strings with a numpy array of `np.bytes_` by default.
176
+ - When deserializing you can choose the representation using the Enum `StringCollectionMode`. `.LIST` mode (`list[bytes]`) is more performant from small arrays, or you can use the most performant `.RAW` mode, to manipulate a `list` like C wrapper directly.
177
+ - When serializing, you can either pass `list[bytes]` or `array[np.bytes_]`
178
+
179
+ ## Cache
180
+
181
+ Generated codecs are cached by the hash of the flattened field-type sequence.
182
+
183
+ - Default cache dir: `./.cydr_cache`
184
+ - Override globally with `CYDR_CACHE_DIR=/path/to/cache`
185
+
186
+ # Benchmarks per primitives
187
+
188
+ | Primitive | Kind | Size | Count/Len | Payload Bytes | Dict Ser μs | Struct Ser μs | Cyclone Ser μs | Dict Deser μs | Struct Deser μs | Cyclone Deser μs |
189
+ |---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
190
+ | `boolean` | `scalar` | `scalar` | 1 | 5 | 0.41 | 0.63 | 2.09 | 0.83 | 0.73 | 2.05 |
191
+ | `boolean` | `array` | `small` | 16 | 20 | 0.58 | 0.83 | 2.51 | 0.91 | 0.80 | 2.18 |
192
+ | `boolean` | `array` | `big` | 250000 | 250004 | 7.55 | 7.81 | 3117.59 | 4.75 | 4.82 | 961.79 |
193
+ | `byte` | `scalar` | `scalar` | 1 | 5 | 0.43 | 0.65 | 2.11 | 0.77 | 0.71 | 2.03 |
194
+ | `byte` | `array` | `small` | 16 | 20 | 0.65 | 0.95 | 2.22 | 1.00 | 0.91 | 2.10 |
195
+ | `byte` | `array` | `big` | 250000 | 250004 | 7.60 | 7.88 | 190.03 | 4.96 | 4.99 | 15.08 |
196
+ | `int8` | `scalar` | `scalar` | 1 | 5 | 0.48 | 0.77 | 2.37 | 0.90 | 0.81 | 2.31 |
197
+ | `int8` | `array` | `small` | 16 | 20 | 0.65 | 0.93 | 2.91 | 0.96 | 0.92 | 2.43 |
198
+ | `int8` | `array` | `big` | 250000 | 250004 | 9.06 | 9.40 | 5571.20 | 5.07 | 5.01 | 2017.53 |
199
+ | `uint8` | `scalar` | `scalar` | 1 | 5 | 0.42 | 0.64 | 2.08 | 0.78 | 0.71 | 2.06 |
200
+ | `uint8` | `array` | `small` | 16 | 20 | 0.58 | 0.93 | 2.23 | 0.93 | 0.78 | 1.90 |
201
+ | `uint8` | `array` | `big` | 250000 | 250004 | 7.67 | 7.91 | 190.90 | 5.00 | 5.03 | 16.97 |
202
+ | `int16` | `scalar` | `scalar` | 1 | 6 | 0.42 | 0.66 | 2.09 | 0.81 | 0.72 | 2.06 |
203
+ | `int16` | `array` | `small` | 16 | 36 | 0.58 | 0.83 | 2.51 | 0.81 | 0.81 | 2.17 |
204
+ | `int16` | `array` | `big` | 250000 | 500004 | 18.11 | 18.61 | 7405.62 | 12.76 | 12.73 | 3236.44 |
205
+ | `uint16` | `scalar` | `scalar` | 1 | 6 | 0.50 | 0.76 | 2.46 | 0.83 | 0.81 | 2.35 |
206
+ | `uint16` | `array` | `small` | 16 | 36 | 0.66 | 0.95 | 2.81 | 0.92 | 0.92 | 2.07 |
207
+ | `uint16` | `array` | `big` | 250000 | 500004 | 15.48 | 15.99 | 6504.11 | 10.82 | 10.90 | 2721.29 |
208
+ | `int32` | `scalar` | `scalar` | 1 | 8 | 0.43 | 0.66 | 2.10 | 0.78 | 0.71 | 2.06 |
209
+ | `int32` | `array` | `small` | 16 | 68 | 0.56 | 0.84 | 2.53 | 0.80 | 0.81 | 2.19 |
210
+ | `int32` | `array` | `big` | 250000 | 1000004 | 45.15 | 53.37 | 7345.25 | 39.06 | 39.71 | 2821.39 |
211
+ | `uint32` | `scalar` | `scalar` | 1 | 8 | 0.43 | 0.67 | 2.14 | 0.78 | 0.72 | 2.09 |
212
+ | `uint32` | `array` | `small` | 16 | 68 | 0.58 | 0.82 | 2.53 | 0.80 | 0.81 | 2.18 |
213
+ | `uint32` | `array` | `big` | 250000 | 1000004 | 44.25 | 45.20 | 6672.12 | 32.67 | 32.86 | 3102.01 |
214
+ | `int64` | `scalar` | `scalar` | 1 | 12 | 0.43 | 0.67 | 2.15 | 0.79 | 0.71 | 2.05 |
215
+ | `int64` | `array` | `small` | 16 | 132 | 0.68 | 0.96 | 2.91 | 0.93 | 0.94 | 2.47 |
216
+ | `int64` | `array` | `big` | 250000 | 2000004 | 124.78 | 126.39 | 7625.85 | 80.02 | 79.53 | 3187.78 |
217
+ | `uint64` | `scalar` | `scalar` | 1 | 12 | 0.52 | 0.80 | 2.46 | 0.77 | 0.72 | 2.10 |
218
+ | `uint64` | `array` | `small` | 16 | 132 | 0.67 | 0.95 | 2.90 | 0.93 | 0.92 | 2.46 |
219
+ | `uint64` | `array` | `big` | 250000 | 2000004 | 109.25 | 109.09 | 6826.88 | 68.66 | 68.83 | 2828.40 |
220
+ | `float32` | `scalar` | `scalar` | 1 | 8 | 0.42 | 0.66 | 2.11 | 0.79 | 0.72 | 2.08 |
221
+ | `float32` | `array` | `small` | 16 | 68 | 0.58 | 0.81 | 2.59 | 0.81 | 0.81 | 2.25 |
222
+ | `float32` | `array` | `big` | 250000 | 1000004 | 54.01 | 54.65 | 8183.15 | 38.92 | 38.87 | 3735.67 |
223
+ | `float64` | `scalar` | `scalar` | 1 | 12 | 0.41 | 0.65 | 2.61 | 0.78 | 0.72 | 2.10 |
224
+ | `float64` | `array` | `small` | 16 | 132 | 0.58 | 0.84 | 2.57 | 0.80 | 0.81 | 2.26 |
225
+ | `float64` | `array` | `big` | 250000 | 2000004 | 133.97 | 140.94 | 8115.61 | 83.78 | 83.42 | 3679.49 |
226
+ | `string` | `scalar` | `small` | 16 | 25 | 0.41 | 0.66 | 2.58 | 0.82 | 0.72 | 2.44 |
227
+ | `string` | `scalar` | `big` | 10000 | 10009 | 0.56 | 0.84 | 3.97 | 0.86 | 0.82 | 3.56 |
228
+ | `string` | `array` | `small` | 16 | 385 | 0.53 | 0.78 | 13.60 | 1.48 | 1.52 | 13.50 |
cydr-0.1.0/README.md ADDED
@@ -0,0 +1,194 @@
1
+ # `cydr` Cython CDR
2
+
3
+ | Requirements | Compatibility | Tests Matrix |
4
+ |---|:---|:---:|
5
+ | [![python](https://img.shields.io/badge/Python-3.10--3.14-%20blue?logo=python&logoColor=white)](./pyproject.toml) <br> [![numpy](https://img.shields.io/badge/NumPy-1.26%20%7C%202.x-%20blue?logo=numpy&logoColor=white)](./pixi.toml) <br> [![mit](https://img.shields.io/badge/License-MIT-gold)](https://opensource.org/license/mit) | [![linux](https://img.shields.io/badge/OS-Linux-black?logo=linux&logoColor=white)](./pixi.toml) <br> [![windows](https://img.shields.io/badge/OS-Windows-black?logo=windows)](./pixi.toml) <br> [![macos](https://img.shields.io/badge/OS-macOS-black?logo=apple)](./pixi.toml) <br> [![xcdr1](https://img.shields.io/badge/Wire-XCDR1-blue)](./README.md#runtime-conventions) | Python: `3.10`, `3.11`, `3.12`, `3.13`, `3.14` <br> NumPy: `1.26`, `2.x`<br> [![Tests](https://github.com/2lian/cydr/actions/workflows/tests.yml/badge.svg)](https://github.com/2lian/cydr/actions/workflows/tests.yml)|
6
+
7
+ `cydr` is a fast, pythonic, focused `XCDR1` serializer/deserializer for Python with a schema API and just-in-time compilation. After defining your message schema with a Python class, `cydr` generates a Cython codec and compiles it down to C unlocking sub-microsecond operations.
8
+
9
+ > [!NOTE]
10
+ > A working C compiler toolchain is required at runtime.
11
+
12
+ Priorities:
13
+
14
+ 1. SPEED
15
+ 2. Pythonic-style
16
+ 3. JIT compilation
17
+
18
+ Runnable examples:
19
+
20
+ - [`examples/roundtrip_custom_message.py`](examples/roundtrip_custom_message.py) for the minimal low-level nested-dict interface
21
+ - [`examples/roundtrip_xcdrstruct_message.py`](examples/roundtrip_xcdrstruct_message.py) for the higher-level `XcdrStruct` interface based on [`msgspec`](https://github.com/jcrist/msgspec)
22
+
23
+ > [!WARNING]
24
+ > `cydr` prioritizes speed and therefore supports only a focused subset of XCDR1: little-endian XCDR1, plain nested structs, and fixed arrays / sequences of scalars and strings.
25
+ >
26
+ > To stay fast, `cydr` is exclusively based on numpy and opinionated about runtime types. In particular, schema `string` means UTF-8 `bytes` at runtime, not Python `str`.
27
+ >
28
+ > Constraints:
29
+ > - `string` fields are `bytes`, and string arrays / sequences are NumPy arrays with `np.bytes_` dtype. However this datastructure is not optimal for all applications, hence:
30
+ > - You can alternatively pass `list[bytes]` for encoding.
31
+ > - You can alternatively decode into `list[bytes]` or raw C representation.
32
+ > - Arrays and sequences must be 1D NumPy arrays with the matching dtype
33
+ > - Collections of strings are much slower than numeric arrays, thus large arrays / sequences of strings should be avoided if speed matters. One long `string` entry is fine.
34
+ > - Collections of schemas are not supported, only collections of primitive types.
35
+ > - Enums, unions, optionals, bounded strings, `char` / `wchar`, XCDR2 mutable or appendable encodings, and big-endian targets are not supported
36
+ >
37
+ > If you need anything outside this subset, use `cyclonedds_idl` directly. Contributions to extend our subset are however welcome!
38
+
39
+ ## Benchmarks
40
+
41
+ Those benchmarks were performed on `JointState` messages containing 3 sequence of floats, 1 sequence of strings, one nested `Header` (containing a string, and another nested `Time` with 2 integers). The `Count` row of table idicates the length of the 4 sequences.
42
+
43
+ #### Serialize
44
+
45
+ | Case | Count | Bytes | Implementation | Median | Speedup |
46
+ |---|---:|---:|---|---:|---:|
47
+ | small | 8 | 372 | `cydr_dict` | `2.22 μs` | `6.53x` |
48
+ | small | 8 | 372 | `cydr_struct` | `1.99 μs` | `7.05x` |
49
+ | small | 8 | 372 | `cyclonedds_idl` | `14.01 μs` | `1.00x` |
50
+ | large | 10000 | 400052 | `cydr_dict` | `55.07 μs` | `164.55x` |
51
+ | large | 10000 | 400052 | `cydr_struct` | `54.70 μs` | `164.57x` |
52
+ | large | 10000 | 400052 | `cyclonedds_idl` | `8993.45 μs` | `1.00x` |
53
+
54
+ #### Deserialize
55
+
56
+ | Case | Count | Bytes | Implementation | Median | Speedup |
57
+ |---|---:|---:|---|---:|---:|
58
+ | small | 8 | 372 | `cydr_dict` | `3.67 μs` | `4.21x` |
59
+ | small | 8 | 372 | `cydr_struct` | `2.84 μs` | `5.25x` |
60
+ | small | 8 | 372 | `cyclonedds_idl` | `14.80 μs` | `1.00x` |
61
+ | large | 10000 | 400052 | `cydr_dict` | `46.63 μs` | `170.36x` |
62
+ | large | 10000 | 400052 | `cydr_struct` | `41.01 μs` | `172.04x` |
63
+ | large | 10000 | 400052 | `cyclonedds_idl` | `7055.84 μs` | `1.00x` |
64
+
65
+ ## Quick Start
66
+
67
+ ```python
68
+ from typing import Any
69
+ import msgspec
70
+ import numpy as np
71
+ from nptyping import Bytes, Float64, NDArray
72
+
73
+ from cydr.idl import XcdrStruct
74
+ from cydr.types import int32, string, uint32
75
+
76
+ # Define adn use your message schema using a simple python class
77
+ # Type hints (`: int32` / `: uint32`) describe the cdr type of the field
78
+ class Time(XcdrStruct):
79
+ sec: int32 = np.int32(0)
80
+ nanosec: uint32 = np.uint32(0)
81
+
82
+ # Create more schemas using one you previously created
83
+ class Header(XcdrStruct):
84
+ stamp: Time = msgspec.field(default_factory=Stamp)
85
+ frame_id: string = b""
86
+
87
+ # And also define collections (arrays of set/varialbe length) using numpy and nptyping
88
+ class JointState(XcdrStruct):
89
+ header: Header = msgspec.field(default_factory=Header)
90
+ name: NDArray[Any, Bytes] = msgspec.field(
91
+ default_factory=lambda: np.array([], dtype=np.bytes_)
92
+ )
93
+ position: NDArray[Any, Float64] = msgspec.field(
94
+ default_factory=lambda: np.array([], dtype=np.float64)
95
+ )
96
+ velocity: NDArray[Any, Float64] = msgspec.field(
97
+ default_factory=lambda: np.array([], dtype=np.float64)
98
+ )
99
+ effort: NDArray[Any, Float64] = msgspec.field(
100
+ default_factory=lambda: np.array([], dtype=np.float64)
101
+ )
102
+
103
+ # Optional: forces caching and compilation of the schema
104
+ JointState.brew()
105
+
106
+ # Instatiate a message with its nested components and arrays
107
+ message = JointState(
108
+ header=Header(
109
+ stamp=Stamp(sec=np.int32(10), nanosec=np.uint32(123)),
110
+ frame_id=b"map",
111
+ ),
112
+ name=np.array([b"joint_a", b"joint_b"], dtype=np.bytes_),
113
+ position=np.array([1.0, 2.0], dtype=np.float64),
114
+ )
115
+
116
+ # Encode / Decode
117
+ payload = message.serialize()
118
+ decoded = JointState.deserialize(payload)
119
+ ```
120
+
121
+ ## Schema Types
122
+ - **WIRE** -> **Python**
123
+
124
+ #### Primitive types
125
+ - `boolean` -> `np.bool_`
126
+ - `byte`, `uint8` -> `np.uint8`
127
+ - `int8` -> `np.int8`
128
+ - `int16` -> `np.int16`
129
+ - `uint16` -> `np.uint16`
130
+ - `int32` -> `np.int32`
131
+ - `uint32` -> `np.uint32`
132
+ - `int64` -> `np.int64`
133
+ - `uint64` -> `np.uint64`
134
+ - `float32` -> `np.float32`
135
+ - `float64` -> `np.float64`
136
+ - `string` -> UTF-8 `bytes`
137
+
138
+ #### Collection types
139
+ - `Sequence[Primitive]` -> `NDArray[Any, dtype]` defines a variable-length 1D collection of one primitive dtype.
140
+ - `Array[n, Primitive]` -> `NDArray[Shape["n"], dtype]` defines a fixed-length 1D collection of one primitive dtype.
141
+ - `Sequence[string]` -> `NDArray[Any, Bytes]` Represent a collection of strings with a numpy array of `np.bytes_` by default.
142
+ - When deserializing you can choose the representation using the Enum `StringCollectionMode`. `.LIST` mode (`list[bytes]`) is more performant from small arrays, or you can use the most performant `.RAW` mode, to manipulate a `list` like C wrapper directly.
143
+ - When serializing, you can either pass `list[bytes]` or `array[np.bytes_]`
144
+
145
+ ## Cache
146
+
147
+ Generated codecs are cached by the hash of the flattened field-type sequence.
148
+
149
+ - Default cache dir: `./.cydr_cache`
150
+ - Override globally with `CYDR_CACHE_DIR=/path/to/cache`
151
+
152
+ # Benchmarks per primitives
153
+
154
+ | Primitive | Kind | Size | Count/Len | Payload Bytes | Dict Ser μs | Struct Ser μs | Cyclone Ser μs | Dict Deser μs | Struct Deser μs | Cyclone Deser μs |
155
+ |---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
156
+ | `boolean` | `scalar` | `scalar` | 1 | 5 | 0.41 | 0.63 | 2.09 | 0.83 | 0.73 | 2.05 |
157
+ | `boolean` | `array` | `small` | 16 | 20 | 0.58 | 0.83 | 2.51 | 0.91 | 0.80 | 2.18 |
158
+ | `boolean` | `array` | `big` | 250000 | 250004 | 7.55 | 7.81 | 3117.59 | 4.75 | 4.82 | 961.79 |
159
+ | `byte` | `scalar` | `scalar` | 1 | 5 | 0.43 | 0.65 | 2.11 | 0.77 | 0.71 | 2.03 |
160
+ | `byte` | `array` | `small` | 16 | 20 | 0.65 | 0.95 | 2.22 | 1.00 | 0.91 | 2.10 |
161
+ | `byte` | `array` | `big` | 250000 | 250004 | 7.60 | 7.88 | 190.03 | 4.96 | 4.99 | 15.08 |
162
+ | `int8` | `scalar` | `scalar` | 1 | 5 | 0.48 | 0.77 | 2.37 | 0.90 | 0.81 | 2.31 |
163
+ | `int8` | `array` | `small` | 16 | 20 | 0.65 | 0.93 | 2.91 | 0.96 | 0.92 | 2.43 |
164
+ | `int8` | `array` | `big` | 250000 | 250004 | 9.06 | 9.40 | 5571.20 | 5.07 | 5.01 | 2017.53 |
165
+ | `uint8` | `scalar` | `scalar` | 1 | 5 | 0.42 | 0.64 | 2.08 | 0.78 | 0.71 | 2.06 |
166
+ | `uint8` | `array` | `small` | 16 | 20 | 0.58 | 0.93 | 2.23 | 0.93 | 0.78 | 1.90 |
167
+ | `uint8` | `array` | `big` | 250000 | 250004 | 7.67 | 7.91 | 190.90 | 5.00 | 5.03 | 16.97 |
168
+ | `int16` | `scalar` | `scalar` | 1 | 6 | 0.42 | 0.66 | 2.09 | 0.81 | 0.72 | 2.06 |
169
+ | `int16` | `array` | `small` | 16 | 36 | 0.58 | 0.83 | 2.51 | 0.81 | 0.81 | 2.17 |
170
+ | `int16` | `array` | `big` | 250000 | 500004 | 18.11 | 18.61 | 7405.62 | 12.76 | 12.73 | 3236.44 |
171
+ | `uint16` | `scalar` | `scalar` | 1 | 6 | 0.50 | 0.76 | 2.46 | 0.83 | 0.81 | 2.35 |
172
+ | `uint16` | `array` | `small` | 16 | 36 | 0.66 | 0.95 | 2.81 | 0.92 | 0.92 | 2.07 |
173
+ | `uint16` | `array` | `big` | 250000 | 500004 | 15.48 | 15.99 | 6504.11 | 10.82 | 10.90 | 2721.29 |
174
+ | `int32` | `scalar` | `scalar` | 1 | 8 | 0.43 | 0.66 | 2.10 | 0.78 | 0.71 | 2.06 |
175
+ | `int32` | `array` | `small` | 16 | 68 | 0.56 | 0.84 | 2.53 | 0.80 | 0.81 | 2.19 |
176
+ | `int32` | `array` | `big` | 250000 | 1000004 | 45.15 | 53.37 | 7345.25 | 39.06 | 39.71 | 2821.39 |
177
+ | `uint32` | `scalar` | `scalar` | 1 | 8 | 0.43 | 0.67 | 2.14 | 0.78 | 0.72 | 2.09 |
178
+ | `uint32` | `array` | `small` | 16 | 68 | 0.58 | 0.82 | 2.53 | 0.80 | 0.81 | 2.18 |
179
+ | `uint32` | `array` | `big` | 250000 | 1000004 | 44.25 | 45.20 | 6672.12 | 32.67 | 32.86 | 3102.01 |
180
+ | `int64` | `scalar` | `scalar` | 1 | 12 | 0.43 | 0.67 | 2.15 | 0.79 | 0.71 | 2.05 |
181
+ | `int64` | `array` | `small` | 16 | 132 | 0.68 | 0.96 | 2.91 | 0.93 | 0.94 | 2.47 |
182
+ | `int64` | `array` | `big` | 250000 | 2000004 | 124.78 | 126.39 | 7625.85 | 80.02 | 79.53 | 3187.78 |
183
+ | `uint64` | `scalar` | `scalar` | 1 | 12 | 0.52 | 0.80 | 2.46 | 0.77 | 0.72 | 2.10 |
184
+ | `uint64` | `array` | `small` | 16 | 132 | 0.67 | 0.95 | 2.90 | 0.93 | 0.92 | 2.46 |
185
+ | `uint64` | `array` | `big` | 250000 | 2000004 | 109.25 | 109.09 | 6826.88 | 68.66 | 68.83 | 2828.40 |
186
+ | `float32` | `scalar` | `scalar` | 1 | 8 | 0.42 | 0.66 | 2.11 | 0.79 | 0.72 | 2.08 |
187
+ | `float32` | `array` | `small` | 16 | 68 | 0.58 | 0.81 | 2.59 | 0.81 | 0.81 | 2.25 |
188
+ | `float32` | `array` | `big` | 250000 | 1000004 | 54.01 | 54.65 | 8183.15 | 38.92 | 38.87 | 3735.67 |
189
+ | `float64` | `scalar` | `scalar` | 1 | 12 | 0.41 | 0.65 | 2.61 | 0.78 | 0.72 | 2.10 |
190
+ | `float64` | `array` | `small` | 16 | 132 | 0.58 | 0.84 | 2.57 | 0.80 | 0.81 | 2.26 |
191
+ | `float64` | `array` | `big` | 250000 | 2000004 | 133.97 | 140.94 | 8115.61 | 83.78 | 83.42 | 3679.49 |
192
+ | `string` | `scalar` | `small` | 16 | 25 | 0.41 | 0.66 | 2.58 | 0.82 | 0.72 | 2.44 |
193
+ | `string` | `scalar` | `big` | 10000 | 10009 | 0.56 | 0.84 | 3.97 | 0.86 | 0.82 | 3.56 |
194
+ | `string` | `array` | `small` | 16 | 385 | 0.53 | 0.78 | 13.60 | 1.48 | 1.52 | 13.50 |
cydr-0.1.0/cydr/__init__.py ADDED
@@ -0,0 +1,28 @@
1
+ """Public cydr API."""
2
+
3
+ from .idl import (
4
+ CYDR_CACHE_DIR,
5
+ Codec,
6
+ XcdrStruct,
7
+ assert_messages_equal,
8
+ boolean,
9
+ byte,
10
+ flatten_runtime_values,
11
+ flatten_schema_fields,
12
+ float32,
13
+ float64,
14
+ generate_cython_codec_source,
15
+ get_codec_for,
16
+ int8,
17
+ int16,
18
+ int32,
19
+ int64,
20
+ rebuild_runtime_values,
21
+ schema_hash,
22
+ string,
23
+ uint8,
24
+ uint16,
25
+ uint32,
26
+ uint64,
27
+ warmup_codec,
28
+ )