objgraph

The project supports Python 2.7 and 3.5+. You can use tox to run the test suite across all supported versions automatically.

tox -p auto

To fully rebuild the project documentation and all associated images, run:

make clean images docs

Note: When committing changes, use git checkout -- docs/*.png for images that haven't changed significantly, as memory addresses in images often change between runs.

To start contributing to objgraph, clone the repository and run the test suite to ensure everything is working correctly.

# Clone the source
git clone https://github.com/mgedmin/objgraph

# Run the test suite
make test

To see how much of the code is covered by the existing (mostly smoke) tests, use the coverage tool via the provided Makefile command.

To view a text-based summary:

make coverage

To generate an HTML report:

make coverage
coverage html

Then browse the results in htmlcov/index.html.

You can install objgraph using pip from PyPI.

pip install objgraph

To draw pretty graphs, you must have graphviz installed on your system. For interactive use, it is recommended to install xdot. objgraph will automatically look for xdot in your PATH.

pip install xdot

The PyPI long description is generated by concatenating README.rst and CHANGES.rst. You can preview how this will look using the make command:

make preview-pypi-description

All new functions must have a PEP-257 compliant docstring. When adding them, ensure you add the appropriate autodoc directive to objgraph.txt.

Docstring Formatting Rules:

1. Closing Triple Quotes: The closing """ should not be preceded by a blank line.

   def do_something():
       """Do something.
   
       Return something valuable.
       """

2. Indented Blocks: If the last part of a docstring is an indented block quote or a doctest, it must be surrounded by blank lines.

   def do_something():
       """Do something.
   
       Return something valuable.
   
       Example:
   
           >>> do_something()
           42
   
       """

Since many tests are verified by inspecting generated images, you can debug failures by comparing visual output. Use make images with a specific Python version and imgdiff to see the differences.

# Generate images for a specific Python version
make images PYTHON=pythonX.Y

# Configure git to use imgdiff for visual comparison
git config diff.imgdiff.command 'f() { imgdiff --eog -H $1 $2; }; f'

# Compare the generated images
git diff docs/*.png