Python Lists — Under the Hood¶

import dis

def create_list():
    nums = [1, 2, 3]
    return nums

dis.dis(create_list)

import dis

def comprehension():
    return [x * 2 for x in range(5)]

dis.dis(comprehension)

import dis

def append_example():
    lst = []
    lst.append(1)

def extend_example():
    lst = []
    lst.extend([1, 2, 3])

print("=== append ===")
dis.dis(append_example)
print("\n=== extend ===")
dis.dis(extend_example)

import dis

def slice_example():
    lst = [1, 2, 3, 4, 5]
    return lst[1:3]

dis.dis(slice_example)

import sys
import ctypes

lst = [10, 20, 30]

# Basic info
print(f"len(lst):       {len(lst)}")
print(f"sys.getsizeof:  {sys.getsizeof(lst)} bytes")
print(f"id(lst):        {id(lst):#x}")

# Inspect internal structure using ctypes
# PyListObject layout (simplified):
#   offset 0:  ob_refcnt (Py_ssize_t)
#   offset 8:  ob_type (pointer)
#   offset 16: ob_size (Py_ssize_t) — this is len()
#   offset 24: ob_item (pointer to array)
#   offset 32: allocated (Py_ssize_t)

addr = id(lst)
ob_size = ctypes.c_ssize_t.from_address(addr + 16).value
allocated = ctypes.c_ssize_t.from_address(addr + 32).value

print(f"ob_size (len):  {ob_size}")
print(f"allocated:      {allocated}")

# After appending
for i in range(10):
    lst.append(i)
    new_allocated = ctypes.c_ssize_t.from_address(addr + 32).value
    new_size = ctypes.c_ssize_t.from_address(addr + 16).value
    print(f"  len={new_size}, allocated={new_allocated}")

def simulate_growth():
    """Simulate CPython list growth pattern."""
    import sys

    lst = []
    prev_alloc = 0
    growth_points = []

    for i in range(100):
        lst.append(i)
        # We can't directly access allocated in pure Python,
        # but sys.getsizeof reveals allocation changes
        current_size = sys.getsizeof(lst)
        if i == 0 or current_size != prev_alloc:
            growth_points.append((len(lst), current_size))
            prev_alloc = current_size

    print(f"{'len':>5} | {'getsizeof':>10} | {'approx slots':>12}")
    print("-" * 35)
    for length, size in growth_points:
        # Each slot is 8 bytes (pointer), base overhead is ~56 bytes
        approx_slots = (size - 56) // 8
        print(f"{length:>5} | {size:>10} | {approx_slots:>12}")


simulate_growth()

import sys

a = [1, 2, 3]

# sys.getrefcount returns refcount + 1 (because the argument itself is a reference)
obj = object()
print(f"refcount before: {sys.getrefcount(obj)}")  # 2

lst = [obj, obj, obj]  # 3 more references
print(f"refcount after adding to list: {sys.getrefcount(obj)}")  # 5

lst.pop()  # remove one reference
print(f"refcount after pop: {sys.getrefcount(obj)}")  # 4

del lst  # remove the list (and all remaining references from it)
print(f"refcount after del lst: {sys.getrefcount(obj)}")  # 2

import gc

# Create a reference cycle
a = []
b = []
a.append(b)
b.append(a)

# Now a → b → a → b → ... (cycle)
# Reference counting alone won't free these because each has refcount > 0

del a
del b
# Objects are still in memory! Only cyclic GC can collect them.

# Force cyclic GC
collected = gc.collect()
print(f"Collected {collected} objects")

# Inspect GC generations
for i, gen in enumerate(gc.get_count()):
    print(f"Generation {i}: {gen} objects tracked")

import dis

def increment_in_list(lst, i):
    lst[i] += 1  # NOT atomic!

dis.dis(increment_in_list)

# CPython caches integers from -5 to 256
# This affects list memory when storing small ints

a = [1, 1, 1, 1, 1]
# All 5 slots point to the SAME PyLongObject(1)
# Only 1 int object exists, not 5

print(a[0] is a[1])  # True — same object

# For larger integers:
b = [257, 257, 257]
print(b[0] is b[1])  # False in most cases — separate objects
# (CPython may intern them in the same code object, but not guaranteed)

import sys

# Short strings are often interned
a = ["hello", "hello", "hello"]
print(a[0] is a[1])  # True — interned

# Longer or dynamically created strings are not
b = ["hello world 123", "hello world 123"]
print(b[0] is b[1])  # May be True (same constant) or False

# Force interning
c = [sys.intern("long dynamic string"), sys.intern("long dynamic string")]
print(c[0] is c[1])  # True — explicitly interned

# CPython maintains a "free list" of up to 80 empty list objects
# When you delete a list, its PyListObject struct may be cached
# and reused for the next list creation

import gc

# This loop does NOT allocate 1M PyListObject structs
for _ in range(1_000_000):
    tmp = [1, 2, 3]
    # tmp is freed here, PyListObject goes to free list
    # next iteration reuses the cached PyListObject

# Verify free list exists (CPython internals)
# In CPython 3.12, check via: python -c "import sys; print(sys._debugmallocstats())"

# CPython does NOT raise an error when you mutate a list during iteration
# (unlike Java's ConcurrentModificationException)
# This is because the iterator only tracks an index, not a version counter

lst = [0, 1, 2, 3, 4]
result = []
for item in lst:
    result.append(item)
    if item == 2:
        lst.append(99)  # modifies list during iteration

print(result)  # [0, 1, 2, 3, 4, 99]
print(lst)     # [0, 1, 2, 3, 4, 99]

import sys

# Negative indexing uses Py_ssize_t (signed)
# Maximum positive index: sys.maxsize - 1
# But you'll run out of memory long before reaching it

lst = [1]
try:
    lst[sys.maxsize]  # IndexError, not OverflowError
except IndexError:
    print("IndexError as expected")

# Slice bounds are clamped, not errored
print(lst[0:sys.maxsize])  # [1] — silently clamped
print(lst[-sys.maxsize:])  # [1] — silently clamped

# Python detects recursive equality checks
a = [1, 2]
a.append(a)
b = [1, 2]
b.append(b)

# a == b would cause infinite recursion without detection
# CPython uses a stack of pending comparisons to detect this
print(a == b)  # True (CPython handles recursive comparison)