abracadabra

Author: ZeroIntensity

README.md

@@ -10,10 +10,10 @@ Why would you ever need this
 -   [Repository](https://github.com/ZeroIntensity/pointers.py)
 -   [PyPI](https://pypi.org/project/pointers.py)
 
-### Example
+### Examples
 
 ```py
-from pointers import to_ptr, Pointer, decay
+from pointers import Pointer, decay
 
 a: str = '123'
 b: str = 'abc'
@@ -26,12 +26,17 @@ move(a, b)
 print(a, b) # abc abc
 ```
 
-#### Example with bindings
+```py
+from pointers import _
+
+ptr = _&"hello world" # creates a new pointer object
+assert _*ptr == "hello world"
+```
 
 ```py
 from pointers import fopen, fprintf, fclose
 
-file = fopen("/dev/null", "w")
+file = fopen("/dev/null", "w") # assigns file to the c FILE* type
 fprintf(file, "hello world")
 fclose(file)
 ```

docs/getting_started.md

@@ -57,6 +57,16 @@ int main() {
 }
 ```
 
+## Using `_`
+
+Instead of using `to_ptr`, you can use pointers.py's `_` object to replicate C/C++'s address-of operator:
+
+```py
+from pointers import _
+
+ptr = _&"test"
+```
+
 ## Decaying
 
 While the pointer API is cool, having `to_ptr` everywhere isn't exactly great.

docs/index.md

@@ -5,10 +5,10 @@
 -   [Repository](https://github.com/ZeroIntensity/pointers.py)
 -   [PyPI](https://pypi.org/project/pointers.py)
 
-### Example
+### Examples
 
 ```py
-from pointers import to_ptr, Pointer, decay
+from pointers import Pointer, decay
 
 a: str = '123'
 b: str = 'abc'
@@ -21,6 +21,21 @@ move(a, b)
 print(a, b) # abc abc
 ```
 
+```py
+from pointers import _
+
+ptr = _&"hello world" # creates a new pointer object
+assert _*ptr == "hello world"
+```
+
+```py
+from pointers import fopen, fprintf, fclose
+
+file = fopen("/dev/null", "w") # assigns file to the c FILE* type
+fprintf(file, "hello world")
+fclose(file)
+```
+
 ### Features
 
 -   Fully type safe

docs/pointers.md

@@ -28,7 +28,7 @@ def test(ptr: Pointer[str])
     print(~ptr) # much shorter and easier to type
 ```
 
-Finally, you can use the `*` operator, like in low level languages:
+You can also use the `*` operator, like in low level languages:
 
 ```py
 from pointers import Pointer, decay
@@ -70,6 +70,17 @@ def test(ptr: Pointer[list])
 test([1, 2, 3])
 ```
 
+## Using `_`
+
+Like with the address-of operator, you can use `_` for dereferencing as well:
+
+```py
+from pointers import _
+
+ptr = _&"hello world"
+print(_*ptr)
+```
+
 ### Dereference Errors
 
 In versions prior to 1.3.3, a `DereferenceError` could occur if the target object had been garbage collected.
@@ -159,7 +170,20 @@ int main() {
 }
 ```
 
+## Null Pointers
+
+To create a null pointer, simply assign an existing pointer to `None`:
+
+```py
+from pointers import to_ptr
+
+a = to_ptr("a")
+a >>= None
+print(~a)  # NullPointerError
+```
+
 ## Setting Attributes
+
 If you would like to force setting an attribute on the targets type (or itself if you are pointing to a type), you can use `Pointer.set_attr`:
 
 ```py

setup.py

@@ -6,7 +6,7 @@
 if __name__ == "__main__":
     setup(
         name="pointers.py",
-        version="1.3.9",
+        version="1.4.0",
         author="ZeroIntensity",
         author_email="<zintensitydev@gmail.com>",
         description="Bringing the hell of pointers to Python.",

src/pointers/__init__.py

@@ -1,4 +1,4 @@
-from .pointer import Pointer, to_ptr, dereference_address, force_set_attr
+from .pointer import Pointer, to_ptr, dereference_address, force_set_attr, _
 from .malloc import (
     malloc,
     IsMallocPointerError,

src/pointers/bindings.py

@@ -31,14 +31,16 @@
 import ctypes
 from . import _cstd
 from .exceptions import InvalidBindingParameter
+from .pointer import Pointer
 
 if TYPE_CHECKING:
     from .struct import Struct
 
 T = TypeVar("T")
-PointerLike = Union[TypedCPointer[Any], VoidPointer]
+PointerLike = Union[TypedCPointer[Any], VoidPointer, None]
 StringLike = Union[str, bytes, VoidPointer, TypedCPointer[bytes]]
-Format = Union[str, bytes, PointerLike]
+Format = Union[StringLike, PointerLike]
+TypedPtr = Optional[TypedCPointer[T]]
 
 __all__ = (
     "isalnum",
@@ -204,6 +206,19 @@ def _validate_args(
         if not isinstance(value, n_type):
             v_type = type(value)
 
+            if (n_type is Pointer) and (value is None):
+                continue
+
+            if (
+                typ
+                in {
+                    ctypes.c_char_p,
+                    ctypes.c_void_p,
+                    ctypes.POINTER,
+                }
+            ) and (value is None):
+                continue
+
             if ((v_type is ctypes.c_char_p) and (n_type is bytes)) or (
                 issubclass(v_type, _BaseCPointer) and (typ is ctypes.c_void_p)
             ):
@@ -317,15 +332,15 @@ def setlocale(category: int, locale: StringLike) -> str:
     return _base(dll.setlocale, category, _make_char_pointer(locale))
 
 
-def frexp(x: float, exponent: TypedCPointer[int]) -> int:
+def frexp(x: float, exponent: TypedPtr[int]) -> int:
     return _base(dll.frexp, x, exponent)
 
 
 def ldexp(x: float, exponent: int) -> int:
     return _base(dll.ldexp, x, exponent)
 
 
-def modf(x: float, integer: TypedCPointer[float]) -> int:
+def modf(x: float, integer: TypedPtr[float]) -> int:
     return _base(dll.modf, x, integer)
 
 
@@ -362,7 +377,7 @@ def fopen(filename: StringLike, mode: StringLike) -> VoidPointer:
 
 
 def fread(
-    ptr: TypedCPointer[Any],
+    ptr: PointerLike,
     size: int,
     nmemb: int,
     stream: PointerLike,
@@ -396,7 +411,7 @@ def ftell(stream: PointerLike) -> int:
 
 
 def fwrite(
-    ptr: TypedCPointer[Any],
+    ptr: PointerLike,
     size: int,
     nmemb: int,
     stream: PointerLike,
@@ -544,13 +559,13 @@ def perror(string: StringLike) -> None:
     return _base(dll.perror, _make_char_pointer(string))
 
 
-def strtod(string: StringLike, endptr: TypedCPointer[str]) -> int:
+def strtod(string: StringLike, endptr: PointerLike) -> int:
     return _base(dll.strtod, _make_char_pointer(string), endptr)
 
 
 def strtol(
     string: StringLike,
-    endptr: TypedCPointer[str],
+    endptr: PointerLike,
     base: int,
 ) -> int:
     return _base(
@@ -563,7 +578,7 @@ def strtol(
 
 def strtoul(
     string: StringLike,
-    endptr: TypedCPointer[str],
+    endptr: PointerLike,
     base: int,
 ) -> int:
     return _base(
@@ -640,35 +655,35 @@ def wctomb(string: StringLike, wchar: str) -> int:
     return _base(dll.wctomb, _make_char_pointer(string), wchar)
 
 
-def memchr(string: TypedCPointer[Any], c: int, n: int) -> VoidPointer:
+def memchr(string: PointerLike, c: int, n: int) -> VoidPointer:
     return _base(dll.memchr, string, c, n)
 
 
 def memcmp(
-    str1: TypedCPointer[Any],
-    str2: TypedCPointer[Any],
+    str1: PointerLike,
+    str2: PointerLike,
     n: int,
 ) -> int:
     return _base(dll.memcmp, str1, str2, n)
 
 
 def memcpy(
-    dest: TypedCPointer[Any],
-    src: TypedCPointer[Any],
+    dest: PointerLike,
+    src: PointerLike,
     n: int,
 ) -> VoidPointer:
     return _base(dll.memcpy, dest, src, n)
 
 
 def memmove(
-    dest: TypedCPointer[Any],
-    src: TypedCPointer[Any],
+    dest: PointerLike,
+    src: PointerLike,
     n: int,
 ) -> VoidPointer:
     return _base(dll.memmove, dest, src, n)
 
 
-def memset(string: TypedCPointer[Any], c: int, n: int) -> VoidPointer:
+def memset(string: PointerLike, c: int, n: int) -> VoidPointer:
     return _base(dll.memset, string, c, n)
 
 
@@ -804,7 +819,7 @@ def clock() -> int:
     return _base(dll.clock)
 
 
-def ctime(timer: TypedCPointer[int]) -> str:
+def ctime(timer: TypedPtr[int]) -> str:
     return _base(dll.ctime, timer)
 
 
@@ -831,7 +846,7 @@ def strftime(
     )
 
 
-def time(timer: TypedCPointer[int]) -> int:
+def time(timer: TypedPtr[int]) -> int:
     return _base(dll.time, timer)
 
 

src/pointers/c_pointer.py

@@ -78,10 +78,10 @@ def _as_parameter_(self) -> Union[int, ctypes.pointer]:
         if existing:
             return ctypes.pointer(existing.struct)
 
-        return self._address
+        return self.ensure()
 
     def __repr__(self) -> str:
-        return f"<pointer to struct at {hex(self.address)}>"
+        return f"<pointer to struct at {str(self)}>"
 
 
 class _BaseCPointer(Pointer[Any], Generic[T]):
@@ -112,7 +112,7 @@ def _make_stream_and_ptr(
         self,
         data: "_BaseCPointer",
     ) -> Tuple[ctypes.pointer, bytes]:
-        bytes_a = (ctypes.c_ubyte * data.size).from_address(data.address)
+        bytes_a = (ctypes.c_ubyte * data.size).from_address(data.ensure())
 
         return self.make_ct_pointer(), bytes(bytes_a)
 
@@ -128,7 +128,7 @@ def move(self, data: Pointer[T], unsafe: bool = False) -> None:
 
     def make_ct_pointer(self):
         return ctypes.cast(
-            self.address,
+            self.ensure(),
             ctypes.POINTER(ctypes.c_char * self.size),
         )
 
@@ -223,16 +223,14 @@ def _as_parameter_(self) -> ctypes.c_void_p:
 
     def dereference(self) -> Optional[int]:
         """Dereference the pointer."""
-        deref = ctypes.c_void_p.from_address(self.address)
+        deref = ctypes.c_void_p.from_address(self.ensure())
         return deref.value
 
     def __repr__(self) -> str:
-        return f"<void pointer to {hex(self.address)}>"  # noqa
+        return f"<void pointer to {str(self)}>"  # noqa
 
     def __rich__(self):
-        return (
-            f"<[green]void[/green] pointer to [cyan]{hex(self.address)}[/cyan]>"  # noqa
-        )
+        return f"<[green]void[/green] pointer to [cyan]{str(self)}[/cyan]>"  # noqa
 
     def __del__(self):
         pass
@@ -257,14 +255,14 @@ def __init__(
     @property
     def _as_parameter_(self) -> "ctypes.pointer[ctypes._CData]":
         ctype = self.get_mapped(self.type)
-        deref = ctype.from_address(self.address)
+        deref = ctype.from_address(self.ensure())
         return ctypes.pointer(deref)
 
     def dereference(self) -> T:
         """Dereference the pointer."""
         ctype = self.get_mapped(self.type)
         ptr = (
-            ctype.from_address(self.address)
+            ctype.from_address(self.ensure())
             if not self._alt
             else ctype(self.address)  # fmt: off
         )
@@ -278,10 +276,10 @@ def move(self, data: Pointer, unsafe: bool = False) -> None:
         super().move(data, unsafe)
 
     def __repr__(self) -> str:
-        return f"<typed c pointer to {hex(self.address)}>"  # noqa
+        return f"<typed c pointer to {str(self)}>"  # noqa
 
     def __rich__(self):
-        return f"<[green]typed c[/green] pointer to [cyan]{hex(self.address)}[/cyan]>"  # noqa
+        return f"<[green]typed c[/green] pointer to [cyan]{str(self)}[/cyan]>"  # noqa
 
     def __del__(self):
         if (self.type is not str) and (self._decref):
@@ -291,7 +289,7 @@ def __del__(self):
 
 def cast(ptr: VoidPointer, data_type: Type[T]) -> TypedCPointer[T]:
     """Cast a void pointer to a typed pointer."""
-    return TypedCPointer(ptr.address, data_type, ptr.size, decref=False)
+    return TypedCPointer(ptr.ensure(), data_type, ptr.size, decref=False)
 
 
 def to_c_ptr(data: T) -> TypedCPointer[T]: