Merge develop to master for a new pypi release 1.0.2

.gitignore

@@ -11,3 +11,5 @@ dist/
 
 *.pyc
 __pycache__
+.idea
+

.travis.yml

@@ -4,7 +4,18 @@ language:
 python:
   - "2.7"
   - "3.3"
+  - "3.4"
   - "pypy"
+# pytest does not support python 3.5
+# https://bitbucket.org/pytest-dev/pytest/pull-request/296/astcall-signature-changed-on-35
+# - "nightly"
+
+matrix:
+  allow_failures:
+    - python:
+       - "pypy"
+    - python:
+       - "nigthly"
 
 env:
   global:
@@ -16,8 +27,8 @@ before_install:
  - sudo apt-get install -qq graphviz
 
 install:
- - "pip install -r requirements/development.txt --use-mirrors"
- - "if [[ $TRAVIS_PYTHON_VERSION == '3.3' ]]; then make 2to3; fi"
+ - "pip install -r requirements/development.txt"
+ - "if [[ $TRAVIS_PYTHON_VERSION == '3.3' ]] || [[ $TRAVIS_PYTHON_VERSION == '3.4' ]] || [[ $TRAVIS_PYTHON_VERSION == 'nightly' ]]; then make 2to3; fi"
 
 script:
  - make tests

MANIFEST.in

@@ -3,6 +3,6 @@ include LICENSE
 include README.rst
 include requirements
 include test
-include docs
+recursive-include docs *
 include examples/*.py
 include man/pycallgraph.1

README.rst

@@ -3,10 +3,14 @@ Python Call Graph
 
 Welcome! Python Call Graph is a `Python <http://www.python.org>`_ module that creates `call graph <http://en.wikipedia.org/wiki/Call_graph>`_ visualizations for Python applications.
 
-.. image:: https://travis-ci.org/gak/pycallgraph.svg
+.. image:: https://img.shields.io/travis/gak/pycallgraph.svg
     :target: https://travis-ci.org/gak/pycallgraph
-.. image:: https://coveralls.io/repos/gak/pycallgraph/badge.svg?branch=develop
+.. image:: https://img.shields.io/coveralls/gak/pycallgraph/develop.svg
     :target: https://coveralls.io/r/gak/pycallgraph?branch=develop
+.. image:: https://img.shields.io/pypi/v/pycallgraph.svg
+    :target: https://crate.io/packages/pycallgraph/
+.. image:: https://img.shields.io/pypi/dm/pycallgraph.svg
+    :target: https://crate.io/packages/pycallgraph
 
 Screenshots
 ===========
@@ -23,7 +27,7 @@ Click on the images below to see a larger version and the source code that gener
 Project Status
 ==============
 
-The latest version is **1.0.1** which was released on 2013-09-17, and is a backwards incompatbile from the previous release.
+The latest version is **1.0.1** which was released on 2013-09-17, and is a backwards incompatible from the previous release.
 
 The `project lives on GitHub <https://github.com/gak/pycallgraph/#python-call-graph>`_, where you can `report issues <https://github.com/gak/pycallgraph/issues>`_, contribute to the project by `forking the project <https://help.github.com/articles/fork-a-repo>`_ then creating a `pull request <https://help.github.com/articles/using-pull-requests>`_, or just `browse the source code <https://github.com/gak/pycallgraph/>`_.
 
@@ -62,6 +66,34 @@ A simple use of the API is::
     with PyCallGraph(output=GraphvizOutput()):
         code_to_profile()
 
+Use decorators for an even more simple use of the API::
+
+    from pycallgraph.decorators import trace
+
+    @trace("path/to/output.png")
+    def main():
+        code_to_profile()
+
+    main()
+
+Or decorate a specific function inside your code you want to profile::
+
+    from pycallgraph.decorators import trace
+
+    @trace("path/to/output.png")
+    def function_1():
+        do_stuff
+
+    def function_2():
+        do_stuff
+
+    def code_to_profile():
+        function_1()
+        function_2()
+
+    code_to_profile()
+
+
 Documentation
 =============
 

docs/guide/command_line_usage.rst

@@ -15,14 +15,14 @@ Description
 
 	pycallgraph is a program that creates call graph visualization from Python scripts.
 
-*OUTPUT_MODE* can be one of graphviz, gephi and json. *python_file.py* is a python script that will be traced and afterwards, a call graph visualization will be generated.
+*OUTPUT_MODE* can be one of graphviz or gephi. *python_file.py* is a python script that will be traced and afterwards, a call graph visualization will be generated.
 
 General Arguments
 -----------------
 
 .. cmdoption:: <OUTPUT_MODE>
 
-    A choice of graphviz, gephi and json.
+    A choice of graphviz or gephi.
 
 .. cmdoption:: -h, --help
 

docs/guide/intro.rst

@@ -3,7 +3,7 @@ Intro
 
 Python Call Graph was made to be a visual profiling tool for Python applications. It uses a debugging Python function called `sys.set_trace() <http://docs.python.org/dev/library/sys#sys.settrace>`_ which makes a callback every time your code enters or leaves function. This allows Python Call Graph to track the name of every function called, as well as which function called which, the time taken within each function, number of calls, etc.
 
-It is able to generate different types of :ref:`outputs and visualizations <outputs>`. Initially Python Call Graph was only used to generate DOT files for `GraphViz <http://graphviz.org/>`_, and as of version 1.0.0, it can also generate JSON files, and GDF files for Gephi. Creating :ref:`custom outputs <custom_outputs>` is fairly easy by subclassing the :ref:`Output <output>` class.
+It is able to generate different types of :ref:`outputs and visualizations <outputs>`. Initially Python Call Graph was only used to generate DOT files for `GraphViz <http://graphviz.org/>`_, and as of version 1.0.0, it can also generate GDF files for Gephi. Creating :ref:`custom outputs <custom_outputs>` is fairly easy by subclassing the :ref:`Output <output>` class.
 
 You can either use the :ref:`command-line interface <command_line_usage>` for a quick visualization of your Python script, or the :ref:`pycallgraph module <pycallgraph>` for more fine-grained settings.
 

examples/graphviz/example_with_submodules/__init__.py

@@ -0,0 +1,3 @@
+from .example_with_submodules import main
+
+__all__ = [main]

examples/graphviz/example_with_submodules/example_with_submodules.py

@@ -0,0 +1,13 @@
+from submodule_one import SubmoduleOne
+from submodule_two import SubmoduleTwo
+
+
+def main():
+    s1 = SubmoduleOne()
+    s1.report()
+
+    s2 = SubmoduleTwo()
+    s2.report()
+
+if __name__ == "__main__":
+    main()

examples/graphviz/example_with_submodules/helpers.py

@@ -0,0 +1,2 @@
+def helper(something):
+    return something

examples/graphviz/example_with_submodules/submodule_one.py

@@ -0,0 +1,6 @@
+class SubmoduleOne(object):
+    def __init__(self):
+        self.one = 1
+
+    def report(self):
+        return self.one

examples/graphviz/example_with_submodules/submodule_two.py

@@ -0,0 +1,9 @@
+from helpers import helper
+
+
+class SubmoduleTwo(object):
+    def __init__(self):
+        self.two = 2
+
+    def report(self):
+        return helper(self.two)

examples/graphviz/grouper.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+'''
+This example demonstrates the use of grouping.
+'''
+from pycallgraph import PyCallGraph
+from pycallgraph import Config
+from pycallgraph import GlobbingFilter
+from pycallgraph import Grouper
+from pycallgraph.output import GraphvizOutput
+import example_with_submodules
+
+
+def run(name, trace_grouper=None, config=None, comment=None):
+    if not config:
+        config = Config()
+
+    config.trace_filter = GlobbingFilter()
+
+    if trace_grouper is not None:
+        config.trace_grouper = trace_grouper
+
+    graphviz = GraphvizOutput()
+    graphviz.output_file = 'grouper-{}.png'.format(name)
+    if comment:
+        graphviz.graph_attributes['graph']['label'] = comment
+
+    with PyCallGraph(config=config, output=graphviz):
+        example_with_submodules.main()
+
+
+def group_none():
+    run(
+        'without',
+        comment='Default grouping.'
+    )
+
+
+def group_some():
+    trace_grouper = Grouper(groups=[
+        'example_with_submodules.submodule_one.*',
+        'example_with_submodules.submodule_two.*',
+        'example_with_submodules.helpers.*',
+    ])
+
+    run(
+        'with',
+        trace_grouper=trace_grouper,
+        comment='Should assign groups to the two submodules.',
+    )
+
+
+def group_methods():
+    trace_grouper = Grouper(groups=[
+        'example_with_submodules.*.report',
+        ])
+
+    run(
+        'methods',
+        trace_grouper=trace_grouper,
+        comment='Should assign a group to the report methods.',
+    )
+
+
+def main():
+    group_none()
+    group_some()
+    group_methods()
+
+
+if __name__ == '__main__':
+    main()

man/pycallgraph.1

@@ -64,12 +64,12 @@ pycallgraph [\fIOPTION\fP]... \fIOUTPUT_MODE\fP [\fIOUTPUT_OPTIONS\fP] \fIpython
 .sp
 pycallgraph is a program that creates call graph visualization from Python scripts.
 .sp
-\fIOUTPUT_MODE\fP can be one of graphviz, gephi and json. \fIpython_file.py\fP is a python script that will be traced and afterwards, a call graph visualization will be generated.
+\fIOUTPUT_MODE\fP can be one of graphviz or gephi. \fIpython_file.py\fP is a python script that will be traced and afterwards, a call graph visualization will be generated.
 .SH GENERAL ARGUMENTS
 .INDENT 0.0
 .TP
 .B <OUTPUT_MODE>
-A choice of graphviz, gephi and json.
+A choice of graphviz or gephi.
 .UNINDENT
 .INDENT 0.0
 .TP

pycallgraph/__init__.py

@@ -14,8 +14,13 @@
 
 from .pycallgraph import PyCallGraph
 from .exceptions import PyCallGraphException
+try:
+    from . import decorators
+except Exception:
+    import decorators
 from .config import Config
 from .globbing_filter import GlobbingFilter
+from .grouper import Grouper
 from .util import Util
 from .color import Color
 from .color import ColorException

pycallgraph/config.py

@@ -3,6 +3,7 @@
 
 from .output import outputters
 from .globbing_filter import GlobbingFilter
+from .grouper import Grouper
 
 
 class Config(object):
@@ -31,6 +32,9 @@ def __init__(self, **kwargs):
             include=['*'],
         )
 
+        # Grouping
+        self.trace_grouper = Grouper()
+
         self.did_init = True
 
         # Update the defaults with anything from kwargs

pycallgraph/decorators.py

@@ -0,0 +1,20 @@
+import functools
+
+from .pycallgraph import PyCallGraph
+from .output import GraphvizOutput
+
+
+def trace(output=None, config=None):
+    def inner(func):
+        @functools.wraps(func)
+        def exec_func(*args, **kw_args):
+
+            graphviz = GraphvizOutput()
+            graphviz.output_file = output
+
+            with(PyCallGraph(output=graphviz, config=config)):
+                return func(*args, **kw_args)
+
+        return exec_func
+
+    return inner

pycallgraph/grouper.py

@@ -0,0 +1,26 @@
+from fnmatch import fnmatch
+
+
+class Grouper(object):
+    '''Group module names.
+
+    By default, objects are grouped by their top-level module name. Additional
+    groups can be specified with the groups list and all objects will be
+    matched against it.
+    '''
+
+    def __init__(self, groups=None):
+        if groups is None:
+            groups = []
+
+        self.groups = groups
+
+    def __call__(self, full_name=None):
+        for pattern in self.groups:
+            if fnmatch(full_name, pattern):
+                if pattern[-2:] == ".*":
+                    # a wilcard in the middle is probably meaningful, while at
+                    # the end, it's only noise and can be removed
+                    return pattern[:-2]
+                return pattern
+        return full_name.split('.', 1)[0]