mainly docs and decay stuff

Author: ZeroIntensity

docs/pointers.md

@@ -0,0 +1,156 @@
+# Using Pointers
+
+## Creation
+
+To create a pointer, you can use `to_ptr`, like so:
+
+```py
+from pointers import to_ptr
+
+ptr = to_ptr("hello world")
+```
+
+You can also use the `_` object to replicate the address-of operator, like in other languages:
+
+```py
+from pointers import _
+
+ptr = _&"hello world"
+```
+
+Finally, you can directly call `Pointer.make_from`:
+
+```py
+from pointers import Pointer
+
+ptr = Pointer.make_from("hello world")
+```
+
+**Note:** `Pointer.make_from` is more a low level function for creating a pointer. Its API may be changed at any time without warning.
+
+## Dereferencing
+
+There are a few ways to get the underlying value of the pointer, the simplest being calling the `dereference()` method, like so:
+
+```py
+from pointers import _
+
+ptr = _&"hi"
+print(ptr.dereference())  # prints out "hi"
+```
+
+Unfortunately, `dereference` is a pretty long name and doesn't look very pretty when you call it everywhere. Fortunately though, there are different (and more preffered) ways of dereferencing the pointer.
+
+We can use the `_` object to once again replicate the syntax from other languages:
+
+```py
+from pointers import _
+
+ptr = _&"hi"
+print(_*ptr)
+```
+
+In some cases like this one, you can even just directly use `*`, without even having to touch `_`!
+
+```py
+ptr = _&"hi"
+print(*ptr)  # works just fine
+```
+
+However, `*` is for arg splats, which introduces some problems. You can use `~` as an alternative, which will always work:
+
+```py
+ptr = _&"hi"
+print(~ptr)
+# ~ is a unary operator, so we can use it anywhere we want
+```
+
+## Decaying
+
+Converting objects to pointers everywhere may be a bit ugly. To fix this, pointers.py provides a few functions to decay parameters into their pointer equivalents.
+
+The most simple one is `decay`:
+
+```py
+from pointers import decay, Pointer
+
+@decay
+def my_function(a: str, b: str, c: Pointer):  # must be type hinted as Pointer to convert
+    print(a, b, *c)
+
+my_function('a', 'b', 'c')
+```
+
+This will be fine for most people, but it hsa removes type safety on the target function. If you don't care about type safety in your code, then don't worry about this, but if you do, then there are alternatives.
+
+The first alternative is `decay_annotated`, which decays parameters hinted as `Annotated[T, Pointer]` to a pointer.
+
+Here's an example:
+
+```py
+from pointers import decay_annotated, Pointer
+from typing import Annotated  # if you are below python 3.9, you can use typing_extensions here
+
+@decay_annotated
+def my_function(a: str, b: str, c: Annotated[str, Pointer]):
+    print(a, b, *c)
+
+my_function('a', 'b', 'c')
+```
+
+However, `decay_annotated` has a very large drawback.
+
+While it adds type safety for calling the function, it breaks it inside. A type checker still thinks that the argument is a `str`, and not a `Pointer`.
+
+Take the following as an example:
+
+```py
+@decay_annotated
+def my_function(a: str, b: str, c: Annotated[str, Pointer]):
+    print(a, b, ~c)  # type checker error!
+```
+
+The solution is to use `decay_wrapped`, which takes the caller function as a paremeter:
+
+```py
+from pointers import decay_wrapped, Pointer
+
+def my_function_wrapper(a: str, b: str, c: str) -> None:  # this should mimick your actual function
+    ...
+
+@decay_wrapped(my_function_wrapper)
+def my_function(a: str, b: str, c: Pointer[str]):
+    print(a, b, *c)
+    print(a, b, ~c)  # no type checker error, it thinks c is a pointer!
+
+my_function('a', 'b', 'c')  # works just fine, type checker things c takes a string
+```
+
+It can be broken pretty easily though:
+
+```py
+from pointers import decay_wrapped, Pointer
+
+def my_function_wrapper(a: str, b: str, c: str, d: str) -> None:
+    ...
+
+@decay_wrapped(my_function_wrapper)
+def my_function(a: str, b: str, c: Pointer[str]):
+    print(a, b, *c)
+
+my_function('a', 'b', 'c')  # type checker error! missing parameter "d"
+```
+
+## Assignment
+
+We can change where the pointer is looking at by using `assign`, or more commonly, the `>>=` operator:
+
+```py
+from pointers import _
+
+ptr = _&"hi"
+ptr.assign("hello")
+ptr >>= "hello"  # equivalent to the above
+
+print(*ptr)  # prints out "hello"
+```

docs/using_pointers.md

@@ -4,6 +4,7 @@ path = "src/pointers/version.py"
 [envs.default]
 dependencies = [
   "ward",
+  "typing_extensions",
 ]
 [envs.default.scripts]
 tests = "ward"

hatch.toml

@@ -10,7 +10,7 @@
 from .c_utils import force_set_attr
 from .calloc import AllocatedArrayPointer, calloc
 from .custom_binding import binding, binds
-from .decay import decay
+from .decay import decay, decay_annotated, decay_wrapped
 from .exceptions import (
     AllocationError, DereferenceError, FreedMemoryError,
     InvalidBindingParameter, InvalidSizeError

src/pointers/__init__.py

@@ -173,7 +173,7 @@ def _make_stream_and_ptr(
         self,
         size: int,
         address: int,
-    ) -> Tuple[ctypes._PointerLike, bytes]:
+    ) -> Tuple["ctypes._PointerLike", bytes]:
         ...
 
 
@@ -279,7 +279,7 @@ def _make_stream_and_ptr(
         self,
         size: int,
         address: int,
-    ) -> Tuple[ctypes._PointerLike, bytes]:
+    ) -> Tuple["ctypes._PointerLike", bytes]:
         bytes_a = (ctypes.c_ubyte * size).from_address(address)
         return self.make_ct_pointer(), bytes(bytes_a)
 
@@ -394,7 +394,7 @@ def _make_stream_and_ptr(
         self,
         size: int,
         address: int,
-    ) -> Tuple[ctypes._PointerLike, bytes]:
+    ) -> Tuple["ctypes._PointerLike", bytes]:
         if self.freed:
             raise FreedMemoryError("memory has been freed")
 

src/pointers/base_pointers.py

@@ -27,10 +27,10 @@
 
 T = TypeVar("T")
 
-PointerLike = Union[TypedCPointer[Any], VoidPointer, None]
+PointerLike = Union[TypedCPointer[T], VoidPointer, None]
 StringLike = Union[str, bytes, VoidPointer, TypedCPointer[bytes]]
 Format = Union[StringLike, PointerLike]
-TypedPtr = Optional[TypedCPointer[T]]
+TypedPtr = Optional[PointerLike[T]]
 PyCFuncPtrType = type(ctypes.CFUNCTYPE(None))
 
 __all__ = (

src/pointers/bindings.py

@@ -17,7 +17,7 @@
 
 
 def move_to_mem(
-    ptr: ctypes._PointerLike,
+    ptr: "ctypes._PointerLike",
     stream: bytes,
     *,
     unsafe: bool = False,

src/pointers/c_utils.py

@@ -28,7 +28,7 @@ def __init__(
         chunks: int,
         chunk_size: int,
         current_index: int,
-        chunk_cache: Optional[Dict[int, "AllocatedArrayPointer[T]"]] = None,
+        chunk_store: Optional[Dict[int, "AllocatedArrayPointer[T]"]] = None,
         freed: bool = False,
         origin_address: Optional[int] = None,
     ) -> None:
@@ -37,12 +37,12 @@ def __init__(
         self._size = chunk_size
         self._current_index = current_index
         self._chunks = chunks
-        self._chunk_store = chunk_cache or {0: self}
+        self._chunk_store = chunk_store or {0: self}
         self._assigned = True
         self._tracked = False
         self._freed = freed
 
-        if chunk_cache:
+        if chunk_store:
             self._chunk_store[self.current_index] = self
 
     # https://github.com/python/mypy/issues/4125

src/pointers/calloc.py

@@ -1,45 +1,88 @@
 import inspect
 from contextlib import suppress
 from functools import wraps
-from typing import Callable, TypeVar, get_type_hints
+from typing import Any, Callable, Dict, Tuple, TypeVar, get_type_hints
 
-from typing_extensions import ParamSpec
+from typing_extensions import Annotated, ParamSpec, get_args, get_origin
 
 from .object_pointer import Pointer, to_ptr
 
 T = TypeVar("T")
 P = ParamSpec("P")
 
-__all__ = ("decay",)
+__all__ = ("decay", "decay_annotated", "decay_wrapped")
+
+
+def _make_func_params(
+    func: Callable[P, Any],
+    args: Tuple[Any, ...],
+    kwargs: Dict[str, Any],
+) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    hints = get_type_hints(func, include_extras=True)
+    actual: dict = {}
+    params = inspect.signature(func).parameters
+
+    for index, key in enumerate(params):
+        if key in kwargs:
+            actual[key] = kwargs[key]
+        else:
+            with suppress(IndexError):
+                actual[params[key].name] = args[index]
+
+    return (hints, actual)
+
+
+def _decay_params(
+    func: Callable[..., Any],
+    args: Tuple[Any, ...],
+    kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    hints, actual = _make_func_params(func, args, kwargs)
+
+    for key, value in hints.items():
+        if (get_origin(value) is Pointer) or (value is Pointer):
+            actual[key] = to_ptr(actual[key])
+
+    return actual
 
 
 def decay(func: Callable[P, T]) -> Callable[..., T]:
     """Automatically convert values to pointers when called."""
 
     @wraps(func)
     def inner(*args: P.args, **kwargs: P.kwargs) -> T:
-        hints = get_type_hints(func)
-        actual: dict = {}
-        params = inspect.signature(func).parameters
+        actual = _decay_params(func, args, kwargs)
+        return func(**actual)  # type: ignore
+
+    return inner
 
-        # mypy is giving false positives here since it doesn't know how to
-        # handle paramspec
-        for index, key in enumerate(params):
-            if key in kwargs:  # type: ignore
-                actual[key] = kwargs[key]  # type: ignore
-            else:
-                with suppress(IndexError):
-                    actual[params[key].name] = args[index]  # type: ignore
 
-        for key, value in hints.items():
-            if hasattr(value, "__origin__"):
-                origin = value.__origin__
+def decay_annotated(func: Callable[P, T]) -> Callable[P, T]:
+    @wraps(func)
+    def wrapped(*args: P.args, **kwargs: P.kwargs):
+        hints, actual = _make_func_params(func, args, kwargs)
 
-                if origin is not Pointer:
-                    continue
+        for param, hint in hints.items():
+            if get_origin(hint) is not Annotated:
+                continue
 
-                actual[key] = to_ptr(actual[key])
+            hint_arg = get_args(hint)[1]
+
+            if (hint_arg is Pointer) or (get_origin(hint_arg) is Pointer):
+                actual[param] = to_ptr(actual[param])
 
         return func(**actual)  # type: ignore
 
-    return inner
+    return wrapped
+
+
+def decay_wrapped(wrapper: Callable[P, T]) -> Callable[..., Callable[P, T]]:
+    def decorator(func: Callable[..., T]) -> Callable[P, T]:
+        @wraps(func)
+        def wrapped(*args: P.args, **kwargs: P.kwargs):
+            actual = _decay_params(func, args, kwargs)
+            return func(**actual)
+
+        return wrapped
+
+    return decorator  # type: ignore

src/pointers/decay.py

@@ -87,7 +87,7 @@ def __init__(
     @property
     def _as_parameter_(
         self,
-    ) -> Union[int, ctypes._PointerLike]:
+    ) -> Union[int, "ctypes._PointerLike"]:
         existing = self._existing
 
         if existing: