i should commit more often shouldnt i

Author: ZeroIntensity

CONTRIBUTING.md

@@ -8,20 +8,3 @@ Any pull request should include the following:
 -   PEP 8 compliant code
 -   Passes tests specified in the [tests](https://github.com/ZeroIntensity/pointers.py/tree/master/tests) directory
 -   Documentation updated accordingly
-
-## Running tests
-
-Pointers.py uses [pre-commit](https://pre-commit.com/) and [pytest](https://docs.pytest.org/en/7.1.x/) for running tests.
-
-To get pre-commit running, simply run the following:
-
-```
-$ pip install pre-commit
-$ pre-commit install
-```
-
-Then, just install pytest:
-
-```
-$ pip install pytest
-```

docs/reference.md

@@ -0,0 +1,13 @@
+# Reference
+
+<!-- prettier-ignore -->
+::: pointers.base_pointers
+::: pointers.c_pointer
+::: pointers.decay
+::: pointers.struct
+::: pointers.std_structs
+::: pointers.malloc
+::: pointers.calloc
+::: pointers.exceptions
+::: pointers.magic
+::: pointers._utils

docs/using_pointers.md

@@ -203,6 +203,30 @@ ptr = _&"123"
 ptr ^= "1234" # this is the same as ptr.move("1234", unsafe=True)
 ```
 
-Doing this is strictly experimental, and may be removed in the future.
+Doing this is strictly experimental.
 
 Moving objects too large also makes your code vulnerable to [buffer overflow attacks](https://en.wikipedia.org/wiki/Buffer_overflow), along with a chance of segmentation faults.
+
+## Null Pointers
+
+If you would like to point to nothing, you can use `NULL`.
+
+Note that you cannot dereference a `NULL` pointer:
+
+```py
+from pointers import NULL, to_ptr
+
+ptr = to_ptr(NULL)
+~ptr  # NullPointerError
+```
+
+You can also assign an existing pointer to `NULL`:
+
+```py
+from pointers import NULL, to_ptr
+
+ptr = to_ptr(1)
+~ptr  # works just fine
+ptr >>= NULL
+~ptr  # NullPointerError
+```

hatch.toml

@@ -12,6 +12,7 @@ tests = "ward"
 [envs.docs]
 dependencies = [
   "mkdocs",
+  "mkdocstrings[python]",
 ]
 [envs.docs.scripts]
 build = "mkdocs build --clean"

mkdocs.yml

@@ -7,4 +7,11 @@ nav:
     - Allocation: allocation.md
     - C Bindings: bindings.md
     - Making a Program: making_a_program.md
+    - Reference: reference.md
 theme: readthedocs
+
+plugins:
+    - mkdocstrings:
+          handlers:
+              python:
+                  paths: [src] # search packages in the src folder

pyproject.toml

@@ -23,9 +23,4 @@ classifiers = [
 dependencies = [
     "typing_extensions",
 ]
-version="2.0.0"
-
-[project.urls]
-Documentation = "https://pointers.zintensity.dev"
-Issues = "https://github.com/ZeroIntensity/pointers.py/issues"
-Source = "https://github.com/ZeroIntensity/pointers.py"
+version = "2.1.0"

setup.py

@@ -27,7 +27,7 @@
         license="MIT",
         project_urls={
             "Source": "https://github.com/ZeroIntensity/pointers.py",
-            "Documentation": "https://pointerspy.netlify.app/",
+            "Documentation": "https://pointers.zintensity.dev/",
         },
         package_dir={"": "src"},
         ext_modules=[Extension("_pointers", ["./src/mod.c"])],

src/_pointers.pyi

@@ -3,3 +3,4 @@ from typing import Any, Type
 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: ...

src/mod.c

@@ -14,6 +14,14 @@ static PyObject* remove_ref(PyObject* self, PyObject* args) {
     Py_RETURN_NONE;
 }
 
+static PyObject* set_ref(PyObject* self, PyObject* args) {
+    PyObject* obj;
+    Py_ssize_t count;
+    if (!PyArg_ParseTuple(args, "On", &obj, &count)) return NULL;
+    obj->ob_refcnt = count;
+    Py_RETURN_NONE;
+}
+
 static PyObject* force_set_attr(PyObject* self, PyObject* args) {
     PyTypeObject* type;
     PyObject* value;
@@ -33,6 +41,7 @@ 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."},
     {NULL, NULL, 0, NULL}
 };
 

src/pointers/__init__.py

@@ -1,13 +1,19 @@
+if __import__("sys").implementation.name != "cpython":
+    # using __import__ to make sure sys isnt exported
+    raise Exception(
+        "pointers.py is only supported on cpython",
+    )
+
+from ._utils import force_set_attr
 from .base_pointers import (
-    BaseAllocatedPointer, BaseCPointer, BaseObjectPointer, BasePointer,
-    BasicPointer, Dereferencable, IterDereferencable, Sized, Typed
+    NULL, BaseAllocatedPointer, BaseCPointer, BaseObjectPointer, BasePointer,
+    BasicPointer, Dereferencable, IterDereferencable, Nullable, Sized, Typed
 )
 from .bindings import *
 from .c_pointer import (
     StructPointer, TypedCPointer, VoidPointer, array, cast, to_c_ptr,
     to_struct_ptr
 )
-from .c_utils import force_set_attr
 from .calloc import AllocatedArrayPointer, calloc
 from .custom_binding import binding, binds
 from .decay import decay, decay_annotated, decay_wrapped
@@ -19,5 +25,6 @@
 from .malloc import AllocatedPointer, free, malloc, realloc
 from .object_pointer import Pointer, to_ptr
 from .std_structs import DivT, Lconv, LDivT, Tm
-from .struct import Struct
-from .version import __version__
+from .structure import Struct
+
+__version__ = "2.1.0"