pyfect-dev 0.1.0__py3-none-any.whl

pyfect/http/static_server/__init__.py

@@ -0,0 +1,257 @@
+"""Serving files from a directory (Effect's ``HttpStaticServer``).
+
+``make(root=...)`` is an app serving the files below ``root``: a
+directory serves its ``index`` (redirecting to the path with a trailing
+``/`` first), byte ranges get ``206`` (``416`` when unsatisfiable),
+``If-None-Match`` / ``If-Modified-Since`` get ``304``, and with ``spa``
+an extensionless miss that accepts HTML serves the index. ``layer(...)``
+adds it to the ``HttpRouter`` as ``GET /*``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Never, NotRequired, TypedDict, Unpack
+from urllib.parse import urlsplit
+
+from pyfect._core import Effect
+from pyfect._js import decode_uri_component
+from pyfect.effect import fail, fn_untraced, succeed
+from pyfect.file_system import FileInfo, FileSystem, FileSystemService
+from pyfect.http.platform import HttpPlatform, HttpPlatformService
+from pyfect.http.router import HttpRouter
+from pyfect.http.server_error import HttpServerError, InternalError, RouteNotFound
+from pyfect.http.server_request import HttpServerRequest, ServerRequest
+from pyfect.http.server_respondable import to_response
+from pyfect.http.server_response import HttpServerResponse, empty, redirect
+from pyfect.http.static_server import _conditional
+from pyfect.http.static_server._mime import DEFAULT_MIME_TYPES, resolve_mime_type
+from pyfect.http.static_server._range import ByteRange, parse_range
+from pyfect.layer import Layer, effect_discard
+from pyfect.path import Path, PathService
+from pyfect.platform_error import NotFound, PlatformError
+
+type StaticApp = Effect[HttpServerResponse, HttpServerError, HttpServerRequest]
+
+_LEADING_SLASHES = re.compile(r"/+")
+_LEADING_SEPARATORS = re.compile(r"[/\\]+")
+
+
+class Options(TypedDict):
+    """``index`` (default ``"index.html"``; ``None``: directories are not
+    served), ``spa``, ``cache_control`` and extra ``mime_types`` (by
+    extension, without the dot)."""
+
+    root: str
+    index: NotRequired[str | None]
+    spa: NotRequired[bool]
+    cache_control: NotRequired[str]
+    mime_types: NotRequired[Mapping[str, str]]
+
+
+class LayerOptions(Options):
+    prefix: NotRequired[str]
+
+
+def _not_found(request: ServerRequest) -> HttpServerError:
+    return HttpServerError(RouteNotFound(request))
+
+
+def _internal(request: ServerRequest, cause: object) -> HttpServerError:
+    return HttpServerError(InternalError(request, cause=cause))
+
+
+def _platform_error(request: ServerRequest, error: PlatformError) -> HttpServerError:
+    return _not_found(request) if isinstance(error.reason, NotFound) else _internal(request, error)
+
+
+def _strip_query(url: str) -> str:
+    return url.partition("?")[0]
+
+
+def _resolve_file_path(path: PathService, root: str, url: str) -> str | None:
+    try:
+        decoded = decode_uri_component(_strip_query(url))
+    except ValueError:
+        return None
+    if "\x00" in decoded:
+        return None
+    # Every leading separator is part of the URL, not a filesystem root.
+    leading = _LEADING_SEPARATORS if path.sep == "\\" else _LEADING_SLASHES
+    return path.resolve_within(root, leading.sub("", decoded, count=1))
+
+
+def _accepts_html(accept: str | None) -> bool:
+    return accept is not None and "text/html" in accept.lower()
+
+
+@dataclass(frozen=True, slots=True)
+class _Server:
+    file_system: FileSystemService
+    path: PathService
+    platform: HttpPlatformService
+    root: str
+    index: str | None
+    spa: bool
+    cache_control: str | None
+    mime_types: Mapping[str, str]
+
+    def _with_file_headers(
+        self, response: HttpServerResponse, file_path: str
+    ) -> HttpServerResponse:
+        response = response.set_headers(
+            {
+                "Content-Type": resolve_mime_type(self.path, file_path, self.mime_types),
+                "Accept-Ranges": "bytes",
+            }
+        )
+        if self.cache_control is not None:
+            response = response.set_header("Cache-Control", self.cache_control)
+        return response
+
+    def _file_response(
+        self, request: ServerRequest, file_path: str, **file_options: Any
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        made: Effect[HttpServerResponse, PlatformError] = self.platform.file_response(
+            file_path, **file_options
+        )
+        return made.map_error(lambda error: _platform_error(request, error)).map(
+            lambda response: self._with_file_headers(response, file_path)
+        )
+
+    def _serve_range(
+        self, request: ServerRequest, file_path: str, file_size: int, header: str
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        parsed = parse_range(header, file_size)
+        if parsed is None:
+            return self._file_response(request, file_path)
+        if parsed == "unsatisfiable":
+            return succeed(empty(status=416, headers={"Content-Range": f"bytes */{file_size}"}))
+        byte_range: ByteRange = parsed
+        content_range = f"bytes {byte_range.start}-{byte_range.end}/{file_size}"
+        return self._file_response(
+            request,
+            file_path,
+            status=206,
+            offset=byte_range.start,
+            bytes_to_read=byte_range.end - byte_range.start + 1,
+        ).map(lambda response: response.set_header("Content-Range", content_range))
+
+    @fn_untraced
+    def serve_file(self, request: ServerRequest, file_path: str, file_size: int | None = None):
+        range_header = request.headers.get("range") if request.method == "GET" else None
+        full: HttpServerResponse | None = None
+        headers = request.headers
+        if headers.get("if-none-match") is not None or headers.get("if-modified-since") is not None:
+            full = yield from self._file_response(request, file_path)
+            not_modified = _conditional.evaluate(request, full)
+            if not_modified is not None:
+                return not_modified
+        if range_header is None:
+            return (
+                full if full is not None else (yield from self._file_response(request, file_path))
+            )
+        if_range = headers.get("if-range")
+        if if_range is not None:
+            if full is None:
+                full = yield from self._file_response(request, file_path)
+            if not _conditional.matches_if_range(if_range, full.headers.get("etag")):
+                return full
+        if file_size is None:
+            info = yield from self.file_system.stat(file_path).map_error(
+                lambda error: _platform_error(request, error)
+            )
+            file_size = int(info.size)
+        if full is not None and parse_range(range_header, file_size) is None:
+            return full
+        return (yield from self._serve_range(request, file_path, file_size, range_header))
+
+    def _serve_directory(
+        self, request: ServerRequest, directory: str, index: str
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        original_url = request.original_url
+        if not original_url.startswith("/"):
+            parts = urlsplit(original_url)
+            original_url = parts.path + (f"?{parts.query}" if parts.query else "")
+        pathname = _strip_query(original_url)
+        if not pathname.endswith("/"):
+            # Keep the redirect local even when the path starts with several slashes.
+            location = _LEADING_SLASHES.sub("/", pathname, count=1).replace("\\", "%5C")
+            return succeed(redirect(f"{location}/{original_url[len(pathname) :]}", status=301))
+        return self.serve_file(request, self.path.join(directory, index))
+
+    def _on_stat_error(
+        self, request: ServerRequest, resolved: str, error: PlatformError
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        if not isinstance(error.reason, NotFound):
+            return fail(_internal(request, error))
+        if (
+            self.spa
+            and self.index is not None
+            and self.path.extname(resolved) == ""
+            and _accepts_html(request.headers.get("accept"))
+        ):
+            return self.serve_file(request, self.path.join(self.root, self.index))
+        return fail(_not_found(request))
+
+    def _on_info(
+        self, request: ServerRequest, resolved: str, info: FileInfo
+    ) -> Effect[HttpServerResponse, HttpServerError]:
+        if info.type == "File":
+            return self.serve_file(request, resolved, int(info.size))
+        if info.type == "Directory" and self.index is not None:
+            return self._serve_directory(request, resolved, self.index)
+        return fail(_not_found(request))
+
+    def handle(self, request: ServerRequest) -> Effect[HttpServerResponse, HttpServerError]:
+        resolved = _resolve_file_path(self.path, self.root, request.url)
+        if resolved is None:
+            return fail(_not_found(request))
+        found = resolved
+        return self.file_system.stat(found).match_effect(
+            on_failure=lambda error: self._on_stat_error(request, found, error),
+            on_success=lambda info: self._on_info(request, found, info),
+        )
+
+
+@fn_untraced
+def make(**options: Unpack[Options]):
+    """The app serving ``options["root"]`` (see the module docs)."""
+    file_system = yield from FileSystem()
+    path = yield from Path()
+    platform = yield from HttpPlatform()
+    server = _Server(
+        file_system,
+        path,
+        platform,
+        path.resolve(options["root"]),
+        options.get("index", "index.html"),
+        options.get("spa", False),
+        options.get("cache_control"),
+        {**DEFAULT_MIME_TYPES, **options.get("mime_types", {})},
+    )
+    app: StaticApp = HttpServerRequest().flat_map(server.handle)
+    return app
+
+
+def layer(
+    **options: Unpack[LayerOptions],
+) -> Layer[Never, PlatformError, HttpRouter | FileSystem | Path | HttpPlatform]:
+    """``make(...)`` added to the ``HttpRouter`` as ``GET /*`` (under
+    ``prefix`` when given), its errors answered as their responses."""
+    prefix = options.pop("prefix", None)
+
+    @fn_untraced
+    def build():
+        router = yield from HttpRouter()
+        app: StaticApp = yield from make(**options)
+        handler = app.catch_all(to_response)
+        target = router if prefix is None else router.prefixed(prefix)
+        yield from target.add("GET", "/*", handler)
+
+    return effect_discard(build())
+
+
+__all__ = ["LayerOptions", "Options", "StaticApp", "layer", "make"]

pyfect/http/static_server/_conditional.py

@@ -0,0 +1,72 @@
+"""Conditional requests (RFC 9110 §13): ``If-None-Match``,
+``If-Modified-Since`` and ``If-Range`` against a file response."""
+
+from __future__ import annotations
+
+import re
+
+from pyfect.http.headers import parse_http_date
+from pyfect.http.server_request import ServerRequest
+from pyfect.http.server_response import HttpServerResponse, empty
+from pyfect.result import Ok
+
+_WEAK = re.compile(r"w/", re.IGNORECASE)
+
+
+def _strip_weak(value: str) -> str:
+    trimmed = value.strip()
+    return trimmed[2:] if _WEAK.match(trimmed) else trimmed
+
+
+def _matches_if_none_match(if_none_match: str, etag: str | None) -> bool:
+    normalized = None if etag is None else _strip_weak(etag)
+    for candidate in if_none_match.split(","):
+        value = candidate.strip()
+        if value == "":
+            continue
+        if value == "*" or (normalized is not None and _strip_weak(value) == normalized):
+            return True
+    return False
+
+
+def _not_modified_since(if_modified_since: str, last_modified: str | None) -> bool:
+    """An invalid date on either side disables the precondition."""
+    if last_modified is None:
+        return False
+    since = parse_http_date(if_modified_since)
+    modified = parse_http_date(last_modified)
+    return isinstance(since, Ok) and isinstance(modified, Ok) and modified.value <= since.value
+
+
+def matches_if_range(if_range: str, etag: str | None) -> bool:
+    """Only a strong entity-tag matches: weak tags start with ``W/``, and
+    dates never match, as file metadata cannot prove the file did not
+    change twice within a second."""
+    value = if_range.strip()
+    return value.startswith('"') and value == etag
+
+
+def _not_modified(response: HttpServerResponse) -> HttpServerResponse:
+    kept = {
+        name: value
+        for name, value in (
+            ("ETag", response.headers.get("etag")),
+            ("Cache-Control", response.headers.get("cache-control")),
+            ("Last-Modified", response.headers.get("last-modified")),
+        )
+        if value is not None
+    }
+    return empty(status=304, headers=kept)
+
+
+def evaluate(request: ServerRequest, response: HttpServerResponse) -> HttpServerResponse | None:
+    """The ``304`` the request's preconditions call for, if any."""
+    if_none_match = request.headers.get("if-none-match")
+    if if_none_match is not None:
+        etag = response.headers.get("etag")
+        return _not_modified(response) if _matches_if_none_match(if_none_match, etag) else None
+    if_modified_since = request.headers.get("if-modified-since")
+    last_modified = response.headers.get("last-modified")
+    if if_modified_since is not None and _not_modified_since(if_modified_since, last_modified):
+        return _not_modified(response)
+    return None

pyfect/http/static_server/_mime.py

@@ -0,0 +1,55 @@
+"""The content types of file extensions a static server knows."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pyfect.path import PathService
+
+DEFAULT_MIME_TYPES: Mapping[str, str] = {
+    "html": "text/html; charset=utf-8",
+    "htm": "text/html; charset=utf-8",
+    "css": "text/css; charset=utf-8",
+    "js": "text/javascript; charset=utf-8",
+    "mjs": "text/javascript; charset=utf-8",
+    "json": "application/json; charset=utf-8",
+    "xml": "application/xml; charset=utf-8",
+    "txt": "text/plain; charset=utf-8",
+    "csv": "text/csv; charset=utf-8",
+    "md": "text/markdown; charset=utf-8",
+    "yaml": "text/yaml; charset=utf-8",
+    "yml": "text/yaml; charset=utf-8",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "svg": "image/svg+xml; charset=utf-8",
+    "ico": "image/x-icon",
+    "webp": "image/webp",
+    "avif": "image/avif",
+    "woff": "font/woff",
+    "woff2": "font/woff2",
+    "ttf": "font/ttf",
+    "otf": "font/otf",
+    "eot": "application/vnd.ms-fontobject",
+    "mp3": "audio/mpeg",
+    "mp4": "video/mp4",
+    "webm": "video/webm",
+    "ogg": "audio/ogg",
+    "wav": "audio/wav",
+    "flac": "audio/flac",
+    "aac": "audio/aac",
+    "pdf": "application/pdf",
+    "zip": "application/zip",
+    "gz": "application/gzip",
+    "wasm": "application/wasm",
+    "map": "application/json",
+    "webmanifest": "application/manifest+json",
+}
+
+
+def resolve_mime_type(path: PathService, file_path: str, mime_types: Mapping[str, str]) -> str:
+    extension = path.extname(file_path).lower()
+    if len(extension) <= 1:
+        return "application/octet-stream"
+    return mime_types.get(extension[1:], "application/octet-stream")

pyfect/http/static_server/_range.py

@@ -0,0 +1,53 @@
+"""``Range: bytes=...`` headers (one range; several are served whole)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from pyfect._digits import parse_digits
+
+
+@dataclass(frozen=True, slots=True)
+class ByteRange:
+    """The inclusive byte range ``start``..``end``."""
+
+    start: int
+    end: int
+
+
+def _integer(value: str) -> int | None:
+    return parse_digits(value)
+
+
+def parse_range(header: str, file_size: int) -> ByteRange | Literal["unsatisfiable"] | None:  # noqa: PLR0911
+    """The range ``header`` asks for of a ``file_size``-byte file; ``None``
+    when the header is not one byte range (the file is served whole)."""
+    value = header.strip()
+    if not value.lower().startswith("bytes="):
+        return None
+    range_value = value[6:].strip()
+    if range_value == "" or "," in range_value or "-" not in range_value:
+        return None
+    start_part, _, end_part = range_value.partition("-")
+    start_part, end_part = start_part.strip(), end_part.strip()
+    if start_part == "" and end_part == "":
+        return None
+    if start_part == "":
+        suffix = _integer(end_part)
+        if suffix is None:
+            return None
+        if suffix == 0 or file_size == 0:
+            return "unsatisfiable"
+        return ByteRange(max(file_size - suffix, 0), file_size - 1)
+    start = _integer(start_part)
+    if start is None:
+        return None
+    if end_part == "":
+        return "unsatisfiable" if start >= file_size else ByteRange(start, file_size - 1)
+    end = _integer(end_part)
+    if end is None:
+        return None
+    if start > end or start >= file_size:
+        return "unsatisfiable"
+    return ByteRange(start, min(end, file_size - 1))

pyfect/http/status.py

@@ -0,0 +1,51 @@
+"""HTTP status codes by name (Effect's ``HttpStatus``)."""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+type StatusLiteral = Literal[
+    "Continue", "SwitchingProtocols", "Processing", "EarlyHints", "OK", "Ok", "Created",
+    "Accepted", "NonAuthoritativeInformation", "NoContent", "ResetContent", "PartialContent",
+    "MultiStatus", "AlreadyReported", "ImUsed", "MultipleChoices", "MovedPermanently", "Found",
+    "SeeOther", "NotModified", "TemporaryRedirect", "PermanentRedirect", "BadRequest",
+    "Unauthorized", "PaymentRequired", "Forbidden", "NotFound", "MethodNotAllowed",
+    "NotAcceptable", "ProxyAuthenticationRequired", "RequestTimeout", "Conflict", "Gone",
+    "LengthRequired", "PreconditionFailed", "PayloadTooLarge", "UriTooLong",
+    "UnsupportedMediaType", "RangeNotSatisfiable", "ExpectationFailed", "ImATeapot",
+    "MisdirectedRequest", "UnprocessableEntity", "Locked", "FailedDependency", "TooEarly",
+    "UpgradeRequired", "PreconditionRequired", "TooManyRequests",
+    "RequestHeaderFieldsTooLarge", "UnavailableForLegalReasons", "InternalServerError",
+    "NotImplemented", "BadGateway", "ServiceUnavailable", "GatewayTimeout",
+    "HttpVersionNotSupported", "VariantAlsoNegotiates", "InsufficientStorage", "LoopDetected",
+    "NotExtended", "NetworkAuthenticationRequired",
+]  # fmt: skip
+
+CODE_BY_LITERAL: Final[dict[StatusLiteral, int]] = {
+    "Continue": 100, "SwitchingProtocols": 101, "Processing": 102, "EarlyHints": 103,
+    "OK": 200, "Ok": 200, "Created": 201, "Accepted": 202, "NonAuthoritativeInformation": 203,
+    "NoContent": 204, "ResetContent": 205, "PartialContent": 206, "MultiStatus": 207,
+    "AlreadyReported": 208, "ImUsed": 226, "MultipleChoices": 300, "MovedPermanently": 301,
+    "Found": 302, "SeeOther": 303, "NotModified": 304, "TemporaryRedirect": 307,
+    "PermanentRedirect": 308, "BadRequest": 400, "Unauthorized": 401, "PaymentRequired": 402,
+    "Forbidden": 403, "NotFound": 404, "MethodNotAllowed": 405, "NotAcceptable": 406,
+    "ProxyAuthenticationRequired": 407, "RequestTimeout": 408, "Conflict": 409, "Gone": 410,
+    "LengthRequired": 411, "PreconditionFailed": 412, "PayloadTooLarge": 413,
+    "UriTooLong": 414, "UnsupportedMediaType": 415, "RangeNotSatisfiable": 416,
+    "ExpectationFailed": 417, "ImATeapot": 418, "MisdirectedRequest": 421,
+    "UnprocessableEntity": 422, "Locked": 423, "FailedDependency": 424, "TooEarly": 425,
+    "UpgradeRequired": 426, "PreconditionRequired": 428, "TooManyRequests": 429,
+    "RequestHeaderFieldsTooLarge": 431, "UnavailableForLegalReasons": 451,
+    "InternalServerError": 500, "NotImplemented": 501, "BadGateway": 502,
+    "ServiceUnavailable": 503, "GatewayTimeout": 504, "HttpVersionNotSupported": 505,
+    "VariantAlsoNegotiates": 506, "InsufficientStorage": 507, "LoopDetected": 508,
+    "NotExtended": 510, "NetworkAuthenticationRequired": 511,
+}  # fmt: skip
+
+
+def from_literal(literal: StatusLiteral) -> int:
+    """The status code named ``literal`` (``"NotFound"`` is 404)."""
+    return CODE_BY_LITERAL[literal]
+
+
+__all__ = ["CODE_BY_LITERAL", "StatusLiteral", "from_literal"]

pyfect/http/template.py

@@ -0,0 +1,161 @@
+"""Text templates whose interpolations may be effects or streams (Effect's
+``Template``), for HTML responses.
+
+A template is its literal strings and the values between them, as a tagged
+template literal gives them; on Python 3.14 a t-string is one too::
+
+    template.make(["<p>Hello, ", "!</p>"], current_user_name)
+    template.make(t"<p>Hello, {current_user_name}!</p>")   # Python 3.14
+
+A value is a primitive (``str``, ``int``, ``float``, ``bool``; ``None``
+renders as nothing; a sequence renders its items joined), a ``Some``, or an
+effect of one. ``stream`` also takes streams, and writes each part as soon
+as it is known. Effects run concurrently.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Never, Protocol, cast, overload
+
+from pyfect._concurrency import for_each
+from pyfect._core import Effect
+from pyfect._js import js_number
+from pyfect.effect import succeed
+from pyfect.option import Some
+from pyfect.stream import Stream, from_iterable
+from pyfect.stream import succeed as succeed_stream
+
+type PrimitiveValue = str | int | float | bool | None
+type Primitive = PrimitiveValue | Sequence[PrimitiveValue]
+type Interpolated[E = Never, R = Never] = Primitive | Some[Primitive] | Effect[Primitive, E, R]
+type InterpolatedWithStream[E = Never, R = Never] = Interpolated[E, R] | Stream[Primitive, E, R]
+
+
+class _Interpolation(Protocol):
+    @property
+    def value(self) -> object: ...
+
+
+class TemplateLike(Protocol):
+    """Python 3.14's ``string.templatelib.Template`` (a t-string)."""
+
+    @property
+    def strings(self) -> tuple[str, ...]: ...
+    @property
+    def interpolations(self) -> tuple[_Interpolation, ...]: ...
+
+
+def primitive_to_string(value: Primitive) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return js_number(value)
+    if value is None:
+        return ""
+    return "".join(primitive_to_string(item) for item in value)
+
+
+def _parts(
+    strings: Sequence[str] | TemplateLike, args: tuple[object, ...]
+) -> tuple[Sequence[str], tuple[object, ...]]:
+    if isinstance(strings, Sequence):
+        return strings, args
+    return strings.strings, tuple(i.value for i in strings.interpolations)
+
+
+def _consolidate(strings: Sequence[str], values: list[str]) -> str:
+    out = [part for pair in zip(strings, values, strict=False) for part in pair]
+    return "".join(out) + strings[-1]
+
+
+@overload
+def make(strings: TemplateLike, /) -> Effect[str, Any, Any]: ...
+@overload
+def make[EE = Never, RR = Never](
+    strings: Sequence[str], /, *args: Interpolated[EE, RR]
+) -> Effect[str, EE, RR]: ...
+def make(strings: Sequence[str] | TemplateLike, /, *args: object) -> Effect[str, Any, Any]:
+    """The text of the template, after running its effects concurrently.
+    ``strings`` holds one more string than there are ``args``."""
+    texts, values = _parts(strings, args)
+    rendered = [""] * len(values)
+    effects: list[tuple[int, Effect[Primitive, Any, Any]]] = []
+    for index, value in enumerate(values):
+        if isinstance(value, Some):
+            rendered[index] = primitive_to_string(cast("Some[Primitive]", value).value)
+        elif isinstance(value, Effect):
+            effects.append((index, cast("Effect[Primitive, Any, Any]", value)))
+        else:
+            rendered[index] = primitive_to_string(cast("Primitive", value))
+    if not effects:
+        return succeed(_consolidate(texts, rendered))
+
+    def run(entry: tuple[int, Effect[Primitive, Any, Any]]) -> Effect[None, Any, Any]:
+        index, effect = entry
+
+        def store(value: Primitive) -> None:
+            rendered[index] = primitive_to_string(value)
+
+        return effect.map(store)
+
+    return for_each(effects, run, concurrency="unbounded").map(
+        lambda _: _consolidate(texts, rendered)
+    )
+
+
+type _Chunk = str | Effect[str, Any, Any] | Stream[str, Any, Any]
+
+
+@overload
+def stream(strings: TemplateLike, /) -> Stream[str, Any, Any]: ...
+@overload
+def stream[EE = Never, RR = Never](
+    strings: Sequence[str], /, *args: InterpolatedWithStream[EE, RR]
+) -> Stream[str, EE, RR]: ...
+def stream(strings: Sequence[str] | TemplateLike, /, *args: object) -> Stream[str, Any, Any]:
+    """The template's text as it is known, in order: literal text and plain
+    values at once, effects (run concurrently) and streams in their
+    place."""
+    texts, values = _parts(strings, args)
+    chunks: list[_Chunk] = []
+    buffer = ""
+    for index, value in enumerate(values):
+        buffer += texts[index]
+        if isinstance(value, Some):
+            buffer += primitive_to_string(cast("Some[Primitive]", value).value)
+        elif isinstance(value, Effect | Stream):
+            if buffer:
+                chunks.append(buffer)
+                buffer = ""
+            if isinstance(value, Effect):
+                chunks.append(cast("Effect[Primitive, Any, Any]", value).map(primitive_to_string))
+            else:
+                chunks.append(cast("Stream[Primitive, Any, Any]", value).map(primitive_to_string))
+        else:
+            buffer += primitive_to_string(cast("Primitive", value))
+    buffer += texts[-1]
+    if buffer:
+        chunks.append(buffer)
+
+    def evaluate(chunk: _Chunk) -> Effect[str | Stream[str, Any, Any], Any, Any]:
+        return chunk if isinstance(chunk, Effect) else succeed(chunk)
+
+    def expand(chunk: str | Stream[str, Any, Any]) -> Stream[str, Any, Any]:
+        return succeed_stream(chunk) if isinstance(chunk, str) else chunk
+
+    return from_iterable(chunks).map_effect(evaluate, concurrency="unbounded").flat_map(expand)
+
+
+__all__ = [
+    "Interpolated",
+    "InterpolatedWithStream",
+    "Primitive",
+    "PrimitiveValue",
+    "TemplateLike",
+    "make",
+    "primitive_to_string",
+    "stream",
+]