pympler.classtracker

The ClassTracker is a facility delivering insight into the memory distribution of a Python program. It can introspect memory consumption of certain classes and objects. Facilities are provided to track and size individual objects or all instances of certain classes. Tracked objects are sized recursively to provide an overview of memory distribution between the different tracked objects.

Classes

class pympler.classtracker.ClassTracker(stream: Optional[IO] = None)

clear() → None

Clear all gathered data and detach from all tracked objects/classes.

create_snapshot(description: str = '', compute_total: bool = False) → None

Collect current per instance statistics and saves total amount of memory associated with the Python process.

If compute_total is True, the total consumption of all objects known to asizeof is computed. The latter might be very slow if many objects are mapped into memory at the time the snapshot is taken. Therefore, compute_total is set to False by default.

The overhead of the ClassTracker structure is also computed.

Snapshots can be taken asynchronously. The function is protected with a lock to prevent race conditions.

detach_all() → None

Detach from all tracked classes and objects. Restore the original constructors and cleanse the tracking lists.

detach_all_classes() → None

Detach from all tracked classes.

detach_class(cls: type) → None

Stop tracking class ‘cls’. Any new objects of that type are not tracked anymore. Existing objects are still tracked.

start_periodic_snapshots(interval: float = 1.0) → None

Start a thread which takes snapshots periodically. The interval specifies the time in seconds the thread waits between taking snapshots. The thread is started as a daemon allowing the program to exit. If periodic snapshots are already active, the interval is updated.

stop_periodic_snapshots() → None

Post a stop signal to the thread that takes the periodic snapshots. The function waits for the thread to terminate which can take some time depending on the configured interval.

track_class(cls: type, name: Optional[str] = None, resolution_level: int = 0, keep: bool = False, trace: bool = False) → None

Track all objects of the class cls. Objects of that type that already exist are not tracked. If track_class is called for a class already tracked, the tracking parameters are modified. Instantiation traces can be generated by setting trace to True. A constructor is injected to begin instance tracking on creation of the object. The constructor calls track_object internally.

Parameters

• cls – class to be tracked, may be an old-style or a new-style class

• name – reference the class by a name, default is the concatenation of module and class name

• resolution_level – The recursion depth up to which referents are sized individually. Resolution level 0 (default) treats the object as an opaque entity, 1 sizes all direct referents individually, 2 also sizes the referents of the referents and so forth.

• keep – Prevent the object’s deletion by keeping a (strong) reference to the object.

• trace – Save instantiation stack trace for each instance

track_object(instance: Any, name: Optional[str] = None, resolution_level: int = 0, keep: bool = False, trace: bool = False) → None

Track object ‘instance’ and sample size and lifetime information. Not all objects can be tracked; trackable objects are class instances and other objects that can be weakly referenced. When an object cannot be tracked, a TypeError is raised.

Parameters

• resolution_level – The recursion depth up to which referents are sized individually. Resolution level 0 (default) treats the object as an opaque entity, 1 sizes all direct referents individually, 2 also sizes the referents of the referents and so forth.

• keep – Prevent the object’s deletion by keeping a (strong) reference to the object.