Metadata-Version: 1.0
Name: Benchmarker
Version: 2.0.0
Summary: a small utility for benchmarking
Home-page: http://pypi.python.org/pypi/Benchmarker/
Author: makoto kuwata
Author-email: kwa@kuwata-lab.com
License: Public Domain
Download-URL: http://pypi.python.org/packages/source/B/Benchmarker/Benchmarker-2.0.0.tar.gz
Description: Benchmarker is a small utility to benchmark your code.
        
        See `CHANGES.txt <http://bitbucket.org/kwatch/benchmarker/annotate/tip/python/CHANGES.txt>`_
        for details of changes and enhancements.
        
        
        Download
        --------
        
        http://pypi.python.org/pypi/Benchmarker/
        
        Installation::
        
        ## if you have installed easy_install:
        $ sudo easy_install Benchmarker
        ## or download Benchmarker-2.0.0.tar.gz and install it
        $ wget http://pypi.python.org/packages/source/B/Benchmarker/Benchmarker-2.0.0.tar.gz
        $ tar xzf Benchmarker-2.0.0.tar.gz
        $ cd Benchmarker-2.0.0/
        $ sudo python setup.py install
        
        
        Example for Busy People
        -----------------------
        
        ex0.py::
        
        from __future__ import with_statement
        from benchmarker import Benchmarker
        s1, s2, s3, s4, s5 = "Haruhi", "Mikuru", "Yuki", "Itsuki", "Kyon"
        with Benchmarker(loop=1000*1000) as bm:
        for i in bm.empty():    ## empty loop
        pass
        for i in bm('"".join((s,s,s))'):
        sos = "".join((s1, s2, s3, s4, s5))
        for i in bm('s+s+s'):
        sos = s1 + s2 + s3 + s4 + s5
        for i in bm('"%s%s%s" % (s,s,s)'):
        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        
        Output::
        
        $ python ex0.py
        ## benchmarker:       release 0.0.0 (for python)
        ## python platform:   darwin [GCC 4.2.1 (Apple Inc. build 5659)]
        ## python version:    2.5.5
        ## python executable: /usr/local/python/2.5.5/bin/python
        
        ## Benchmark                        user       sys     total      real
        (Empty)                           0.1200    0.0300    0.1500    0.1605
        "".join((s,s,s))                  0.7300   -0.0300    0.7000    0.6992
        s+s+s                             0.6600   -0.0200    0.6400    0.6321
        "%s%s%s" % (s,s,s)                0.8700   -0.0300    0.8400    0.8305
        
        ## Ranking                          real  ratio  chart
        s+s+s                             0.6321 (100.0) ********************
        "".join((s,s,s))                  0.6992 ( 90.4) ******************
        "%s%s%s" % (s,s,s)                0.8305 ( 76.1) ***************
        
        ## Ratio Matrix                     real    [01]    [02]    [03]
        [01] s+s+s                        0.6321   100.0   110.6   131.4
        [02] "".join((s,s,s))             0.6992    90.4   100.0   118.8
        [03] "%s%s%s" % (s,s,s)           0.8305    76.1    84.2   100.0
        
        Notice that empty loop times (user, sys, total, and real) are subtracted from other benchmark times automatically.
        For example, 0.6992 = 0.8597 - 0.1605.
        
        
        Step by Step Examples
        ---------------------
        
        Basic example (ex1.py)::
        
        from __future__ import with_statement
        if 'xrange' not in globals():
        xrange = range
        
        ## benchmarker object
        from benchmarker import Benchmarker
        bm = Benchmarker()     # or Benchmarker(width=30, out=sys.stderr)
        print(bm.platform())   # python version, os information, ...
        
        ## Python 2.5 or later
        loop = 1000 * 1000
        s1, s2, s3, s4, s5 = "Haruhi", "Mikuru", "Yuki", "Itsuki", "Kyon"
        with bm.empty():              # optional: empty loop results are
        for i in xrange(loop):    # subtracted automatically from
        pass                  # other benchmark results.
        with bm('"".join((s,s,s))'):
        for i in xrange(loop):
        sos = "".join((s1, s2, s3, s4, s5))
        with bm('s+s+s'):
        for i in xrange(loop):
        sos = s1 + s2 + s3 + s4 + s5
        with bm('"%s%s%s" % (s,s,s)'):
        for i in xrange(loop):
        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        
        ### Python 2.4
        #def f0(n):
        #    for i in xrange(n):
        #        pass
        #def f1(n):
        #    """''.join((s,s,s))"""
        #    for i in xrange(n):
        #        sos = "".join((s1, s2, s3, s4, s5))
        #def f2(n):
        #    """s+s+s"""
        #    for i in xrange(n):
        #        sos = s1 + s2 + s3 + s4 + s5
        #def f3(n):
        #    """'%s%s%s' % (s,s,s)"""
        #    for i in xrange(n):
        #        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        #bm.empty().run(f0, loop)
        #bm().run(f1, loop)
        #bm().run(f2, loop)
        #bm().run(f3, loop)
        
        ## statistics
        print(bm.stat.all())
        
        
        Output example::
        
        $ python ex1.py
        ## benchmarker:       release 0.0.0 (for python)
        ## python platform:   darwin [GCC 4.2.1 (Apple Inc. build 5659)]
        ## python version:    2.5.5
        ## python executable: /usr/local/python/2.5.5/bin/python
        
        ## Benchmark                        user       sys     total      real
        (Empty)                           0.1200    0.0300    0.1500    0.1605
        "".join((s,s,s))                  0.7300   -0.0300    0.7000    0.6992
        s+s+s                             0.6600   -0.0200    0.6400    0.6321
        "%s%s%s" % (s,s,s)                0.8700   -0.0300    0.8400    0.8305
        
        ## Ranking                          real  ratio  chart
        s+s+s                             0.6321 (100.0) ********************
        "".join((s,s,s))                  0.6992 ( 90.4) ******************
        "%s%s%s" % (s,s,s)                0.8305 ( 76.1) ***************
        
        ## Ratio Matrix                     real    [01]    [02]    [03]
        [01] s+s+s                        0.6321   100.0   110.6   131.4
        [02] "".join((s,s,s))             0.6992    90.4   100.0   118.8
        [03] "%s%s%s" % (s,s,s)           0.8305    76.1    84.2   100.0
        
        
        Notice that benchmark results are subtracted by '(Empty)' loop results.
        For example: 0.7300 = 0.8500 - 0.1200; -0.0300 = 0.000 - 0.0300; 0.7000 = 0.8500 - 0.1500; 0.6992 = 0.8597 - 0.1605; and so on.
        
        If you pass 'loop=N' to Benchmarker(), benchmark code can be more simple.
        
        Example (ex2.py)::
        
        from __future__ import with_statement
        
        ## start benchmark
        from benchmarker import Benchmarker
        bm = Benchmarker(loop=1000*1000)    ## specify loop count (default: 1)
        print(bm.platform())
        
        ## use for-statement instead of with-statement
        s1, s2, s3, s4, s5 = "Haruhi", "Mikuru", "Yuki", "Itsuki", "Kyon"
        for i in bm.empty():
        pass
        for i in bm('"".join((s,s,s))'):
        sos = "".join((s1, s2, s3, s4, s5))
        for i in bm('s+s+s'):
        sos = s1 + s2 + s3 + s4 + s5
        for i in bm('"%s%s%s" % (s,s,s)'):
        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        
        ### or
        #def f0():
        #    pass
        #def f1():
        #    """''.join((s,s,s))"""
        #    sos = "".join((s1, s2, s3, s4, s5))
        #def f2():
        #    """s+s+s"""
        #    sos = s1 + s2 + s3 + s4 + s5
        #def f3():
        #    """'%s%s%s' % (s,s,s)"""
        #    sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        #bm.empty().run(f0)
        #bm().run(f1)
        #bm().run(f2)
        #bm().run(f3)
        
        ## statistics
        print(bm.stat.all())
        
        
        You can repeat benchmarks and calculate average of them.
        If you specify 'extra=1' parameter, Benchmarker will remove min and max values from benchmarks to remove abnormal result.
        
        Example (ex3.py)::
        
        from __future__ import with_statement
        
        ## start benchmark
        from benchmarker import Benchmarker
        bm = Benchmarker(loop=1000*1000)    ## specify loop count
        print(bm.platform())
        
        ## repeat benchmark 3 times + 2*1 times
        s1, s2, s3, s4, s5 = "Haruhi", "Mikuru", "Yuki", "Itsuki", "Kyon"
        for b in bm.repeat(3, extra=1):
        for i in b.empty():
        pass
        for i in b('"".join((s,s,s))'):
        sos = "".join((s1, s2, s3, s4, s5))
        for i in b('s+s+s'):
        sos = s1 + s2 + s3 + s4 + s5
        for i in b('"%s%s%s" % (s,s,s)'):
        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        
        ## or
        #def f0():
        #    pass
        #def f1():
        #    """''.join((s,s,s))"""
        #    sos = "".join((s1, s2, s3, s4, s5))
        #def f2():
        #    """s+s+s"""
        #    sos = s1 + s2 + s3 + s4 + s5
        #def f3():
        #    """'%s%s%s' % (s,s,s)"""
        #    sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        #for b in bm.repeat(5, extra=1):
        #    b.empty().run(f0)
        #    b().run(f1)
        #    b().run(f2)
        #    b().run(f3)
        
        ## statistics
        print(bm.stat.all())
        
        
        Output example::
        
        $ python ex3.py
        ## benchmarker:       release 0.0.0 (for python)
        ## python platform:   darwin [GCC 4.2.1 (Apple Inc. build 5659)]
        ## python version:    2.5.5
        ## python executable: /usr/local/python/2.5.5/bin/python
        
        ## Benchmark #1                     user       sys     total      real
        (Empty)                           0.1600    0.0000    0.1600    0.1637
        "".join((s,s,s))                  0.7400    0.0000    0.7400    0.7474
        s+s+s                             0.6400    0.0000    0.6400    0.6394
        "%s%s%s" % (s,s,s)                0.9000    0.0000    0.9000    0.9071
        
        ## Benchmark #2                     user       sys     total      real
        (Empty)                           0.1700    0.0000    0.1700    0.1715
        "".join((s,s,s))                  0.7200    0.0000    0.7200    0.7289
        s+s+s                             0.6400    0.0000    0.6400    0.6537
        "%s%s%s" % (s,s,s)                0.8600    0.0000    0.8600    0.8662
        
        ## Benchmark #3                     user       sys     total      real
        (Empty)                           0.1600    0.0000    0.1600    0.1679
        "".join((s,s,s))                  0.7500    0.0000    0.7500    0.7416
        s+s+s                             0.6400    0.0000    0.6400    0.6315
        "%s%s%s" % (s,s,s)                0.8800    0.0000    0.8800    0.8829
        
        ## Benchmark #4                     user       sys     total      real
        (Empty)                           0.1600    0.0000    0.1600    0.1588
        "".join((s,s,s))                  0.7400    0.0100    0.7500    0.7465
        s+s+s                             0.6300    0.0000    0.6300    0.6440
        "%s%s%s" % (s,s,s)                0.9000    0.0000    0.9000    0.9057
        
        ## Benchmark #5                     user       sys     total      real
        (Empty)                           0.1500    0.0000    0.1500    0.1589
        "".join((s,s,s))                  0.7500    0.0000    0.7500    0.7549
        s+s+s                             0.6400    0.0000    0.6400    0.6317
        "%s%s%s" % (s,s,s)                0.9100    0.0000    0.9100    0.9147
        
        ## Remove min & max                  min    bench#       max    bench#
        "".join((s,s,s))                  0.7289        #2    0.7549        #5
        s+s+s                             0.6315        #3    0.6537        #2
        "%s%s%s" % (s,s,s)                0.8662        #2    0.9147        #5
        
        ## Average of 3 (=5-2*1)            user       sys     total      real
        "".join((s,s,s))                  0.7433    0.0033    0.7467    0.7452
        s+s+s                             0.6367    0.0000    0.6367    0.6384
        "%s%s%s" % (s,s,s)                0.8933    0.0000    0.8933    0.8986
        
        ## Ranking                          real  ratio  chart
        s+s+s                             0.6384 (100.0) ********************
        "".join((s,s,s))                  0.7452 ( 85.7) *****************
        "%s%s%s" % (s,s,s)                0.8986 ( 71.0) **************
        
        ## Ratio Matrix                     real    [01]    [02]    [03]
        [01] s+s+s                        0.6384   100.0   116.7   140.8
        [02] "".join((s,s,s))             0.7452    85.7   100.0   120.6
        [03] "%s%s%s" % (s,s,s)           0.8986    71.0    82.9   100.0
        
        
        In the above example, minimum and maximum results are removed automatically before calculate average result because 'extra=1' is specified.
        
        If you needs only average result, redirect stderr to /dev/null or dummy file. ::
        
        $ python ex3.py > /dev/null
        ## benchmarker:       release 0.0.0 (for python)
        ## python platform:   darwin [GCC 4.2.1 (Apple Inc. build 5659)]
        ## python version:    2.5.5
        ## python executable: /usr/local/python/2.5.5/bin/python
        
        ## Average of 3 (=5-2*1)            user       sys     total      real
        "".join((s,s,s))                  0.7433    0.0033    0.7467    0.7452
        s+s+s                             0.6367    0.0000    0.6367    0.6384
        "%s%s%s" % (s,s,s)                0.8933    0.0000    0.8933    0.8986
        
        ## Ranking                          real  ratio  chart
        s+s+s                             0.6384 (100.0) ********************
        "".join((s,s,s))                  0.7452 ( 85.7) *****************
        "%s%s%s" % (s,s,s)                0.8986 ( 71.0) **************
        
        ## Ratio Matrix                     real    [01]    [02]    [03]
        [01] s+s+s                        0.6384   100.0   116.7   140.8
        [02] "".join((s,s,s))             0.7452    85.7   100.0   120.6
        [03] "%s%s%s" % (s,s,s)           0.8986    71.0    82.9   100.0
        
        If you always print platform information and statistics, you can simplify code by with-statement.
        
        Example (ex4.py)::
        
        from __future__ import with_statement
        from benchmarker import Benchmarker
        s1, s2, s3, s4, s5 = "Haruhi", "Mikuru", "Yuki", "Itsuki", "Kyon"
        with Benchmarker(loop=1000*1000) as bm:
        for b in bm.repeat(3, extra=1):
        for i in b.empty():
        pass
        for i in b('"".join((s,s,s))'):
        sos = "".join((s1, s2, s3, s4, s5))
        for i in b('s+s+s'):
        sos = s1 + s2 + s3 + s4 + s5
        for i in b('"%s%s%s" % (s,s,s)'):
        sos = "%s%s%s%s%s" % (s1, s2, s3, s4, s5)
        
        
        
        Tips
        ----
        
        * If you don't specify benchmark label, function document or name is used as label.
        ::
        
        def f2():
        """s+s+s"""
        sos = "Haruhi" + "Mikuru" + "Yuki" + "Itsuki" + "Kyon"
        bm = Benchmarker()
        bm().run(f2)     # same as bm('s+s+s').run(f2)
        
        
        * You can get benchmark results by bm.results.
        ::
        
        for result in bm.results:
        print(result)
        ## output example:
        #('"".join((s,s,s))', 0.57, 0.0,  0.57, 0.5772)
        #('s+s+s', 0.44, 0.0, 0.44, 0.4340)
        #('"%s%s%s" % (s,s,s)', 0.75, 0.0, 0.75, 0.7666)
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Public Domain
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.3
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.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Benchmark
