documentation

Author: andreax79

.gitignore

@@ -39,3 +39,4 @@ nosetests.xml
 /include
 .mypy_cache
 pyvenv.cfg
+site/

.readthedocs.yaml

@@ -0,0 +1,7 @@
+# .readthedocs.yaml
+version: 2
+mkdocs:
+  configuration: mkdocs.yml
+python:
+   install:
+   - requirements: requirements-dev.txt

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2017 Andrea Bonomi <andrea.bonomi@gmail.com>
+Copyright (c) 2013-2022 Andrea Bonomi <andrea.bonomi@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

Makefile

@@ -23,7 +23,8 @@ coverage:
 
 .PHONY: docs
 docs:
-	cd docs; $(MAKE) html
+	@mkdocs build
+	@mkdocs gh-deploy
 
 lint:
 	flake8 cstruct tests

cstruct/__init__.py

@@ -1,6 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
 # Copyright (c) 2013-2019 Andrea Bonomi <andrea.bonomi@gmail.com>
 #
 # Published under the terms of the MIT license.
@@ -40,7 +38,6 @@
     TYPEDEFS,
     C_TYPE_TO_FORMAT,
     CHAR_ZERO,
-    EMPTY_BYTES_STRING,
 )
 from .abstract import CStructMeta, AbstractCStruct
 from .cstruct import CStruct
@@ -52,7 +49,6 @@
     'BIG_ENDIAN',
     'NATIVE_ORDER',
     'CHAR_ZERO',
-    'EMPTY_BYTES_STRING',
     'CStruct',
     'MemCStruct',
     'define',
@@ -68,8 +64,9 @@ def define(key: str, value: Any) -> None:
     """
     Define a constant that can be used in the C struct
 
-    :param key: identifier
-    :param value: value of the constant
+    Args:
+        key: identifier
+        value: value of the constant
     """
     DEFINES[key] = value
 
@@ -78,7 +75,8 @@ def undef(key: str) -> None:
     """
     Undefine a symbol that was previously defined with define
 
-    :param key: identifier
+    Args:
+        key: identifier
     """
     del DEFINES[key]
 
@@ -87,7 +85,8 @@ def getdef(key: str) -> Any:
     """
     Return the value for a constant
 
-    :param key: identifier
+    Args:
+        key: identifier
     """
     return DEFINES[key]
 
@@ -96,8 +95,9 @@ def typedef(type_: str, alias: str) -> None:
     """
     Define an alias name for a data type
 
-    :param type_: data type
-    :param alias: new alias name
+    Args:
+        type_: data type
+        alias: new alias name
     """
     TYPEDEFS[alias] = type_
 
@@ -106,8 +106,11 @@ def sizeof(type_: str) -> int:
     """
     Return the size of the type.
 
-    :param type_: C type, struct or union (e.g. 'short int' or 'struct ZYZ')
-    :return: size in bytes
+    Args:
+        type_: C type, struct or union (e.g. 'short int' or 'struct ZYZ')
+
+    Returns:
+        size: size in bytes
     """
     while type_ in TYPEDEFS:
         type_ = TYPEDEFS[type_]
@@ -129,18 +132,24 @@ def sizeof(type_: str) -> int:
 
 
 def parse(
-    __struct__: str, __cls__: Optional[Type[AbstractCStruct]] = None, __name__: Optional[str] = None, **kargs: Dict[str, Any]
+    __struct__: str,
+    __cls__: Optional[Type[AbstractCStruct]] = None,
+    __name__: Optional[str] = None,
+    **kargs: Dict[str, Any]
 ) -> Optional[Type[AbstractCStruct]]:
     """
     Return a new class mapping a C struct/union definition.
     If the string does not contains any definition, return None.
 
-    :param __struct__:     definition of the struct (or union) in C syntax
-    :param __cls__:        (optional) super class - CStruct(default) or MemCStruct
-    :param __name__:       (optional) name of the new class. If empty, a name based on the __struct__ hash is generated
-    :param __byte_order__: (optional) byte order, valid values are LITTLE_ENDIAN, BIG_ENDIAN, NATIVE_ORDER
-    :param __is_union__:   (optional) True for union, False for struct (default)
-    :returns:              __cls__ subclass
+    Args:
+        __struct__ (str): definition of the struct (or union) in C syntax
+        __cls__ (type): super class - CStruct(default) or MemCStruct
+        __name__ (str): name of the new class. If empty, a name based on the __struct__ hash is generated
+        __byte_order__ (str): byte order, valid values are LITTLE_ENDIAN, BIG_ENDIAN, NATIVE_ORDER
+        __is_union__ (bool): True for union, False for struct (default)
+
+    Returns:
+        cls: __cls__ subclass
     """
     if __cls__ is None:
         __cls__ = CStruct

cstruct/abstract.py

@@ -27,18 +27,18 @@
 from abc import ABCMeta
 from collections import OrderedDict
 from typing import Any, BinaryIO, List, Dict, Optional, Type, Tuple, Union
-from .base import STRUCTS
 import hashlib
+from .base import STRUCTS
 from .c_parser import parse_struct, parse_def, Tokens
 from .field import calculate_padding, FieldType
+from .exceptions import CStructException
 
 __all__ = ['CStructMeta', 'AbstractCStruct']
 
 
 class CStructMeta(ABCMeta):
     __size__: int = 0
 
-    # def __new__(cls: Type[type], name: str, bases: tuple, classdict: dict) -> MetaClass:
     def __new__(metacls: Type[type], name: str, bases: Tuple[str], namespace: Dict[str, Any]) -> Type[Any]:
         __struct__ = namespace.get('__struct__', None)
         namespace['__cls__'] = bases[0] if bases else None
@@ -58,6 +58,7 @@ def __new__(metacls: Type[type], name: str, bases: Tuple[str], namespace: Dict[s
         return new_class
 
     def __len__(cls) -> int:
+        "Structure size (in bytes)"
         return cls.__size__
 
     @property
@@ -67,12 +68,22 @@ def size(cls) -> int:
 
 
 class AbstractCStruct(metaclass=CStructMeta):
+    """
+    Abstract C struct to Python class
+    """
+
     __size__: int = 0
+    " Size in bytes "
     __fields__: List[str] = []
+    " Struct/union fileds "
     __fields_types__: Dict[str, FieldType]
+    " Dictionary mapping field names to types "
     __byte_order__: Optional[str] = None
+    " Byte order "
     __alignment__: int = 0
+    " Alignament "
     __is_union__: bool = False
+    " True if the class is an union, False if it is a struct "
 
     def __init__(
         self, buffer: Optional[Union[bytes, BinaryIO]] = None, flexible_array_length: Optional[int] = None, **kargs: Dict[str, Any]
@@ -92,18 +103,30 @@ def __init__(
 
     @classmethod
     def parse(
-        cls, __struct__: Union[str, Tokens, Dict[str, Any]], __name__: Optional[str] = None, **kargs: Dict[str, Any]
+        cls,
+        __struct__: Union[str, Tokens, Dict[str, Any]],
+        __name__: Optional[str] = None,
+        __byte_order__: Optional[str] = None,
+        __is_union__: Optional[bool] = False,
+        **kargs: Dict[str, Any]
     ) -> Type["AbstractCStruct"]:
         """
         Return a new class mapping a C struct/union definition.
 
-        :param __struct__:     definition of the struct (or union) in C syntax
-        :param __name__:       (optional) name of the new class. If empty, a name based on the __struct__ hash is generated
-        :param __byte_order__: (optional) byte order, valid values are LITTLE_ENDIAN, BIG_ENDIAN, NATIVE_ORDER
-        :param __is_union__:   (optional) True for union, False for struct (default)
-        :returns:              cls subclass
+        Args:
+            __struct__:     definition of the struct (or union) in C syntax
+            __name__:       name of the new class. If empty, a name based on the __struct__ hash is generated
+            __byte_order__: byte order, valid values are LITTLE_ENDIAN, BIG_ENDIAN, NATIVE_ORDER
+            __is_union__:   True for union, False for struct
+
+        Returns:
+            cls: a new class mapping the defintion
         """
         cls_kargs: Dict[str, Any] = dict(kargs)
+        if __byte_order__ is not None:
+            cls_kargs['__byte_order__'] = __byte_order__
+        if __is_union__ is not None:
+            cls_kargs['__is_union__'] = __is_union__
         cls_kargs['__struct__'] = __struct__
         if isinstance(__struct__, (str, Tokens)):
             del cls_kargs['__struct__']
@@ -123,20 +146,23 @@ def set_flexible_array_length(self, flexible_array_length: Optional[int]) -> Non
         """
         Set flexible array length (i.e. number of elements)
 
-        :flexible_array_length: flexible array length
+        Args:
+            flexible_array_length: flexible array length
         """
         if flexible_array_length is not None:
             # Search for the flexible array
             flexible_array: Optional[FieldType] = [x for x in self.__fields_types__.values() if x.flexible_array][0]
             if flexible_array is None:
-                raise ValueError("Flexible array not found in struct")
+                raise CStructException("Flexible array not found in struct")
             flexible_array.vlen = flexible_array_length
 
     def unpack(self, buffer: Optional[Union[bytes, BinaryIO]], flexible_array_length: Optional[int] = None) -> bool:
         """
         Unpack bytes containing packed C structure data
 
-        :param buffer: bytes or binary stream to be unpacked
+        Args:
+            buffer: bytes or binary stream to be unpacked
+            flexible_array_length: flexible array length
         """
         self.set_flexible_array_length(flexible_array_length)
         if hasattr(buffer, 'read'):
@@ -151,8 +177,10 @@ def unpack_from(
         """
         Unpack bytes containing packed C structure data
 
-        :param buffer: bytes to be unpacked
-        :param offset: optional buffer offset
+        Args:
+            buffer: bytes to be unpacked
+            offset: optional buffer offset
+            flexible_array_length: flexible array length
         """
         raise NotImplementedError
 

cstruct/base.py

@@ -1,6 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
 # Copyright (c) 2013-2019 Andrea Bonomi <andrea.bonomi@gmail.com>
 #
 # Published under the terms of the MIT license.
@@ -38,16 +36,15 @@
     'DEFINES',
     'TYPEDEFS',
     'C_TYPE_TO_FORMAT',
-    'EMPTY_BYTES_STRING',
     'CHAR_ZERO',
 ]
 
-# little-endian, std. size & alignment
 LITTLE_ENDIAN = '<'
-# big-endian, std. size & alignment
+"Little-endian, std. size & alignment"
 BIG_ENDIAN = '>'
-# native order, size & alignment
+"Big-endian, std. size & alignment"
 NATIVE_ORDER = '@'
+"Native order, size & alignment"
 
 STRUCTS: Dict[str, Type["AbstractCStruct"]] = {}
 
@@ -94,5 +91,4 @@
     'uint64': 'Q',
 }
 
-EMPTY_BYTES_STRING = bytes()
 CHAR_ZERO = bytes('\0', 'ascii')

cstruct/c_expr.py

@@ -1,6 +1,4 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
 # Copyright (c) 2013-2019 Andrea Bonomi <andrea.bonomi@gmail.com>
 #
 # Published under the terms of the MIT license.
@@ -28,6 +26,7 @@
 import operator
 from typing import Any, Callable, Dict, Union, Type, TYPE_CHECKING
 from .base import DEFINES, STRUCTS
+from .exceptions import EvalError
 
 if TYPE_CHECKING:
     from .abstract import AbstractCStruct
@@ -36,9 +35,31 @@
 
 
 def c_eval(expr: str) -> Union[int, float]:
-    "Evaluate a C arithmetic/logic expression and return the result"
-    expr = expr.replace("!", " not ").replace("&&", " and ").replace("||", " or ")
-    return eval_node(ast.parse(expr.strip()).body[0])
+    """
+    Evaluate a C arithmetic/logic expression and return the result
+
+    Examples:
+        >>> c_eval('10 + (5 / 3)')
+        11
+        >>> c_eval('!0')
+        1
+        >>> c_eval('sizeof(x)')
+        128
+
+    Args:
+        expr: C expression
+
+    Returns:
+        result: the expression evaluation result
+
+    Raises:
+        EvalError: expression evaluation error
+    """
+    try:
+        expr = expr.replace("!", " not ").replace("&&", " and ").replace("||", " or ")
+        return eval_node(ast.parse(expr.strip()).body[0])
+    except Exception:
+        raise EvalError
 
 
 def eval_node(node: ast.stmt) -> Union[int, float]:
@@ -79,9 +100,9 @@ def eval_div(node) -> Union[int, float]:
 
 
 def eval_call(node) -> Union[int, float]:
-    if node.func.id == "sizeof":
-        from . import sizeof
+    from . import sizeof
 
+    if node.func.id == "sizeof":
         args = [eval_node(x) for x in node.args]
         return sizeof(*args)
     raise KeyError(node.func.id)