looptime 0.1__tar.gz → 0.3__tar.gz

{looptime-0.1 → looptime-0.3}/.github/workflows/ci.yaml

@@ -9,13 +9,13 @@ on:
 jobs:
   linters:
     name: Linting and static analysis
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.13"
       - run: pip install -r requirements.txt
       - run: pre-commit run --all-files
       - run: mypy looptime --strict
@@ -24,18 +24,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.7", "3.8", "3.9", "3.10" ]
-    name: Python ${{ matrix.python-version }}
-    runs-on: ubuntu-20.04
+        python-version: [ "3.9", "3.10", "3.11", "3.12" ]
+        include:
+          - python-version: "3.13"
+          - python-version: "3.13"
+            install-extras: "pytest-asyncio<1.0.0"
+    name: Python ${{ matrix.python-version }}${{ matrix.install-extras && ', ' || '' }}${{ matrix.install-extras }}
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
       - run: pip install -r requirements.txt
       - run: pip install -e .
+      - run: pip install "${{ matrix.install-extras }}"
+        if: ${{ matrix.install-extras }}
       - run: pytest --color=yes --cov=looptime --cov-branch
 
       - name: Publish coverage to Coveralls.io
@@ -45,7 +51,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.github_token }}
         continue-on-error: true
       - name: Publish coverage to CodeCov.io
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v3
         if: success()
         env:
           PYTHON: ${{ matrix.python-version }}
@@ -59,13 +65,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "pypy-3.7", "pypy-3.8" ]
+        python-version: [ "pypy-3.9", "pypy-3.10", "pypy-3.11" ]
     name: Python ${{ matrix.python-version }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -76,9 +82,9 @@ jobs:
   coveralls-finish:
     name: Finalize coveralls.io
     needs: [unit-tests]
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5
       - run: pip install coveralls
       - run: coveralls --service=github --finish
         env:

{looptime-0.1 → looptime-0.3}/.github/workflows/publish.yaml

@@ -11,10 +11,10 @@ on:
 jobs:
   publish:
     name: Build and publish
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: "3.10"
       - run: pip install --upgrade setuptools wheel twine

{looptime-0.1 → looptime-0.3}/.github/workflows/thorough.yaml

@@ -11,13 +11,13 @@ on:
 jobs:
   linters:
     name: Linting and static analysis
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.13"
       - run: pip install -r requirements.txt
       - run: pre-commit run --all-files
       - run: mypy looptime --strict
@@ -26,13 +26,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.7", "3.8", "3.9", "3.10" ]
+        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13" ]
     name: Python ${{ matrix.python-version }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -47,7 +47,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.github_token }}
         continue-on-error: true
       - name: Publish coverage to CodeCov.io
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v3
         if: success()
         env:
           PYTHON: ${{ matrix.python-version }}
@@ -61,13 +61,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "pypy-3.7", "pypy-3.8" ]
+        python-version: [ "pypy-3.9", "pypy-3.10", "pypy-3.11" ]
     name: Python ${{ matrix.python-version }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -78,9 +78,9 @@ jobs:
   coveralls-finish:
     name: Finalize coveralls.io
     needs: [unit-tests]
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/setup-python@v2
+      - uses: actions/setup-python@v5
       - run: pip install coveralls
       - run: coveralls --service=github --finish
         env:

{looptime-0.1 → looptime-0.3}/.pre-commit-config.yaml

@@ -7,7 +7,7 @@ exclude: |
   )
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
       - id: trailing-whitespace
@@ -46,7 +46,7 @@ repos:
       # - id: double-quote-string-fixer
 
   - repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.8.0
+    rev: v1.10.0
     hooks:
       - id: python-check-blanket-noqa
       - id: python-check-mock-methods
@@ -59,7 +59,7 @@ repos:
       - id: text-unicode-replacement-char
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.8.0
+    rev: 6.0.1
     hooks:
       - id: isort
         name: isort-source-code

{looptime-0.1/looptime.egg-info → looptime-0.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: looptime
-Version: 0.1
+Version: 0.3
 Summary: Fast-forward asyncio event loop time (in tests)
 Home-page: https://github.com/nolar/looptime
 Author: Sergey Vasilyev
@@ -11,18 +11,28 @@ License: MIT
 Project-URL: Bug Tracker, https://github.com/nolar/looptime/issues
 Project-URL: Source Code, https://github.com/nolar/looptime
 Keywords: asyncio,event loop,time,python,pytest
-Platform: UNKNOWN
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
 
 # Fast-forward asyncio event loop time (in tests)
 
 [![CI](https://github.com/nolar/looptime/workflows/Thorough%20tests/badge.svg)](https://github.com/nolar/looptime/actions/workflows/thorough.yaml)
 [![codecov](https://codecov.io/gh/nolar/looptime/branch/main/graph/badge.svg)](https://codecov.io/gh/nolar/looptime)
 [![Coverage Status](https://coveralls.io/repos/github/nolar/looptime/badge.svg?branch=main)](https://coveralls.io/github/nolar/looptime?branch=main)
-[![Total alerts](https://img.shields.io/lgtm/alerts/g/nolar/looptime.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/nolar/looptime/alerts/)
-[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/nolar/looptime.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/nolar/looptime/context:python)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 
 ## What?
@@ -37,11 +47,11 @@ The effects of time removal can be seen from both sides:
   This hides the code overhead and network latencies from the time measurements,
   making the loop time sharply and predictably advancing in configured steps.
 
-* From the **observer's (i.e. your) point of view,**
+* From the **observer's (i.e. your personal) point of view,**
   all activities of the event loop, such as sleeps, events/conditions waits,
   timeouts, "later" callbacks, happen in near-zero amount of the real time
-  (above the usual code overhead).
-  This speeds up the tests execution without breaking the tests' time-based
+  (due to the usual code execution overhead).
+  This speeds up the execution of tests without breaking the tests' time-based
   design, even if they are designed to run in seconds or minutes.
 
 For the latter case, there are a few exceptions when the event loop's activities
@@ -77,28 +87,28 @@ at the same time:
 * One is for the coroutine-under-test which moves between states
   in the background.
 * Another one is for the test itself, which controls the flow
-  of that coroutine-under-test: it sets events, injects data, etc.
+  of that coroutine-under-test: it schedules events, injects data, etc.
 
 In textbook cases with simple coroutines that are more like regular functions,
 it is possible to design a test so that it runs straight to the end in one hop
 — with all the preconditions set and data prepared in advance in the test setup.
 
 However, in the real-world cases, the tests often must verify that
-the corotuine stops at some point, waits for a condition for some limited time,
+the coroutine stops at some point, waits for a condition for some limited time,
 and then passes or fails.
 
 The problem is often "solved" by mocking the low-level coroutines of sleep/wait
 that we expect the coroutine-under-test to call. But this violates the main
-principle of good unit-tests: test the promise, not the implementation.
+principle of good unit-tests: **test the promise, not the implementation.**
 Mocking and checking the low-level coroutines is based on the assumptions
 of how the coroutine is implemented internally, which can change over time.
 Good tests do not change on refactoring if the protocol remains the same.
 
 Another (straightforward) approach is to not mock the low-level routines, but
-to spend the real-world time, just in short bursts as hard-cded in the test.
-Not only it makes the whole test-suite slower, it also brings the exection
-time close to the values where the code overhead affects the timing
-and makes it difficult to assert on the coroutine's pure time.
+to spend the real-world time, just in short bursts as hard-coded in the test.
+Not only it makes the whole test-suite slower, it also brings the execution
+time close to the values where the code overhead or measurement errors affect
+the timing, which makes it difficult to assert on the coroutine's pure time.
 
 
 ## Solution
@@ -125,7 +135,7 @@ pip install pytest-asyncio
 pip install looptime
 ```
 
-Nothing is needed to make async tests to run with the fake time, it just works:
+Nothing is needed to make async tests run with the fake time, it just works:
 
 ```python
 import asyncio
@@ -221,14 +231,14 @@ for each setting separately (i.e. not the closest marker as a whole).
 marked as using the fake loop time —including those not marked at all—
 as if all tests were implicitly marked.
 
-`--no-looptime` runs all tests —both marked and unmarked— with real time.
+`--no-looptime` runs all tests —both marked and unmarked— with the real time.
 This flag effectively disables the plugin.
 
 
 ## Settings
 
 The marker accepts several settings for the test. The closest to the test
-function applies. This lets you to define the test-suite defaults
+function applies. This lets you define the test-suite defaults
 and override them on the directory, module, class, function, or test level:
 
 ```python
@@ -256,7 +266,20 @@ or `start=lambda: random.random() * 100` to add some unpredictability.
 
 `None` is treated the same as `0.0`.
 
-The default is `0.0`.
+The default is `0.0`. For reusable event loops, the default is to keep
+the time untouched, which means `0.0` or the explicit value for the first test,
+but then an ever-increasing value for the 2nd, 3rd, and further tests.
+
+Note: pytest-asyncio 1.0.0+ introduced event loops with higher scopes,
+e.g. class-, module-, packages-, session-scoped event loops used in tests.
+Such event loops are reused, so their time continues growing through many tests.
+However, if the test is explicitly configured with the start time,
+that time is enforced to the event loop when the test function starts —
+to satisfy the clearly declared intentions — even if the time moves backwards,
+which goes against the nature of the time itself (monotonically growing).
+This might lead to surprises in time measurements outside of the test,
+e.g. in fixtures: the code durations can become negative, or the events can
+happen (falsely) before they are scheduled (loop-clock-wise). Be careful.
 
 
 ### The end of time
@@ -273,6 +296,8 @@ e.g. with `asyncio.sleep(0)`, simple `await` statements, etc.
 
 If set to `None`, there is no end of time, and the event loop runs
 as long as needed. Note: `0` means ending the time immediately on start.
+Be careful with the explicit ending time in higher-scoped event loops
+of pytest-asyncio>=1.0.0, since they time increases through many tests.
 
 If it is a callable, it is called once per event loop to get the value:
 e.g. `end=lambda: time.monotonic() + 10`.
@@ -304,7 +329,7 @@ Normally, it should not fail. However, with fake time (without workarounds)
 the following scenario is possible:
 
 * `async_timeout` library sets its delayed timer at 9 seconds since now.
-* the event loop notices that there is and and only one timer at T0+9s.
+* the event loop notices that there is only one timer at T0+9s.
 * the event loop fast-forwards time to be `9`.
 * since there are no other handles/timers, that timer is executed.
 * `async_timeout` fails the test with `asyncio.TimeoutError`
@@ -359,11 +384,11 @@ However, with the fake time (with no workarounds), the following happens:
 * The test suppresses the timeout, checks the assertion, and fails:
   the sync event is still unset.
 * A fraction of a second (e.g. `0.001` second) later, the thread starts,
-  calls the function, and sets the sync event, but it is too late.
+  calls the function and sets the sync event, but it is too late.
 
 Compared to the fake fast-forwarding time, even such fast things as threads
 are too slow to start. Unfortunately, `looptime` and the event loop can
-neither control what is happening outside of the event loop, nor predict
+neither control what is happening outside of the event loop nor predict
 how long it will take.
 
 To work around this, `looptime` remembers all calls to executors and then
@@ -375,11 +400,11 @@ So, the fake time and real time move along while waiting for executors.
 Luckily for this case, in 1 or 2 such steps, the executor's thread will
 do its job, the event will be set, so as the synchronous & asynchronous
 futures of the executor. The latter one (the async future) will also
-let the `await` to move on.
+let the `await` move on.
 
 The `idle_step` (`float` or `None`) setting is the duration of a single
 time step when fast-forwarding the time if there are executors used —
-i.e. if there are some synchronous tasks running in the thread pools.
+i.e. if some synchronous tasks are running in the thread pools.
 
 Note that the steps are both true-time and fake-time: they spend the same
 amount of the observer's true time as they increment the loop's fake time.
@@ -413,7 +438,7 @@ With no workarounds, the test will hang forever waiting for the i/o to happen.
 This mostly happens when the only thing left in the event loop is the i/o,
 all internal scheduled callbacks are gone.
 
-`looptime` can artifically limit the lifetime of the event loop.
+`looptime` can artificially limit the lifetime of the event loop.
 This can be done as a default setting for the whole test suite, for example.
 
 The `idle_timeout` (`float` or `None`) setting is the true-time limit
@@ -459,7 +484,7 @@ while `looptime(end=N)` applies to the lifecycle of the whole event loop,
 which is usually the duration of the whole test and monotonically increases.
 
 Second, `looptime(end=N)` syncs the loop time with the real time for N seconds,
-i.e. it does not instantly fast-forwards the loop time when the loops
+i.e. it does not instantly fast-forward the loop time when the loops
 attempts to make an "infinite sleep" (technically, `selector.select(None)`).
 `async_timeout.timeout()` and `asyncio.wait_for()` set a delayed callback,
 so the time fast-forwards to it on the first possible occasion.
@@ -530,6 +555,63 @@ For example, with the resolution `0.001`, the time
 everything smaller than `0.001` becomes `0` and probably misbehaves._
 
 
+### Time magic coverage
+
+The time compaction magic is enabled only for the duration of the test,
+i.e. the test function — but not the fixtures.
+The fixtures run in the real (wall-clock) time.
+
+The options (including the force starting time) are applied at the test function
+starting moment, not when it is setting up the fixtures (even function-scoped).
+
+This is caused by a new concept of multiple co-existing event loops
+in pytest-asyncio>=1.0.0:
+
+- It is unclear which options to apply to higher-scoped fixtures
+  used by many tests, which themselves use higher-scoped event loops —
+  especially in selective partial runs. Technically, it is the 1st test,
+  with the options of 2nd and further tests simply ignored.
+- It is impossible to guess which event loop will be the running loop
+  in the test until we reach the test itself, i.e. we do not know this
+  when setting up the fixtures, even function-scoped fixtures.
+- There is no way to cover the fixture teardown (no hook in pytest),
+  only for the fixture setup and post-teardown cleanup.
+
+As such, this functionality (covering of function-scoped fixtures)
+was abandoned — since it was never promised, tested, or documented —
+plus an assumption that it was never used by anyone (it should not be).
+It was rather a side effect of the previous implemention,
+which is not available or possible anymore.
+
+
+### pytest-asyncio>=1.0.0
+
+As it is said above, pytest-asyncio>=1.0.0 introduced several co-existing
+event loops of different scopes. The time compaction in these event loops
+is NOT activated. Only the running loop of the test function is activated.
+
+Configuring and activating multiple co-existing event loops brings a few
+conceptual challenges, which require a good sample case to look into,
+and some time to think.
+
+Would you need time compaction in your fixtures of higher scopes,
+do it explicitly:
+
+```python
+import asyncio
+import pytest
+
+@pytest.fixture
+async def fixt():
+    loop = asyncio.get_running_loop()
+    loop.setup_looptime(start=123, end=456)
+    with loop.looptime_enabled():
+        await do_things()
+```
+
+There is #11 to add a feature to do this automatically, but it is not yet done.
+
+
 ## Extras
 
 ### Chronometers
@@ -578,7 +660,7 @@ async def test_me(chronometer, event_loop):
 
 ### Loop time assertions
 
-The `looptime` **fixture** is a syntax sugar for easy loop time assertions::
+The `looptime` **fixture** is syntax sugar for easy loop time assertions::
 
 ```python
 import asyncio
@@ -593,13 +675,13 @@ async def test_me(looptime):
 
 Technically, it is a proxy object to `asyncio.get_running_loop().time()`.
 The proxy object supports the direct comparison with numbers (integers/floats),
-so as some basic arithmetics (adding, substracting, multiplication, etc).
+so as some basic arithmetics (adding, subtracting, multiplication, etc).
 However, it adjusts to the time precision of 1 nanosecond (1e-9): every digit
 beyond that precision is ignored — so you can be not afraid of
 `123.456/1.2` suddenly becoming `102.88000000000001` and not equal to `102.88`
 (as long as the time proxy object is used and not converted to a native float).
 
-The proxy object can be used to create a new proxy which is bound to a specific
+The proxy object can be used to create a new proxy that is bound to a specific
 event loop (it works for loops both with fake- and real-world time)::
 
 ```python
@@ -623,6 +705,8 @@ the loop time also includes the time of all fixtures setups.
 Do you use a custom event loop? No problem! Create a test-specific descendant
 with the provided mixin — and it will work the same as the default event loop.
 
+For `pytest-asyncio<1.0.0`:
+
 ```python
 import looptime
 import pytest
@@ -638,6 +722,29 @@ def event_loop():
     return LooptimeCustomEventLoop()
 ```
 
+For `pytest-asyncio>=1.0.0`:
+
+```python
+import asyncio
+import looptime
+import pytest
+from wherever import CustomEventLoop
+
+
+class LooptimeCustomEventLoop(looptime.LoopTimeEventLoop, CustomEventLoop):
+    pass
+
+
+class LooptimeCustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+    def new_event_loop(self):
+        return LooptimeCustomEventLoop()
+
+
+@pytest.fixture(scope='session')
+def event_loop_policy():
+    return LooptimeCustomEventLoopPolicy()
+```
+
 Only selector-based event loops are supported: the event loop must rely on
 `self._selector.select(timeout)` to sleep for `timeout` true-time seconds.
 Everything that inherits from `asyncio.BaseEventLoop` should work.
@@ -645,6 +752,8 @@ Everything that inherits from `asyncio.BaseEventLoop` should work.
 You can also patch almost any event loop class or event loop object
 the same way as `looptime` does that (via some dirty hackery):
 
+For `pytest-asyncio<1.0.0`:
+
 ```python
 import asyncio
 import looptime
@@ -657,6 +766,25 @@ def event_loop():
     return looptime.patch_event_loop(loop)
 ```
 
+For `pytest-asyncio>=1.0.0`:
+
+```python
+import asyncio
+import looptime
+import pytest
+
+
+class LooptimeEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+    def new_event_loop(self):
+        loop = super().new_event_loop()
+        return looptime.patch_event_loop(loop)
+
+
+@pytest.fixture(scope='session')
+def event_loop_policy():
+    return LooptimeEventLoopPolicy()
+```
+
 `looptime.make_event_loop_class(cls)` constructs a new class that inherits
 from the referenced class and the specialised event loop class mentioned above.
 The resulting classes are cached, so it can be safely called multiple times.
@@ -668,5 +796,3 @@ constructed one. For those who care, it is an equivalent of the following hack
 ```python
 loop.__class__ = looptime.make_event_loop_class(loop.__class__)
 ```
-
-