variable pointers

Author: ZeroIntensity

.gitignore

@@ -13,4 +13,6 @@ vgcore.*
 _pointers.cpython*
 *.egg-info/
 wheelhouse/
-gen.py
+gen.py
+ext/
+*.o

docs/using_pointers.md

@@ -162,7 +162,8 @@ However, this **does not** change the original value. To do that, see the sectio
 Movement is somewhat complicated. In low level languages with pointers, you can use dereferencing assignment, like so:
 
 ```c
-int* a = &1;
+int b = 1;
+int* a = &b;
 *a = 2;
 ```
 
@@ -190,6 +191,16 @@ While pointers.py does its best to try and prevent segmentation faults, data mov
 
 In fact, unless you are familiar with the CPython internal machinery, I wouldn't touch movement at all.
 
+### For C/C++ developers
+
+Data movement would be like the following C code:
+
+```c
+int* ptr = &1; // lets pretend this is allowed (which it is in python)
+*ptr = 2;
+assert(1 == 2);
+```
+
 ### Bypassing size limits
 
 An important safety feature of movement is making sure that you can't move an object larger than the underlying value.

docs/variable_pointers.md

@@ -0,0 +1,77 @@
+# Variable Pointers
+
+## What's the difference?
+
+An object pointer (created by `to_ptr` or `Pointer.make_from`) points to the actual Python object (`PyObject*`), while a variable pointer points to that actual variable.
+
+```py
+hello = "123"
+ptr = to_ptr(hello)
+# ptr now points to "123", not "hello"
+```
+
+## Creation
+
+You can make a variable pointer through `to_var_ptr`:
+
+```py
+from pointers import to_var_ptr
+
+a = "hi"
+ptr = to_var_ptr(a)
+```
+
+Note that of course you can't use a literal, because that isn't a variable:
+
+```py
+from pointers import to_var_ptr
+
+ptr = to_var_ptr(123)  # ValueError
+```
+
+## Movement
+
+Moving is much different when it comes to variable pointers. With an object pointer, you are overwriting that actual value, while with variable pointers you are just changing the value of that variable.
+
+You can use movement the same way you would with an object pointer:
+
+```py
+from pointers import to_var_ptr
+
+my_var = 1
+my_ptr = to_var_ptr(my_var)
+my_ptr <<= 2
+print(my_var, 1)
+# outputs 2 1, since we didnt overwrite 1 like we would with object pointers
+```
+
+You are free to use movement however you like with variable pointers. It isn't dangerous, unlike its counterpart.
+
+### For C/C++ developers
+
+Movement in variable pointers is equivalent to the following C code:
+
+```c
+int my_var = 1; // "my_var = 1"
+int my_ptr = &my_var; // "my_ptr = to_var_ptr(my_var)"
+*my_ptr = 2; // "my_ptr <<= 2"
+// my_var is now 2 (the actual 1 is unchanged, thankfully)
+```
+
+## Assignment
+
+Assignment works the same way as it does with object pointers:
+
+```py
+from pointers import to_var_ptr, NULL
+
+hello = "world"
+foo = "bar"
+
+ptr = to_var_ptr(hello)
+print(*ptr)  # world
+ptr >>= NULL
+# ...
+ptr >>= foo
+print(*ptr)  # bar
+```

hatch.toml

@@ -1,5 +1,5 @@
 [version]
-path = "src/pointers/version.py"
+path = "src/pointers/__init__.py"
 
 [envs.default]
 dependencies = [
@@ -19,4 +19,8 @@ build = "mkdocs build --clean"
 serve = "mkdocs serve --dev-addr localhost:8000"
 
 [build.targets.wheel]
-packages = ["src/pointers", "_pointers"]
+packages = ["src/pointers"]
+include = ["src/pointers/*.py", "src/pointers/_pointers.pyi"]
+
+[build.hooks.custom]
+enable-by-default = true

hatch_build.py

@@ -0,0 +1,71 @@
+import os
+import shutil
+import sysconfig
+from distutils.extension import Extension
+from glob import glob
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from hatchling.plugin import hookimpl
+from setuptools._distutils.ccompiler import new_compiler
+
+ext_modules = [
+    Extension(
+        "_pointers",
+        include_dirs=["<header-file-directory>"],
+        sources=glob("src/_pointers/*"),
+    ),
+]
+
+
+class CustomBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, data: dict):
+        self.clean()
+        compiler = new_compiler()
+        ext = os.path.join(self.root, "ext")
+        lib = os.path.join(ext, "./ext/lib")
+
+        compiler.add_include_dir(sysconfig.get_path("include"))
+        compiler.define_macro("PY_SSIZE_T_CLEAN")
+
+        self.app.display_waiting("compiling _pointers")
+
+        try:
+            compiler.compile(
+                glob("./src/mod.c"), output_dir=ext, extra_preargs=["-fPIC"]
+            )
+        except Exception:
+            self.app.abort("failed to compile _pointers")
+
+        self.app.display_success("successfully compiled _pointers")
+        self.app.display_waiting("linking _pointers")
+
+        files = []
+
+        for root, _, fls in os.walk(ext):
+            for i in fls:
+                if i.endswith(".o"):
+                    files.append(os.path.join(root, i))
+
+        try:
+            compiler.link_shared_lib(files, "_pointers", output_dir=lib)
+        except Exception:
+            self.app.abort("failed to link _pointers")
+
+        self.app.display_success("successfully linked _pointers")
+        data["force_include"][
+            os.path.join(lib, "lib_pointers.so")
+        ] = "src/_pointers.so"
+        data["infer_tag"] = True
+        data["pure_python"] = False
+
+    def clean(self, *_):
+        path = os.path.join(self.root, "ext")
+        if os.path.exists(path):
+            shutil.rmtree(path)
+
+
+@hookimpl
+def hatch_register_build_hook():
+    return CustomBuildHook

mkdocs.yml

@@ -4,6 +4,7 @@ nav:
     - Home: index.md
     - Getting Started: getting_started.md
     - Using Pointers: using_pointers.md
+    - Variable Pointers: variable_pointers.md
     - Allocation: allocation.md
     - C Bindings: bindings.md
     - CPython ABI Bindings: cpython_bindings.md

pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
-requires = ["setuptools"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling", "setuptools"]
+build-backend = "hatchling.build"
 
 [project]
 name = "pointers.py"
@@ -23,9 +23,17 @@ classifiers = [
 dependencies = [
     "typing_extensions",
 ]
-version = "2.5.0"
+dynamic = ["version"]
 
 [project.urls]
 Documentation = "https://pointers.zintensity.dev"
 Issues = "https://github.com/ZeroIntensity/pointers.py/issues"
 Source = "https://github.com/ZeroIntensity/pointers.py"
+
+[tool.ward]
+path = ["tests"]
+capture-output = true
+order = "standard"
+test-output-style = "test-per-line"
+fail-limit = 5
+progress-style = ["bar"]

setup.py

@@ -1,15 +1,19 @@
+from types import FrameType
 from typing import Any, Callable, Type, TypeVar
 
 _T = TypeVar("_T")
 _A = TypeVar("_A")
 
-def add_ref(obj: Any) -> None: ...
-def remove_ref(obj: Any) -> None: ...
-def force_set_attr(typ: type[Any], key: str, value: Any) -> None: ...
-def set_ref(obj: Any, count: int) -> None: ...
+def add_ref(__obj: Any) -> None: ...
+def remove_ref(__obj: Any) -> None: ...
+def force_set_attr(__typ: type[Any], __key: str, __value: Any) -> None: ...
+def set_ref(__obj: Any, __count: int) -> None: ...
 def handle(
-    func: Callable[..., _T],
-    args: tuple[Any, ...] | None = None,
-    kwargs: dict[str, Any] | None = None,
+    __func: Callable[..., _T],
+    __args: tuple[Any, ...] | None = None,
+    __kwargs: dict[str, Any] | None = None,
 ) -> _T: ...
-def run_stack_callback(size: int, ptr: Type[_T], func: Callable[[_T], _A]) -> _A: ...
+def run_stack_callback(
+    __size: int, __ptr: Type[_T], __func: Callable[[_T], _A]
+) -> _A: ...
+def force_update_locals(__f: FrameType, __key: str, __value: Any) -> None: ...

src/_pointers.pyi

@@ -141,13 +141,41 @@ static PyObject* run_stack_callback(PyObject* self, PyObject* args) {
     return result;
 }
 
+static PyObject* force_update_locals(PyObject* self, PyObject* args) {
+    PyFrameObject* f;
+    PyObject* key;
+    PyObject* value;
+
+    if (!PyArg_ParseTuple(args, "O!UO", &PyFrame_Type, &f, &key, &value))
+        return NULL;
+
+    Py_INCREF(f->f_locals);
+    PyObject* target = PyDict_GetItem(f->f_locals, key);
+    Py_INCREF(target);
+
+    for (int i = 0; i < PyDict_GET_SIZE(f->f_locals); i++) {
+        if (Py_Is(f->f_localsplus[i], target)) {
+            Py_DECREF(f->f_localsplus[i]);
+            f->f_localsplus[i] = value;
+            Py_INCREF(value);
+            break;
+        }
+    }
+
+    Py_DECREF(f->f_locals);
+    Py_DECREF(target);
+
+    Py_RETURN_NONE;
+}
+
 static PyMethodDef methods[] = {
     {"add_ref", add_ref, METH_VARARGS, "Increment the reference count on the target object."},
     {"remove_ref", remove_ref, METH_VARARGS, "Decrement the reference count on the target object."},
     {"force_set_attr", force_set_attr, METH_VARARGS, "Force setting an attribute on the target type."},
     {"set_ref", set_ref, METH_VARARGS, "Set the reference count on the target object."},
     {"handle", handle, METH_VARARGS, "Enable the SIGSEGV handler."},
-    {"run_stack_callback", run_stack_callback, METH_VARARGS, "."},
+    {"run_stack_callback", run_stack_callback, METH_VARARGS, "Run a callback with a stack allocated pointer."},
+    {"force_update_locals", force_update_locals, METH_VARARGS, "Force update the locals of the target frame."},
     {NULL, NULL, 0, NULL}
 };