or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

graph-visualization.mdgrowth-analysis.mdindex.mdobject-discovery.mdobject-statistics.mdreference-chains.md
tile.json

tessl/pypi-objgraph

Draws Python object reference graphs with graphviz

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/objgraph@3.6.x

To install, run

npx @tessl/cli install tessl/pypi-objgraph@3.6.0

index.mddocs/

objgraph

A Python module for visualizing Python object reference graphs with graphviz. objgraph helps developers track memory usage, identify memory leaks, and understand object relationships by providing tools to count objects, analyze growth patterns, and generate visual graphs of object references.

Package Information

  • Package Name: objgraph
  • Language: Python
  • Installation: pip install objgraph
  • Version: 3.6.2

Core Imports

import objgraph

Basic Usage

import objgraph

# Count objects by type
print(objgraph.count('list'))  # Count all list objects
print(objgraph.count('dict'))  # Count all dict objects

# Show most common object types
objgraph.show_most_common_types()

# Track object growth between code sections
objgraph.show_growth()
# ... run some code that might create objects ...
objgraph.show_growth()  # Shows increases since last call

# Find objects by type
my_lists = objgraph.by_type('list')
print(f"Found {len(my_lists)} list objects")

# Visualize what refers to an object
my_object = [1, 2, 3]
objgraph.show_backrefs([my_object], filename='backrefs.png')

# Visualize what an object refers to  
objgraph.show_refs([my_object], filename='refs.png')

Architecture

objgraph operates on Python's garbage collector and provides three main interaction patterns:

  • Statistical Analysis: Count and categorize objects tracked by the garbage collector
  • Growth Monitoring: Track changes in object counts over time to identify memory leaks
  • Reference Visualization: Generate graphviz diagrams showing object reference relationships

The module integrates with Python's gc module to access tracked objects and uses graphviz for visualization. Optional xdot integration provides interactive graph viewing.

Capabilities

Object Statistics and Counting

Functions for counting objects, analyzing type distributions, and getting statistical overviews of memory usage patterns.

def count(typename, objects=None): ...
def typestats(objects=None, shortnames=True, filter=None): ...
def most_common_types(limit=10, objects=None, shortnames=True, filter=None): ...
def show_most_common_types(limit=10, objects=None, shortnames=True, file=None, filter=None): ...

Object Statistics

Growth Analysis and Monitoring

Tools for tracking object creation and growth patterns over time, essential for identifying memory leaks and monitoring memory usage.

def growth(limit=10, peak_stats={}, shortnames=True, filter=None): ...
def show_growth(limit=10, peak_stats=None, shortnames=True, file=None, filter=None): ...
def get_new_ids(skip_update=False, limit=10, sortby='deltas', shortnames=None, file=None, _state={}): ...

Growth Analysis

Object Discovery and Access

Functions for finding specific objects by type or memory address, and identifying potential memory leaks.

def by_type(typename, objects=None): ...
def at(addr): ...
def at_addrs(address_set): ...
def get_leaking_objects(objects=None): ...

Object Discovery

Reference Chain Analysis

Tools for tracing reference chains between objects to understand how objects are connected and what keeps them alive.

def find_ref_chain(obj, predicate, max_depth=20, extra_ignore=()): ...
def find_backref_chain(obj, predicate, max_depth=20, extra_ignore=()): ...

Reference Chains

Graph Visualization

Generate visual representations of object reference graphs using graphviz, with support for interactive viewing and various output formats.

def show_backrefs(objs, max_depth=3, extra_ignore=(), filter=None, too_many=10, highlight=None, filename=None, extra_info=None, refcounts=False, shortnames=True, output=None, extra_node_attrs=None): ...
def show_refs(objs, max_depth=3, extra_ignore=(), filter=None, too_many=10, highlight=None, filename=None, extra_info=None, refcounts=False, shortnames=True, output=None, extra_node_attrs=None): ...
def show_chain(*chains, **kw): ...

Graph Visualization

Utility Functions

Module Detection

def is_proper_module(obj):
    """
    Check if object is a proper module (in sys.modules).
    
    Args:
        obj: Object to check
        
    Returns:
        bool: True if obj is a proper module
    """

Constants

# Module metadata
__version__: str    # "3.6.2"
__author__: str     # "Marius Gedminas (marius@gedmin.as)"
__copyright__: str  # "Copyright (c) 2008-2023 Marius Gedminas and contributors"
__license__: str    # "MIT"
__date__: str       # "2024-10-10"

# Runtime configuration  
IS_INTERACTIVE: bool  # True if running in IPython/Jupyter

Error Handling

objgraph functions generally raise standard Python exceptions:

  • ValueError: For invalid parameter combinations (e.g., specifying both filename and output in visualization functions)
  • AttributeError: For missing object attributes during introspection
  • OSError/FileNotFoundError: When output files cannot be created
  • ImportError: When optional dependencies like graphviz are missing
  • Functions with safe representation fallbacks catch generic Exception and return safe string alternatives