----------------------------
A timer as a context manager
----------------------------
``contexttimer`` provides you with a couple of utilities to quickly measure the execution time of a code block or a function.
Timer as a context manager
--------------------------
``contexttimer.Timer`` is a context manager measuring the execution time of the code block it contains.
The elapsed time is accessible through the ``elapsed`` property.
>>> with Timer() as t:
... # some code here
>>> print t.elapsed
# a value in seconds
The ``contexttimer.Timer`` context manager
------------------------------------------
``contexttimer.Timer`` is a `context manager <http://docs.python.org/reference/datamodel.html#context-managers>`_ with 2 parameters and a public property:
* ``default_timer``: a platform specific timer function (``time.time`` for Unix platforms and ``time.clock`` for Windows platforms). You can instanciate a ``Timer`` object with your own timer, by passing it to the constructor.
* ``factor``: a multiplying factor applied to the ``elapsed`` property. For example, a factor or 1000 will lead to ``elapsed`` being expressed in milliseconds instead of seconds. Default value of 1.
* ``elapsed``: (read only property) the wall clock timing of the execution of the code block, in seconds. By default, expressed in seconds.
Example
"""""""
>>> from contexttimer import Timer
>>> with Timer(factor=1000) as t:
... for i in xrange(10000000):
... pass
...
>>> print(t.elapsed)
73.6618041992 # in miliseconds
Note that ``elapsed`` is calculated on demand, so it is possible to time sub-parts of your code block:
>>> with Timer(factor=1000) as t:
... # do some things
... print t.elapsed
... # do other tings
... print t.elapsed
...
10.122 # in ms
20.567
The ``contexttimer.timer`` function decorator
---------------------------------------------
You can use the ``@timer`` function decorator to measure the time execution of an entire function.
When the function returns its value, its execution time will be printed to the stdout (default), or to the argument logger.
Examples
""""""""
>>> @timer
... def sleep_for_2s():
... time.sleep(2)
>>> sleep_for_2s()
function sleep_for_2s execution time: 2.002
>>> logging.basicConfig()
>>> @timer(logger=logging.getLogger())
... def sleep_for_2s():
... time.sleep(2)
>>> sleep_for_2s()
DEBUG:root:function blah execution time: 2.002
As it makes use of the ``Timer`` context manager inside, all arguments passed to the ``@timer`` decorator will be used a ``Timer`` init arguments.
Example:
""""""""
>>> @timer(factor=1000)
... def sleepawhile(n):
... time.sleep(n)
...
>>> sleepawhile(2)
function sleepawhile execution time: 2000.089
The ``contexttimer.timeout.timeout`` decorator
----------------------------------------------
You can use the ``@timeout`` function decorator to stop a function/method call and call a handler if the call exceeds a fixed amount of time.
Example:
""""""""
>>> def timeout_handler(limit, f, *args, **kwargs):
... print "{func} call timed out after {lim}s.".format(
... func=f.__name__, lim=limit)
...
>>> @timeout(limit=5, handler=timeout_handler)
... def work(foo, bar, baz="spam")
... time.sleep(10)
>>> work("foo", "bar", "baz")
# time passes...
work call timed out after 5s.
>>>
Thanks
------
Thanks to halloi, wolanko and Jon Blackburn for their helpful insights and contributions.
License
-------
``contexttimer`` is released under the GPLv3 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/brouberol/contexttimer",
"name": "contexttimer",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "time,timer",
"author": "Balthazar Rouberol",
"author_email": "brouberol@imap.cc",
"download_url": "https://files.pythonhosted.org/packages/1d/e0/504aa08a83dc2ff90f61a83b5f70d689e1f5138ab30576124ea2ff9f5076/contexttimer-0.3.3.tar.gz",
"platform": "UNKNOWN",
"description": "----------------------------\nA timer as a context manager\n----------------------------\n\n``contexttimer`` provides you with a couple of utilities to quickly measure the execution time of a code block or a function.\n\nTimer as a context manager\n--------------------------\n``contexttimer.Timer`` is a context manager measuring the execution time of the code block it contains.\nThe elapsed time is accessible through the ``elapsed`` property.\n\n>>> with Timer() as t:\n... # some code here\n>>> print t.elapsed\n# a value in seconds\n\n\nThe ``contexttimer.Timer`` context manager\n------------------------------------------\n``contexttimer.Timer`` is a `context manager <http://docs.python.org/reference/datamodel.html#context-managers>`_ with 2 parameters and a public property:\n\n* ``default_timer``: a platform specific timer function (``time.time`` for Unix platforms and ``time.clock`` for Windows platforms). You can instanciate a ``Timer`` object with your own timer, by passing it to the constructor.\n* ``factor``: a multiplying factor applied to the ``elapsed`` property. For example, a factor or 1000 will lead to ``elapsed`` being expressed in milliseconds instead of seconds. Default value of 1.\n* ``elapsed``: (read only property) the wall clock timing of the execution of the code block, in seconds. By default, expressed in seconds.\n\nExample\n\"\"\"\"\"\"\"\n\n>>> from contexttimer import Timer\n>>> with Timer(factor=1000) as t:\n... for i in xrange(10000000):\n... pass\n...\n>>> print(t.elapsed)\n73.6618041992 # in miliseconds\n\nNote that ``elapsed`` is calculated on demand, so it is possible to time sub-parts of your code block:\n\n>>> with Timer(factor=1000) as t:\n... # do some things\n... print t.elapsed\n... # do other tings\n... print t.elapsed\n...\n10.122 # in ms\n20.567\n\n\nThe ``contexttimer.timer`` function decorator\n---------------------------------------------\n\nYou can use the ``@timer`` function decorator to measure the time execution of an entire function.\nWhen the function returns its value, its execution time will be printed to the stdout (default), or to the argument logger.\n\n\nExamples\n\"\"\"\"\"\"\"\"\n>>> @timer\n... def sleep_for_2s():\n... time.sleep(2)\n\n>>> sleep_for_2s()\nfunction sleep_for_2s execution time: 2.002\n\n>>> logging.basicConfig()\n>>> @timer(logger=logging.getLogger())\n... def sleep_for_2s():\n... time.sleep(2)\n\n>>> sleep_for_2s()\nDEBUG:root:function blah execution time: 2.002\n\nAs it makes use of the ``Timer`` context manager inside, all arguments passed to the ``@timer`` decorator will be used a ``Timer`` init arguments.\n\nExample:\n\"\"\"\"\"\"\"\"\n\n>>> @timer(factor=1000)\n... def sleepawhile(n):\n... time.sleep(n)\n...\n>>> sleepawhile(2)\nfunction sleepawhile execution time: 2000.089\n\nThe ``contexttimer.timeout.timeout`` decorator\n----------------------------------------------\n\nYou can use the ``@timeout`` function decorator to stop a function/method call and call a handler if the call exceeds a fixed amount of time.\n\n\nExample:\n\"\"\"\"\"\"\"\"\n\n>>> def timeout_handler(limit, f, *args, **kwargs):\n... print \"{func} call timed out after {lim}s.\".format(\n... func=f.__name__, lim=limit)\n...\n>>> @timeout(limit=5, handler=timeout_handler)\n... def work(foo, bar, baz=\"spam\")\n... time.sleep(10)\n>>> work(\"foo\", \"bar\", \"baz\")\n# time passes...\nwork call timed out after 5s.\n>>>\n\n\nThanks\n------\nThanks to halloi, wolanko and Jon Blackburn for their helpful insights and contributions.\n\nLicense\n-------\n``contexttimer`` is released under the GPLv3 license.",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A timer context manager measuring the clock wall time of the code block it contains.",
"version": "0.3.3",
"split_keywords": [
"time",
"timer"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "dfeb413be43d88e287687036cdb3a71e",
"sha256": "35a1efd389af3f1ca509f33ff23e17d98b66c8fde5ba2a4eb8a8b7fa456598a5"
},
"downloads": -1,
"filename": "contexttimer-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "dfeb413be43d88e287687036cdb3a71e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4875,
"upload_time": "2016-09-02T09:58:32",
"upload_time_iso_8601": "2016-09-02T09:58:32.610353Z",
"url": "https://files.pythonhosted.org/packages/1d/e0/504aa08a83dc2ff90f61a83b5f70d689e1f5138ab30576124ea2ff9f5076/contexttimer-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-09-02 09:58:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "brouberol",
"github_project": "contexttimer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "contexttimer"
}
JSON
