The Python Object Model: Memory, gc & Weak References

/* Every Python object starts with this header */
typedef struct _object {
    Py_ssize_t ob_refcnt;    /* reference count — atomic in free-threaded mode */
    PyTypeObject *ob_type;   /* pointer to the type object (int, str, list …) */
} PyObject;

/* Objects with variable length (list, tuple, str) add ob_size */
typedef struct {
    PyObject_HEAD
    Py_ssize_t ob_size;      /* number of items */
} PyVarObject;

/* Example: a Python integer */
typedef struct {
    PyObject_HEAD
    _PyLongValue long_value; /* actual integer value (arbitrary precision) */
} PyLongObject;

import sys
import ctypes

x = [1, 2, 3]

# How many bytes does this object occupy?
print(sys.getsizeof(x))           # 88 bytes (list shell; elements not counted)
print(sys.getsizeof(x[0]))        # 28 bytes (small int — CPython 3.12)

# Reference count (getrefcount adds 1 for the argument itself)
print(sys.getrefcount(x))         # 2 (x + getrefcount's argument)

# Read ob_refcnt directly via ctypes
id_x = id(x)
refcnt = ctypes.c_ssize_t.from_address(id_x).value
print(f"ob_refcnt via ctypes: {refcnt}")

# ob_type pointer
ob_type_ptr = ctypes.c_size_t.from_address(id_x + ctypes.sizeof(ctypes.c_ssize_t)).value
print(f"ob_type pointer: 0x{ob_type_ptr:x}")
print(f"type(x): {type(x)}")

import sys

a = []             # refcount = 1  (a)
b = a              # refcount = 2  (a, b)
c = [a]            # refcount = 3  (a, b, c[0])

print(sys.getrefcount(a))  # 4 — +1 for getrefcount's own argument

del b              # refcount = 3
c.clear()          # refcount = 2 (a, getrefcount arg)

# When refcount hits 0, __del__ is called immediately (if defined)
class Tracked:
    def __init__(self, name): self.name = name
    def __del__(self):        print(f"{self.name} freed")

t = Tracked("A")   # refcount=1
del t              # prints "A freed" immediately — deterministic!

# Cycle: a → b → a
a = {}
b = {"ref": a}
a["ref"] = b

import sys
print(sys.getrefcount(a))   # 3 (a, b["ref"], getrefcount arg)
print(sys.getrefcount(b))   # 3

del a
del b
# Both still have refcount=1 from each other — never freed by refcounting alone
# Requires the cyclic GC to collect

import gc

# Current thresholds
print(gc.get_threshold())     # (700, 10, 10) by default

# Force a full collection
collected = gc.collect()
print(f"Collected {collected} objects")

# Collect only generation 0
gc.collect(0)

# Disable the cyclic GC (useful in scripts with no cycles, saves ~10% overhead)
gc.disable()
# ... do work ...
gc.enable()

# Manual generation inspection
print(gc.get_count())         # (n0, n1, n2) — current object counts per gen

# Find what objects are tracked
tracked = gc.get_objects(generation=0)
print(f"Gen 0 tracked: {len(tracked)} objects")

# Diagnostics: what's in a cycle?
gc.set_debug(gc.DEBUG_SAVEALL)  # save unreachable objects to gc.garbage
gc.collect()
if gc.garbage:
    print("Uncollected:", gc.garbage)
gc.set_debug(0)

import gc

class Node:
    def __init__(self, name):
        self.name = name
        self.partner = None
    def __repr__(self):
        return f"Node({self.name!r})"
    def __del__(self):
        print(f"  🗑️  {self.name} collected")

# Disable automatic GC so we control timing
gc.disable()

# Create a cycle
n1 = Node("alpha")
n2 = Node("beta")
n1.partner = n2
n2.partner = n1

print("Before del — objects alive")
del n1
del n2
print("After del — objects STILL alive (cycle holds them)")

# Now trigger collection
print("Running gc.collect()...")
collected = gc.collect()
print(f"Collected {collected} objects")  # Prints "alpha collected", "beta collected"

gc.enable()

import gc, weakref

class Resource:
    _count = 0

    def __init__(self, name: str):
        self.name = name
        Resource._count += 1
        print(f"  [+] {name} created  (total={Resource._count})")

    def __del__(self):
        Resource._count -= 1
        print(f"  [-] {self.name} freed  (total={Resource._count})")

# Normal case: freed deterministically when refcount → 0
r = Resource("R1")
del r      # prints immediately

# Cycle case: NOT freed until GC runs
r2 = Resource("R2")
r2.self_ref = r2   # cycle!
del r2
print("After del r2 (still alive due to cycle)")
gc.collect()       # now freed
print("After gc.collect()")

# The __del__ gotcha: accessing global state during interpreter shutdown
# is dangerous — globals may already be None
import atexit

class SafeResource:
    def __init__(self, name):
        self.name = name

    def close(self):
        print(f"Closing {self.name}")

    def __enter__(self):
        return self

    def __exit__(self, *exc):
        self.close()
        return False

# Always prefer context managers over __del__ for deterministic cleanup
with SafeResource("DB connection") as res:
    pass   # __exit__ guaranteed to run

# ── Small integers: cached in range [-5, 256] ──
a = 256;  b = 256;  print(a is b)    # True  — same object
a = 257;  b = 257;  print(a is b)    # False — different objects (CPython)

# ── String interning ──
s1 = "hello"
s2 = "hello"
print(s1 is s2)        # True  — interned (looks like an identifier)

s3 = "hello world"
s4 = "hello world"
print(s3 is s4)        # True in CPython (compile-time constant folding)
# But:
s5 = "hello" + " world"   # runtime concatenation
s6 = "hello" + " world"
print(s5 is s6)            # False — NOT the same object

import sys
s7 = sys.intern("my-non-identifier string!")
s8 = sys.intern("my-non-identifier string!")
print(s7 is s8)            # True — explicitly interned

# ── Tuple interning ──
t1 = ()
t2 = ()
print(t1 is t2)   # True — empty tuple is singleton

t3 = (1, 2)
t4 = (1, 2)
print(t3 is t4)   # True in CPython (small constant tuples may be interned)

# ── None, True, False are singletons ──
print(None is None)    # always True
print(True  is True)   # always True

import sys

# Base sizes (CPython 3.12, 64-bit Linux)
print(sys.getsizeof(None))           # 16
print(sys.getsizeof(True))           # 28
print(sys.getsizeof(0))              # 28
print(sys.getsizeof(2**30))          # 32  (larger int, more limbs)
print(sys.getsizeof(2**300))         # 68
print(sys.getsizeof(""))             # 49
print(sys.getsizeof("a"))            # 50  (+1 per Latin-1 char)
print(sys.getsizeof("α"))            # 76  (UCS-2 — non-Latin chars)
print(sys.getsizeof([]))             # 56  (empty list shell)
print(sys.getsizeof([1]))            # 64  (+8 bytes per pointer)
print(sys.getsizeof({}))             # 64  (empty dict)
print(sys.getsizeof(set()))          # 216 (empty set — pre-allocated hash table)
print(sys.getsizeof(lambda: None))   # 144

# getsizeof does NOT include referenced objects
lst = [1, 2, 3]
print(sys.getsizeof(lst))            # 88 — shell only, not the integers

import sys, gc

def deep_sizeof(obj, seen=None):
    if seen is None: seen = set()
    obj_id = id(obj)
    if obj_id in seen: return 0
    seen.add(obj_id)
    size = sys.getsizeof(obj)
    if isinstance(obj, dict):
        size += sum(deep_sizeof(k, seen) + deep_sizeof(v, seen) for k, v in obj.items())
    elif hasattr(obj, '__dict__'):
        size += deep_sizeof(obj.__dict__, seen)
    elif hasattr(obj, '__iter__') and not isinstance(obj, (str, bytes)):
        size += sum(deep_sizeof(i, seen) for i in obj)
    return size

print(deep_sizeof([1, 2, 3]))   # ~140 bytes including the integers

import weakref
import gc

class BigCache:
    def __init__(self, key): self.key = key
    def __repr__(self): return f"BigCache({self.key!r})"

# ── Basic weak reference ──
obj = BigCache("data")
ref = weakref.ref(obj)

print(ref())        #   — object alive
print(ref() is obj) # True

del obj
gc.collect()
print(ref())        # None — object was collected

# ── Callback on collection ──
def on_finalize(ref):
    print(f"Object collected: {ref}")

obj2 = BigCache("x")
ref2 = weakref.ref(obj2, on_finalize)
del obj2   # prints "Object collected: "

# ── WeakValueDictionary — auto-evicts dead entries ──
cache: weakref.WeakValueDictionary[str, BigCache] = weakref.WeakValueDictionary()
item = BigCache("item1")
cache["item1"] = item

print(dict(cache))   # {'item1': BigCache('item1')}
del item
gc.collect()
print(dict(cache))   # {}  — entry automatically removed

# ── WeakSet — set of weakly-referenced objects ──
class Subscriber:
    def __init__(self, name): self.name = name

ws: weakref.WeakSet[Subscriber] = weakref.WeakSet()
s1 = Subscriber("Alice")
s2 = Subscriber("Bob")
ws.add(s1); ws.add(s2)
print([s.name for s in ws])   # ['Alice', 'Bob']
del s1
gc.collect()
print([s.name for s in ws])   # ['Bob']  — Alice auto-removed

import weakref

class EventBus:
    def __init__(self):
        self._handlers: weakref.WeakSet = weakref.WeakSet()

    def subscribe(self, handler):
        self._handlers.add(handler)

    def publish(self, event):
        for h in list(self._handlers):
            h(event)

bus = EventBus()

class Handler:
    def __init__(self, name): self.name = name
    def __call__(self, event): print(f"{self.name} received: {event}")

h1 = Handler("Logger")
h2 = Handler("Alerter")
bus.subscribe(h1); bus.subscribe(h2)

bus.publish("login")   # both fire
del h1
import gc; gc.collect()
bus.publish("logout")  # only Alerter fires — Logger auto-unregistered

import sys

# Object freelists — CPython recycles recently freed objects
# E.g. list freelist: up to 80 empty list shells are kept ready

a = []
id_a = id(a)
del a
b = []
print(id(b) == id_a)   # True on CPython — same memory address reused from freelist!

# Frame freelist: function call overhead is low partly because
# frame objects are recycled from a per-type freelist
import dis

def inner(): pass
def outer():
    for _ in range(5):
        inner()   # frame recycled each iteration

# tracemalloc: track Python-level allocations
import tracemalloc
tracemalloc.start()

data = [dict(x=i) for i in range(10_000)]

snapshot = tracemalloc.take_snapshot()
stats = snapshot.statistics("lineno")
for stat in stats[:5]:
    print(stat)

import gc, tracemalloc, weakref

# ── Pattern 1: Unbounded global cache ──
_cache: dict = {}

def get_data(key):
    if key not in _cache:
        _cache[key] = {"data": b"x" * 1024 * 10}   # 10 KB per entry
    return _cache[key]

# Fix: use WeakValueDictionary or limit size with functools.lru_cache
from functools import lru_cache

@lru_cache(maxsize=128)
def get_data_cached(key):
    return {"data": b"x" * 1024 * 10}   # auto-evicts oldest entries

# ── Pattern 2: Cycle with __del__ ──
class Node:
    def __init__(self, val):
        self.val = val
        self.next = None
    def __del__(self):
        pass   # even trivial __del__ can trap cycles pre-3.4

a = Node(1)
b = Node(2)
a.next = b
b.next = a    # cycle
del a, b
print(f"Collected: {gc.collect()}")   # 2

# ── Pattern 3: Closures holding large objects ──
def make_leak():
    large = list(range(100_000))   # 800 KB
    def inner():
        return large[0]            # inner holds ref to large forever
    return inner                   # large lives as long as inner lives

# Fix: only capture what you need
def make_fixed():
    large = list(range(100_000))
    first = large[0]               # capture only the scalar
    del large                      # large freed here
    def inner():
        return first
    return inner

# ── tracemalloc snapshot diff ──
tracemalloc.start()
snap1 = tracemalloc.take_snapshot()

data = [Node(i) for i in range(1000)]

snap2 = tracemalloc.take_snapshot()
for stat in snap2.compare_to(snap1, "lineno")[:3]:
    print(stat)

# ── Identity vs Equality ──
a = [1, 2, 3]
b = [1, 2, 3]
c = a

print(a == b)      # True  — same value (__eq__)
print(a is b)      # False — different objects (different id)
print(a is c)      # True  — same object

# ── Hash contract: equal objects MUST have equal hashes ──
# If __eq__ is defined, __hash__ must also be defined (or set to None for unhashable)

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __eq__(self, other):
        return isinstance(other, Point) and self.x == other.x and self.y == other.y

    def __hash__(self):
        return hash((self.x, self.y))   # tuple hash — fast, well-distributed

p1 = Point(1, 2)
p2 = Point(1, 2)
print(p1 == p2)    # True
print(p1 is p2)    # False
print(hash(p1) == hash(p2))  # True
print({p1, p2})    # {Point(1,2)} — deduplicated in set

# ── Hash collisions — still equal objects must compare equal ──
# Python's dict/set resolves collisions by calling __eq__ after hash match
# hash("abc") == hash("abc") — always
# Two distinct objects CAN have the same hash (collision), so __eq__ is the tiebreaker

# ── Mutable objects and hashing ──
lst = [1, 2, 3]
# hash(lst)  → TypeError: unhashable type: 'list'
# Lists define __eq__ but set __hash__ = None → unhashable

# ── id() uniqueness guarantee ──
# id() is unique only for SIMULTANEOUSLY ALIVE objects
# After del x, a new object can get the same id
x = object()
xid = id(x)
del x
y = object()
print(id(y) == xid)   # Possibly True! ids can be reused after deallocation

# ── Interning and the is trap ──
import sys
a = sys.intern("cached_key")
b = sys.intern("cached_key")
print(a is b)   # True  — safe to use is for interned strings in caches

# ── __eq__ without __hash__ ──
class NoHash:
    def __eq__(self, other): return True
    # __hash__ automatically set to None by Python when __eq__ is defined without __hash__

nh = NoHash()
try:
    hash(nh)
except TypeError as e:
    print(e)   # unhashable type: 'NoHash'