pytest-stream-lifecycle 0.1.0a1__py3-none-any.whl

pytest_stream_lifecycle/__init__.py

@@ -0,0 +1,6 @@
+"""Real-loopback ASGI test server."""
+
+from .probe import LifecycleError, LifecycleProbe
+from .server import ServerError, ServerHandle, live_server
+
+__all__ = ["LifecycleError", "LifecycleProbe", "ServerError", "ServerHandle", "live_server"]

pytest_stream_lifecycle/_errors.py

@@ -0,0 +1,20 @@
+"""Attach secondary exception evidence without replacing a primary failure."""
+
+
+def add_exception_notes(primary: BaseException, label: str, error: BaseException) -> None:
+    seen: set[int] = set()
+    pending = [error]
+    while pending:
+        current = pending.pop()
+        if current is primary or id(current) in seen:
+            continue
+        seen.add(id(current))
+        primary.add_note(f"{label}: {current!r}")
+        for note in getattr(current, "__notes__", ()):
+            primary.add_note(note)
+        if isinstance(current, BaseExceptionGroup):
+            pending.extend(reversed(current.exceptions))
+        if current.__context__ is not None:
+            pending.append(current.__context__)
+        if current.__cause__ is not None:
+            pending.append(current.__cause__)

pytest_stream_lifecycle/plugin.py

@@ -0,0 +1,18 @@
+"""Pytest fixture registration."""
+
+import pytest
+
+from .probe import LifecycleProbe
+from .server import live_server
+
+
+@pytest.fixture
+def stream_server():
+    """Return a factory for async context managers serving ASGI applications."""
+    return live_server
+
+
+@pytest.fixture
+def stream_probe():
+    """Return a new explicit application-lifecycle probe."""
+    return LifecycleProbe()

pytest_stream_lifecycle/probe.py

@@ -0,0 +1,153 @@
+"""Explicit observations of application-owned resource lifetimes."""
+
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict
+from types import TracebackType
+from typing import Self
+
+
+class LifecycleError(AssertionError):
+    """An observed lifecycle or streaming expectation was not met."""
+
+
+def _positive_timeout(timeout: float) -> float:
+    import math
+
+    try:
+        value = float(timeout)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("timeout must be a positive finite number") from exc
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError("timeout must be a positive finite number")
+    return value
+
+
+class _Observation:
+    def __init__(self, probe: LifecycleProbe, name: str):
+        self._probe = probe
+        self.name = name
+        self.active = False
+        self.acknowledged = False
+        self.failure: BaseException | None = None
+        self._entered = False
+
+    def __enter__(self) -> Self:
+        self._probe._check_loop()
+        if self._entered:
+            raise RuntimeError("an observation cannot be entered more than once")
+        self._entered = self.active = True
+        self._probe._entries[self.name].append(self)
+        self._probe._changed()
+        return self
+
+    def mark_closed(self) -> None:
+        """Acknowledge that this instance's awaited cleanup has completed."""
+        self._probe._check_loop()
+        if not self.active:
+            raise RuntimeError("mark_closed() requires an active observation")
+        self.acknowledged = True
+        self._probe._changed()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self._probe._check_loop()
+        self.active = False
+        if exc is not None and not isinstance(exc, (asyncio.CancelledError, GeneratorExit)):
+            self.failure = exc
+        self._probe._changed()
+
+
+class LifecycleProbe:
+    """Record explicitly instrumented resource instances on one asyncio loop.
+
+    A cleanup acknowledgement is supplied by the application, not proof of
+    remote-provider cancellation. The probe never cancels application tasks.
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[str, list[_Observation]] = defaultdict(list)
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._event: asyncio.Event | None = None
+
+    def _check_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is None:
+            self._loop = loop
+            self._event = asyncio.Event()
+        elif self._loop is not loop:
+            raise RuntimeError("LifecycleProbe cannot be reused across asyncio event loops")
+
+    def _changed(self) -> None:
+        assert self._event is not None
+        self._event.set()
+        self._event = asyncio.Event()
+
+    def track(self, name: str) -> _Observation:
+        if not isinstance(name, str) or not name:
+            raise ValueError("resource name must be a nonempty string")
+        return _Observation(self, name)
+
+    @property
+    def active_labels(self) -> frozenset[str]:
+        self._check_loop()
+        return frozenset(
+            name for name, entries in self._entries.items() if any(e.active for e in entries)
+        )
+
+    def started_count(self, name: str) -> int:
+        self._check_loop()
+        return len(self._entries.get(name, ()))
+
+    def assert_active(self, name: str) -> None:
+        self._check_loop()
+        if name not in self.active_labels:
+            state = "not observed" if not self.started_count(name) else "not active"
+            raise LifecycleError(f"resource {name!r} is {state}")
+
+    async def wait_started(self, name: str, *, timeout: float = 2.0) -> None:
+        self._check_loop()
+        deadline = asyncio.get_running_loop().time() + _positive_timeout(timeout)
+        while not self.started_count(name):
+            await self._wait_change(deadline, f"resource {name!r} was not observed")
+
+    async def _wait_change(self, deadline: float, diagnostic: str) -> None:
+        assert self._event is not None
+        remaining = deadline - asyncio.get_running_loop().time()
+        if remaining <= 0:
+            raise LifecycleError(f"timed out: {diagnostic}")
+        try:
+            await asyncio.wait_for(self._event.wait(), timeout=remaining)
+        except TimeoutError as exc:
+            raise LifecycleError(f"timed out: {diagnostic}") from exc
+
+    async def wait_closed(self, *names: str, timeout: float = 2.0) -> None:
+        self._check_loop()
+        if not names:
+            raise LifecycleError("wait_closed requires at least one resource name")
+        deadline = asyncio.get_running_loop().time() + _positive_timeout(timeout)
+        while True:
+            unknown = [name for name in names if not self._entries.get(name)]
+            active = [name for name in names if any(e.active for e in self._entries.get(name, ()))]
+            failed = [e for name in names for e in self._entries.get(name, ()) if e.failure]
+            unacknowledged = [
+                name
+                for name in names
+                if any(not e.active and not e.acknowledged for e in self._entries.get(name, ()))
+            ]
+            if failed:
+                raise LifecycleError(
+                    f"resource {failed[0].name!r} exited with error: {failed[0].failure!r}"
+                ) from failed[0].failure
+            if unacknowledged:
+                raise LifecycleError(
+                    f"resource cleanup unacknowledged: {', '.join(unacknowledged)}"
+                )
+            if not unknown and not active:
+                return
+            await self._wait_change(deadline, f"unknown: {unknown}; active: {active}")

pytest_stream_lifecycle/server.py

@@ -0,0 +1,314 @@
+"""In-process, asyncio-only Uvicorn server on a reserved loopback socket.
+
+Cancellation-resistant application code cannot be forcibly killed in process.
+Timeouts bound our waits; any tasks that ignore cancellation may continue running.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import socket
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import uvicorn
+
+from ._errors import add_exception_notes
+
+ASGIApp = Callable[..., Any]
+Lifespan = Literal["on", "off", "auto"]
+
+
+class ServerError(RuntimeError):
+    """The server failed to start or stop within its allotted time."""
+
+
+@dataclass(frozen=True, slots=True)
+class ServerHandle:
+    """Address of a running HTTP server."""
+
+    url: str
+
+    def sse(self, path: str, *, method: str = "GET", timeout: float = 2.0, **request_kwargs: Any):
+        """Open a bounded SSE reader over the server's real HTTP socket."""
+        from .streams import open_stream
+
+        return open_stream(
+            self.url, path, kind="sse", method=method, timeout=timeout, **request_kwargs
+        )
+
+    def lines(self, path: str, *, method: str = "GET", timeout: float = 2.0, **request_kwargs: Any):
+        """Open a bounded line reader over the server's real HTTP socket."""
+        from .streams import open_stream
+
+        return open_stream(
+            self.url, path, kind="lines", method=method, timeout=timeout, **request_kwargs
+        )
+
+
+class _Config(uvicorn.Config):
+    def configure_logging(self) -> None:
+        # Uvicorn's default method changes global logging even when
+        # log_config=None (and removes access handlers when access_log=False).
+        pass
+
+
+class _Server(uvicorn.Server):
+    @contextmanager
+    def capture_signals(self):
+        # Embedded server must never replace the test process's signal handlers.
+        yield
+
+
+def _timeout(name: str, value: float) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a positive finite number") from exc
+    if not math.isfinite(number) or number <= 0:
+        raise ValueError(f"{name} must be a positive finite number")
+    return number
+
+
+async def _wait_until_started(server: _Server, task: asyncio.Task[None], timeout: float) -> None:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while not server.started:
+        if task.done():
+            try:
+                task.result()
+            except BaseException as exc:
+                raise ServerError("server failed during startup") from exc
+            raise ServerError("server exited before startup completed")
+        remaining = deadline - loop.time()
+        if remaining <= 0:
+            raise ServerError(f"server startup timed out after {timeout:g}s")
+        await asyncio.wait({task}, timeout=min(0.01, remaining))
+
+
+async def _stop(
+    server: _Server,
+    task: asyncio.Task[None],
+    sock: socket.socket,
+    app_tasks: set[asyncio.Task[Any]],
+    timeout: float,
+    task_errors: list[BaseException],
+) -> None:
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    server.should_exit = True
+    timed_out = False
+    # Reserve part of the deadline for cooperative cancellation and its cleanup.
+    grace = timeout * 0.8
+    grace_deadline = loop.time() + grace
+    try:
+        done, pending = await asyncio.wait({task}, timeout=grace)
+        if pending:
+            timed_out = True
+            server.force_exit = True
+            task.cancel()
+        owned = {t for t in app_tasks if not t.done()} | set(pending)
+        if owned and not timed_out:
+            _, owned = await asyncio.wait(owned, timeout=max(0, grace_deadline - loop.time()))
+            timed_out = bool(owned)
+        if owned:
+            for owned_task in owned:
+                owned_task.cancel()
+            completed, _ = await asyncio.wait(owned, timeout=max(0, deadline - loop.time()))
+            for completed_task in completed:
+                if not completed_task.cancelled():
+                    error = completed_task.exception()
+                    if error is not None and error not in task_errors:
+                        task_errors.append(error)
+        server_error = task.exception() if done and not task.cancelled() else None
+        if server_error is not None:
+            error = ServerError("server failed while running or shutting down")
+            for secondary in task_errors:
+                add_exception_notes(error, "Owned task cleanup failure", secondary)
+            raise error from server_error
+        if timed_out:
+            error = ServerError(f"server shutdown timed out after {timeout:g}s")
+            for secondary in task_errors:
+                add_exception_notes(error, "Owned task cleanup failure", secondary)
+            raise error
+        if task_errors:
+            error = ServerError(f"owned task cleanup failed: {task_errors[0]!r}")
+            for secondary in task_errors[1:]:
+                add_exception_notes(error, "Additional owned task failure", secondary)
+            raise error from task_errors[0]
+    finally:
+        # Uvicorn's asyncio.Server normally owns the supplied socket. If its
+        # serve task was cancelled mid-shutdown, close its listener explicitly
+        # before closing the original socket, and never touch other servers.
+        for listener in getattr(server, "servers", ()):
+            listener.close()
+        for connection in tuple(server.server_state.connections):
+            transport = getattr(connection, "transport", None)
+            if transport is not None:
+                transport.abort()
+        sock.close()
+
+
+@asynccontextmanager
+async def live_server(
+    app: ASGIApp,
+    *,
+    startup_timeout: float = 5.0,
+    shutdown_timeout: float = 5.0,
+    lifespan: Lifespan = "on",
+) -> AsyncIterator[ServerHandle]:
+    """Serve ``app`` on a reserved 127.0.0.1 port within this event loop.
+
+    Startup and shutdown waits are bounded. Cancellation-resistant application
+    code can outlive those waits; process isolation is required for a hard kill.
+    """
+    startup_timeout = _timeout("startup_timeout", startup_timeout)
+    shutdown_timeout = _timeout("shutdown_timeout", shutdown_timeout)
+    if lifespan not in ("on", "off", "auto"):
+        raise ValueError("lifespan must be 'on', 'off', or 'auto'")
+    app_tasks: set[asyncio.Task[Any]] = set()
+    task_errors: list[BaseException] = []
+    lifespan_started = False
+    startup_failure: BaseException | str | None = None
+    lifespan_failure: BaseException | str | None = None
+
+    async def tracked_app(scope, receive, send):
+        nonlocal lifespan_started, lifespan_failure, startup_failure
+        current = asyncio.current_task()
+        if current is not None:
+            app_tasks.add(current)
+
+            def task_done(done):
+                app_tasks.discard(done)
+                if not done.cancelled():
+                    error = done.exception()
+                    if error is not None and error not in task_errors:
+                        task_errors.append(error)
+
+            current.add_done_callback(task_done)
+        if scope["type"] != "lifespan":
+            try:
+                await app(scope, receive, send)
+            except BaseException as exc:
+                if (
+                    current is not None
+                    and current.cancelling()
+                    and not isinstance(exc, asyncio.CancelledError)
+                ):
+                    task_errors.append(exc)
+                raise
+            return
+
+        async def tracked_send(message):
+            nonlocal lifespan_started, lifespan_failure, startup_failure
+            if message["type"] == "lifespan.startup.complete":
+                lifespan_started = True
+            elif message["type"] == "lifespan.startup.failed":
+                startup_failure = message.get("message") or "application reported startup failure"
+            elif message["type"] == "lifespan.shutdown.failed":
+                lifespan_failure = message.get("message") or "application reported shutdown failure"
+            await send(message)
+
+        try:
+            await app(scope, receive, tracked_send)
+        except BaseException as exc:
+            if not isinstance(exc, asyncio.CancelledError):
+                if lifespan_started:
+                    lifespan_failure = exc
+                elif startup_failure is None:
+                    startup_failure = exc
+            raise
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    task: asyncio.Task[None] | None = None
+    server: _Server | None = None
+    failure: BaseException | None = None
+    try:
+        sock.bind(("127.0.0.1", 0))
+        sock.listen(socket.SOMAXCONN)
+        sock.setblocking(False)
+        port = sock.getsockname()[1]
+        config = _Config(
+            tracked_app,
+            lifespan=lifespan,
+            log_config=None,
+            access_log=False,
+            http="h11",
+            ws="none",
+            # Uvicorn also polls in main_loop and sleeps before waiting for
+            # active connections. Reserve fixed time for those phases and
+            # scheduler jitter, in addition to our cancellation reserve.
+            timeout_graceful_shutdown=min(
+                shutdown_timeout * 0.4, max(0.0, shutdown_timeout * 0.8 - 0.3)
+            ),
+        )
+        server = _Server(config)
+
+        async def serve() -> None:
+            try:
+                await server.serve(sockets=[sock])
+            except SystemExit as exc:
+                # Recent Uvicorn versions call sys.exit on failed startup.
+                # A BaseException escaping a task stops the host event loop.
+                raise ServerError("Uvicorn exited during startup") from exc
+
+        task = asyncio.create_task(serve(), name="stream-lifecycle-server")
+        try:
+            await _wait_until_started(server, task, startup_timeout)
+        except ServerError:
+            if startup_failure is not None:
+                detail = f"application lifespan startup failed: {startup_failure}"
+                if isinstance(startup_failure, BaseException):
+                    raise ServerError(detail) from startup_failure
+                raise ServerError(detail) from None
+            raise
+        yield ServerHandle(url=f"http://127.0.0.1:{port}")
+    except BaseException as exc:
+        failure = exc
+        raise
+    finally:
+        if task is not None and server is not None:
+
+            async def cleanup() -> None:
+                cleanup_error: BaseException | None = None
+                try:
+                    await _stop(server, task, sock, app_tasks, shutdown_timeout, task_errors)
+                except Exception as exc:  # noqa: BLE001 - preserve cleanup failure
+                    cleanup_error = exc
+                if lifespan_failure is not None:
+                    detail = f"application lifespan failed after startup: {lifespan_failure}"
+                    if cleanup_error is not None:
+                        if isinstance(lifespan_failure, BaseException):
+                            add_exception_notes(cleanup_error, detail, lifespan_failure)
+                        else:
+                            cleanup_error.add_note(detail)
+                    elif isinstance(lifespan_failure, BaseException):
+                        raise ServerError(detail) from lifespan_failure
+                    else:
+                        raise ServerError(detail)
+                if cleanup_error is not None:
+                    raise cleanup_error
+
+            cleanup_task = asyncio.create_task(cleanup(), name="stream-lifecycle-cleanup")
+            interrupted: asyncio.CancelledError | None = None
+            while not cleanup_task.done():
+                try:
+                    await asyncio.shield(cleanup_task)
+                except asyncio.CancelledError as exc:
+                    if interrupted is None:
+                        interrupted = exc
+                except Exception:  # noqa: BLE001 - retrieve the cleanup task error below
+                    break
+            cleanup_error = None if cleanup_task.cancelled() else cleanup_task.exception()
+            primary = failure if failure is not None else interrupted
+            if cleanup_error is not None:
+                if primary is None:
+                    raise cleanup_error
+                add_exception_notes(primary, "Server cleanup failure", cleanup_error)
+            if failure is None and interrupted is not None:
+                raise interrupted
+        else:
+            sock.close()

pytest_stream_lifecycle/streams.py

@@ -0,0 +1,152 @@
+"""Bounded real-network line and server-sent-event readers."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from functools import partial
+from typing import Any
+
+import httpx
+from httpx_sse import EventSource
+
+from ._errors import add_exception_notes
+from .probe import LifecycleError, _positive_timeout
+
+
+async def _close_steps(*steps) -> None:
+    error: BaseException | None = None
+    for close in steps:
+        try:
+            await close()
+        except BaseException as exc:  # noqa: BLE001 - attempt every owned cleanup step
+            if error is None:
+                error = exc
+            else:
+                add_exception_notes(error, "Additional stream cleanup failure", exc)
+    if error is not None:
+        raise error
+
+
+class Stream:
+    """An open response; closing it does not assert application cleanup."""
+
+    def __init__(self, client, response_context, response, iterator, timeout: float, label: str):
+        self._client = client
+        self._response_context = response_context
+        self._response = response
+        self._iterator = iterator
+        self._timeout = timeout
+        self._label = label
+        self._closed = False
+        self._reading = False
+
+    async def next(self, *, timeout: float | None = None) -> Any:
+        if self._closed:
+            raise LifecycleError(f"{self._label} stream is closed")
+        if self._reading:
+            raise LifecycleError(f"{self._label} stream already has a pending read")
+        duration = self._timeout if timeout is None else _positive_timeout(timeout)
+        self._reading = True
+        try:
+            try:
+                return await asyncio.wait_for(anext(self._iterator), timeout=duration)
+            except TimeoutError as exc:
+                error = LifecycleError(f"{self._label} stream timed out after {duration:g}s")
+                await self._close_with_primary(error)
+                raise error from exc
+            except StopAsyncIteration as exc:
+                error = LifecycleError(f"{self._label} stream ended unexpectedly (EOF)")
+                await self._close_with_primary(error)
+                raise error from exc
+            except asyncio.CancelledError as exc:
+                await self._close_with_primary(exc)
+                raise
+            except Exception as exc:
+                error = LifecycleError(f"{self._label} stream read failed: {exc}")
+                await self._close_with_primary(error)
+                raise error from exc
+        finally:
+            self._reading = False
+
+    async def _close_with_primary(self, primary: BaseException) -> None:
+        try:
+            await self.aclose()
+        except BaseException as exc:  # noqa: BLE001 - preserve the primary failure
+            add_exception_notes(primary, "Stream cleanup failure", exc)
+
+    async def aclose(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        await _close_steps(
+            self._iterator.aclose,
+            partial(self._response_context.__aexit__, None, None, None),
+            self._client.aclose,
+        )
+
+
+@asynccontextmanager
+async def open_stream(
+    base_url: str,
+    path: str,
+    *,
+    kind: str,
+    method: str = "GET",
+    timeout: float = 2.0,
+    **request_kwargs: Any,
+) -> AsyncIterator[Stream]:
+    duration = _positive_timeout(timeout)
+    if not isinstance(path, str) or not path.startswith("/") or path.startswith("//"):
+        raise ValueError("path must be a relative path starting with a single '/'")
+    if kind == "sse":
+        headers = httpx.Headers(request_kwargs.pop("headers", {}))
+        headers["Accept"] = "text/event-stream"
+        headers["Cache-Control"] = "no-store"
+        request_kwargs["headers"] = headers
+    client = httpx.AsyncClient(trust_env=False, timeout=None)
+    response_context = client.stream(method, base_url + path, **request_kwargs)
+    response = None
+    stream = None
+    failure: BaseException | None = None
+    try:
+        try:
+            response = await asyncio.wait_for(response_context.__aenter__(), timeout=duration)
+            response.raise_for_status()
+            if kind == "sse":
+                media_type = (
+                    response.headers.get("content-type", "").partition(";")[0].strip().lower()
+                )
+                if media_type != "text/event-stream":
+                    raise LifecycleError(f"SSE stream has invalid content-type: {media_type!r}")
+                iterator = EventSource(response).aiter_sse()
+            else:
+                iterator = response.aiter_lines()
+            stream = Stream(
+                client, response_context, response, iterator, duration, f"{kind.upper()} {path}"
+            )
+        except TimeoutError as exc:
+            raise LifecycleError(
+                f"{kind.upper()} {path} connection timed out after {duration:g}s"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise LifecycleError(f"{kind.upper()} {path} request failed: {exc}") from exc
+        yield stream
+    except BaseException as exc:
+        failure = exc
+        raise
+    finally:
+        try:
+            if stream is not None:
+                await stream.aclose()
+            else:
+                steps = []
+                if response is not None:
+                    steps.append(partial(response_context.__aexit__, None, None, None))
+                steps.append(client.aclose)
+                await _close_steps(*steps)
+        except BaseException as exc:
+            if failure is None:
+                raise
+            add_exception_notes(failure, "Stream cleanup failure", exc)

pytest_stream_lifecycle-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: pytest-stream-lifecycle
+Version: 0.1.0a1
+Summary: Real-network streaming and explicit cleanup assertions for ASGI tests
+Project-URL: Documentation, https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/api.md
+Project-URL: Source, https://github.com/shenxi200-eng/pytest-stream-lifecycle
+Project-URL: Issues, https://github.com/shenxi200-eng/pytest-stream-lifecycle/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,pytest,sse,streaming,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse<0.5,>=0.4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pytest<10,>=8
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: fastapi; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sse-starlette; extra == 'dev'
+Requires-Dist: starlette; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-stream-lifecycle
+
+Test streaming delivery and disconnect cleanup over real loopback HTTP.
+
+**Experimental alpha. Python 3.11+, asyncio.**
+No GPU, model API credentials, or external service is needed.
+
+## What it catches
+
+A final response-body assertion can pass even when every token was buffered.
+Closing a client can also leave a producer or upstream task running. This plugin
+provides:
+
+- `stream_server`: an ASGI app served by Uvicorn on a retained local socket.
+- `server.sse()` / `server.lines()`: bounded incremental reads over real HTTP/1.1.
+- `stream_probe`: explicit resource observations and cleanup acknowledgements.
+
+It is not a load tester, LLM evaluator, SSE parser, or general leak detector.
+The SSE parser is [httpx-sse](https://github.com/florimondmanca/httpx-sse).
+
+## Install
+
+Install the experimental alpha in your test environment:
+
+```sh
+python -m pip install pytest-stream-lifecycle==0.1.0a1
+```
+
+To install the current source instead:
+
+```sh
+python -m pip install 'git+https://github.com/shenxi200-eng/pytest-stream-lifecycle.git'
+```
+
+Maintainers can follow the [release checklist](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/releasing.md).
+
+For the example below, also install `fastapi` and `sse-starlette`. These are
+example/development dependencies, not plugin runtime requirements. Installation
+registers the pytest fixtures automatically; pytest-asyncio is not required.
+
+## Test delivery, then disconnect
+
+Save as `test_stream.py` and run `python -m pytest -q test_stream.py`:
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+from sse_starlette.sse import EventSourceResponse
+
+
+def test_disconnect(stream_server, stream_probe):
+    async def scenario():
+        app = FastAPI()
+        release = asyncio.Event()
+
+        async def tokens():
+            with stream_probe.track("producer") as observed:
+                try:
+                    yield {"event": "token", "data": "first"}
+                    await release.wait()
+                    yield {"event": "token", "data": "second"}
+                finally:
+                    # This synthetic producer owns no external resource.
+                    # In real code, await cleanup BEFORE marking it closed.
+                    observed.mark_closed()
+
+        @app.get("/events")
+        async def events():
+            # Listens for disconnects even while tokens() is waiting.
+            return EventSourceResponse(tokens())
+
+        async with stream_server(app) as server:
+            async with server.sse("/events") as stream:
+                assert (await stream.next()).data == "first"
+                stream_probe.assert_active("producer")
+            # Assert while the server is STILL RUNNING: its shutdown must
+            # not hide an application that ignores client disconnects.
+            await stream_probe.wait_closed("producer", timeout=2)
+            assert not release.is_set()
+
+    asyncio.run(scenario())
+```
+
+The first event must arrive before the release gate opens. Exiting the stream
+context disconnects the client; it does **not** assert server cleanup. The
+separate probe assertion checks that an observed producer exited and explicitly
+acknowledged cleanup without a non-cancellation error.
+
+For a real upstream, instrument its lifetime separately. Call `mark_closed()`
+only after the cleanup you intend to test has completed successfully. Leaving
+`track()` without that acknowledgement fails `wait_closed()`, even if the task
+has already exited. The marker is application-supplied evidence, not an
+independent guarantee that a remote provider stopped work or billing.
+
+## Executable comparisons
+
+```sh
+git clone https://github.com/shenxi200-eng/pytest-stream-lifecycle.git
+cd pytest-stream-lifecycle
+python -m venv .venv
+# Activate .venv using your shell's activation command.
+python -m pip install -e '.[dev]'
+python -m pytest examples/test_contracts.py -v
+python -m pytest -q
+```
+
+The examples compare a buffered implementation that passes a body-only test
+with a streaming contract that detects it. They also cover incremental delivery,
+20 sequential sessions, and a detached upstream that remains alive after the
+producer closes. Negative examples use `pytest.raises`: a passing test means
+the defect was **detected**, not that the intentionally broken app is correct.
+
+## Boundaries
+
+- Same-loop asyncio and loopback HTTP/1.1 only: not Trio, HTTP/2, TLS,
+  WebSockets, or browser/proxy emulation.
+- Resource observations are explicit. Unknown resources do not count as clean;
+  uninstrumented tasks are outside the probe's coverage.
+- Cleanup checks should run before server teardown. Server shutdown can itself
+  cancel request tasks and otherwise hide a broken disconnect handler.
+- An in-process server cannot forcibly kill code that blocks the event loop or
+  continually suppresses cancellation. Such apps need process isolation.
+- A local cleanup marker does not prove remote cancellation, GPU work cessation,
+  or a provider's billing state.
+
+See the [API guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/api.md), [design and related work](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/design.md), and
+[contribution guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/CONTRIBUTING.md). Development uses AI-assisted implementation
+and review; generated code and claims must be checked rather than treated as
+verification evidence. AI-assisted contributions have the same testing and review
+requirements as other contributions.

pytest_stream_lifecycle-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,11 @@
+pytest_stream_lifecycle/__init__.py,sha256=kgO-gFpj7iNalN9iKlX82BDHTB1nsE0QHam-vDiT-6k,242
+pytest_stream_lifecycle/_errors.py,sha256=Ktx53YwMxpbmoWLs4IuiZ7syqJ4A08IKuq4OnC_cGFA,806
+pytest_stream_lifecycle/plugin.py,sha256=lKgbzXIDCsBGfKZv72rAq4L9taWDzUdILsAONxGYUwM,387
+pytest_stream_lifecycle/probe.py,sha256=2Z0AuzniZyoe18puWwkdDTtIFjeRv3clL4hohQwxKno,5806
+pytest_stream_lifecycle/server.py,sha256=ZuLx2Wj-bwlCBQ44XaJBN5bmdVuS1GauJkIoBVazSUM,12740
+pytest_stream_lifecycle/streams.py,sha256=wKafYFo3CxO3GXTuddpv248U1LKXyeGokJQWkyRAzok,5731
+pytest_stream_lifecycle-0.1.0a1.dist-info/METADATA,sha256=VvY5JFuv2ls7_weTQpvuhsvuNF7rAkpG7IJPrsfxOH8,6902
+pytest_stream_lifecycle-0.1.0a1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pytest_stream_lifecycle-0.1.0a1.dist-info/entry_points.txt,sha256=v7toDewlwVbhOHcT6aYnMZQp8_608ofiVbeUZM3mZek,61
+pytest_stream_lifecycle-0.1.0a1.dist-info/licenses/LICENSE,sha256=tyLk9zlzElZ8PMQcbAoIHywEqffyuHtcSFDgh1cPagM,1070
+pytest_stream_lifecycle-0.1.0a1.dist-info/RECORD,,

pytest_stream_lifecycle-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_stream_lifecycle-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+stream_lifecycle = pytest_stream_lifecycle.plugin

pytest_stream_lifecycle-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenxi200-eng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.