{"author":"Jon Crall","author_email":"erotemic@gmail.com","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","License :: OSI Approved :: Apache Software License","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.6","Programming Language :: Python :: 3.7","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Software Development :: Libraries :: Python Modules","Topic :: Utilities"],"description":"\n|GithubActions| |Appveyor| |Codecov| |Pypi| |Downloads| |ReadTheDocs|\n\n\nTimerit\n=======\n\nA powerful multiline alternative to Python's builtin ``timeit`` module.\n\nDocs are published at https://timerit.readthedocs.io/en/latest/ but this README\nand code comments contain a walkthrough.\n\n+---------------+--------------------------------------------+\n| Github | https://github.com/Erotemic/timerit |\n+---------------+--------------------------------------------+\n| Pypi | https://pypi.org/project/timerit |\n+---------------+--------------------------------------------+\n| ReadTheDocs | https://timerit.readthedocs.io/en/latest/ |\n+---------------+--------------------------------------------+\n\nDescription\n-----------\n\nEasily do robust timings on existing blocks of code by simply indenting\nthem. There is no need to refactor into a string representation or\nconvert to a single line.\n\nInstallation\n------------\n\n.. code:: bash\n\n pip install timerit\n\n\nInteractive Use\n---------------\n\nThe ``timerit`` library provides a succinct API for interactive use:\n\n.. code:: python\n\n >>> import timerit\n >>> for _ in timerit:\n ... sum(range(100000))\n Timed for: 288 loops, best of 5\n time per loop: best=616.740 µs, mean=668.933 ± 124.2 µs\n\nCompare to ``timeit``:\n\n.. code:: bash\n\n $ python -m timeit 'sum(range(100000))'\n 500 loops, best of 5: 721 usec per loop\n\nBy default, any code within the loop will be repeatedly executed until at least\n200 ms have elapsed. The timing results are then printed out.\n\nHere's what each of the numbers means:\n\n- \"288 loops\": The code in the loop was run 288 times before the time limit was\n reached.\n\n- \"best of 5\": Consider only the fastest of every 5 measured times, when\n calculating the mean and standard deviation. The reason for doing this is\n that you can get slow times if the something in the background is consuming\n resources, so you're generally only interested in the fastest times. This\n idea is also described in the\n `timeit `_ docs.\n\n- \"best=616.740 µs\": How long the fastest iteration took to run. For the reasons\n described above, this is usually the most consistent number, and the primary\n number you should focus on.\n\n- \"mean=668.933 ± 124.2 µs\": The mean and the standard deviation of the \"best of 5\"\n iterations. This statistic is usually not as robust or useful as the fastest\n time, but sometimes its helpful to know if there's high variance.\n\nThe loop variable can be used as a context manager to only time a part of each\nloop (e.g. to make the timings more accurate, or to incorporate a setup phase\nthat is not timed):\n\n.. code:: python\n\n >>> for timer in timerit:\n ... n = 100 * 1000\n ... with timer:\n ... sum(range(n))\n Timed for: 318 loops, best of 5\n time per loop: best=616.673 µs, mean=617.545 ± 0.9 µs\n\nIt is also possible to provide arguments controlling how the timing\nmeasurements are made. See the online documentation for more information on\nthese arguments, but the snippet below runs for exactly 100 iterations, instead\nof however many fit in 200 ms.\n\n.. code:: python\n\n >>> for _ in timerit(num=100):\n ... sum(range(100000))\n Timed for: 100 loops, best of 5\n time per loop: best=616.866 µs, mean=619.120 ± 5.3 µs\n\n\nAutomatic Import\n~~~~~~~~~~~~~~~~\nIf you want to make ``timerit`` even easier to use interactively, you can move\nthe import to the PYTHONSTARTUP_ file. If defined, this environment variable\ngives the path to a python script that will be executed just before every\ninteractive session. For example:\n\n.. code:: bash\n\n $ export PYTHONSTARTUP=~/.pythonrc\n $ cat $PYTHONSTARTUP\n import timerit\n $ python\n >>> for _ in timerit:\n ... sum(range(100000))\n ...\n Timed for: 59 loops, best of 3\n time per loop: best=2.532 ms, mean=3.309 ± 1.0 ms\n\n\nProgrammatic Use\n----------------\n\nThe timerit library also provides a ``Timerit`` class that can be used\nprogrammatically.\n\n.. code:: python\n\n >>> import math, timerit\n >>> for timer in timerit:\n >>> setup_vars = 10000\n >>> with timer:\n >>> math.factorial(setup_vars)\n >>> print('t1.total_time = %r' % (t1.total_time,))\n Timing for 200 loops\n Timed for: 200 loops, best of 3\n time per loop: best=2.064 ms, mean=2.115 ± 0.05 ms\n t1.total_time = 0.4427177629695507\n\nA common pattern is to create a single ``Timerit`` instance, then to repeatedly\n\"reset\" it with different labels to test a number of different algorithms. The\nlabels assigned in this way will be incorporated into the report strings that\nthe ``Timerit`` instance produces. The \"Benchmark Recipe\" below shows an example\nof this pattern. So do all of the scripts in the ``examples/`` directory.\n\nThere is also a simple one-liner that is comparable to ``timeit``'s IPython magic:\n\nCompare the timeit version:\n\n.. code:: python\n\n >>> %timeit math.factorial(100)\n 564 ns ± 5.46 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)\n\nWith the Timerit version:\n\n.. code:: python\n\n >>> Timerit(100000).call(math.factorial, 100).print()\n Timed for: 1 loops, best of 1\n time per loop: best=4.828 µs, mean=4.828 ± 0.0 µs\n\n\nHow it works\n------------\n\nThe timerit module defines ``timerit.Timerit``, which is an iterable object\nthat yields ``timerit.Timer`` context managers.\n\n.. code:: python\n\n >>> import math\n >>> from timerit import Timerit\n >>> for timer in Timerit(num=200, verbose=2):\n >>> with timer:\n >>> math.factorial(10000)\n\nThe timer context manager measures how much time the body of it takes by\n\"tic\"-ing on ``__enter__`` and \"toc\"-ing on ``__exit__``. The parent\n``Timerit`` object has access to the context manager, so it is able to read its\nmeasurement. These measurements are stored and then we compute some statistics\non them. Notably the minimum, mean, and standard-deviation of grouped (batched)\nrunning times.\n\nUsing the with statement inside the loop is nice because you can run untimed\nsetup code before you enter the context manager.\n\nIn the case where no setup code is required, a more concise version of the\nsyntax is available.\n\n.. code:: python\n\n >>> import math\n >>> from timerit import Timerit\n >>> for _ in Timerit(num=200, verbose=2):\n >>> math.factorial(10000)\n\nIf the context manager is never called, the ``Timerit`` object detects this and\nthe measurement is made in the ``__iter__`` method in the ``Timerit`` object\nitself. I believe that this concise method contains slightly more overhead than\nthe with-statement version. (I have seen evidence that this might actually be\nmore accurate, but it needs further testing).\n\nBenchmark Recipe\n----------------\n\n.. code:: python\n\n import ubelt as ub\n import pandas as pd\n import timerit\n\n def method1(x):\n ret = []\n for i in range(x):\n ret.append(i)\n return ret\n\n def method2(x):\n ret = [i for i in range(x)]\n return ret\n\n method_lut = locals() # can populate this some other way\n\n ti = timerit.Timerit(100, bestof=10, verbose=2)\n\n basis = {\n 'method': ['method1', 'method2'],\n 'x': list(range(7)),\n # 'param_name': [param values],\n }\n grid_iter = ub.named_product(basis)\n\n # For each variation of your experiment, create a row.\n rows = []\n for params in grid_iter:\n key = ub.repr2(params, compact=1, si=1)\n kwargs = params.copy()\n method_key = kwargs.pop('method')\n method = method_lut[method_key]\n # Timerit will run some user-specified number of loops.\n # and compute time stats with similar methodology to timeit\n for timer in ti.reset(key):\n # Put any setup logic you dont want to time here.\n # ...\n with timer:\n # Put the logic you want to time here\n method(**kwargs)\n row = {\n 'mean': ti.mean(),\n 'min': ti.min(),\n 'key': key,\n **params,\n }\n rows.append(row)\n\n # The rows define a long-form pandas data array.\n # Data in long-form makes it very easy to use seaborn.\n data = pd.DataFrame(rows)\n print(data)\n\n plot = True\n if plot:\n # import seaborn as sns\n # kwplot autosns works well for IPython and script execution.\n # not sure about notebooks.\n import kwplot\n sns = kwplot.autosns()\n\n # Your variables may change\n ax = kwplot.figure(fnum=1, doclf=True).gca()\n sns.lineplot(data=data, x='x', y='min', hue='method', marker='o', ax=ax)\n ax.set_title('Benchmark Name')\n ax.set_xlabel('x-variable description')\n ax.set_ylabel('y-variable description')\n\n\n.. |Travis| image:: https://img.shields.io/travis/Erotemic/timerit/master.svg?label=Travis%20CI\n :target: https://travis-ci.org/Erotemic/timerit?branch=master\n.. |Codecov| image:: https://codecov.io/github/Erotemic/timerit/badge.svg?branch=master&service=github\n :target: https://codecov.io/github/Erotemic/timerit?branch=master\n.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/github/Erotemic/timerit?branch=master&svg=True\n :target: https://ci.appveyor.com/project/Erotemic/timerit/branch/master\n.. |Pypi| image:: https://img.shields.io/pypi/v/timerit.svg\n :target: https://pypi.python.org/pypi/timerit\n.. |Downloads| image:: https://img.shields.io/pypi/dm/timerit.svg\n :target: https://pypistats.org/packages/timerit\n.. |CircleCI| image:: https://circleci.com/gh/Erotemic/timerit.svg?style=svg\n :target: https://circleci.com/gh/Erotemic/timerit\n.. |ReadTheDocs| image:: https://readthedocs.org/projects/timerit/badge/?version=latest\n :target: http://timerit.readthedocs.io/en/latest/\n.. |CodeQuality| image:: https://api.codacy.com/project/badge/Grade/fdcedca723f24ec4be9c7067d91cb43b\n :target: https://www.codacy.com/manual/Erotemic/timerit?utm_source=github.com&utm_medium=referral&utm_content=Erotemic/timerit&utm_campaign=Badge_Grade\n.. |GithubActions| image:: https://github.com/Erotemic/timerit/actions/workflows/tests.yml/badge.svg?branch=main\n :target: https://github.com/Erotemic/timerit/actions?query=branch%3Amain\n\n.. _PYTHONSTARTUP: https://docs.python.org/3/using/cmdline.html?highlight=pythonstartup#envvar-PYTHONSTARTUP\n\n\n\n","description_content_type":"text/x-rst","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/Erotemic/timerit","keywords":"","license":"Apache 2","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"timerit","package_url":"https://pypi.org/project/timerit/","platform":null,"project_url":"https://pypi.org/project/timerit/","project_urls":{"Homepage":"https://github.com/Erotemic/timerit"},"provides_extra":null,"release_url":"https://pypi.org/project/timerit/1.1.0/","requires_dist":["xdoctest (>=1.1.0) ; extra == 'all'","xdoctest (==1.1.0) ; extra == 'all-strict'","pytest-cov (==2.8.1) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'all-strict'","pytest (<=4.6.11,==4.6.0) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'all-strict'","pytest (==4.6.0) ; (python_version < \"3.10.0\" and python_version >= \"3.7.0\") and extra == 'all-strict'","pytest-cov (==2.8.1) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'all-strict'","pytest (<=4.6.11,==4.6.0) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'all-strict'","pytest-cov (==2.9.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'all-strict'","pytest (<=6.1.2,==4.6.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'all-strict'","pytest (==4.6.0) ; (python_version < \"3.7.0\" and python_version >= \"3.6.0\") and extra == 'all-strict'","pytest (==6.2.5) ; (python_version >= \"3.10.0\") and extra == 'all-strict'","pytest-cov (==3.0.0) ; (python_version >= \"3.6.0\") and extra == 'all-strict'","pytest-cov (>=2.8.1) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'all'","pytest (<=4.6.11,>=4.6.0) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'all'","pytest (>=4.6.0) ; (python_version < \"3.10.0\" and python_version >= \"3.7.0\") and extra == 'all'","pytest-cov (>=2.8.1) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'all'","pytest (<=4.6.11,>=4.6.0) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'all'","pytest-cov (>=2.9.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'all'","pytest (<=6.1.2,>=4.6.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'all'","pytest (>=4.6.0) ; (python_version < \"3.7.0\" and python_version >= \"3.6.0\") and extra == 'all'","pytest (>=6.2.5) ; (python_version >= \"3.10.0\") and extra == 'all'","pytest-cov (>=3.0.0) ; (python_version >= \"3.6.0\") and extra == 'all'","xdoctest (>=1.1.0) ; extra == 'tests'","xdoctest (==1.1.0) ; extra == 'tests-strict'","pytest-cov (==2.8.1) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'tests-strict'","pytest (<=4.6.11,==4.6.0) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'tests-strict'","pytest (==4.6.0) ; (python_version < \"3.10.0\" and python_version >= \"3.7.0\") and extra == 'tests-strict'","pytest-cov (==2.8.1) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'tests-strict'","pytest (<=4.6.11,==4.6.0) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'tests-strict'","pytest-cov (==2.9.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'tests-strict'","pytest (<=6.1.2,==4.6.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'tests-strict'","pytest (==4.6.0) ; (python_version < \"3.7.0\" and python_version >= \"3.6.0\") and extra == 'tests-strict'","pytest (==6.2.5) ; (python_version >= \"3.10.0\") and extra == 'tests-strict'","pytest-cov (==3.0.0) ; (python_version >= \"3.6.0\") and extra == 'tests-strict'","pytest-cov (>=2.8.1) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'tests'","pytest (<=4.6.11,>=4.6.0) ; (python_version < \"2.8.0\" and python_version >= \"2.7.0\") and extra == 'tests'","pytest (>=4.6.0) ; (python_version < \"3.10.0\" and python_version >= \"3.7.0\") and extra == 'tests'","pytest-cov (>=2.8.1) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'tests'","pytest (<=4.6.11,>=4.6.0) ; (python_version < \"3.5.0\" and python_version >= \"3.4.0\") and extra == 'tests'","pytest-cov (>=2.9.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'tests'","pytest (<=6.1.2,>=4.6.0) ; (python_version < \"3.6.0\" and python_version >= \"3.5.0\") and extra == 'tests'","pytest (>=4.6.0) ; (python_version < \"3.7.0\" and python_version >= \"3.6.0\") and extra == 'tests'","pytest (>=6.2.5) ; (python_version >= \"3.10.0\") and extra == 'tests'","pytest-cov (>=3.0.0) ; (python_version >= \"3.6.0\") and extra == 'tests'"],"requires_python":">=3.6","summary":"A powerful multiline alternative to timeit","version":"1.1.0","yanked":false,"yanked_reason":null}

Dependencies of timerit (3).
Dependency	Optional
pytest	true
pytest-cov	true
xdoctest	true

Package search

timerit

Release table

project_urls

Dependencies

All package metadata

Releases