update docs

Author: ZeroIntensity

.github/workflows/lint.yml

@@ -0,0 +1,27 @@
+name: Lint
+
+on:
+    push:
+        branches:
+            - master
+    pull_request:
+concurrency: lint-${{ github.sha }}
+
+jobs:
+    lint:
+        runs-on: ubuntu-latest
+
+        env:
+            PYTHON_VERSION: "3.10"
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v3
+
+            - name: Set up Python ${{ env.PYTHON_VERSION }}
+              uses: actions/setup-python@v3
+              with:
+                  python-version: ${{ env.PYTHON_VERSION }}
+
+            - name: Pre-commit hooks
+              uses: pre-commit/[email protected]

docs/cpython_bindings.md

@@ -0,0 +1,54 @@
+# CPython ABI Bindings
+
+There is currently limited support for most of the CPython ABI.
+
+The ABI follows the naming convention of `Py<namespace>_<method>`, so you may use one by importing the namespace from pointers.py:
+
+```py
+# example for PyEval_* methods
+from pointers import PyEval
+
+PyEval.something(...)
+```
+
+However, the method names are in `PascalCase`, and according to [PEP 8](https://peps.python.org/pep-0008/), Python functions should be named in `snake_case`.
+
+Since pointers.py is PEP 8 compliant, method names have been converted to snake case.
+
+Here's an example with `PyEval_GetFrame`:
+
+```py
+from pointers import PyEval
+
+frame = PyEval.get_frame()  # calls the c PyEval_GetFrame function
+```
+
+## Casting Pointers
+
+Some functions don't just return `PyObject`, and instead return something that can be casted instead (in this case, `PyFrameObject`):
+
+Any binding that doesn't return a `PyObject*` is simply converted to a `StructPointer`:
+
+```py
+from pointers import PyEval
+
+frame = PyEval.get_frame()
+# frame is not a frame object, instead its StructPointer[FrameObject]
+```
+
+You may cast this pointer to the correct Python object by calling `struct_cast`:
+
+```py
+from pointers import PyEval, struct_cast
+
+frame = struct_cast(PyEval.get_frame())
+# frame is now a valid frame object!
+```
+
+## Limited Support
+
+CPython ABI bindings are still unfinished, and any method that contains one of the following remains unsupported:
+
+-   Uses a format string
+-   Undocumented on [python.org](https://python.org)
+-   Isn't documented properly

docs/getting_started.md

@@ -34,4 +34,6 @@ ptr = to_ptr("hello world")
 print(*ptr)
 ```
 
+**Note:** As of now, pointers.py does not officially support Python 3.11 and 3.12
+
 Running this should print `hello world` into the console.

docs/index.md

@@ -49,7 +49,7 @@ fclose(file)
 -   Fully type safe
 -   Pythonic pointer API
 -   Bindings for the entire C standard library
--   Segfaults
+-   Undefined behaviour
 
 ### Why does this exist?
 

docs/making_a_program.md

@@ -86,6 +86,6 @@ assert 1 != 2
 free(cache)
 ```
 
-Go ahead and run this to ensure that everything worked fine.
+**Note:** This may not work depending on your build of CPython.
 
 Congratulations, you have written a working program with pointers.py!

docs/using_pointers.md

@@ -230,3 +230,31 @@ ptr = to_ptr(1)
 ptr >>= NULL
 ~ptr  # NullPointerError
 ```
+
+## Handling Segmentation Faults
+
+If you've ever used a language like C or C++, you probably know what a segmentation fault/segfault is.
+
+These can happen when a memory error occurs (e.g. accessing a NULL pointer), and can be annoying to debug in Python.
+
+Luckily, pointers.py has a custom built handler for converting segfaults into Python exceptions.
+
+Here's an example:
+
+```py
+from pointers import handle
+import ctypes
+
+@handle
+def main():
+    ctypes.string_at(0)  # 0 is the same as a NULL address
+
+main()
+# instead of python crashing with a segfault, pointers.SegmentViolation error occurs
+```
+
+### Pointer Methods
+
+Most pointer methods where a segment violation could occur (`dereference`, `move`, etc.) are decorated with `handle`, so you don't have to worry about manually catching those yourself.
+
+However, methods like `move` can be destructive and cause the error outside of the function (such as when Python does garbage collection), so you may need to make a `main` method and decorate it with `handle` to catch it.

mkdocs.yml

@@ -6,6 +6,7 @@ nav:
     - Using Pointers: using_pointers.md
     - Allocation: allocation.md
     - C Bindings: bindings.md
+    - CPython ABI Bindings: cpython_bindings.md
     - Making a Program: making_a_program.md
     - Reference: reference.md
 theme: readthedocs

src/pointers/__init__.py

@@ -15,7 +15,7 @@
     TypedCPointer, VoidPointer, array, cast, to_c_ptr, to_struct_ptr, to_voidp
 )
 from .calloc import AllocatedArrayPointer, calloc
-from .constants import NULL, Nullable, handle, raw_type
+from .constants import NULL, Nullable, handle, raw_type, struct_cast
 from .custom_binding import binding, binds
 from .decay import decay, decay_annotated, decay_wrapped
 from .exceptions import (

src/pointers/object_pointer.py

@@ -44,6 +44,7 @@ def move(
         size_a: int = sys.getsizeof(deref_a)
         size_b: int = sys.getsizeof(deref_b)
         refcnt = sys.getrefcount(deref_b)
+        refcnt_a = sys.getrefcount(deref_a)
 
         if (self._origin_size < size_a) and (not unsafe):
             raise InvalidSizeError(
@@ -61,7 +62,7 @@ def move(
 
         self.assign(~data)
         ctypes.memmove(bytes_b, bytes_a, len(bytes_a))
-        set_ref(deref_b, refcnt - 1)
+        set_ref(deref_b, (refcnt - 1) + (refcnt_a - 2))
 
     @classmethod
     def make_from(cls, obj: Nullable[T]) -> "Pointer[T]":

tests/test_pointer.py

@@ -1,11 +1,9 @@
-import ctypes
+from ward import raises, test
 
-from _pointers import add_ref
-from pointers import NULL, InvalidSizeError, Pointer, SegmentViolation
+from pointers import NULL, InvalidSizeError, Pointer
 from pointers import _ as m
-from pointers import handle, to_c_ptr, to_ptr
+from pointers import to_c_ptr, to_ptr
 from pointers.exceptions import NullPointerError
-from ward import raises, test
 
 
 @test("creating pointers")