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

Imported Upstream version 1.6.0

parent bf92903e
......@@ -3,94 +3,113 @@ Changes
.. currentmodule:: objgraph
1.6.0 (2010-12-18)
------------------
- Python 3 support, thanks to Stefano Rivera (fixes `LP#687601
<http://launchpad.net/bugs/687601>`_).
- Removed weird weakref special-casing.
1.5.1 (2010-12-09)
------------------
- Avoid test failures in uncollectable-garbage.txt (fixes `LP#686731
<http://launchpad.net/bugs/686731>`_).
- Added HACKING.txt.
1.5.0 (2010-12-05)
------------------
Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
- Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
New functions: :func:`show_growth`, :func:`show_chain`.
- 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.
- :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``.
- 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.
- Make :func:`show_refs` descend into modules.
Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
- 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`.
- 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.
- 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).
- Compatibility with Python 2.4 and 2.5 (``tempfile.NamedTemporaryFile`` has no
``delete`` argument).
New function: :func:`most_common_types`.
- 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>`_).
- 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.
- 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.
- 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#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.
- 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>`_).
- 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).
- 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.
- Project website, public source repository, uploaded to PyPI.
No code changes.
- No code changes.
1.1 (2008-09-10)
----------------
New function: :func:`show_refs` for showing forward references.
- New function: :func:`show_refs` for showing forward references.
New functions: :func:`typestats` and :func:`show_most_common_types`.
- New functions: :func:`typestats` and :func:`show_most_common_types`.
Object boxes are less crammed with useless information (such as IDs).
- Object boxes are less crammed with useless information (such as IDs).
Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
- Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
1.0 (2008-06-14)
----------------
First public release.
- First public release.
.. _hacking:
Hacking on objgraph
===================
Start by geting the latest source with ::
bzr branch lp:objgraph
Run the test suite with ::
make test
The test suite is mostly smoke tests (i.e. crashes will be noticed, subtly
wrong output will be missed). I hope to improve that in the future, but don't
hold your breath. Most of the testing is done manually or semi-automatically,
e.g. by running ``make images`` and eyeballing the results (`imgdiff
<http://pypi.python.org/pypi/imgdiff>`_ is handy there).
Sending me patches
------------------
Bazaar branches and merge proposals are probably the best way to send me
patches. Or just attach the pathces to a bug in Launchpad. Or email them
to <marius@gedmin.as>.
I'd appreciate `bugs in launchpad
<https://bugs.launchpad.net/objgraph/+filebug>`_ for each proposed change, be
it a bug or a feature request.
Supported Python versions
-------------------------
Python 2.4 through 2.7, as well as 3.x.
You can run the test suite for all supported Python versions with ::
make test-all-pythons
An easy way to get Pythons 2.4 through 2.7 (and 3.1) on Ubuntu is to use Felix
Krull's "`deadsnakes <https://launchpad.net/~fkrull/+archive/deadsnakes>`_"
PPA::
sudo add-apt-repository ppa:~fkrull/deadsnakes
sudo apt-get install python2.{4,5,6,7} python3.1
Test coverage
-------------
As I mentioned, the tests are mostly smoke tests, and even then they're
incomplete. Install `coverage <http://pypi.python.org/pypi/coverage>`_
to see how incomplete they are with ::
make coverage
I use a `vim plugin <http://mg.pov.lt/vim/plugin/py-coverage-highlight.vim>`_
to higlight lines not covered by tests while I edit ::
mkdir -p ~/.vim/plugin
cd ~/.vim/plugin
wget http://mg.pov.lt/vim/plugin/py-coverage-highlight.vim
cd ...
make coverage
vim objgraph.py
:HighlightCoverage
If you prefer HTML reports, run ::
make coverage
coverage html
and then browse ``htmlcov/index.html``.
Documentation
-------------
To fully rebuild the documentation, run ::
make clean images docs
Please ``bzr revert`` the png files that haven't changed significantly. (Many
of the images include things like memory addresses which tend to change from
run to run.)
`imgdiff <http://pypi.python.org/pypi/imgdiff>`_ is useful for comparing the
images with older versions::
bzr diff --using imgdiff *.png
When you add a new doctest file, remember to include it in ``docs/index.txt``.
When you add a new function, make sure it has a `PEP-257
<http://www.python.org/dev/peps/pep-0257/>`_-compliant docstring and
add the appropriate autodoc directive to ``objgraph.txt``.
I insist on one departure from PEP-257: the closing ``"""`` should *not* be
preceded by a blank line. Example::
def do_something():
"""Do something.
Return something valuable.
"""
If Emacs is broken, fix emacs, do not make my docstrings ugly.
On the other hand, if the last thing in a docstring is an indented block
quote/doctest section, it should be surrounded by blank lines. Like this::
def do_something():
"""Do something.
Return something valuable.
Example:
>>> do_something()
42
"""
I find `restview <http://pypi.python.org/pypi/restview>`_ very handy for
documentation writing: it lets me see how the text looks by pressing Ctrl-R
in a browser window, without having to re-run any documentation building
commands. The downside is that ``restview`` doesn't support Sphinx extensions
to ReStructuredText, so you end up with error messages all over the place.
Then again this is useful for bits that *can't* use Sphinx extensions, like
the PyPI long description.
To preview the PyPI long description (which is generated by concatenating
``README.txt`` and ``CHANGES.txt``) with ``restview``, use this handy command::
make preview-pypi-description
because typing ::
restview -e "python setup.py --long-description"
is tedious, and bash has tab-completion for makefile rules.
Making releases
---------------
You need write access to the PyPI package and to the Bazaar branch on
Launchpad. At the moment of this writing, this means you must be me.
Run ``make release`` and follow the instructions. It is safe to run this
command at any time: it never commits/pushes/uploads to PyPI, it just tells
you what to do.
Avoiding incomplete releases
----------------------------
It is important to keep `MANIFEST.in
<http://docs.python.org/distutils/sourcedist.html#manifest-template>`_ up to
date so that source tarballs generated with ``python setup.py sdist`` aren't
missing any files, even if you don't have the right setuptools version control
plugins installed. You can run ::
make distcheck
to be sure this is so, but it's not necessary -- ``make release`` will do this
every time.
include Makefile
include *.txt
include *.png
include tests.py
include conf.py
include _static/*.css
include docs/*.txt
include docs/*.png
include docs/conf.py
include docs/_static/*.css
......@@ -4,8 +4,8 @@ FILE_WITH_CHANGELOG = CHANGES.txt
SPHINXOPTS =
SPHINXBUILD = sphinx-build
BUILDDIR = _build
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
BUILDDIR = docs/_build
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) docs/
.PHONY: default
......@@ -32,10 +32,21 @@ test check:
.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
set -e; \
for ver in 2.4 2.5 2.6 2.7 3.0 3.1 3.2; do \
if which python$$ver > /dev/null; then \
$(MAKE) test PYTHON=python$$ver; \
else \
echo "=================================="; \
echo "Skipping python$$ver, not available."; \
echo "=================================="; \
fi; \
done
.PHONY: preview-pypi-description
preview-pypi-description:
# pip install restview, if missing
restview -e "$(PYTHON) setup.py --long-description"
.PHONY: coverage
coverage:
......
Metadata-Version: 1.0
Name: objgraph
Version: 1.5.0
Version: 1.6.0
Summary: Draws Python object reference graphs with graphviz
Home-page: http://mg.pov.lt/objgraph/
Author: Marius Gedminas
......@@ -65,96 +65,127 @@ Description: Python Object Graphs
1.6.0 (2010-12-18)
------------------
- Python 3 support, thanks to Stefano Rivera (fixes `LP#687601
<http://launchpad.net/bugs/687601>`_).
- Removed weird weakref special-casing.
1.5.1 (2010-12-09)
------------------
- Avoid test failures in uncollectable-garbage.txt (fixes `LP#686731
<http://launchpad.net/bugs/686731>`_).
- Added HACKING.txt.
1.5.0 (2010-12-05)
------------------
Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
- Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
New functions: `show_growth`, `show_chain`.
- 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.
- `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``.
- Show how many references were skipped from the output of
`show_refs`/`show_backrefs` by specifying ``too_many``.
Make `show_refs` descend into modules.
- Make `show_refs` descend into modules.
Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
- Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
Option to show reference counts in `show_refs`/`show_backrefs`.
- Option to show reference counts in `show_refs`/`show_backrefs`.
Add `Sphinx <http://pypi.python.org/pypi/Sphinx>`_ documentation and a PyPI
long description.
- 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).
- Compatibility with Python 2.4 and 2.5 (``tempfile.NamedTemporaryFile`` has no
``delete`` argument).
New function: `most_common_types`.
- 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>`_).
- 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.
- 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.
- 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#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.
- 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>`_).
- 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).
- 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.
- Project website, public source repository, uploaded to PyPI.
No code changes.
- No code changes.
1.1 (2008-09-10)
----------------
New function: `show_refs` for showing forward references.
- New function: `show_refs` for showing forward references.
New functions: `typestats` and `show_most_common_types`.
- New functions: `typestats` and `show_most_common_types`.
Object boxes are less crammed with useless information (such as IDs).
- Object boxes are less crammed with useless information (such as IDs).
Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
- Spawns `xdot <http://pypi.python.org/pypi/xdot>`_ if it is available.
1.0 (2008-06-14)
----------------
First public release.
- First public release.
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.4
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
.. include:: ../CHANGES.txt
.. include:: ../HACKING.txt
......@@ -16,7 +16,7 @@ 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('.'))
sys.path.append(os.path.abspath('..'))
def relative(filename):
here = os.path.dirname('__file__')
......@@ -24,7 +24,7 @@ def relative(filename):
def get_version():
d = {}
exec open(relative('objgraph.py')).read() in d
exec open(relative('../objgraph.py')).read() in d
return d['__version__']
def get_short_version():
......
......@@ -17,7 +17,7 @@ Suppose we've a generator that uses it
and we make it active
>>> it = count_to_three()
>>> it.next()
>>> next(it)
1
Now we can see that our Canary object is alive in memory
......@@ -30,7 +30,7 @@ and we can see what holds it in memory
>>> objgraph.show_backrefs(objgraph.by_type('Canary'),
... max_depth=7,
... filename='canary.png')
... filename='canary.png') # doctest: +NODES_VARY
Graph written to ....dot (15 nodes)
Image generated as canary.png
......
.. include:: README.txt
.. include:: ../README.txt
:end-before: .. _history:
......@@ -28,7 +28,7 @@ Backreferences
Now try
>>> objgraph.show_backrefs([x], filename='sample-backref-graph.png')
>>> objgraph.show_backrefs([x], filename='sample-backref-graph.png') # doctest: +NODES_VARY
Graph written to ....dot (8 nodes)
Image generated as sample-backref-graph.png
......@@ -39,6 +39,19 @@ and you'll see
:scale: 50%
Memory overview
---------------
To get a quick overview of the objects in memory
>>> objgraph.show_most_common_types() # doctest: +RANDOM_OUTPUT
tuple 5351
function 1369
wrapper_descriptor 967
dict 786
...
Memory leak example
-------------------
......@@ -123,7 +136,7 @@ Reference Documentation
objgraph
.. include:: README.txt
.. include:: ../README.txt
:start-after: .. _history:
:end-before: .. _devel:
......@@ -135,9 +148,16 @@ And here's the change log
CHANGES
.. include:: README.txt
.. include:: ../README.txt
:start-after: .. _devel:
For more information, see :ref:`hacking`.
.. toctree::
:hidden:
HACKING
.. Indices and tables
.. ------------------
......
......@@ -4,7 +4,7 @@ Too many references
Objects that have too many references are truncated
>>> import objgraph
>>> objgraph.show_refs([range(7)], too_many=5, filename='too-many.png')
>>> objgraph.show_refs([list(range(7))], too_many=5, filename='too-many.png')
Graph written to ....dot (6 nodes)
Image generated as too-many.png
......@@ -32,7 +32,7 @@ the reference count somewhat.
>>> import sys
>>> one_reference = object()
>>> objgraph.show_backrefs([one_reference], refcounts=True,
... filename='refcounts.png')
... filename='refcounts.png') # doctest: +NODES_VARY
Graph written to ....dot (5 nodes)
Image generated as refcounts.png
......
......@@ -14,14 +14,21 @@ collector if they participate in a cycle.
>>> x.append(y)
>>> y.append(z)
>>> z.append(x)
When you remove all other references to these, they end up in ``gc.garbage``.
>>> import objgraph
>>> del x, y, z
>>> import gc
>>> _ = gc.collect()
>>> len(gc.garbage)
1
We highlight these objects by showing the existence of a ``__del__``.
>>> import objgraph
>>> objgraph.show_backrefs(objgraph.by_type('Nondestructible'),
... filename='finalizers.png')
Graph written to ....dot (3 nodes)
... filename='finalizers.png') # doctest: +NODES_VARY
Graph written to ....dot (8 nodes)
Image generated as finalizers.png
.. figure:: finalizers.png
......
Metadata-Version: 1.0
Name: objgraph
Version: 1.5.0
Version: 1.6.0
Summary: Draws Python object reference graphs with graphviz
Home-page: http://mg.pov.lt/objgraph/
Author: Marius Gedminas
......@@ -65,96 +65,127 @@ Description: Python Object Graphs
1.6.0 (2010-12-18)
------------------
- Python 3 support, thanks to Stefano Rivera (fixes `LP#687601
<http://launchpad.net/bugs/687601>`_).
- Removed weird weakref special-casing.
1.5.1 (2010-12-09)
------------------
- Avoid test failures in uncollectable-garbage.txt (fixes `LP#686731
<http://launchpad.net/bugs/686731>`_).
- Added HACKING.txt.
1.5.0 (2010-12-05)
------------------
Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
- Show frame objects as well (fixes `LP#361704
<http://launchpad.net/bugs/361704>`_).
New functions: `show_growth`, `show_chain`.
- 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.
- `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``.
- Show how many references were skipped from the output of
`show_refs`/`show_backrefs` by specifying ``too_many``.
Make `show_refs` descend into modules.
- Make `show_refs` descend into modules.
Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
- Do not highlight classes that define a ``__del__``, highlight only instances of
those classes.
Option to show reference counts in `show_refs`/`show_backrefs`.
- Option to show reference counts in `show_refs`/`show_backrefs`.
Add `Sphinx <http://pypi.python.org/pypi/Sphinx>`_ documentation and a PyPI