pycstructdataparser-lib 1.0.1__tar.gz → 1.0.3__tar.gz

{pycstructdataparser_lib-1.0.1/pycstructdataparser_lib.egg-info → pycstructdataparser_lib-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycstructdataparser-lib
-Version: 1.0.1
+Version: 1.0.3
 Summary: Parse C/C++ struct definitions from header text and serialize/deserialize binary data with ctypes — no compilation needed
 Author: NGC13009
 License-Expression: GPL-3.0-only
@@ -33,7 +33,7 @@ Dynamic: license-file
 </p>
 
 <p align="center">
-  [<a href="README_CN.md">中文说明书</a>] | English
+  [<a href="https://github.com/NGC13009/pycstructdataparser_lib/blob/main/README_CN.md">中文说明书</a>] | English
 </p>
 
 **Automatically parse struct definitions directly from C/C++ header text and process binary data in Python** — No compilation required, no manual `ctypes.Structure` subclass writing needed, zero boilerplate code. Seamless data transfer between C/C++ and Python with automated data unpacking/packing.
@@ -107,7 +107,7 @@ pack output: 21 bytes
 - **Nested Structs**: Supports struct types used as fields within other structs
 - **Serialization (pack)**: Converts Python dictionaries into C struct binary bytes
 - **Deserialization (unpack)**: Parses raw bytes back into nested Python dictionaries
-- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing
+- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing, plus value‑domain checks (bitfield overflow, integer type range)
 
 ## Installation Methods
 
@@ -239,7 +239,10 @@ Serializes a Python dictionary into binary bytes corresponding to a C struct.
 - `parser`: A `CStructParser` instance on which `parse()` has been called.
 - `struct_name`: The target struct type name.
 - `data_dict`: A dictionary mapping field names to field values.
-- `strict`: If `True` (default), raises `ValueError` when non-bitfield fields are missing; if `False`, missing fields are silently filled with 0.
+- `strict`: If `True` (default):
+  - Raises `ValueError` when a **non-bitfield** field is missing.
+  - Performs **value‑domain validation** on each scalar value: bitfield values must be within `[0, 2^width - 1]`; integer types must be within their type min/max (e.g. `uint8_t` → `[0, 255]`, `int32_t` → `[-2147483648, 2147483647]`); floating‑point and struct types are not range‑checked.
+  - If `False`, missing fields are silently filled with 0 and no value‑domain checks are performed.
 
 ### `unpack(parser, struct_name, data)`
 
@@ -295,4 +298,5 @@ Deserializes raw binary bytes into a nested Python dictionary.
 
 ## License
 
-This project is licensed under [GPLv3.0](LICENSE).
+This project is licensed under [GPLv3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
+[NGC13009/pycstructdataparser_lib.git](https://github.com/NGC13009/pycstructdataparser_lib.git)

{pycstructdataparser_lib-1.0.1 → pycstructdataparser_lib-1.0.3}/README.md

@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-  [<a href="README_CN.md">中文说明书</a>] | English
+  [<a href="https://github.com/NGC13009/pycstructdataparser_lib/blob/main/README_CN.md">中文说明书</a>] | English
 </p>
 
 **Automatically parse struct definitions directly from C/C++ header text and process binary data in Python** — No compilation required, no manual `ctypes.Structure` subclass writing needed, zero boilerplate code. Seamless data transfer between C/C++ and Python with automated data unpacking/packing.
@@ -81,7 +81,7 @@ pack output: 21 bytes
 - **Nested Structs**: Supports struct types used as fields within other structs
 - **Serialization (pack)**: Converts Python dictionaries into C struct binary bytes
 - **Deserialization (unpack)**: Parses raw bytes back into nested Python dictionaries
-- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing
+- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing, plus value‑domain checks (bitfield overflow, integer type range)
 
 ## Installation Methods
 
@@ -213,7 +213,10 @@ Serializes a Python dictionary into binary bytes corresponding to a C struct.
 - `parser`: A `CStructParser` instance on which `parse()` has been called.
 - `struct_name`: The target struct type name.
 - `data_dict`: A dictionary mapping field names to field values.
-- `strict`: If `True` (default), raises `ValueError` when non-bitfield fields are missing; if `False`, missing fields are silently filled with 0.
+- `strict`: If `True` (default):
+  - Raises `ValueError` when a **non-bitfield** field is missing.
+  - Performs **value‑domain validation** on each scalar value: bitfield values must be within `[0, 2^width - 1]`; integer types must be within their type min/max (e.g. `uint8_t` → `[0, 255]`, `int32_t` → `[-2147483648, 2147483647]`); floating‑point and struct types are not range‑checked.
+  - If `False`, missing fields are silently filled with 0 and no value‑domain checks are performed.
 
 ### `unpack(parser, struct_name, data)`
 
@@ -269,4 +272,5 @@ Deserializes raw binary bytes into a nested Python dictionary.
 
 ## License
 
-This project is licensed under [GPLv3.0](LICENSE).
+This project is licensed under [GPLv3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
+[NGC13009/pycstructdataparser_lib.git](https://github.com/NGC13009/pycstructdataparser_lib.git)

{pycstructdataparser_lib-1.0.1 → pycstructdataparser_lib-1.0.3}/cstruct_parser.py

@@ -14,7 +14,49 @@ import re
 import ctypes
 from typing import Any, Dict, List, Optional, Tuple
 
-from ctype_map_def import TYPE_MAP
+from ctype_map_def import TYPE_MAP, get_value_range
+
+
+# Value‑range validation (used by pack() when strict=True)
+def _validate_value(value: Any, ctypes_type: Any, bitwidth: Optional[int] = None, field_path: str = "?") -> None:
+    """Validate *value* against the domain of *ctypes_type*.
+
+    Rules (applied only when *strict* is True):
+
+    * **Bitfield** (``bitwidth is not None``):
+      Raises :exc:`ValueError` if *value* < 0 or *value* >= 2\\ :sup:`bitwidth`.
+    * **Integer type** (registered in ``_VALUE_RANGE_DEFS``):
+      Raises :exc:`ValueError` if *value* lies outside ``[min, max]``.
+    * **Floating‑point types / structs / pointers**:
+      No validation performed (silently passes).
+
+    Args:
+        value: The raw Python value (typically ``int``) to validate.
+        ctypes_type: The target ctypes type (e.g. ``ctypes.c_uint8``).
+        bitwidth: Bit‑width for bitfield fields; ``None`` for normal fields.
+        field_path: Human‑readable path used in error messages
+            (e.g. ``"BBBtype.eee"``).
+
+    Raises:
+        ValueError: If the value is out of the allowed domain.
+    """
+    # --- 1. Bitfield check ---
+    if bitwidth is not None:
+        max_val = (1 << bitwidth) - 1
+        if not isinstance(value, int) or value < 0 or value > max_val:
+            raise ValueError(f"Value {value} out of range for bitfield '{field_path}' "
+                             f"(width={bitwidth}, allowed [0, {max_val}])")
+        return
+
+    # --- 2. Integer type range check ---
+    rng = get_value_range(ctypes_type)
+    if rng is None:
+        return     # float / struct / pointer — skip
+
+    lo, hi = rng
+    if not isinstance(value, int) or value < lo or value > hi:
+        raise ValueError(f"Value {value} out of range for field '{field_path}' "
+                         f"(type={ctypes_type.__name__}, allowed [{lo}, {hi}])")
 
 
 # Recursive conversion helper (dict ↔ ctypes.Structure)
@@ -37,37 +79,63 @@ def _struct_to_dict(obj: Any) -> Any:
         return obj
 
 
-def _dict_to_struct(obj: ctypes.Structure, data: Dict[str, Any], strict: bool = True) -> None:
+def _dict_to_struct(obj: ctypes.Structure, data: Dict[str, Any], strict: bool = True, parent_path: str = "") -> None:
     """Recursively fill a ctypes Structure from a plain Python dict.
 
-    When *strict* is True, a ``ValueError`` is raised if *data* is missing
-    a **non-bitfield** key. Bitfield fields are always optional (default to 0).
-    When *strict* is False, all missing keys silently default to 0.
+    When *strict* is True:
+
+    * Raises :exc:`ValueError` if *data* is missing a **non-bitfield** key.
+      Bitfield fields are always optional (default to 0).
+    * Validates each scalar value against its type domain (bitwidth for
+      bitfields, integer range for integer types).
+
+    When *strict* is False, all missing keys silently default to 0 and
+    no value‑domain checks are performed.
+
+    Args:
+        obj: The ctypes Structure instance to fill.
+        data: The source dictionary.
+        strict: Enable strict validation.
+        parent_path: Accumulated field path for error messages
+            (e.g. ``"BBBtype"``, ``"BBBtype.aaalist[3]"``).
     """
-    # Pre-compute bitfield names so strict mode can exclude them
-    bitfield_names: set = set()
+    # Pre-compute bitfield name→width map for validation
+    bitfield_widths: Dict[str, int] = {}
     for f in obj._fields_:
         if len(f) == 3: # (name, type, width)
-            bitfield_names.add(f[0])
+            bitfield_widths[f[0]] = f[2]
 
     for f in obj._fields_:
         field_name = f[0]
+        ftype = f[1] # ctypes type
         is_bitfield = len(f) == 3
+        field_path = f"{parent_path}.{field_name}" if parent_path else field_name
 
         if field_name in data:
             value = data[field_name]
             target = getattr(obj, field_name)
 
             if isinstance(target, ctypes.Structure):
-                _dict_to_struct(target, value, strict)
+                # Nested struct — recurse
+                _dict_to_struct(target, value, strict, field_path)
+
             elif isinstance(target, ctypes.Array):
+                elem_type = target._type_
                 for i, item in enumerate(value):
                     elem = target[i]
+                    elem_path = f"{field_path}[{i}]"
                     if isinstance(elem, ctypes.Structure):
-                        _dict_to_struct(elem, item, strict)
+                        _dict_to_struct(elem, item, strict, elem_path)
                     else:
+                        # Scalar array element — validate in strict mode
+                        if strict:
+                            _validate_value(item, elem_type, None, elem_path)
                         target[i] = item
             else:
+                # Plain scalar — validate in strict mode, then assign
+                if strict:
+                    bw = f[2] if is_bitfield else None
+                    _validate_value(value, ftype, bw, field_path)
                 setattr(obj, field_name, value)
 
         elif strict and not is_bitfield:
@@ -324,9 +392,18 @@ def pack(parser: CStructParser, struct_name: str, data_dict: Dict[str, Any], str
         parser: A :class:`CStructParser` that has had :meth:`parse` called.
         struct_name: The struct type name to use.
         data_dict: A dictionary whose keys correspond to struct field names.
-        strict: If ``True`` (default), raises :class:`ValueError` when a
-            **non-bitfield** key is missing. If ``False``, missing keys
-            silently default to 0.
+        strict: If ``True`` (default):
+
+            * Raises :class:`ValueError` when a **non‑bitfield** key is missing.
+            * Validates each scalar value against its type domain:
+
+              * **Bitfields** — value must be in ``[0, 2\\ :sup:`width`\\ - 1]``.
+              * **Integer types** — value must be in ``[type_min, type_max]``
+                (e.g. ``uint8_t`` → ``[0, 255]``, ``int32_t`` → ``[-2147483648, 2147483647]``).
+              * **Floating‑point / struct** types are **not** range‑checked.
+
+            If ``False``, missing keys silently default to 0 and no value‑domain
+            checks are performed.
 
     Returns:
         Raw binary bytes.

pycstructdataparser_lib-1.0.3/ctype_map_def.py

@@ -0,0 +1,113 @@
+# coding = utf-8
+# Arch   = manyArch
+#
+# @File name:       type_map_def.py
+# @brief:           Type definition file for Python struct parser
+# @attention:       None
+# @Author:          NGC13009
+# @History:         2026-05-07		Create
+
+import ctypes
+from typing import Any, Dict, List, Optional, Tuple
+
+# Character types
+_CHAR_TYPES = {
+    'char': ctypes.c_byte,
+    'signed char': ctypes.c_byte,
+    'unsigned char': ctypes.c_ubyte,
+}
+
+# Integer types (short/int/long)
+_INTEGER_TYPES = {
+    'short': ctypes.c_short,
+    'unsigned short': ctypes.c_ushort,
+    'short int': ctypes.c_short,
+    'unsigned short int': ctypes.c_ushort,
+    'int': ctypes.c_int,
+    'signed int': ctypes.c_int,
+    'unsigned int': ctypes.c_uint,
+    'long': ctypes.c_long,
+    'unsigned long': ctypes.c_ulong,
+    'long int': ctypes.c_long,
+    'unsigned long int': ctypes.c_ulong,
+    'long long': ctypes.c_longlong,
+    'unsigned long long': ctypes.c_ulonglong,
+    'long long int': ctypes.c_longlong,
+    'unsigned long long int': ctypes.c_ulonglong,
+}
+
+# Floating-point types
+_FLOAT_TYPES = {
+    'float': ctypes.c_float,
+    'double': ctypes.c_double,
+    'long double': ctypes.c_longdouble,
+}
+
+# Fixed-width types (stdint.h)
+_STDINT_TYPES = {
+    'int8_t': ctypes.c_int8,
+    'uint8_t': ctypes.c_uint8,
+    'int16_t': ctypes.c_int16,
+    'uint16_t': ctypes.c_uint16,
+    'int32_t': ctypes.c_int32,
+    'uint32_t': ctypes.c_uint32,
+    'int64_t': ctypes.c_int64,
+    'uint64_t': ctypes.c_uint64,
+}
+
+# Alias mapping
+_ALIAS_TYPES = {
+    'float32_t': ctypes.c_float,
+    'float64_t': ctypes.c_double,
+}
+
+# Final aggregation
+TYPE_MAP: Dict[str, Any] = {**_CHAR_TYPES, **_INTEGER_TYPES, **_FLOAT_TYPES, **_STDINT_TYPES, **_ALIAS_TYPES}
+
+# Value‑range definitions for strict value‑domain validation
+#
+# Each entry is a (min, max) tuple for the corresponding ctypes type.
+# Used by _validate_value() in cstruct_parser.py when pack(strict=True).
+# Floating‑point types and struct types are omitted — they are not
+# subject to integer‑range validation.
+#
+# Overflow definitions follow the C standard two's‑complement ranges.
+# For unsigned types, min is always 0.
+
+_VALUE_RANGE_DEFS: Dict[Any, Tuple[int, int]] = {
+                                                                    # Character types
+    ctypes.c_byte: (-128, 127),
+    ctypes.c_ubyte: (0, 255),
+
+                                                                    # Short types
+    ctypes.c_short: (-32768, 32767),
+    ctypes.c_ushort: (0, 65535),
+
+                                                                    # Int types
+    ctypes.c_int: (-2147483648, 2147483647),
+    ctypes.c_uint: (0, 4294967295),
+
+                                                                    # Long types (platform‑dependent; these are Win64 / LP64 values)
+    ctypes.c_long: (-9223372036854775808, 9223372036854775807),
+    ctypes.c_ulong: (0, 18446744073709551615),
+
+                                                                    # Long‑long types
+    ctypes.c_longlong: (-9223372036854775808, 9223372036854775807),
+    ctypes.c_ulonglong: (0, 18446744073709551615),
+
+                                                                    # Fixed‑width stdint types
+    ctypes.c_int8: (-128, 127),
+    ctypes.c_uint8: (0, 255),
+    ctypes.c_int16: (-32768, 32767),
+    ctypes.c_uint16: (0, 65535),
+    ctypes.c_int32: (-2147483648, 2147483647),
+    ctypes.c_uint32: (0, 4294967295),
+    ctypes.c_int64: (-9223372036854775808, 9223372036854775807),
+    ctypes.c_uint64: (0, 18446744073709551615),
+}
+
+
+def get_value_range(ctypes_type: Any) -> Optional[Tuple[int, int]]:
+    """Return the ``(min, max)`` integer range for *ctypes_type*, or ``None``
+    if the type has no range constraint (floats, structs, pointers, etc.)."""
+    return _VALUE_RANGE_DEFS.get(ctypes_type)

{pycstructdataparser_lib-1.0.1 → pycstructdataparser_lib-1.0.3/pycstructdataparser_lib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycstructdataparser-lib
-Version: 1.0.1
+Version: 1.0.3
 Summary: Parse C/C++ struct definitions from header text and serialize/deserialize binary data with ctypes — no compilation needed
 Author: NGC13009
 License-Expression: GPL-3.0-only
@@ -33,7 +33,7 @@ Dynamic: license-file
 </p>
 
 <p align="center">
-  [<a href="README_CN.md">中文说明书</a>] | English
+  [<a href="https://github.com/NGC13009/pycstructdataparser_lib/blob/main/README_CN.md">中文说明书</a>] | English
 </p>
 
 **Automatically parse struct definitions directly from C/C++ header text and process binary data in Python** — No compilation required, no manual `ctypes.Structure` subclass writing needed, zero boilerplate code. Seamless data transfer between C/C++ and Python with automated data unpacking/packing.
@@ -107,7 +107,7 @@ pack output: 21 bytes
 - **Nested Structs**: Supports struct types used as fields within other structs
 - **Serialization (pack)**: Converts Python dictionaries into C struct binary bytes
 - **Deserialization (unpack)**: Parses raw bytes back into nested Python dictionaries
-- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing
+- **Strict Mode**: Optionally validates that all non-bitfield fields are present during packing, plus value‑domain checks (bitfield overflow, integer type range)
 
 ## Installation Methods
 
@@ -239,7 +239,10 @@ Serializes a Python dictionary into binary bytes corresponding to a C struct.
 - `parser`: A `CStructParser` instance on which `parse()` has been called.
 - `struct_name`: The target struct type name.
 - `data_dict`: A dictionary mapping field names to field values.
-- `strict`: If `True` (default), raises `ValueError` when non-bitfield fields are missing; if `False`, missing fields are silently filled with 0.
+- `strict`: If `True` (default):
+  - Raises `ValueError` when a **non-bitfield** field is missing.
+  - Performs **value‑domain validation** on each scalar value: bitfield values must be within `[0, 2^width - 1]`; integer types must be within their type min/max (e.g. `uint8_t` → `[0, 255]`, `int32_t` → `[-2147483648, 2147483647]`); floating‑point and struct types are not range‑checked.
+  - If `False`, missing fields are silently filled with 0 and no value‑domain checks are performed.
 
 ### `unpack(parser, struct_name, data)`
 
@@ -295,4 +298,5 @@ Deserializes raw binary bytes into a nested Python dictionary.
 
 ## License
 
-This project is licensed under [GPLv3.0](LICENSE).
+This project is licensed under [GPLv3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).
+[NGC13009/pycstructdataparser_lib.git](https://github.com/NGC13009/pycstructdataparser_lib.git)

{pycstructdataparser_lib-1.0.1 → pycstructdataparser_lib-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pycstructdataparser-lib"
-version = "1.0.1"
+version = "1.0.3"
 description = "Parse C/C++ struct definitions from header text and serialize/deserialize binary data with ctypes — no compilation needed"
 readme = "README.md"
 license = "GPL-3.0-only"

pycstructdataparser_lib-1.0.1/ctype_map_def.py

@@ -1,65 +0,0 @@
-# coding = utf-8
-# Arch   = manyArch
-#
-# @File name:       type_map_def.py
-# @brief:           Type definition file for Python struct parser
-# @attention:       None
-# @Author:          NGC13009
-# @History:         2026-05-07		Create
-
-import ctypes
-from typing import Any, Dict, List, Optional, Tuple
-
-# Character types
-_CHAR_TYPES = {
-    'char': ctypes.c_byte,
-    'signed char': ctypes.c_byte,
-    'unsigned char': ctypes.c_ubyte,
-}
-
-# Integer types (short/int/long)
-_INTEGER_TYPES = {
-    'short': ctypes.c_short,
-    'unsigned short': ctypes.c_ushort,
-    'short int': ctypes.c_short,
-    'unsigned short int': ctypes.c_ushort,
-    'int': ctypes.c_int,
-    'signed int': ctypes.c_int,
-    'unsigned int': ctypes.c_uint,
-    'long': ctypes.c_long,
-    'unsigned long': ctypes.c_ulong,
-    'long int': ctypes.c_long,
-    'unsigned long int': ctypes.c_ulong,
-    'long long': ctypes.c_longlong,
-    'unsigned long long': ctypes.c_ulonglong,
-    'long long int': ctypes.c_longlong,
-    'unsigned long long int': ctypes.c_ulonglong,
-}
-
-# Floating-point types
-_FLOAT_TYPES = {
-    'float': ctypes.c_float,
-    'double': ctypes.c_double,
-    'long double': ctypes.c_longdouble,
-}
-
-# Fixed-width types (stdint.h)
-_STDINT_TYPES = {
-    'int8_t': ctypes.c_int8,
-    'uint8_t': ctypes.c_uint8,
-    'int16_t': ctypes.c_int16,
-    'uint16_t': ctypes.c_uint16,
-    'int32_t': ctypes.c_int32,
-    'uint32_t': ctypes.c_uint32,
-    'int64_t': ctypes.c_int64,
-    'uint64_t': ctypes.c_uint64,
-}
-
-# Alias mapping
-_ALIAS_TYPES = {
-    'float32_t': ctypes.c_float,
-    'float64_t': ctypes.c_double,
-}
-
-# Final aggregation
-TYPE_MAP: Dict[str, Any] = {**_CHAR_TYPES, **_INTEGER_TYPES, **_FLOAT_TYPES, **_STDINT_TYPES, **_ALIAS_TYPES}