Commit bf92903e authored by SVN-Git Migration's avatar SVN-Git Migration

Imported Upstream version 1.5.0

parent 7c28cafe
42.png

17.9 KB

Changes
=======
.. currentmodule:: objgraph
1.5.0 (2010-12-05)
------------------
Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
New functions: :func:`show_growth`, :func:`show_chain`.
:func:`find_backref_chain` returns ``[obj]`` instead of ``None`` when a chain
could not be found. This makes ``show_chain(find_backref_chain(...), ...)``
not break.
Show how many references were skipped from the output of
:func:`show_refs`/:func:`show_backrefs` by specifying ``too_many``.
Make :func:`show_refs` descend into modules.
Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
Option to show reference counts in :func:`show_refs`/:func:`show_backrefs`.
Add `Sphinx <http://pypi.python.org/pypi/Sphinx>`_ documentation and a PyPI
long description.
1.4.0 (2010-11-03)
------------------
Compatibility with Python 2.4 and 2.5 (``tempfile.NamedTemporaryFile`` has no
``delete`` argument).
New function: :func:`most_common_types`.
1.3.1 (2010-07-17)
------------------
Rebuild an sdist with no missing files (fixes `LP#606604
<http://launchpad.net/bugs/606604>`_).
Added MANIFEST.in and a Makefile to check that setup.py sdist generates
source distributions with no files missing.
1.3 (2010-07-13)
----------------
Highlight objects with a ``__del__`` method.
Fixes `LP#483411 <http://launchpad.net/bugs/483411>`_: suggest always passing
``[obj]`` to :func:`show_refs`, :func:`show_backrefs`, since obj might be a
list/tuple.
Fixes `LP#514422 <http://launchpad.net/bugs/514422>`_: :func:`show_refs`,
:func:`show_backrefs` don't create files in the current working directory any
more. Instead they accept a filename argument, which can be a .dot file or a
.png file. If None or not specified, those functions will try to spawn xdot
as before.
New extra_info argument to graph-generating functions (patch by Thouis Jones,
`LP#558914 <http://launchpad.net/bugs/558914>`_).
setup.py should work with distutils now (`LP#604430
<http://launchpad.net/bugs/604430>`_, thanks to Randy Heydon).
1.2 (2009-03-25)
----------------
Project website, public source repository, uploaded to PyPI.
No code changes.
1.1 (2008-09-10)
----------------
New function: :func:`show_refs` for showing forward references.
New functions: :func:`typestats` and :func:`show_most_common_types`.
Object boxes are less crammed with useless information (such as IDs).
Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
1.0 (2008-06-14)
----------------
First public release.
include Makefile include Makefile
include examples.txt include *.txt
include *.png include *.png
include tests.py include tests.py
include conf.py
include _static/*.css
PYTHON = python PYTHON = python
FILE_WITH_VERSION = objgraph.py FILE_WITH_VERSION = objgraph.py
FILE_WITH_CHANGELOG = objgraph.py FILE_WITH_CHANGELOG = CHANGES.txt
SPHINXOPTS =
SPHINXBUILD = sphinx-build
BUILDDIR = _build
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
.PHONY: default .PHONY: default
default: default:
@echo "Nothing to build here" @echo "Nothing to build here"
.PHONY: images
images:
$(PYTHON) setup.py --build-images
.PHONY: docs
docs:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Now look at $(BUILDDIR)/html/index.html"
.PHONY: clean
clean:
-rm -rf $(BUILDDIR)/*
.PHONY: test check .PHONY: test check
test check: test check:
$(PYTHON) tests.py $(PYTHON) tests.py
.PHONY: test-all-pythons
test-all-pythons:
make test PYTHON=python2.4
make test PYTHON=python2.5
make test PYTHON=python2.6
make test PYTHON=python2.7
.PHONY: coverage
coverage:
PYTHONPATH=.:$$PYTHONPATH coverage run tests.py
coverage report
.PHONY: dist .PHONY: dist
dist: dist:
$(PYTHON) setup.py sdist $(PYTHON) setup.py sdist
...@@ -55,7 +86,12 @@ releasechecklist: ...@@ -55,7 +86,12 @@ releasechecklist:
.PHONY: release .PHONY: release
release: releasechecklist release: releasechecklist
# I'm chicken so I won't actually do these things yet # I'm chicken so I won't actually do these things yet
@echo "Please run" @echo "It is a good idea to run"
@echo
@echo " make test-all-pythons"
@echo " make clean images docs"
@echo
@echo "about now. Then commit the new images and run"
@echo @echo
@echo " $(PYTHON) setup.py sdist register upload && bzr tag `$(PYTHON) setup.py --version`" @echo " $(PYTHON) setup.py sdist register upload && bzr tag `$(PYTHON) setup.py --version`"
@echo @echo
...@@ -64,4 +100,5 @@ release: releasechecklist ...@@ -64,4 +100,5 @@ release: releasechecklist
@echo @echo
@echo ' bzr ci -m "Post-release version bump" && bzr push' @echo ' bzr ci -m "Post-release version bump" && bzr push'
@echo @echo
@echo "and don't forget to publish the docs from _build/html"
Metadata-Version: 1.0 Metadata-Version: 1.0
Name: objgraph Name: objgraph
Version: 1.4.0 Version: 1.5.0
Summary: Draws Python object reference graphs with graphviz Summary: Draws Python object reference graphs with graphviz
Home-page: http://mg.pov.lt/objgraph/ Home-page: http://mg.pov.lt/objgraph/
Author: Marius Gedminas Author: Marius Gedminas
Author-email: marius@gedmin.as Author-email: marius@gedmin.as
License: MIT License: MIT
Description: UNKNOWN Description: Python Object Graphs
====================
``objgraph`` is a module that lets you visually explore Python object graphs.
You'll need `graphviz <http://www.graphviz.org/>`_ if you want to draw
the pretty graphs.
I recommend `xdot <http://pypi.python.org/pypi/xdot>`_ for interactive use.
``pip install xdot`` should suffice; objgraph will automatically look for it
in your ``PATH``.
Installation and Documentation
------------------------------
``pip install objgraph`` or `download it from PyPI
<http://pypi.python.org/pypi/objgraph>`_.
Documentation lives at http://mg.pov.lt/objgraph.
.. _history:
History
-------
I've developed a set of functions that eventually became objgraph when I
was hunting for memory leaks in a Python program. The whole story -- with
illustrated examples -- is in this series of blog posts:
* `Hunting memory leaks in Python
<http://mg.pov.lt/blog/hunting-python-memleaks.html>`_
* `Python object graphs
<http://mg.pov.lt/blog/python-object-graphs.html>`_
* `Object graphs with graphviz
<http://mg.pov.lt/blog/object-graphs-with-graphviz.html>`_
.. _devel:
Support and Development
-----------------------
The source code can be found in this Bazaar repository:
https://code.launchpad.net/~mgedmin/objgraph/trunk.
To check it out, use ``bzr branch lp:objgraph``.
Report bugs at https://bugs.launchpad.net/objgraph.
Changes
=======
1.5.0 (2010-12-05)
------------------
Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
New functions: `show_growth`, `show_chain`.
`find_backref_chain` returns ``[obj]`` instead of ``None`` when a chain
could not be found. This makes ``show_chain(find_backref_chain(...), ...)``
not break.
Show how many references were skipped from the output of
`show_refs`/`show_backrefs` by specifying ``too_many``.
Make `show_refs` descend into modules.
Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
Option to show reference counts in `show_refs`/`show_backrefs`.
Add `Sphinx <http://pypi.python.org/pypi/Sphinx>`_ documentation and a PyPI
long description.
1.4.0 (2010-11-03)
------------------
Compatibility with Python 2.4 and 2.5 (``tempfile.NamedTemporaryFile`` has no
``delete`` argument).
New function: `most_common_types`.
1.3.1 (2010-07-17)
------------------
Rebuild an sdist with no missing files (fixes `LP#606604
<http://launchpad.net/bugs/606604>`_).
Added MANIFEST.in and a Makefile to check that setup.py sdist generates
source distributions with no files missing.
1.3 (2010-07-13)
----------------
Highlight objects with a ``__del__`` method.
Fixes `LP#483411 <http://launchpad.net/bugs/483411>`_: suggest always passing
``[obj]`` to `show_refs`, `show_backrefs`, since obj might be a
list/tuple.
Fixes `LP#514422 <http://launchpad.net/bugs/514422>`_: `show_refs`,
`show_backrefs` don't create files in the current working directory any
more. Instead they accept a filename argument, which can be a .dot file or a
.png file. If None or not specified, those functions will try to spawn xdot
as before.
New extra_info argument to graph-generating functions (patch by Thouis Jones,
`LP#558914 <http://launchpad.net/bugs/558914>`_).
setup.py should work with distutils now (`LP#604430
<http://launchpad.net/bugs/604430>`_, thanks to Randy Heydon).
1.2 (2009-03-25)
----------------
Project website, public source repository, uploaded to PyPI.
No code changes.
1.1 (2008-09-10)
----------------
New function: `show_refs` for showing forward references.
New functions: `typestats` and `show_most_common_types`.
Object boxes are less crammed with useless information (such as IDs).
Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
1.0 (2008-06-14)
----------------
First public release.
Platform: UNKNOWN Platform: UNKNOWN
...@@ -2,45 +2,50 @@ Python Object Graphs ...@@ -2,45 +2,50 @@ Python Object Graphs
==================== ====================
``objgraph`` is a module that lets you visually explore Python object graphs. ``objgraph`` is a module that lets you visually explore Python object graphs.
I've used it in the past to go hunt for memory leaks in Python programs as
described by this series of blog posts:
* http://mg.pov.lt/blog/hunting-python-memleaks.html
* http://mg.pov.lt/blog/python-object-graphs.html
* http://mg.pov.lt/blog/object-graphs-with-graphviz.html
You'll need `graphviz <http://www.graphviz.org/>`_ if you want to draw You'll need `graphviz <http://www.graphviz.org/>`_ if you want to draw
pretty graphs. the pretty graphs.
I recommend `xdot <http://pypi.python.org/pypi/xdot>`_ for interactive use.
``pip install xdot`` should suffice; objgraph will automatically look for it
in your ``PATH``.
Installation and Documentation
------------------------------
``pip install objgraph`` or `download it from PyPI
<http://pypi.python.org/pypi/objgraph>`_.
Documentation lives at http://mg.pov.lt/objgraph.
.. This is a reStructuredText file. I recommend http://mg.pov.lt/restview
for viewing it.
.. _history:
Examples History
-------- -------
Try this in a Python shell: I've developed a set of functions that eventually became objgraph when I
was hunting for memory leaks in a Python program. The whole story -- with
illustrated examples -- is in this series of blog posts:
>>> x = [] * `Hunting memory leaks in Python
>>> y = [x, [x], dict(x=x)] <http://mg.pov.lt/blog/hunting-python-memleaks.html>`_
>>> import objgraph * `Python object graphs
>>> objgraph.show_refs([y], filename='sample-graph.png') <http://mg.pov.lt/blog/python-object-graphs.html>`_
Graph written to ....dot (5 nodes) * `Object graphs with graphviz
Image generated as sample-graph.png <http://mg.pov.lt/blog/object-graphs-with-graphviz.html>`_
You should see a graph like this:
.. image:: sample-graph.png .. _devel:
:alt: [graph of objects reachable from y]
Now try Support and Development
-----------------------
>>> objgraph.show_backrefs([x], filename='sample-backref-graph.png') The source code can be found in this Bazaar repository:
Graph written to ....dot (7 nodes) https://code.launchpad.net/~mgedmin/objgraph/trunk.
Image generated as sample-backref-graph.png
and you'll see To check it out, use ``bzr branch lp:objgraph``.
.. image:: sample-backref-graph.png Report bugs at https://bugs.launchpad.net/objgraph.
:alt: [graph of objects from which y is reachable]
@import url("default.css");
pre {
border: 1px dotted #869abf;
overflow: hidden;
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
border: none;
font-weight: bold;
}
div.figure {
text-align: center;
}
# -*- coding: utf-8 -*-
#
# objgraph documentation build configuration file, created by
# sphinx-quickstart on Sun Dec 5 04:46:55 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath('.'))
def relative(filename):
here = os.path.dirname('__file__')
return os.path.join(here, filename)
def get_version():
d = {}
exec open(relative('objgraph.py')).read() in d
return d['__version__']
def get_short_version():
return '.'.join(get_version().split('.')[:2])
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.txt'
# The encoding of source files.
#source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'objgraph'
copyright = u'2010, Marius Gedminas'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = get_short_version()
# The full version, including alpha/beta/rc tags.
release = get_version()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
unused_docs = [
'README',
]
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = [
'_build',
'build',
'objgraph.egg-info',
]
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'rightsidebar': True,
'footerbgcolor': 'white',
'footertextcolor': 'gray',
'headbgcolor': 'white',
'headtextcolor': '#134D73',
'relbarbgcolor': 'white',
'relbartextcolor': 'gray',
'relbarlinkcolor': '#869ABF',
'sidebarbgcolor': 'white',
'sidebartextcolor': 'gray',
'sidebarlinkcolor': '#869ABF',
'bgcolor': 'white',
'textcolor': 'black',
'linkcolor': '#869ABF',
## 'visitedlinkcolor': 'purple', <-- my sphinx is too old?
'codebgcolor': '#f0f5ef',
'codetextcolor': 'black',
}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The stylesheet used instead of default.css
html_style = "mg.css"
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "home"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = [
'_static',
]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_use_modindex = True
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'objgraphdoc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'objgraph.tex', u'objgraph Documentation',
u'Marius Gedminas', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_use_modindex = True
Extra information
-----------------
You can add extra information to object graphs, if you desire.
>>> x = []
>>> y = [x, [x], dict(x=x)]
>>> import objgraph
>>> objgraph.show_refs([y], extra_info=lambda x: hex(id(x)),
... filename='extra-info.png')
Graph written to ....dot (5 nodes)
Image generated as extra-info.png
.. figure:: extra-info.png
finalizers.png

15.6 KB | W: | H:

finalizers.png

14.3 KB | W: | H:

finalizers.png
finalizers.png
finalizers.png
finalizers.png
  • 2-up
  • Swipe
  • Onion skin
Stack frames and generators
===========================
Let's define a custom class
>>> class Canary(object):
... pass
Suppose we've a generator that uses it
>>> def count_to_three():
... tweety = Canary()
... yield 1
... yield 2
... yield 3
and we make it active
>>> it = count_to_three()
>>> it.next()
1
Now we can see that our Canary object is alive in memory
>>> import objgraph
>>> objgraph.count('Canary')
1
and we can see what holds it in memory
>>> objgraph.show_backrefs(objgraph.by_type('Canary'),
... max_depth=7,
... filename='canary.png')
Graph written to ....dot (15 nodes)
Image generated as canary.png
.. figure:: canary.png
:alt: [graph of objects from which the canary is reachable]
:scale: 50%
Or we can examine just one of the reference chains leading straight a module.
>>> import inspect
>>> objgraph.show_chain(
... objgraph.find_backref_chain(objgraph.by_type('Canary')[0],
... inspect.ismodule),
... filename='canary-chain.png')
Graph written to ....dot (11 nodes)
Image generated as canary-chain.png
.. figure:: canary-chain.png
:alt: [chain of objects from a module to the canary]
:scale: 50%