pointer-x 0.1.0

Pure Python C-style pointers with pluggable memory backend.

Pointer

A Python package that simulates C-style pointers — because Python said it can't have pointers. I took that personally.

Overview

pointer provides a memory simulation layer on top of Python, implementing raw pointer arithmetic, typed memory allocation, and manual memory management — all inside a single bytearray acting as virtual RAM.

How It Works

• A global _vram (bytearray) serves as the "physical memory".
• PtrType objects hold an integer address into _vram and interpret the bytes according to a Type (short, int, long, char, bool, etc.).
• Type is defined via MainTypes (size in bytes) and ModifiedTypes (signed/unsigned).
• nullptr is a sentinel object representing a null pointer.
• Memory allocation is tracked via a global used set to prevent overlapping.

Core Components

Class / Enum	Purpose
MainTypes	Defines base C types with byte sizes (short=2, int=4, long=8, etc.)
ModifiedTypes	Modifiers like unsigned
PtrType	A typed pointer that reads/writes from _vram
nullptr	Null pointer sentinel
_vram	The actual bytearray acting as raw memory

Usage

Basic Pointer

import pointer as ptr

# Create an integer pointer (default nullptr)
p = ptr.PtrType(ptr.Type(ptr.mat.int))

# Allocate memory (assign a value -> triggers allocation)
p.value = 42
print(p.value)  # 42
print(p.ptr)    # address in _vram

# Free memory
p.free()

Pointer Arithmetic

p = ptr.PtrType(ptr.Type(ptr.mat.int))
p.value = 100

# Move pointer by N elements (in bytes = N * type.size)
p += 1  # move forward by 4 bytes
p -= 1  # move back by 4 bytes

Array / Multiple Elements

# Create a pointer pointing to 5 consecutive ints
p = ptr.PtrType(ptr.Type(ptr.mat.int), _length=5)
for i in range(5):
    p[i] = i * 10

print(p[2])  # 20

Direct Memory Manipulation via _vram

Since _vram is a public bytearray, you can manipulate it directly using ctypes or raw byte operations:

import ctypes
import pointer

# Create a writable buffer that shares memory with _vram
pointer._vram = ctypes.create_string_buffer(1 * 1024 ** 2)

# Now any PtrType reads/writes to this ctypes buffer
p = pointer.PtrType(pointer.Type(pointer.mat.int))
p.value = 999
print(pointer._vram[p.ptr:p.ptr+4])  # raw bytes

Warning: Modifying _vram directly can corrupt existing pointers. Use with caution.

API Reference

PtrType(type, default=nullptr, _length=1)

• type: A Type(mat, mot) object.
• default: Initial value (or nullptr).
• _length: Number of elements (for array-style access).

Properties:

• .value → get/set the value at the current pointer address.
• .ptr → current integer address (or nullptr).
• [index] → array-style element access.

Methods:

• .free() → release allocated memory.
• __iadd__ / __isub__ → pointer arithmetic.

Type(mat, mot=ModifiedTypes.unsigned)

• mat: A MainTypes enum member.
• mot: ModifiedTypes.unsigned or default.

Limitations

• Single global _vram — no per-process isolation.
• No garbage collection; manual free() required.
• Not thread-safe.
• Pointer arithmetic is element-based, not byte-based (unlike real C).

License

MIT — because even fake pointers deserve freedom.