looptime 0.2__py3-none-any.whl → 0.3__py3-none-any.whl

looptime/__init__.py

@@ -1,10 +1,11 @@
 from .chronometers import Chronometer
-from .loops import IdleTimeoutError, LoopTimeEventLoop, LoopTimeoutError
+from .loops import IdleTimeoutError, LoopTimeEventLoop, LoopTimeoutError, TimeWarning
 from .patchers import make_event_loop_class, new_event_loop, patch_event_loop, reset_caches
 from .timeproxies import LoopTimeProxy
 
 __all__ = [
     'Chronometer',
+    'TimeWarning',
     'LoopTimeProxy',
     'IdleTimeoutError',
     'LoopTimeoutError',

looptime/loops.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import selectors
 import time
+import warnings
 import weakref
-from typing import TYPE_CHECKING, Any, Callable, MutableSet, TypeVar, cast, overload
+from typing import TYPE_CHECKING, Any, Callable, Iterator, MutableSet, TypeVar, cast, overload
 
 _T = TypeVar('_T')
 
@@ -16,6 +18,11 @@ else:
     AnyTask = asyncio.Task
 
 
+class TimeWarning(UserWarning):
+    """Issued when the loop time moves backwards, violating its monotonicity."""
+    pass
+
+
 class LoopTimeoutError(asyncio.TimeoutError):
     """A special kind of timeout when the loop's time reaches its end."""
     pass
@@ -61,6 +68,7 @@ class LoopTimeEventLoop(asyncio.BaseEventLoop):
             idle_step: float | None = None,
             idle_timeout: float | None = None,
             noop_cycles: int = 42,
+            _enabled: bool | None = None,  # None means do nothing
     ) -> None:
         """
         Set all the fake-time fields and patch the i/o selector.
@@ -69,9 +77,33 @@ class LoopTimeEventLoop(asyncio.BaseEventLoop):
         when the mixin/class is injected into the existing event loop object.
         In that case, the object is already initialised except for these fields.
         """
+        new_time: float | None = start() if callable(start) else start
+        end_time: float | None = end() if callable(end) else end
+        old_time: float | None
+        try:
+            # NB: using the existing (old) reciprocal!
+            old_time = self.__int2time(self.__now)
+        except AttributeError:  # initial setup: either reciprocals or __now are absent
+            old_time = None
+        new_time = float(new_time) if new_time is not None else None
+
+        # If it is the 2nd or later setup, double-check on time monotonicity.
+        # In some configurations, this waring might raise an error and fail the test.
+        # In that case, the time must not be changed for the next test.
+        if old_time is not None and new_time is not None and new_time < old_time:
+            warnings.warn(
+                f"The time of the event loop moves backwards from {old_time} to {new_time},"
+                " thus breaking the monotonicity of time. This is dangerous!"
+                " Perhaps, caused by reusing a higher-scope event loop in tests."
+                " Revise the scopes of fixtures & event loops."
+                " Remove the start=… kwarg and rely on arbitrary time values."
+                " Migrate from `loop.time()` to the `looptime` numeric fixture.",
+                TimeWarning,
+            )
+
         self.__resolution_reciprocal: int = round(1/resolution)
-        self.__now: int = self.__time2int(start() if callable(start) else start) or 0
-        self.__end: int | None = self.__time2int(end() if callable(end) else end)
+        self.__now: int = self.__time2int(new_time or old_time) or 0
+        self.__end: int | None = self.__time2int(end_time)
 
         self.__idle_timeout: int | None = self.__time2int(idle_timeout)
         self.__idle_step: int | None = self.__time2int(idle_step)
@@ -85,6 +117,13 @@ class LoopTimeEventLoop(asyncio.BaseEventLoop):
         self.__sync_clock: Callable[[], float] = time.perf_counter
         self.__sync_ts: float | None = None  # system/true-time clock timestamp
 
+        try:
+            self.__enabled  # type: ignore
+        except AttributeError:
+            self.__enabled = _enabled if _enabled is not None else True  # old behaviour
+        else:
+            self.__enabled = _enabled if _enabled is not None else self.__enabled
+
         # TODO: why do we patch the selector as an object while the event loop as a class?
         #       this should be the same patching method for both.
         try:
@@ -93,10 +132,28 @@ class LoopTimeEventLoop(asyncio.BaseEventLoop):
             self.__original_select = self._selector.select
             self._selector.select = self.__replaced_select  # type: ignore
 
+    @property
+    def looptime_on(self) -> bool:
+        return bool(self.__enabled)
+
+    @contextlib.contextmanager
+    def looptime_enabled(self) -> Iterator[None]:
+        """
+        Temporarily enable the time compaction, restore the normal mode on exit.
+        """
+        if self.__enabled:
+            raise RuntimeError('Looptime mode is already enabled. Entered twice? Avoid this!')
+        old_enabled = self.__enabled
+        self.__enabled = True
+        try:
+            yield
+        finally:
+            self.__enabled = old_enabled
+
     def time(self) -> float:
         return self.__int2time(self.__now)
 
-    def run_in_executor(self, executor: Any, func: Any, *args: Any) -> AnyFuture:
+    def run_in_executor(self, executor: Any, func: Any, *args: Any) -> AnyFuture:  # type: ignore
         future = super().run_in_executor(executor, func, *args)
         if isinstance(future, asyncio.Future):
             self.__sync_futures.add(future)
@@ -111,6 +168,16 @@ class LoopTimeEventLoop(asyncio.BaseEventLoop):
         if ready:
             pass
 
+        # If nothing to do right now, and the time is not compacted, truly sleep as requested.
+        # Move the fake time by the exact real time spent in this wait (±discrepancies).
+        elif not self.__enabled:
+            t0 = time.monotonic()
+            ready = self.__original_select(timeout=timeout)
+            t1 = time.monotonic()
+
+            # If timeout=None, it never exists until ready. This timeout check is for typing only.
+            self.__now += self.__time2int(t1 - t0 if ready or timeout is None else timeout)
+
         # Regardless of the timeout, if there are executors sync futures, we move the time in steps.
         # The timeout (if present) can limit the size of the step, but not the logic of stepping.
         # Generally, external things (threads) take some time (e.g. for thread spawning).

looptime/math.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import abc
+from typing import Any
 
 
 class Numeric(metaclass=abc.ABCMeta):
@@ -108,5 +109,6 @@ class Numeric(metaclass=abc.ABCMeta):
         else:
             return NotImplemented
 
-    def __pow__(self, power: float, modulo: None = None) -> float:
+    # See the StdLib's comments on pow() on why it is Any, not float.
+    def __pow__(self, power: float, modulo: None = None) -> Any:
         return pow(round(self._value * self.__rr), power, modulo) / pow(self.__rr, power, modulo)

looptime/plugin.py

@@ -1,36 +1,147 @@
+"""
+Integrations with pytest & pytest-asyncio (irrelevant for other frameworks).
+
+
+IMPLEMENTATION DETAIL - reverse time movement
+=============================================
+
+Problem
+-------
+
+Pytest-asyncio>=1.0.0 has removed the ``event_loop`` fixture and fully switched
+to the ``event_loop_policy`` (session-scoped) plus several independent fixtures:
+session-, package-, module-, class-, function-scoped. It means that a test
+might use any of these fixtures or several or all of them at the same time.
+
+As a result, our previous assumption that every test & all its fixtures run
+in its own isolated short-lived event loop, is now broken:
+
+- A single event loop can be shared by multiple (but not all) tests.
+- A single test can be spread over multiple (but not all) event loops.
+
+An classic example:
+
+- A session-scoped fixture ``server`` starts a port listener & an HTTP server.
+- A module-scoped fixture ``data`` populates the server via POST requests.
+- A few function-scoped tests access & assert these data via GET requests.
+- Other tests verify the database and do not touch the event loops.
+
+Looptime suggests setting the start time of the event loop or expect it to be 0.
+This simplifies assertions, scheduling of events, callbacks, and other triggers.
+
+As a result, a long-living event loop might see the time set/reset by tests,
+and in most cases, it will be moving the time backwards.
+
+Time, by its nature, is supposed to be monotonic (but can be non-linear),
+specifically positively monotonic — always growing, never going backwards.
+
+
+Solution
+--------
+
+We sacrifice this core property of time for the sake of simplicity of tests.
+
+So we should be prepared for the consequences when all hell breaks loose. E.g.:
+the callbacks and other events triggering before they were set up (clock-wise);
+the durations of activities being negative; so on.
+
+Either way, we set the loop time as requested, but with a few nuances:
+
+1. If the start time is NOT explicitly defined, for higher-scoped event loops,
+   we keep the time as is for every test and let it flow monotonically.
+   Previously, the higher-scoped fixtures did not exist, so nothing breaks.
+
+2. If the start time is explicitly defined and is in the future, move the time
+   forwards as specified — indistinguishable from the previous behaviour
+   (except there could be artifacts from the previous tests in the loop).
+
+3. If the start time is explicitly defined and is in the past, issue a warning
+   of class ``looptime.TimeWarning``, which inherits from ``UserWarning``,
+   indicating a user-side misbehaviour & broken test-suite design.
+   It can be configured to raise an error (strict mode), or be ignored.
+
+This ensures the most possible backwards compatibility with the old behavior
+with a few truthworthy assumptions in mind:
+
+- Fixtures do not measure time and do not rely on time. Their purpose should be
+  preparing the environment, filling the data. Only the tests can move the time.
+  As such, they will not suffer much from the backward time movements.
+
+- Old-style tests typically use the function scope & the function-scoped loop,
+  which has the time set at 0 by default. No changes to the previous behaviour.
+
+- New-style tests that run in higher-scoped loops (a new pytest-asyncio feature)
+  should not rely on an isolated event loop and the time starting with 0,
+  and should be clearly prepared for the backward time movements
+  if they express the intention to reset the start time of the event loop.
+  Such tests should measure the "since" and "till" and assert on the difference.
+
+
+IMPLEMENTATION DETAIL — patching always, activating on-demand
+=============================================================
+
+In order to make event loops compatible with looptime, they (the event loops)
+MUST be patched at creation, not in the middle of a runtime when it reaches
+the looptime-enabled tests (consider a global session-scoped event loop here).
+
+Therefore, we patch ALL the implicit event loops of pytest-asyncio, regardless
+of whether they are supposed to be used or not. They are disabled (inactive)
+initally, i.e. their time flows normally, using the wall-clock (true) time.
+
+We then activate the looptime magic on demand for those tests that need it,
+and only when needed (i.e. when requested/configured/marked).
+
+We only activate the time magic on the running loop of the test, and only
+during the test execution. We do not compact the time of the event loops
+used in fixtures, even when the fixtures use the same-scoped event loop.
+
+(This might be a breaking change. See the assumptions above for the rationale.)
+
+Even for the lowest "function" scope, we cannot patch-and-activate it only once
+at creation, since at the time of the event loop setup (creation),
+we do not know which event loop will be the running loop of the test.
+This affects to which loop the configured options should be applied.
+
+We only know this when we reach the test.
+We then apply the options, and activate the pre-patched running event loop.
+"""
 from __future__ import annotations
 
 import asyncio
-from typing import Any, cast
+import warnings
+from typing import Any
 
+import _pytest.nodes
 import pytest
 
-from looptime import loops, patchers
+from looptime import loops, patchers, timeproxies
 
 
-@pytest.hookimpl(hookwrapper=True)  # type: ignore
-def pytest_fixture_setup(fixturedef: Any, request: Any) -> Any:
-    if fixturedef.argname == "event_loop":
-        result = yield
-        loop = cast(asyncio.BaseEventLoop, result.get_result()) if result.excinfo is None else None
-        if loop is not None and not isinstance(loop, loops.LoopTimeEventLoop):
+# Critical implementation details: It MUST be sync! It CANNOT be async!
+# It might seem that the easiest way to implement the ``looptime`` fixture is
+# to make it ``async def`` and get the running loop inside. This does NOT work.
+# When a function-scoped fixture is used in any higher-scoped test, it degrades
+# the test from its scope to the function scope and breaks the test design.
+# See an example at https://github.com/pytest-dev/pytest-asyncio/issues/1142.
+# As such, the fixture MUST be synchronous (simple ``def``). As a result,
+# the fixture CANNOT get a running loop, because there is no running loop.
+# We take the running loop inside the time-measuring proxy at runtime.
+@pytest.fixture
+def looptime(request: pytest.FixtureRequest) -> timeproxies.LoopTimeProxy:
+    """
+    The event loop time for assertions.
 
-            # True means implicitly on; False means explicitly off; None means "only if marked".
-            option: bool | None = request.config.getoption('looptime')
+    The fixture's numeric value is the loop time as a number of seconds
+    since the "time zero", which is usuaully the creation time
+    of the event loop, but can be adjusted by the ``start=…`` option.
 
-            markers = list(request.node.iter_markers('looptime'))
-            enabled = bool((markers or option is True) and option is not False)  # but not None!
-            options = {}
-            for marker in reversed(markers):
-                options.update(marker.kwargs)
-                enabled = bool(marker.args[0]) if marker.args else enabled
+    - It can be used in assertions & comparisons (``==``, ``<=``, etc).
+    - It can also be used in simple math (additions, substractions, etc).
+    - It can be converted to ``int()`` or ``float()``.
 
-            if enabled:
-                patched_loop = patchers.patch_event_loop(loop)
-                patched_loop.setup_looptime(**options)
-                result.force_result(patched_loop)
-    else:
-        yield
+    It is an equivalent of a more wordy ``asyncio.get_running_loop().time()``.
+    """
+    return timeproxies.LoopTimeProxy()
 
 
 def pytest_configure(config: Any) -> None:
@@ -43,3 +154,163 @@ def pytest_addoption(parser: Any) -> None:
                     help="Force all (even marked) tests to the true loop time.")
     group.addoption("--looptime", dest='looptime', action="store_const", const=True,
                     help="Run unmarked tests with the fake loop time by default.")
+
+
+EventLoopScopes = dict[str, list[str]]  # {fixture_name -> [outer_scopes, …, innermost_scope]}
+EVENT_LOOP_SCOPES = pytest.StashKey[EventLoopScopes]()
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_fixture_setup(fixturedef: pytest.FixtureDef[Any], request: pytest.FixtureRequest) -> Any:
+    # Setup as usual. We do the magic only afterwards, when we have the event loop created.
+    result = yield
+
+    # Only do the magic if in the area of our interest & only for fixtures making the event loops.
+    if _should_patch(fixturedef, request) and isinstance(result, asyncio.BaseEventLoop):
+
+        # Populate the helper mapper of names-to-scopes, as used in the test hook below.
+        if EVENT_LOOP_SCOPES not in request.session.stash:
+            request.session.stash[EVENT_LOOP_SCOPES] = {}
+        event_loop_scopes: EventLoopScopes = request.session.stash[EVENT_LOOP_SCOPES]
+        event_loop_scopes.setdefault(fixturedef.argname, []).append(fixturedef.scope)
+
+        # Patch the event loop at creation — even if unused and not enabled. We cannot patch later
+        # in the middle of the run: e.g. for a session-scoped loop used in a few tests out of many.
+        # NB: For the lowest "function" scope, we still cannot decide which options to use, since
+        # we do not know yet if it will be the running loop or not — so we cannot optimize here
+        # in order to patch-and-configure only once; we must patch here & configure+activate later.
+        result = patchers.patch_event_loop(result, _enabled=False)
+
+    return result
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_fixture_post_finalizer(fixturedef: pytest.FixtureDef[Any], request: pytest.FixtureRequest) -> Any:
+    # Cleanup the helper mapper of the fixture's names-to-scopes, as used in the test-running hook.
+    # Internal consistency check: some cases should not happen, but we do not fail if they do.
+    if EVENT_LOOP_SCOPES in request.session.stash:
+        event_loop_scopes: EventLoopScopes = request.session.stash[EVENT_LOOP_SCOPES]
+        if fixturedef.argname not in event_loop_scopes:
+            warnings.warn(
+                f"Fixture {fixturedef.argname!r} not found in the cache of scopes."
+                f" Report as a bug, please add a reproducible snippet.",
+                RuntimeWarning,
+            )
+        elif not event_loop_scopes[fixturedef.argname]:
+            warnings.warn(
+                f"Fixture {fixturedef.argname!r} has the empty cache of scopes."
+                f" Report as a bug, please add a reproducible snippet.",
+                RuntimeWarning,
+            )
+        elif event_loop_scopes[fixturedef.argname][-1] != fixturedef.scope:
+            warnings.warn(
+                f"Fixture {fixturedef.argname!r} has the broken cache of scopes:"
+                f" {event_loop_scopes[fixturedef.argname]!r}, expecting {fixturedef.scope!r}"
+                f" Report as a bug, please add a reproducible snippet.",
+                RuntimeWarning,
+            )
+        else:
+            event_loop_scopes[fixturedef.argname][-1:] = []
+
+    # Go as usual.
+    return (yield)
+
+
+# This hook is the latest (deepest) possible entrypoint before diving into the test function itself,
+# with all the fixtures executed earlier, so that their setup time is not taken into account.
+# Here, we know the actual running loop (out of many) chosen by pytest-asyncio & its marks/configs.
+# The alternatives to consider — the subtle differences are unclear to me for now:
+# - pytest_pyfunc_call(pyfuncitem)
+# - pytest_runtest_call(item)
+# - pytest_runtest_setup(item), wrapped as @hookimpl(trylast=True)
+@pytest.hookimpl(wrapper=True)
+def pytest_pyfunc_call(pyfuncitem: pytest.Function) -> Any:
+
+    # Get the running loop from the pre-populated & pre-resolved fixtures (done in the setup stage).
+    # This includes all the auto-used fixtures, but NOT the dynamic `getfixturevalue(…)` ones.
+    # Alternatively, use the private `pyfuncitem._request.getfixturevalue(…)`, though this is hacky.
+    funcargs: dict[str, Any] = pyfuncitem.funcargs
+    if 'event_loop_policy' in funcargs:  # pytest-asyncio>=1.0.0
+        # This can be ANY event loop of ANY declared scope of pytest-asyncio.
+        policy: asyncio.AbstractEventLoopPolicy = funcargs['event_loop_policy']
+        running_loop = policy.get_event_loop()
+    elif 'event_loop' in funcargs:  # pytest-asyncio<1.0.0
+        # The hook itself has NO "running" loop — because it is sync, not async.
+        running_loop = funcargs['event_loop']
+    else: # not pytest-asyncio? not our business!
+        return (yield)
+
+    # The event loop is not patched? We are doomed to fail, so let it run somehow on its own.
+    # This might happen if the custom event loop policy was set not by pytest-asyncio.
+    if not isinstance(running_loop, loops.LoopTimeEventLoop):
+        return (yield)
+
+    # If not enabled/enforced for this test, even if the event loop is patched, let it run as usual.
+    options: dict[str, Any] | None = _get_options(pyfuncitem)
+    if options is None:
+        return (yield)
+
+    # Finally, if enabled/enforced, activate the magic and run the test in the compacted time mode.
+    # We only activate the running loop for the test, not the other event loops used in fixtures.
+    running_loop.setup_looptime(**options)
+    with running_loop.looptime_enabled():
+        return (yield)
+
+
+def _should_patch(fixturedef: pytest.FixtureDef[Any], request: pytest.FixtureRequest) -> bool:
+    """
+    Check if the fixture should be patched (in case it is an event loop).
+
+    Only patch the implicit (hidden) event loops and their user-side overrides.
+    They are declared as internal with underscored names, but nevertheless.
+    Example implicit names: ``_session_event_loop`` … ``_function_event_loop``.
+
+    We do not intercept arbitrary fixtures or event loops of unknown plugins.
+    Custom event loops can be patched explicitly if needed.
+    """
+    # pytest-asyncio<1.0.0 exposed the specific fixture; deprecated since >=0.23.0, removed >=1.0.0.
+    if fixturedef.argname == "event_loop":
+        return True
+
+    # pytest-asyncio>=1.0.0 exposes several event loops, one per scope, all hidden in the module.
+    asyncio_plugin = request.config.pluginmanager.getplugin("asyncio")  # a module object
+    asyncio_names: set[str] = {
+        name for name in dir(asyncio_plugin) if _is_fixture(getattr(asyncio_plugin, name))
+    }
+    asyncio_module = asyncio_plugin.__name__
+    fixture_module = fixturedef.func.__module__
+    should_patch = fixture_module == asyncio_module or fixturedef.argname in asyncio_names
+    return should_patch
+
+
+def _is_fixture(obj: Any) -> bool:
+    # Any of these internal names can be moved or renamed any time. Do our best to guess.
+    import _pytest.fixtures
+
+    try:
+        if isinstance(obj, _pytest.fixtures.FixtureFunctionDefinition):
+            return True
+    except AttributeError:
+        pass
+    try:
+        if isinstance(obj, _pytest.fixtures.FixtureFunctionMarker):
+            return True
+    except AttributeError:
+        pass
+    return False
+
+
+def _get_options(node: _pytest.nodes.Node) -> dict[str, Any] | None:
+    """Combine all the declared looptime options; None for disabled."""
+
+    # True means implicitly on; False means explicitly off; None means "only if marked".
+    flag: bool | None = node.config.getoption('looptime')
+
+    markers = list(node.iter_markers('looptime'))
+    enabled: bool = bool((markers or flag is True) and not flag is False)
+    options: dict[str, Any] = {}
+    for marker in reversed(markers):
+        options.update(marker.kwargs)
+        enabled = bool(marker.args[0]) if marker.args else enabled
+
+    return options if enabled else None

looptime/timeproxies.py

@@ -31,13 +31,3 @@ class LoopTimeProxy(math.Numeric):
     @property
     def _value(self) -> float:
         return self._loop.time() if self._loop is not None else asyncio.get_running_loop().time()
-
-
-try:
-    import pytest
-except ImportError:
-    pass
-else:
-    @pytest.fixture()
-    def looptime() -> LoopTimeProxy:
-        return LoopTimeProxy()

{looptime-0.2.dist-info → looptime-0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: looptime
-Version: 0.2
+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,10 +47,10 @@ 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).
+  (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.
 
@@ -77,19 +87,19 @@ 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 real-world cases, the tests often must verify that
+However, in the real-world cases, the tests often must verify that
 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.
@@ -97,8 +107,8 @@ 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-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 affects the timing
-and makes it difficult to assert on the coroutine's pure time.
+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
@@ -250,13 +260,26 @@ async def test_me():
 `start` (`float` or `None`, or a no-argument callable that returns the same)
 is the initial time of the event loop.
 
-If it is callable, it is invoked once per event loop to get the value:
+If it is a callable, it is invoked once per event loop to get the value:
 e.g. `start=time.monotonic` to align with the true time,
 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`.
@@ -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
@@ -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__)
 ```
-
-

looptime-0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+looptime/__init__.py,sha256=oxt_f8ZdFSTmpjSRNMAnwNjyp4ajwucpFKnpisGPDik,497
+looptime/chronometers.py,sha256=AgLYweIq-bjfxhR0Qqt0QOXrKR48fornjEIhNMrycOo,1803
+looptime/loops.py,sha256=ccrfsa15W0JW2LLYJUEagH03XlE2Lw2Uxe_W9ZuuQNU,17621
+looptime/math.py,sha256=50d4ul1XEMzhvtBnYqYdkLwiovvhqEWu00q9ZySHVR0,3689
+looptime/patchers.py,sha256=T8eDCyf7bPGAKm1cMbi6V3xTtH7VbJpYgB_kDIr6tOw,1252
+looptime/plugin.py,sha256=XtJ7NxLk2SFXQPRiQHmpenfcvQ44VVFKnlw7446AUuU,14869
+looptime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+looptime/timeproxies.py,sha256=dhFng7mw8V6icDnKeHw8SNk74iXsOCtCe2mD8kRO-uI,874
+looptime-0.3.dist-info/licenses/LICENSE,sha256=QBTPjghK-H2Ctv9yejhXyT3zrf6HTKCETMQaOGotl28,1091
+looptime-0.3.dist-info/METADATA,sha256=82gW_FB6vxusJLpIrZPIWXaLzNAQAONA7V33e2pyZ70,27917
+looptime-0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+looptime-0.3.dist-info/entry_points.txt,sha256=KSBS46wdBGv7lmhfsCyAPsWlQNbmkktVYZc2Ze0spcU,135
+looptime-0.3.dist-info/top_level.txt,sha256=S4Ty0YHUCB1cf-PE5YiskuOSiMctlsLrUp3c2Yywzz4,9
+looptime-0.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+looptime-0.3.dist-info/RECORD,,

{looptime-0.2.dist-info → looptime-0.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.37.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{looptime-0.2.dist-info → looptime-0.3.dist-info}/entry_points.txt

@@ -2,4 +2,3 @@
 looptime_chronometers = looptime.chronometers
 looptime_plugin = looptime.plugin
 looptime_timeproxies = looptime.timeproxies
-

looptime-0.2.dist-info/RECORD

@@ -1,15 +0,0 @@
-looptime/__init__.py,sha256=xDfdZVz49skblf5TGh9PfPG1EDS8VZnHOLKDft_hiWM,465
-looptime/chronometers.py,sha256=AgLYweIq-bjfxhR0Qqt0QOXrKR48fornjEIhNMrycOo,1803
-looptime/loops.py,sha256=dREp8usEU3Bdt8VhGGmjji9lZ0ud0djTQ8VCr66eabg,14706
-looptime/math.py,sha256=fgtKLHWry7ivZNHHqakUcK_A-YP2nTVpZ1yZfMm0Y-M,3598
-looptime/patchers.py,sha256=T8eDCyf7bPGAKm1cMbi6V3xTtH7VbJpYgB_kDIr6tOw,1252
-looptime/plugin.py,sha256=Cspm-sTZ3q6K9gX0K0Jinr8CxOBBrHmdo52kyMz2ZCI,1818
-looptime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-looptime/timeproxies.py,sha256=9E5pFcwMv4Rr2K7bqOa0ucfdXbUib7C9122WKIf6pNk,1024
-looptime-0.2.dist-info/LICENSE,sha256=QBTPjghK-H2Ctv9yejhXyT3zrf6HTKCETMQaOGotl28,1091
-looptime-0.2.dist-info/METADATA,sha256=r4KfvgLVT05G04D-YhZnMdqf2aEEMkB2RLNXO9hQDr4,23774
-looptime-0.2.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-looptime-0.2.dist-info/entry_points.txt,sha256=KiodpY8Q7SvZrrbmSWbck3HTB65NYJQkIA0wij4bjQ4,136
-looptime-0.2.dist-info/top_level.txt,sha256=S4Ty0YHUCB1cf-PE5YiskuOSiMctlsLrUp3c2Yywzz4,9
-looptime-0.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-looptime-0.2.dist-info/RECORD,,