Skip to main content

Bringing the hell of pointers to Python.

Project description

pointers.py

Bringing the hell of pointers to Python

Why would you ever need this

Example

from pointers import Pointer, to_ptr

class test_class:
    pass

def some_function(ptr: Pointer[test_class]):
    print(repr(ptr)) # <pointer to test_class object at [address]>"

some_function(to_ptr(test_class()))

Installation

Linux/macOS

python3 -m pip install -U pointers.py

Windows

py -3 -m pip install -U pointers.py

Usage

Creation

To convert something to a pointer, use the pointers.to_ptr() function. Then, when annotating function types use the pointers.Pointer class, like so:

from pointers import Pointer, to_ptr

class test_class:
    pass

def some_function(ptr: Pointer[test_class]): # can be any data type (str, tuple, etc)
    ...

some_function(to_ptr(test_class())) # converts the instance to a pointer object

Dereferencing

To dereference a pointer, use the Pointer.dereference() function:

def some_function(ptr: Pointer[test_class]):
    my_instance: test_class = ptr.dereference() # dereferences the pointer

instance = test_class()
some_function(to_ptr(instance))

Alternatively, you can use the * operator to dereference the pointer:

def some_function(ptr: Pointer[str]):
    print(*ptr) # a

some_function(to_ptr("a"))

Note that when using the * operator, the following syntax will not work properly:

deref = *ptr
print(deref)

For the above scenario you can use the dereferencing assignment operator, ,=, or the ~ operator:

deref ,= ptr # works correctly
print(deref)

deref = ~ptr # also works correctly
print(deref)

A segmentation fault will occur if the address does not exist, so make sure the pointer is valid.

To assign the pointer to a different address, use the assign() method:

ptr = to_ptr("abc")
ptr2 = to_ptr("test") # must be same type

ptr.assign(ptr2)
print(*ptr) # test

Decaying

If you would like to automatically decay values to a pointer, use the pointers.decay decorator, like this:

@decay
def some_function(ptr: Pointer[str], b: str): # converts "ptr" to a pointer since its hinted as Pointer[str]
    print(ptr.dereference(), b) # a b

some_function("a", "b") # converts "a" to a pointer, and leaves b as it is

Make sure you annotate the argument with Pointer or else decay won't convert it.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pointers.py-1.0.7.tar.gz (4.2 kB view hashes)

Uploaded Source

Built Distribution

pointers.py-1.0.7-py3-none-any.whl (4.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page