pytest-dev / pytest-dev/pytest-timeout

Make timeout duration unit self-documenting

Open
#80 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
258
Forks
69
PR merge metrics
No merged PRs in 30d

Description

In a statement like @mark.timeout(50) there is nothing to say the duration is defined in seconds. This has a few disadvantages:

  • Many other timing mechanisms use milliseconds or minutes as their units, so we can't simply assume that it's seconds. A new or returning user has to read the documentation (or code) to ascertain this, wasting time and producing cognitive overhead.
  • Extreme timeouts like 1200 or 0.00005 have more cognitive overhead, since converting to the "natural" unit of minutes/microseconds etc isn't always trivial.

It would be nice if it instead were self-documenting. Some alternatives:

  • @mark.timeout(seconds=50) would make it pretty obvious, and would make it easy to support several units.
  • @mark.timeout(timedelta(minutes=5)) would make it more explicit, while supporting the widest possible range of units at no extra cost.
  • @mark.timeout(seconds=timedelta(minutes=5).total_seconds()) is a clunky workaround.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the current @mark.timeout API and the documentation that defines its duration units. Compare the proposed keyword-argument and timedelta interfaces, including compatibility and supported units. Done means selecting and specifying a self-documenting API, with its behavior and migration implications clearly documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.