Reference counts, cycle collection and weak references

Caches and listeners hold objects past their welcome. Lifetime reasoning decides between a leak and a dangling callback.

explain
measure

You can now

Explain reference counting and cycle collection, and predict when each frees an object.
Use weak references for caches and callbacks without creating ownership bugs.
Measure collection behavior with gc.collect, gc.get_count and sys.getrefcount on a diagnosed case.

Covers

Reference counts, cycle collection and weak references

Study, in this order

4 steps

Objects and garbage collection
Python language reference

Section 3.1: refcounting with delayed cycle detection; never depend on immediate finalization; close files explicitly

Done
The cycle collector
gc - cycle garbage collector

collect, get_count, get_threshold, garbage and disable/enable

Depth · The generations changed within 3.14: 3.14.0 to 3.14.4 run an incremental collector (gc.get_threshold() reads (2000, 10, 0) on 3.14.4), and the docs record that 3.14.5 restores the three 3.13 generations. Read gc.get_threshold() on your interpreter before reasoning about generations.

Done
Weak references
weakref - weak references

Weak-reference objects with callbacks; which types refuse weakrefs; the WeakValueDictionary pattern

Done
Finding leaks
Stas' Python Cookbook - selected path

Profiling CPU and Memory: Finding leaks (gc.collect, gc.garbage) with the refcounting one-liner; tracemalloc above it for sizing

Done

Focus on

CPython frees by refcount immediately and collects cycles later. A self-referencing object with __del__ is still collected since Python 3.4 by PEP 442.
sys.getrefcount counts its own argument, and CPython 3.14 borrows references when it loads locals, so one fresh object reads 2 at module level and 1 inside a function. The docs promise nothing beyond 0 or 1; compare readings taken in one context, never absolutes.
weakref.ref fails on list and dict instances (subclasses can opt in), on tuple and int, and on slotted classes without __weakref__; sets and frozensets support it. Caches want WeakValueDictionary, not manual callback books.
gc.garbage holds objects the collector refused; an empty list after gc.collect() proves the run happened, not that nothing leaked.

Reproduce closed-book

Closed-book, build a two-object cycle with a __del__ method and a weakref callback, delete both names, and, with gc.disable() first, show that nothing runs until gc.collect(), which fires the callback and both __del__ methods. Then show sys.getrefcount on a fresh object reads 2 at module level and 1 inside a function on CPython 3.14.4.

Traps

Depending on __del__ timing. Collection order is unspecified, so close resources explicitly.
Caching instances in a plain dict. The cache owns them forever; WeakValueDictionary or explicit eviction bounds it.
Reading gc.garbage as the leak list. It holds objects the collector refused; ordinary leaks never appear there.

Practice

The section mini-project covers this: lifetime reasoning behind the seeded cleanup defect, with a cycle-collection probe as the regression test.

Self-test

a = []; b = [a]; a.append(b); del a, b. When is the memory freed?
sys.getrefcount(x) reads 2 for a fresh object at module level but 1 inside a function. Why?
weakref.ref([1, 2, 3]) raises TypeError. Why?
A slotted class cannot be weak-referenced. What is missing?

Completion criterion

Stop when

Your cycle probe frees on collect, your weakref callback fires, and you can state which reference keeps any object alive.

Mark passed, then open 4.1 Only mark this when you can do it without notes.

Leads to

6.5 Profiling CPU and memory, and benchmarking honestly Memory growth in profiles often traces to cycles and caches.
3.4 Iterators, generators and lazy pipelines Lazy pipelines and weak caches both bound memory; compare the two tools.

Comes after

3.1 Names, identity, mutability, copying and hashabilityConnect aliasing to object lifetimes and weak references.

Resources for this unit

Stas' Python Cookbook - selected path
Stas Bekmanprimarycourse
Run Part I on dictionaries, iteration, functions, closures, decorators, classes and context managers; Part II on modules, files, paths, environment and arguments; and Part IV on versions, dependencies, packaging and code quality. Finish by building one src-layout package from a blank directory.
Python language reference
Python Software Foundationrequiredreference
Check Data model, Execution model, Import system and Exceptions whenever a claim depends on Python semantics. These pages are the authority when the course and a runtime observation disagree.
gc - cycle garbage collector
Python Software Foundationreferencereference
Read the cycle collector interface: collect, get_count, garbage and disable/enable. Use for the cycle-collection and measurement parts of refcounting-gc-weakrefs.
weakref - weak references
Python Software Foundationreferencereference
Read weak-reference objects (ref callbacks, proxy objects) and the WeakValueDictionary example. Use for the weak-reference part of refcounting-gc-weakrefs.

Also in this section

Packaging Python Projects
Python Packaging Authorityrequiredimplementation
Follow the packaging tutorial once from a blank directory, using a src layout, pyproject.toml, an isolated build and a clean-environment installation test.
AlgoMaster Python - structured revision
AlgoMastersupportpractice
Use Functions, Modules and Packages, OOP, Advanced OOP, Exception Handling, Iterators and Generators, Type Hints and Annotations only after the cookbook pass. Open it for recall practice or a diagnosed weak mechanism, not as a second complete course.
dataclasses - data classes
Python Software Foundationreferencereference
Read the @dataclass parameters (eq, order, frozen, slots), field() with default_factory, frozen instances, post-init processing, replace, asdict and astuple. Use for the validated frozen dataclass in attributes-protocols-dataclasses.
typing - type hints and protocols
Python Software Foundationreferencereference
Read Protocols for structural typing and runtime_checkable limits, Generics for TypeVar generics, and assert_type for narrowing checks. Use for the Protocol and narrowing parts of type-hints-protocols; PEP 695 syntax itself is in the language reference.