cbridge 0.1.0__tar.gz

cbridge-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: cbridge
+Version: 0.1.0
+Summary: Creating ctype structure like dataclass
+Author: ZhengYu, Xu
+Author-email: ZhengYu, Xu <zen-xu@outlook.com>
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: typing-extensions ; python_full_version < '3.12'
+Requires-Python: >=3.9
+Project-URL: homepage, https://github.com/zen-xu/cbridge
+Project-URL: issues, https://github.com/zen-xu/cbridge/issues
+Project-URL: repository, https://github.com/zen-xu/cbridge.git
+Description-Content-Type: text/markdown
+
+# cbridge
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![GitHub License](https://img.shields.io/github/license/zen-xu/cbridge)
+![PyPI - Version](https://img.shields.io/pypi/v/cbridge)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cbridge)
+[![Tests](https://github.com/zen-xu/cbridge/actions/workflows/test.yaml/badge.svg)](https://github.com/zen-xu/cbridge/actions/workflows/test.yaml)
+[![codecov](https://codecov.io/gh/zen-xu/cbridge/graph/badge.svg?token=6HeWXTrTvn)](https://codecov.io/gh/zen-xu/cbridge)
+
+A Python library that provides a dataclass-like interface for creating ctypes structures, making it easier to work with C libraries and data structures in Python.
+
+## Features
+
+- **Dataclass-like syntax**: Define C structures using familiar Python class syntax with type hints
+- **Automatic field management**: Fields are automatically converted to ctypes types based on type annotations
+- **Array support**: Built-in support for fixed-size arrays with proper type checking
+- **Pointer support**: Easy handling of C pointers with type safety
+- **Default values**: Support for default field values and factories
+- **Inheritance**: Full support for class inheritance in C structures
+- **Memory layout control**: Control structure packing and alignment
+- **C function binding**: Decorator for easy binding to C library functions
+
+## Installation
+
+```bash
+pip install cbridge
+```
+
+## Quick Start
+
+### Creating C Structures
+
+```python
+from cbridge import CStruct
+from cbridge import types
+
+class Point(CStruct):
+    x: types.int32
+    y: types.int32
+
+class Rectangle(CStruct):
+    top_left: Point
+    bottom_right: Point
+    color: types.uint32 = 0xFF0000  # Default value
+
+# Create instances
+point = Point(x=10, y=20)
+rect = Rectangle(
+    top_left=Point(x=0, y=0),
+    bottom_right=Point(x=100, y=100)
+)
+
+print(rect)  # Rectangle(top_left=Point(x=0, y=0), bottom_right=Point(x=100, y=100), color=16711680)
+```
+
+### Working with Arrays
+
+```python
+from typing import Literal
+
+from cbridge import CStruct
+from cbridge import types
+
+
+class Data(CStruct):
+    id: types.int32
+    values: types.Array[types.int8, Literal[4]]  # Array of 4 int8 values
+    name: types.char_ptr
+
+
+# Create with array data
+data = Data(id=1, values=[1, 2, 3, 4], name=b"test")
+print(data.values)  # [1, 2, 3, 4]
+```
+
+### C Function Binding
+
+```python
+from cbridge import cfunc
+from cbridge import types
+
+@cfunc("c")  # Bind to libc
+def time(t: types.Pointer[types.ctime_t]) -> types.ctime_t: ...
+
+# Call the C function
+current_time = time(None)
+print(current_time)
+```
+
+### Memory Operations
+
+```python
+import array
+
+from cbridge import CStruct
+from cbridge import types
+
+class Point(CStruct):
+    x: types.int32
+    y: types.int32
+
+
+# Create from buffer
+buffer = array.array("B", b"\x01\x00\x00\x00\x02\x00\x00\x00")
+point = Point.from_buffer(buffer)
+print(point)  # Point(x=1, y=2)
+```
+
+## Advanced Usage
+
+### Structure Packing
+
+```python
+import ctypes
+
+from cbridge import CStruct
+from cbridge import types
+
+
+class DefaultPackData(CStruct):  # 1-byte alignment
+    a: types.char
+    b: types.int32
+
+
+class Pack1Data(CStruct, pack=1):  # 1-byte alignment
+    a: types.char
+    b: types.int32
+
+
+print(ctypes.sizeof(DefaultPackData))  # 8 bytes
+print(ctypes.sizeof(Pack1Data))  # 5 bytes
+
+```
+
+### Default Values and Factories
+
+```python
+from typing import Literal
+
+from cbridge import CStruct
+from cbridge import field
+from cbridge import types
+
+
+class Config(CStruct):
+    name: types.char_ptr
+    timeout: types.int32 = 30
+    flags: types.Array[types.int32, Literal[2]] = field(default_factory=lambda: [0, 1])
+
+
+print(Config(name=b"test"))  # Config(name=b'test', timeout=30, flags=[0, 1])
+```
+
+### Pointer Operations
+
+> [!WARNING]
+> Python 3.13 and above are currently not supported forward declarations
+
+```python
+from cbridge import CStruct
+from cbridge import types
+from cbridge.types import pointer
+
+
+class Node(CStruct):
+    data: types.int32
+    next: "types.Pointer[Node]"
+
+
+# Create linked list
+node1 = Node(data=1, next=None)
+node2 = Node(data=2, next=pointer(node1))
+node1.next = pointer(node2)
+
+node = node1
+data = []
+for _ in range(8):
+    data.append(node.data)
+    node = node.next[0]   # same as *node.next
+assert data == [1, 2, 1, 2, 1, 2, 1, 2]
+```

cbridge-0.1.0/README.md

@@ -0,0 +1,182 @@
+# cbridge
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![GitHub License](https://img.shields.io/github/license/zen-xu/cbridge)
+![PyPI - Version](https://img.shields.io/pypi/v/cbridge)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cbridge)
+[![Tests](https://github.com/zen-xu/cbridge/actions/workflows/test.yaml/badge.svg)](https://github.com/zen-xu/cbridge/actions/workflows/test.yaml)
+[![codecov](https://codecov.io/gh/zen-xu/cbridge/graph/badge.svg?token=6HeWXTrTvn)](https://codecov.io/gh/zen-xu/cbridge)
+
+A Python library that provides a dataclass-like interface for creating ctypes structures, making it easier to work with C libraries and data structures in Python.
+
+## Features
+
+- **Dataclass-like syntax**: Define C structures using familiar Python class syntax with type hints
+- **Automatic field management**: Fields are automatically converted to ctypes types based on type annotations
+- **Array support**: Built-in support for fixed-size arrays with proper type checking
+- **Pointer support**: Easy handling of C pointers with type safety
+- **Default values**: Support for default field values and factories
+- **Inheritance**: Full support for class inheritance in C structures
+- **Memory layout control**: Control structure packing and alignment
+- **C function binding**: Decorator for easy binding to C library functions
+
+## Installation
+
+```bash
+pip install cbridge
+```
+
+## Quick Start
+
+### Creating C Structures
+
+```python
+from cbridge import CStruct
+from cbridge import types
+
+class Point(CStruct):
+    x: types.int32
+    y: types.int32
+
+class Rectangle(CStruct):
+    top_left: Point
+    bottom_right: Point
+    color: types.uint32 = 0xFF0000  # Default value
+
+# Create instances
+point = Point(x=10, y=20)
+rect = Rectangle(
+    top_left=Point(x=0, y=0),
+    bottom_right=Point(x=100, y=100)
+)
+
+print(rect)  # Rectangle(top_left=Point(x=0, y=0), bottom_right=Point(x=100, y=100), color=16711680)
+```
+
+### Working with Arrays
+
+```python
+from typing import Literal
+
+from cbridge import CStruct
+from cbridge import types
+
+
+class Data(CStruct):
+    id: types.int32
+    values: types.Array[types.int8, Literal[4]]  # Array of 4 int8 values
+    name: types.char_ptr
+
+
+# Create with array data
+data = Data(id=1, values=[1, 2, 3, 4], name=b"test")
+print(data.values)  # [1, 2, 3, 4]
+```
+
+### C Function Binding
+
+```python
+from cbridge import cfunc
+from cbridge import types
+
+@cfunc("c")  # Bind to libc
+def time(t: types.Pointer[types.ctime_t]) -> types.ctime_t: ...
+
+# Call the C function
+current_time = time(None)
+print(current_time)
+```
+
+### Memory Operations
+
+```python
+import array
+
+from cbridge import CStruct
+from cbridge import types
+
+class Point(CStruct):
+    x: types.int32
+    y: types.int32
+
+
+# Create from buffer
+buffer = array.array("B", b"\x01\x00\x00\x00\x02\x00\x00\x00")
+point = Point.from_buffer(buffer)
+print(point)  # Point(x=1, y=2)
+```
+
+## Advanced Usage
+
+### Structure Packing
+
+```python
+import ctypes
+
+from cbridge import CStruct
+from cbridge import types
+
+
+class DefaultPackData(CStruct):  # 1-byte alignment
+    a: types.char
+    b: types.int32
+
+
+class Pack1Data(CStruct, pack=1):  # 1-byte alignment
+    a: types.char
+    b: types.int32
+
+
+print(ctypes.sizeof(DefaultPackData))  # 8 bytes
+print(ctypes.sizeof(Pack1Data))  # 5 bytes
+
+```
+
+### Default Values and Factories
+
+```python
+from typing import Literal
+
+from cbridge import CStruct
+from cbridge import field
+from cbridge import types
+
+
+class Config(CStruct):
+    name: types.char_ptr
+    timeout: types.int32 = 30
+    flags: types.Array[types.int32, Literal[2]] = field(default_factory=lambda: [0, 1])
+
+
+print(Config(name=b"test"))  # Config(name=b'test', timeout=30, flags=[0, 1])
+```
+
+### Pointer Operations
+
+> [!WARNING]
+> Python 3.13 and above are currently not supported forward declarations
+
+```python
+from cbridge import CStruct
+from cbridge import types
+from cbridge.types import pointer
+
+
+class Node(CStruct):
+    data: types.int32
+    next: "types.Pointer[Node]"
+
+
+# Create linked list
+node1 = Node(data=1, next=None)
+node2 = Node(data=2, next=pointer(node1))
+node1.next = pointer(node2)
+
+node = node1
+data = []
+for _ in range(8):
+    data.append(node.data)
+    node = node.next[0]   # same as *node.next
+assert data == [1, 2, 1, 2, 1, 2, 1, 2]
+```

cbridge-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "cbridge"
+version = "0.1.0"
+authors = [{ name = "ZhengYu, Xu", email = "zen-xu@outlook.com" }]
+description = "Creating ctype structure like dataclass"
+requires-python = ">=3.9"
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["typing-extensions; python_version< '3.12'"]
+
+[dependency-groups]
+nox = ["nox", "nox-uv"]
+test = ["pytest", "pytest-coverage"]
+
+[project.urls]
+homepage = "https://github.com/zen-xu/cbridge"
+repository = "https://github.com/zen-xu/cbridge.git"
+issues = "https://github.com/zen-xu/cbridge/issues"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.9"]
+build-backend = "uv_build"
+
+[tool.ruff]
+extend-exclude = ["docs/*"]
+fix = true
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+extend-select = [
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "ERA", # flake8-eradicate/eradicate
+    "I",   # isort
+    "N",   # pep8-naming
+    "PIE", # flake8-pie
+    "PGH", # pygrep
+    "RUF", # ruff checks
+    "SIM", # flake8-simplify
+    "TC",  # flake8-type-checking
+    "TID", # flake8-tidy-imports
+    "UP",  # pyupgrade
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+known-first-party = ["cbridge"]
+lines-after-imports = 2
+lines-between-types = 1
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+files = "src"
+explicit_package_bases = true
+namespace_packages = true
+show_error_codes = true
+
+[tool.coverage.run]
+source = ["src/cbridge"]
+branch = true
+omit = ["src/cbridge/types.py"]
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:"]

cbridge-0.1.0/src/cbridge/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .cbridge import CStruct
+from .cbridge import field
+from .cfunc import cfunc
+
+
+__version__ = "0.1.0"
+__authors__ = [
+    "ZhengYu, Xu <zen-xu@outlook.com>",
+]
+__all__ = ["CStruct", "cfunc", "field"]

cbridge-0.1.0/src/cbridge/cbridge.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import ctypes
+import dataclasses as ds
+import sys
+
+from functools import wraps
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import ClassVar
+from typing import TypeVar
+from typing import get_origin
+from typing import get_type_hints
+
+
+if sys.version_info >= (3, 12):
+    from typing import Self
+    from typing import dataclass_transform
+else:
+    from typing_extensions import Self
+    from typing_extensions import dataclass_transform
+
+
+_T = TypeVar("_T")
+
+_CStructType: type = type(ctypes.Structure)
+
+
+@dataclass_transform()
+class CStructType(_CStructType):
+    def __new__(
+        meta_self,  # type: ignore[misc]
+        name: str,
+        bases: tuple[type, ...],
+        attrs: dict[str, Any],
+        pack: int = 0,
+        **extra,
+    ):
+        if sys.version_info >= (3, 13):
+            attrs["_fields_"] = []
+        attrs["_pack_"] = pack
+        cls = super().__new__(meta_self, name, bases, attrs)
+        fields_map = {
+            f_name: f_type
+            for f_name, f_type in get_type_hints(
+                cls, localns={**locals(), name: cls}
+            ).items()
+            if get_origin(f_type) is not ClassVar
+        }
+        fields = list(fields_map.items())
+        if fields:
+            # update fields
+            if sys.version_info >= (3, 13):
+                cls._fields_[:] = fields
+            else:
+                cls._fields_ = fields
+
+        cls = ds.dataclass(cls)
+
+        @wraps(cls.__init__)
+        def wrapped_init(self, *args, **kwargs):
+            args = list(args)
+
+            for i, arg in enumerate(args):
+                field_name = fields[i][0]
+                kwargs[field_name] = arg
+
+            # fill default values
+            for field_name, _ in fields:
+                if field_name in kwargs:
+                    continue
+
+                if field_option := attrs.get(field_name):
+                    if isinstance(field_option, ds.Field):
+                        if field_option.default is not ds.MISSING:
+                            kwargs[field_name] = field_option.default
+                        elif field_option.default_factory is not ds.MISSING:
+                            kwargs[field_name] = field_option.default_factory()
+                    else:
+                        kwargs[field_name] = field_option
+
+            for arg_name, arg_value in kwargs.items():
+                field_type = fields_map[arg_name]
+                if issubclass(field_type, ctypes.Array):
+                    kwargs[arg_name] = field_type(*arg_value)
+
+            return ctypes.Structure.__init__(self, **kwargs)
+
+        cls.__init__ = wrapped_init
+
+        return cls
+
+
+field = ds.field
+
+if TYPE_CHECKING:
+
+    @dataclass_transform(field_specifiers=(field,))
+    class CStruct(ctypes.Structure):
+        def __init_subclass__(cls, pack: int = 0) -> None: ...
+
+        @classmethod
+        def empty(cls) -> Self:
+            """Create an empty instance of the structure."""
+            ...
+
+else:
+
+    class CStruct(ctypes.Structure, metaclass=CStructType):
+        @classmethod
+        def empty(cls) -> Self:
+            return cls()

cbridge-0.1.0/src/cbridge/cfunc.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import ctypes
+
+from ctypes.util import find_library
+from typing import Callable
+from typing import TypeVar
+from typing import get_type_hints
+
+
+_F = TypeVar("_F", bound=Callable)
+
+
+def cfunc(clib: str | ctypes.CDLL) -> Callable[[_F], _F]:
+    """
+    Decorator to bind a Python function signature to a C function from a shared library.
+
+    Args:
+        clib (str | ctypes.CDLL): The name of the C library (as a string) or a ctypes.CDLL instance.
+
+    Returns:
+        Callable[[_F], _F]: A decorator that replaces the Python function with the corresponding C function,
+        setting its argument and return types based on the Python type hints.
+
+    Examples:
+        >>> from cbridge import cfunc
+        >>> from cbridge import types
+        >>> from cbridge.types import pointer
+        >>> @cfunc("c")
+        ... def time(t: types.Pointer[types.ctime_t]) -> types.ctime_t: ...
+        >>> print(time(None))
+        >>> 1727433600
+    """
+    clib = ctypes.CDLL(find_library(clib)) if isinstance(clib, str) else clib
+
+    def wrapper(func: _F) -> _F:
+        hints = get_type_hints(func)
+        restype = hints.pop("return", None)
+        argtypes = list(hints.values())
+        cfunc = getattr(clib, func.__name__)
+        cfunc.restype = restype
+        cfunc.argtypes = tuple(argtypes)
+        return cfunc
+
+    return wrapper

cbridge-0.1.0/src/cbridge/types.py

@@ -0,0 +1,134 @@
+import ctypes
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+from typing import Generic
+from typing import TypeVar
+from typing import overload
+
+
+_T = TypeVar("_T")
+
+if TYPE_CHECKING:
+    from _ctypes import _CData as CData
+    from typing import Any
+    from typing import Union
+
+    bool = Union[bool, CData]
+    byte = Union[bytes, CData]
+    char = Union[bytes, CData]
+    double = Union[float, CData]
+    float = Union[float, CData]
+    ubyte = Union[bytes, CData]
+    int = Union[int, CData]
+    int8 = Union[int, CData]
+    int16 = Union[int, CData]
+    int32 = Union[int, CData]
+    int64 = Union[int, CData]
+    long = Union[int, CData]
+    longdouble = Union[float, CData]
+    longlong = Union[float, CData]
+    short = Union[int, CData]
+    size_t = Union[int, CData]
+    ssize_t = Union[int, CData]
+    uint = Union[int, CData]
+    uint8 = Union[int, CData]
+    uint16 = Union[int, CData]
+    uint32 = Union[int, CData]
+    uint64 = Union[int, CData]
+    ulong = Union[int, CData]
+    ulonglong = Union[int, CData]
+    ushort = Union[int, CData]
+    wchar = Union[str, CData]
+    void_ptr = Union[ctypes.c_void_p, Any]
+
+    _Len = TypeVar("_Len")
+
+    class _Array(Generic[_T, _Len], ctypes.Array[_T]): ...  # type: ignore[type-var]
+
+    Array = Union[_Array[_T, _Len], Sequence[_T]]
+
+    class _Pointer(ctypes._Pointer[_T]):  #  type: ignore[type-var]
+        @overload
+        def __getitem__(self, index: int) -> _T: ...
+        @overload
+        def __getitem__(self, index: slice) -> list[_T]: ...
+        def __getitem__(self, index: int | slice) -> _T | list[_T]: ...
+
+    Pointer = Union[_Pointer[_T], None]
+
+    char_ptr = Pointer[char] | bytes
+    wchar_ptr = Pointer[wchar] | str
+
+    def pointer(obj: _T) -> Pointer[_T]: ...
+else:
+    CData = object
+    byte = ctypes.c_byte
+    bool = ctypes.c_bool
+    char = ctypes.c_char
+    double = ctypes.c_double
+    float = ctypes.c_float
+    ubyte = ctypes.c_ubyte
+    int = ctypes.c_int
+    int8 = ctypes.c_int8
+    int16 = ctypes.c_int16
+    int32 = ctypes.c_int32
+    int64 = ctypes.c_int64
+    long = ctypes.c_long
+    longdouble = ctypes.c_longdouble
+    longlong = ctypes.c_longlong
+    short = ctypes.c_short
+    size_t = ctypes.c_size_t
+    ssize_t = ctypes.c_ssize_t
+    uint = ctypes.c_uint
+    uint8 = ctypes.c_uint8
+    uint16 = ctypes.c_uint16
+    uint32 = ctypes.c_uint32
+    uint64 = ctypes.c_uint64
+    ulong = ctypes.c_ulong
+    ulonglong = ctypes.c_ulonglong
+    ushort = ctypes.c_ushort
+    wchar = ctypes.c_wchar
+    void_ptr = ctypes.c_void_p
+    char_ptr = ctypes.c_char_p
+    wchar_ptr = ctypes.c_wchar_p
+
+    import builtins
+
+    from typing import get_args
+
+    class Array:
+        def __class_getitem__(cls, types: tuple[type[CData], int]):
+            ctype, length = types
+            if not isinstance(length, builtins.int):
+                length = get_args(length)[0]
+
+            return type(f"Array_{ctype.__name__}_{length}", (ctype * length, cls), {})
+
+        def __repr__(self):
+            return str(list(self))
+
+        def __eq__(self, value: object, /) -> bool:
+            if not isinstance(value, Sequence):
+                return False
+            return list(self) == list(value)
+
+    class Pointer(ctypes._Pointer):
+        def __class_getitem__(cls, type):
+            cls = ctypes.POINTER(type)
+
+            def pointer_repr(self):
+                try:
+                    _ = self.contents
+                except ValueError:
+                    return "nullptr"
+                else:
+                    return f"*{type.__name__}"
+
+            cls.__repr__ = pointer_repr
+
+            return cls
+
+    pointer = ctypes.pointer
+
+ctime_t = ulong