First version of codetiming.Timer

Author: gahjelle

.bumpversion.cfg

@@ -0,0 +1,7 @@
+[bumpversion]
+current_version = 0.1.0
+commit = True
+tag = True
+
+[bumpversion:file:codetiming/__init__.py]
+

README.md

@@ -1 +1,77 @@
-# codetiming
+# `codetiming` - A flexible, customizable timer for your Python code
+
+Install `codetiming` from PyPI:
+
+```
+$ python -m pip install codetiming
+```
+
+The source code is [available at GitHub](https://github.com/realpython/codetiming).
+
+## Basic Usage
+
+You can use `codetiming.Timer` in several different ways:
+
+1. As a **class**:
+
+    ```python
+    t = Timer(name="class")
+    t.start()
+    # Do something
+    t.stop()
+    ```
+
+2. As a **context manager**:
+
+    ```python
+    with Timer(name="context manager"):
+        # Do something
+    ```
+
+3. As a **decorator**:
+
+    ```python
+    @Timer(name="decorator")
+    def stuff():
+        # Do something
+    ```
+
+## Arguments
+
+`Timer` accepts the following arguments when it's created, all are optional:
+
+- **`name`:** An optional name for your timer
+- **`text`:** The text shown when your timer ends. It should contain a `{}` placeholder that will be filled by the elapsed time in seconds (default: `"Elapsed time: {:.4f} seconds"`)
+- **`logger`:** A function/callable that takes a string argument, and will report the elapsed time when the logger is stopped (default: `print()`)
+
+You can turn off explicit reporting of the elapsed time by setting `logger=None`.
+
+When using `Timer` as a class, you can capture the elapsed time when calling `.stop()`:
+
+```python
+elapsed_time = t.stop()
+```
+
+Named timers are made available in the class dictionary `Timer.timers`. The elapsed time will accumulate if the same name or same timer is used several times. Consider the following example:
+
+```python
+>>> import logging
+>>> from codetiming import Timer
+
+>>> t = Timer("example", text="Time spent: {:.2f}", logger=logging.warning)
+
+>>> t.start()
+>>> t.stop()
+WARNING:root:Time spent: 3.58
+3.5836678670002584
+
+>>> with t:
+...     _ = list(range(100000000))
+... 
+WARNING:root:Time spent: 1.73
+
+>>> Timer.timers
+{'example': 5.312697440000193}
+```
+
+The example shows how you can redirect the timer output to the logging module. Note that the elapsed time spent in the two different uses of `t` has been accumulated in `Timer.timers`.

codetiming/__init__.py

@@ -0,0 +1,88 @@
+"""A flexible, customizable timer for your Python code
+
+You can use `codetiming.Timer` in several different ways:
+
+1. As a **class**:
+
+    ```python
+    t = Timer(name="class")
+    t.start()
+    # Do something
+    t.stop()
+    ```
+
+2. As a **context manager**:
+
+    ```python
+    with Timer(name="context manager"):
+        # Do something
+    ```
+
+3. As a **decorator**:
+
+    ```python
+    @Timer(name="decorator")
+    def stuff():
+        # Do something
+    ```
+"""
+
+from contextlib import ContextDecorator
+from dataclasses import dataclass, field
+import time
+from typing import Any, Callable, ClassVar, Dict, Optional
+
+__version__ = "0.1.0"
+
+
+class TimerError(Exception):
+    """A custom exception used to report errors in use of Timer class"""
+
+
+@dataclass
+class Timer(ContextDecorator):
+    """Time your code using a class, context manager, or decorator"""
+
+    timers: ClassVar[Dict[str, float]] = dict()
+    name: Optional[str] = None
+    text: str = "Elapsed time: {:0.4f} seconds"
+    logger: Optional[Callable[[str], None]] = print
+    _start_time: Optional[float] = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        """Initialization: add timer to dict of timers"""
+        if self.name:
+            self.timers.setdefault(self.name, 0)
+
+    def start(self) -> None:
+        """Start a new timer"""
+        if self._start_time is not None:
+            raise TimerError(f"Timer is running. Use .stop() to stop it")
+
+        self._start_time = time.perf_counter()
+
+    def stop(self) -> float:
+        """Stop the timer, and report the elapsed time"""
+        if self._start_time is None:
+            raise TimerError(f"Timer is not running. Use .start() to start it")
+
+        # Calculate elapsed time
+        elapsed_time = time.perf_counter() - self._start_time
+        self._start_time = None
+
+        # Report elapsed time
+        if self.logger:
+            self.logger(self.text.format(elapsed_time))
+        if self.name:
+            self.timers[self.name] += elapsed_time
+
+        return elapsed_time
+
+    def __enter__(self) -> "Timer":
+        """Start a new timer as a context manager"""
+        self.start()
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        """Stop the context manager timer"""
+        self.stop()

pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["flit"]
+build-backend = "flit.buildapi"
+
+[tool.flit.metadata]
+module = "codetiming"
+author = "Real Python"
+author-email = "[email protected]"
+home-page = "https://realpython.com/"
+description-file = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Topic :: Education",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+keywords = "timer class contextmanager decorator"
+
+# Requirements
+requires-python    = ">=3.6"
+requires           = []
+
+
+[tool.flit.metadata.requires-extra]
+dev                = ["black", "bumpversion", "flake8", "flit", "mypy"]
+test               = ["pytest", "pytest-cov", "tox"]
+

tests/test_codetiming.py

@@ -0,0 +1,166 @@
+"""Tests for codetiming.Timer
+
+Based on the Pytest test runner
+"""
+# Standard library imports
+import re
+
+# Third party imports
+import pytest
+
+# Codetiming imports
+from codetiming import Timer, TimerError
+
+
+#
+# Test functions
+#
+TIME_PREFIX = "Wasted time:"
+TIME_MESSAGE = f"{TIME_PREFIX} {{:.4f}} seconds"
+RE_TIME_MESSAGE = re.compile(TIME_PREFIX + r" 0\.\d{4} seconds")
+
+
+@Timer(text=TIME_MESSAGE)
+def timewaster(num):
+    """Just waste a little bit of time"""
+    sum(n ** 2 for n in range(num))
+
+
+@Timer(name="accumulator", text=TIME_MESSAGE)
+def accumulated_timewaste(num):
+    """Just waste a little bit of time"""
+    sum(n ** 2 for n in range(num))
+
+
+class CustomLogger:
+    """Simple class used to test custom logging capabilities in Timer"""
+
+    def __init__(self):
+        self.messages = ""
+
+    def __call__(self, message):
+        self.messages += message
+
+
+#
+# Tests
+#
+def test_timer_as_decorator(capsys):
+    """Test that decorated function prints timing information"""
+    timewaster(1000)
+    stdout, stderr = capsys.readouterr()
+    assert RE_TIME_MESSAGE.match(stdout)
+    assert stdout.count("\n") == 1
+    assert stderr == ""
+
+
+def test_timer_as_context_manager(capsys):
+    """Test that timed context prints timing information"""
+    with Timer(text=TIME_MESSAGE):
+        sum(n ** 2 for n in range(1000))
+    stdout, stderr = capsys.readouterr()
+    assert RE_TIME_MESSAGE.match(stdout)
+    assert stdout.count("\n") == 1
+    assert stderr == ""
+
+
+def test_explicit_timer(capsys):
+    """Test that timed section prints timing information"""
+    t = Timer(text=TIME_MESSAGE)
+    t.start()
+    sum(n ** 2 for n in range(1000))
+    t.stop()
+    stdout, stderr = capsys.readouterr()
+    assert RE_TIME_MESSAGE.match(stdout)
+    assert stdout.count("\n") == 1
+    assert stderr == ""
+
+
+def test_error_if_timer_not_running():
+    """Test that timer raises error if it is stopped before started"""
+    t = Timer(text=TIME_MESSAGE)
+    with pytest.raises(TimerError):
+        t.stop()
+
+
+def test_access_timer_object_in_context(capsys):
+    """Test that we can access the timer object inside a context"""
+    with Timer(text=TIME_MESSAGE) as t:
+        assert isinstance(t, Timer)
+        assert t.text.startswith(TIME_PREFIX)
+    _, _ = capsys.readouterr()  # Do not print log message to standard out
+
+
+def test_custom_logger():
+    """Test that we can use a custom logger"""
+    logger = CustomLogger()
+    with Timer(text=TIME_MESSAGE, logger=logger):
+        sum(n ** 2 for n in range(1000))
+    assert RE_TIME_MESSAGE.match(logger.messages)
+
+
+def test_timer_without_text(capsys):
+    """Test that timer with logger=None does not print anything"""
+    with Timer(logger=None):
+        sum(n ** 2 for n in range(1000))
+
+    stdout, stderr = capsys.readouterr()
+    assert stdout == ""
+    assert stderr == ""
+
+
+def test_accumulated_decorator(capsys):
+    """Test that decorated timer can accumulate"""
+    accumulated_timewaste(1000)
+    accumulated_timewaste(1000)
+
+    stdout, stderr = capsys.readouterr()
+    lines = stdout.strip().split("\n")
+    assert len(lines) == 2
+    assert RE_TIME_MESSAGE.match(lines[0])
+    assert RE_TIME_MESSAGE.match(lines[1])
+    assert stderr == ""
+
+
+def test_accumulated_context_manager(capsys):
+    """Test that context manager timer can accumulate"""
+    t = Timer(name="accumulator", text=TIME_MESSAGE)
+    with t:
+        sum(n ** 2 for n in range(1000))
+    with t:
+        sum(n ** 2 for n in range(1000))
+
+    stdout, stderr = capsys.readouterr()
+    lines = stdout.strip().split("\n")
+    assert len(lines) == 2
+    assert RE_TIME_MESSAGE.match(lines[0])
+    assert RE_TIME_MESSAGE.match(lines[1])
+    assert stderr == ""
+
+
+def test_accumulated_explicit_timer(capsys):
+    """Test that explicit timer can accumulate"""
+    t = Timer(name="accumulated_explicit_timer", text=TIME_MESSAGE)
+    total = 0
+    t.start()
+    sum(n ** 2 for n in range(1000))
+    total += t.stop()
+    t.start()
+    sum(n ** 2 for n in range(1000))
+    total += t.stop()
+
+    stdout, stderr = capsys.readouterr()
+    lines = stdout.strip().split("\n")
+    assert len(lines) == 2
+    assert RE_TIME_MESSAGE.match(lines[0])
+    assert RE_TIME_MESSAGE.match(lines[1])
+    assert stderr == ""
+    assert total == Timer.timers["accumulated_explicit_timer"]
+
+
+def test_error_if_restarting_running_timer():
+    """Test that restarting a running timer raises an error"""
+    t = Timer(text=TIME_MESSAGE)
+    t.start()
+    with pytest.raises(TimerError):
+        t.start()