Package: einspect
einspectExtended Inspections for CPythonDocumentationView and modify memory structures of live objects.Able to mutate immutable objects like tuples and ints.Modify slot functions or attributes of built-in types.Fully typed, extensible framework in pure Python.Check detailed states of built-in objectsfromeinspectimportviewls=[1,2,3]v=view(ls)print(v.info())PyListObject(at0x2833738):ob_refcnt:Py_ssize_t=5ob_type:*PyTypeObject=&[list]ob_item:**PyObject=&[&[1],&[2],&[3]]allocated:Py_ssize_t=4Mutate tuples, strings, ints, or other immutable typesTupleViewandStrViewsupports allMutableSequencemethods (append, extend, insert, pop, remove, reverse, clear).⚠️ A note onsafety.fromeinspectimportviewtup=(1,2)v=view(tup)v[1]=500print(tup)# (1, 500)v.append(3)print(tup)# (1, 500, 3)delv[:2]print(tup)# (3,)print(v.pop())# 3v.extend([1,2])print(tup)# (1, 2)v.clear()print(tup)# ()fromeinspectimportviewtext="hello"v=view(text)v[1]="3"v[4:]="o~"v.append("!")print(text)# h3llo~!v.reverse()print(text)# !~oll3hfromeinspectimportviewn=500view(n).value=10print(500)# 10print(500==10)# TrueModify attributes of built-in types, get original attributes withorigfromeinspectimportview,origv=view(int)v["__name__"]="custom_int"v["__iter__"]=lambdas:iter(range(s))v["__repr__"]=lambdas:"custom: "+orig(int).__repr__(s)print(int)foriin3:print(i)<class 'custom_int'>
custom: 0
custom: 1
custom: 2Implement methods on built-in typesSee theExtending Typesdocs page for more information.fromeinspectimportimpl,orig@impl(int)def__add__(self,other):other=int(other)returnorig(int).__add__(self,other)print(50+"25")# 75Move objects in memoryfromeinspectimportviews="meaning of life"v=view(s)withv.unsafe():v<<=42print("meaning of life")# 42print("meaning of life"==42)# TrueCPython Struct bindings and API methodsEasily make calls to CPython stable ABI (ctypes.pythonapi) as bound methods onPyObjectinstances.fromeinspect.structsimportPyDictObjectd={"a":(1,2),"b":(3,4)}res=PyDictObject(d).GetItem("a")ifres:print(res.contents.NewRef())Equivalent to the following with ctypes:fromctypesimportpythonapi,py_object,c_void_p,castd={"a":(1,2),"b":(3,4)}PyDict_GetItem=pythonapi["PyDict_GetItem"]# Can't use auto cast py_object for restype,# since missing keys return NULL and causes segmentation fault with no set errorPyDict_GetItem.restype=c_void_pPyDict_GetItem.argtypes=[py_object,py_object]res=PyDict_GetItem(d,"a")res=cast(res,py_object)Py_NewRef=pythonapi["Py_NewRef"]Py_NewRef.restype=py_objectPy_NewRef.argtypes=[py_object]try:print(Py_NewRef(res.value))exceptValueError:passCreate new instances of PyObject structs with field values, from existing objects, or from address.fromeinspect.structsimportPyLongObject,PyTypeObjectx=PyLongObject(ob_refcnt=1,ob_type=PyTypeObject(int).as_ref(),ob_size=1,ob_item=[15],).into_object()print(x)# 15print(x==15)# Trueprint(xis15)# FalseFully typed interfaceSafetyThis project is mainly for learning purposes or inspecting and debugging CPython internals for development and fun. You should not violate language conventions like mutability in production software and libraries.The interpreter makes assumptions regarding types that are immutable, and changing them causes all those usages to be affected. While the intent of the project is to make a memory-correct mutation without further side effects, there can be very significant runtime implications of mutating interned strings with lots of shared references, including interpreter crashes.For example, some strings like "abc" are interned and used by the interpreter. Changing them changes all usages of them, even attribute calls likecollections.abc.The spirit of safety maintained by einspect is to do with memory layouts, not functional effects.For example, appending to tuple views (without an unsafe context) will check that the resize can fit within allocated memoryfromeinspectimportviewtup=(1,2)v=view(tup)v.append(3)print(tup)# (1, 2, 3)v.append(4)# UnsafeError: insert required tuple to be resized beyond current memory allocation. Enter an unsafe context to allow this.Despite this, mutating shared references like empty tuples can cause issues in interpreter shutdown and other runtime operations.fromeinspectimportviewtup=()view(tup).append(1)Exception ignored in: <module 'threading' from '/lib/python3.11/threading.py'>
Traceback (most recent call last):
  File "/lib/python3.11/threading.py", line 1563, in _shutdown
    _main_thread._stop()
  File "/lib/python3.11/threading.py", line 1067, in _stop
    with _shutdown_locks_lock:
TypeError: 'str' object cannot be interpreted as an integerSimilarly, memory moves are also checked for GC-header compatibility and allocation sizesfromeinspectimportviewv=view(101)v<<=2print(101)# 2v<<="hello"# UnsafeError: memory move of 54 bytes into allocated space of 32 bytes is out of bounds. Enter an unsafe context to allow this.However, this will not check the fact that small integers between (-5, 256) are interned and used by the interpreter. Changing them may cause issues in any library or interpreter Python code.fromeinspectimportviewview(0)<<100exit()# sys:1: ImportWarning: can't resolve package from __spec__ or __package__, falling back on __name__ and __path__# IndexError: string index out of rangeTable of ContentsViewsUsing theeinspect.viewconstructorInspecting struct attributesViewsUsing theeinspect.viewconstructorThis is the recommended and simplest way to create aViewonto an object. Equivalent to constructing a specificViewsubtype fromeinspect.views, except the choice of subtype is automatic based on object type.fromeinspectimportviewprint(view(1))print(view("hello"))print(view([1,2]))print(view((1,2)))IntView(<PyLongObject at 0x102058920>)
StrView(<PyUnicodeObject at 0x100f12ab0>)
ListView(<PyListObject at 0x10124f800>)
TupleView(<PyTupleObject at 0x100f19a00>)Inspecting struct attributesAttributes of the underlying C Struct of objects can be accessed through the view's properties.fromeinspectimportviewls=[1,2]v=view(ls)# Inherited from PyObjectprint(v.ref_count)# ob_refcntprint(v.type)# ob_type# Inherited from PyVarObjectprint(v.size)# ob_size# From PyListObjectprint(v.item)# ob_itemprint(v.allocated)# allocated4
<class 'tuple'>
3
<einspect.structs.c_long_Array_3 object at 0x105038ed0>2. Writing to view attributesWriting to these attributes will affect the underlying object of the view.Note that most memory-unsafe attribute modifications require entering an unsafe context manager withView.unsafe()withv.unsafe():v.size-=1print(obj)(1, 2)Sinceitemsis an array of integer pointers to python objects, they can be replaced byid()addresses to modify
index items in the tuple.fromeinspectimportviewtup=(100,200)withview(tup).unsafe()asv:s="dog"v.item[0]=id(s)print(tup)('dog', 200)

>> Process finished with exit code 139 (interrupted by signal 11: SIGSEGV)So here we did set the item at index 0 with our new item, the string"dog", but this also caused a segmentation fault.
Note that the act of setting an item in containers like tuples and lists "steals" a reference to the object, even
if we only supplied the address pointer.To make this safe, we will have to manually increment a ref-count before the new item is assigned. To do this we can
either create aviewof our new item, and increment itsref_count += 1, or use the apis fromeinspect.api, which
are pre-typed implementations ofctypes.pythonapimethods.fromeinspectimportviewfromeinspect.apiimportPytup=(100,200)withview(tup).unsafe()asv:a="bird"Py.IncRef(a)v.item[0]=id(a)b="kitten"Py.IncRef(b)v.item[1]=id(b)print(tup)('bird', 'kitten')🎉 No more seg-faults, and we just successfully set both items in an otherwise immutable tuple.To make the above routine easier, you can access an abstraction by simply indexing the view.fromeinspectimportviewtup=("a","b","c")v=view(tup)v[0]=123v[1]="hm"v[2]="🤔"print(tup)(123, 'hm', '🤔')