feat(http-client-python): generate structured JSONL/SSE streaming

[Libba Lawrence (l0lawrence)]

Summary

• Generate Azure-flavor client methods that return Stream[T] / AsyncStream[T] for JSONL (application/jsonl) and SSE (text/event-stream) response streams.
• Use TCGC streamMetadata / sseMetadata to deserialize JSONL items and dispatch named SSE events to their concrete generated models, including terminal-event handling.
• Vendor the JSONL/SSE streaming runtime in generated packages while preserving unbranded raw-byte iterator behavior.
• Preserve registered stream item-type references across request overloads.

stream = client.receive()  # Stream[Thing]
for thing in stream:
    ...

Coverage

• Emitter structured-streaming tests https://github.com/microsoft/typespec/blob/main/packages/http-specs/specs/streaming/
• Pygen response and serializer coverage
• Azure JSONL/SSE regeneration
• Sync and async Spector smoke coverage for homogeneous and heterogeneous streams

Notes

This uses the TCGC prerelease containing sseMetadata. The external Azure mock API streaming test still asserts the previous raw-byte contract and is expected to remain failing until that test is aligned with the type-driven behavior.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-python@11594

commit: aa76c0d

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client-python

Show changes

@typespec/http-client-python - feature ✏️

Generate structured streaming client methods: operations whose HTTP response is a JSONL (application/jsonl) or SSE (text/event-stream) stream now return Stream[T] / AsyncStream[T], yielding deserialized model instances instead of raw bytes.,> ,> The Stream / AsyncStream runtime (plus the JSONL / SSE decoders) is vendored at _utils/streaming_base.py and depends only on the released core runtime for the flavor — azure.core.rest for the Azure flavor and corehttp.rest for the unbranded flavor. These types are an internal implementation detail and are not part of the package's public API.,> ,> python,> stream = client.receive(),> for thing in stream:,> ...,>

[github-actions]

Python emitter diff

Baseline gh:6f61820603610b1306e462942d86f0fdd17d789a vs this PR.

Diff summary: 22 file(s), +3330 / -352

Rendered diff: inline on the run summary, or the emitter-diff-html artifact.

Informational check (eng/emitter-diff); does not block the PR.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[Copilot]

Pull request overview

This PR adds structured streaming support to the TypeSpec Python emitter/generator for the Azure flavor, emitting client methods that return Stream[T] / AsyncStream[T] for JSONL (application/jsonl) and SSE (text/event-stream) responses, using TCGC streaming metadata to drive per-item deserialization and SSE event dispatch. It also vendors a small streaming runtime into generated packages to avoid requiring an unreleased azure.core.streaming dependency.

Changes:

• Emit a streaming block in response YAML for structured JSONL/SSE streams (including SSE event/terminal metadata) and preserve it across request overloads.
• Generate and write a vendored _utils/streaming_base.py runtime (Stream/AsyncStream + JSONL/SSE decoders) when needed, and update response/operation modeling + response handling to return Stream[T]/AsyncStream[T].
• Add emitter-side unit tests for structured-stream detection and update dependency versions to TCGC prereleases that expose sseMetadata.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/http-client-python/README.md	Documents structured streaming behavior for Azure flavor and the vendored runtime.
packages/http-client-python/package.json	Updates dev dependencies to prereleases and adds an npm overrides entry for compiler version alignment.
packages/http-client-python/package-lock.json	Locks new prerelease dependency resolutions used by the emitter/generator tests.
packages/http-client-python/generator/pygen/preprocess/init.py	Preserves streaming metadata across generated overload YAML updates.
packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2	Adds vendored streaming runtime template (Stream/AsyncStream + JSONL/SSE decoding).
packages/http-client-python/generator/pygen/codegen/serializers/general_serializer.py	Adds serializer for the new streaming runtime template.
packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py	Emits response handling that returns Stream/AsyncStream with per-item deserialization callbacks.
packages/http-client-python/generator/pygen/codegen/serializers/init.py	Writes _utils/streaming_base.py when structured streaming is present.
packages/http-client-python/generator/pygen/codegen/models/response.py	Models structured stream metadata, stream return annotations, and imports needed for generated operations.
packages/http-client-python/generator/pygen/codegen/models/operation.py	Forces stream=True for structured streaming operations and exposes a structured-stream predicate.
packages/http-client-python/generator/pygen/codegen/models/code_model.py	Tracks whether any structured streaming exists to decide if vendored runtime must be emitted.
packages/http-client-python/emitter/test/streaming.test.ts	Adds emitter unit tests for structured-stream detection and kind inference.
packages/http-client-python/emitter/src/http.ts	Emits response streaming YAML using TCGC stream/sse metadata; adds structured stream detection helpers.
cspell.yaml	Adds streaming/runtime-related identifiers to the spellchecker dictionary.
.chronus/changes/structured-streaming-2026-0-0.md	Changelog entry describing the new Azure-flavor structured streaming support.

Files not reviewed (1)

• packages/http-client-python/package-lock.json: Generated file

[iscai-msft]

overall design looks good, can you implement the spector streaming tests in the pr as well?

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• packages/http-client-python/package-lock.json: Generated file

Suppressed comments (3)

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:53

• The StreamDecoder/AsyncStreamDecoder docstrings reference DecodedType_co, but that TypeVar isn't defined (the type parameter is T_co). This looks like a vendoring typo and can confuse generated documentation/type readers; update the :rtype: lines to use T_co (or rename the TypeVar to match).

    def iter_events(self, iter_bytes: Iterator[bytes]) -> Iterator[T_co]:
        """Iterate over events from a byte iterator.

        :param iter_bytes: An iterator of byte chunks.
        :type iter_bytes: Iterator[bytes]
        :return: An iterator of decoded data.
        :rtype: Iterator[DecodedType_co]
        """

packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py:1276

• handle_structured_stream_response hardcodes _deserialize(...) for stream item deserialization, but other parts of the generator switch deserialization strategy based on models-mode (e.g., self._deserialize(...) for msrest, _deserialize/_deserialize_xml for dpg). As-is, structured streaming will fail or deserialize incorrectly when models-mode is not dpg. Consider reusing the existing response_deserialization strategy selection for stream items.

        retval.append("def _callback(_http_response, _event):")
        if response.streaming_kind == "sse":  # type: ignore[attr-defined]
            retval.append("    _event_json = json.loads(_event.data)")
            named_events = [
                (event_type, event_item_type)

packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py:1312

• In the structured streaming callback, cls is invoked with an empty headers dict ({}), even if the response has headers. This drops header values for callers relying on cls and is inconsistent with the non-streaming path which passes response_headers. If structured stream responses can have headers, compute response_headers once and pass it into cls(...) here.

        retval.append("    if cls:")
        retval.append("        return cls(pipeline_response, deserialized, {})  # type: ignore")
        retval.append("    return deserialized")

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• packages/http-client-python/package-lock.json: Generated file

Suppressed comments (4)

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:69

• AsyncStreamDecoder.aiter_events docstring uses :rtype: AsyncIterator[DecodedType_co], but DecodedType_co is not defined in this template (the type parameter is T_co). Update the docstring to match the actual type parameter to avoid confusing generated-package docs.

        :param iter_bytes: An asynchronous iterator of byte chunks.
        :type iter_bytes: AsyncIterator[bytes]
        :return: An asynchronous iterator of decoded data.
        :rtype: AsyncIterator[DecodedType_co]
        """

.chronus/changes/structured-streaming-2026-0-0.md:10

• The changelog states that Stream/AsyncStream are an internal implementation detail and not part of the public API, but the README and generated method signatures explicitly return Stream[T] / AsyncStream[T] and re-export these names from the package root. Please align the docs with the intended support policy (either treat them as public API, or avoid exposing/re-exporting them and avoid putting them in public signatures).

Generate structured streaming client methods: operations whose HTTP response is a JSONL (`application/jsonl`) or SSE (`text/event-stream`) stream now return `Stream[T]` / `AsyncStream[T]`, yielding deserialized model instances instead of raw bytes.

The `Stream` / `AsyncStream` runtime (plus the JSONL / SSE decoders) is vendored at `_utils/streaming_base.py` and depends only on the released core runtime for the flavor — `azure.core.rest` for the Azure flavor and `corehttp.rest` for the unbranded flavor. These types are an internal implementation detail and are not part of the package's public API.

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:52

• StreamDecoder.iter_events docstring uses :rtype: Iterator[DecodedType_co], but DecodedType_co is not defined in this template (the type parameter is T_co). Update the docstring to match the actual type parameter to avoid confusing generated-package docs.

        :param iter_bytes: An iterator of byte chunks.
        :type iter_bytes: Iterator[bytes]
        :return: An iterator of decoded data.
        :rtype: Iterator[DecodedType_co]
        """

packages/http-client-python/generator/pygen/codegen/models/response.py:136

• For SSE streams where terminal_event is derived from a string-literal member of the item union (fallback path), iteration stops before yielding that terminal marker. However, stream_item_type returns the full union (self.type), so the generated return type can still include the terminal literal even though it will never be yielded. Consider excluding the terminal-literal member from the stream item type/annotation when it is used only as the terminal marker.

    @property
    def stream_item_type(self) -> Optional[BaseType]:
        if len(self.streaming_events) == 1:
            return self.streaming_events[0][1]
        return self.type

[Yuchao Yan (msyyc)]

To fix #5778

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• packages/http-client-python/package-lock.json: Generated file

Suppressed comments (4)

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:53

• Docstring uses DecodedType_co in the :rtype: but that type variable is not defined (the protocol is parameterized by T_co). This looks like a stale name and can confuse readers/tools that validate docstrings.

        :param iter_bytes: An iterator of byte chunks.
        :type iter_bytes: Iterator[bytes]
        :return: An iterator of decoded data.
        :rtype: Iterator[DecodedType_co]
        """

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:69

• AsyncStreamDecoder docstring also references DecodedType_co in the :rtype: even though the protocol is parameterized by T_co and no DecodedType_co is defined.

        :param iter_bytes: An asynchronous iterator of byte chunks.
        :type iter_bytes: AsyncIterator[bytes]
        :return: An asynchronous iterator of decoded data.
        :rtype: AsyncIterator[DecodedType_co]
        """

packages/http-client-python/README.md:172

• README claims generated packages re-export Stream/AsyncStream from the base namespace, but the generator now explicitly tests that these types are not publicly exported (tests/unit/test_streaming_init.py:46-58), and the changelog entry states they are an internal implementation detail (.chronus/changes/structured-streaming-2026-0-0.md:9). Please update this section/example to avoid from your_sdk import Stream and describe the intended (non-public) access/typing story instead.

Generated packages re-export `Stream` and `AsyncStream` from their base namespace:

```python
from your_sdk import Stream
from your_sdk.models import Thing

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:179

• aiter_lines is an async generator over AsyncIterator[bytes], but the docstring still says :type iter_bytes: Iterator[bytes] and :rtype: Iterator[str]. Update these to the async equivalents to avoid misleading documentation.

    """Iterate over lines from a byte iterator.

    :param iter_bytes: An iterator of byte chunks.
    :type iter_bytes: Iterator[bytes]
    :rtype: Iterator[str]
    :return: An iterator of lines.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• packages/http-client-python/package-lock.json: Generated file

Suppressed comments (4)

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:70

• In the Protocol docstrings, the declared :rtype: references DecodedType_co, but that type variable isn’t defined in this module (the Protocol is parameterized by T_co). This is likely a copy/paste typo and can confuse generated docs/type readers; update the rtype to Iterator[T_co] / AsyncIterator[T_co] (or DecodedType if that’s what you intended).

@runtime_checkable
class StreamDecoder(Protocol[T_co]):
    """Protocol for stream decoders."""

    def iter_events(self, iter_bytes: Iterator[bytes]) -> Iterator[T_co]:
        """Iterate over events from a byte iterator.

        :param iter_bytes: An iterator of byte chunks.
        :type iter_bytes: Iterator[bytes]
        :return: An iterator of decoded data.
        :rtype: Iterator[DecodedType_co]
        """
        ...


@runtime_checkable
class AsyncStreamDecoder(Protocol[T_co]):
    """Protocol for async stream decoders."""

    # Why this isn't async def: https://mypy.readthedocs.io/en/stable/more_types.html#asynchronous-iterators
    def aiter_events(self, iter_bytes: AsyncIterator[bytes]) -> AsyncIterator[T_co]:
        """Asynchronously iterate over events from a byte iterator.

        :param iter_bytes: An asynchronous iterator of byte chunks.
        :type iter_bytes: AsyncIterator[bytes]
        :return: An asynchronous iterator of decoded data.
        :rtype: AsyncIterator[DecodedType_co]
        """
        ...

.chronus/changes/structured-streaming-2026-0-0.md:10

• This changelog entry states Stream/AsyncStream are “not part of the package's public API”, but the README documents importing Stream from the generated package’s base namespace. Please reconcile the public-API stance (either document them as public/semipublic, or adjust docs/tests to avoid advertising direct imports).

Generate structured streaming client methods: operations whose HTTP response is a JSONL (`application/jsonl`) or SSE (`text/event-stream`) stream now return `Stream[T]` / `AsyncStream[T]`, yielding deserialized model instances instead of raw bytes.

The `Stream` / `AsyncStream` runtime (plus the JSONL / SSE decoders) is vendored at `_utils/streaming_base.py` and depends only on the released core runtime for the flavor — `azure.core.rest` for the Azure flavor and `corehttp.rest` for the unbranded flavor. These types are an internal implementation detail and are not part of the package's public API.

packages/http-client-python/generator/pygen/codegen/templates/streaming_base.py.jinja2:12

• The header comment says this file is vendored from {{ code_model.core_library }}.streaming, but the README explicitly calls out that no azure.core.streaming runtime dependency is required. Consider rewording this comment to avoid implying that *.streaming is an existing/importable module (e.g., “vendored copy of the (unreleased) core streaming runtime”).

# --------------------------------------------------------------------------
# This file is vendored from the core streaming runtime
# ({{ code_model.core_library }}.streaming). It provides the Stream / AsyncStream
# helpers (plus the JSONL / SSE decoders and event types) used by generated
# structured-streaming operations, so the generated package does not take a hard
# dependency on a core runtime that ships the streaming helpers. Do not edit by hand.
# --------------------------------------------------------------------------

packages/http-client-python/README.md:176

• The README states generated packages re-export Stream/AsyncStream from the base namespace (from your_sdk import Stream), but the generator’s model_init.py.jinja2/rest_init.py.jinja2 templates currently only export clients/models/enums (no Stream/AsyncStream). Either implement the promised re-export in the generated package __init__.py files, or adjust this documentation (and any tests) to reflect that consumers must import from _utils.streaming_base.

Also, please reconcile this section with the changelog note that these types are “not part of the public API” if they are meant to be imported directly.

Generated packages re-export `Stream` and `AsyncStream` from their base namespace:

```python
from your_sdk import Stream
from your_sdk.models import Thing

stream: Stream[Thing] = client.receive()
for thing in stream:
    ...

The Stream / AsyncStream runtime (plus the JSONL and SSE decoders) is vendored into the generated package at _utils/streaming_base.py (alongside _utils/model_base.py). It depends only on the released core runtime for the flavor — azure.core.rest for the Azure flavor and corehttp.rest for the unbranded flavor — so no unreleased azure.core.streaming dependency is required at runtime.

SSE @events unions use TCGC event metadata to deserialize each named event into its corresponding generated model. Events marked with @terminalEvent stop iteration without being yielded.

</details>

[Libba Lawrence (l0lawrence)]

Can a terminal event carry data?

[Yuchao Yan (msyyc)]

Libba Lawrence (@l0lawrence) I looked into this from three angles:

1. The @typespec/sse docs define @terminalEvent as: "the presence of this event is a terminal event, and the client should disconnect from the server." The decorator has no parameter, so it marks a union variant as terminal rather than separately defining a stop value.

2. The @typespec/sse examples and the Spector cases model terminal events as string-literal payloads with text/plain content. For example:

@events
union ResponseEvents {
  @Events.contentType("application/json")
  responseDelta: ResponseDelta,

  @Events.contentType("text/plain")
  @terminalEvent
  "[DONE]",
}

and the expected wire response includes:

event: responseDelta
data: {"delta": "Hello"}

data: [DONE]

So yes, in the existing pattern the terminal event does carry data: the data: payload is the terminal sentinel ([DONE]). The client should use that event to stop iteration and should not yield it as a normal stream item.

3. The current PR implementation matches that string-sentinel interpretation. The emitter extracts a terminal value only if the terminal event payload/type is a string constant:

const terminalEventValue =
  getStringConstantValue(terminalEvent.payloadType) ??
  getStringConstantValue(terminalEvent.type);

and the generated runtime stops by comparing the decoded SSE event data to that string:

if self._terminal_event is not None and getattr(event, "data", None) == self._terminal_event:
    break

So my answer is: yes, terminal events can carry data in the supported Spector sense where the terminal event's data: payload is a string sentinel like [DONE]. What this PR does not currently support is a structured terminal payload, for example:

event: done
data: {"reason": "complete", "usage": 123}

For that case, we would need to decide different semantics: should the terminal event be yielded, should its payload be exposed somewhere, or should termination happen by event name regardless of payload? The current implementation filters terminal events out of the dispatch table and only preserves a string terminal_event marker, so structured terminal payloads are effectively out of scope unless we extend the metadata/runtime behavior.

NOTE: before we make update for the PR, it is better to make it clear whether we need a new spector case for this scenario. CC iscai-msft

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (3)

packages/http-client-python/generator/pygen/codegen/models/response.py:187

• The structured-stream docstring type reference (~{namespace}.Stream[...] / AsyncStream[...]) assumes Stream is re-exported from the generated package root, but the generator currently imports Stream/AsyncStream from _utils.streaming_base and the root __init__.py template doesn't re-export these symbols. Either add the intended re-export to the generated package root (and include it in __all__), or update docstring_type to reference the actual location (~{namespace}._utils.streaming_base.Stream[...]) to avoid broken Sphinx references.

        if self.is_structured_stream and self.type:
            stream_class = self.stream_class_name(kwargs.get("async_mode", False))
            item_type = (self.stream_item_type or self.type).docstring_type(**kwargs)
            return f"~{self.code_model.namespace}.{stream_class}[{item_type}]"

packages/http-client-python/README.md:172

• This section states that generated packages re-export Stream/AsyncStream from the base namespace, but the generator templates currently only vendor _utils/streaming_base.py and import the types from there (no root re-export). This also conflicts with the changelog note that these types are an internal implementation detail. Please either implement the re-export in the generated package root or adjust the README (and changelog wording) to match the actual public surface.

Operations whose HTTP response is a JSONL (`application/jsonl`) or SSE (`text/event-stream`) stream generate client methods that return `Stream[T]` (sync) / `AsyncStream[T]` (async), yielding deserialized model instances instead of raw bytes. This is driven by the TCGC response stream metadata (the response stream type) — there is no opt-in emitter option. This applies to both the Azure and unbranded flavors.

For an operation returning `JsonlStream<Thing>`, the generated method returns `Stream[Thing]` (sync) / `AsyncStream[Thing]` (async), yielding deserialized `Thing` instances as each JSONL line arrives. Similarly, `SSEStream<Events>` produces a `Stream` / `AsyncStream` over the SSE event payloads.

Generated packages re-export `Stream` and `AsyncStream` from their base namespace:

```python
from your_sdk import Stream
from your_sdk.models import Thing

stream: Stream[Thing] = client.receive()
for thing in stream:
    ...

**packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py:1309**
* `handle_structured_stream_response` always emits `_deserialize(...)` calls inside the per-event callback, but `_deserialize` is only imported/available in `models-mode: dpg`. In `models-mode: none` (and the legacy msrest path), this will raise `NameError` at runtime when consuming the stream. The callback generation should branch like `response_deserialization` does: use `self._deserialize(...)` for msrest, `_deserialize(...)` for dpg, and fall back to returning the parsed JSON value for `models-mode: none` / typed-dict-only cases.

                keyword = "if" if index == 0 else "elif"
                retval.append(f"    {keyword} _event.event == {event_type!r}:")
                retval.append(f"        deserialized = _deserialize({event_annotation}, _event_json)")
            retval.append("    else:")
            if len(unnamed_events) == 1:
                event_annotation = unnamed_events[0].type_annotation(
                    is_operation_file=True,
                    serialize_namespace=self.serialize_namespace,
                )
                retval.append(f"        deserialized = _deserialize({event_annotation}, _event_json)")
            else:
                retval.append("        deserialized = _event_json")
        elif len(unnamed_events) == 1:
            event_annotation = unnamed_events[0].type_annotation(
                is_operation_file=True,
                serialize_namespace=self.serialize_namespace,
            )
            retval.append(f"    deserialized = _deserialize({event_annotation}, _event_json)")
        else:
            retval.append(f"    deserialized = _deserialize({item_annotation}, _event_json)")
    else:
        retval.append("    _event_json = _event.json()")
        retval.append(f"    deserialized = _deserialize({item_annotation}, _event_json)")
    retval.append("    if cls:")
    retval.append("        return cls(pipeline_response, deserialized, {})  # type: ignore")
    retval.append("    return deserialized")

</details>

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

packages/http-client-python/generator/pygen/codegen/serializers/builder_serializer.py:1315

• cls is currently applied inside the per-event _callback, which means a user-provided cls will be invoked once per streamed event (and see individual items), rather than once for the operation result. This diverges from the existing cls contract used elsewhere in generated operations and makes it hard/impossible to customize the returned Stream itself.

        retval.append("    if cls:")
        retval.append("        return cls(pipeline_response, deserialized, {})  # type: ignore")
        retval.append("    return deserialized")
        retval.append("")
        stream_kwargs = ["response=response", "deserialization_callback=_callback"]

packages/http-client-python/README.md:176

• The README says generated packages re-export Stream/AsyncStream from the base namespace (from your_sdk import Stream), but the generator templates don't currently export these symbols from the package __init__.py (only clients are exported). Also, terminal-event behavior is more nuanced: named/model @terminalEvents are yielded then stop, while a bare sentinel like [DONE] stops without yielding.

Generated packages re-export `Stream` and `AsyncStream` from their base namespace:

```python
from your_sdk import Stream
from your_sdk.models import Thing

.chronus/changes/structured-streaming-2026-0-0.md:9

• This changelog entry says Stream/AsyncStream are not part of the public API, but the feature is explicitly a new return type for generated client methods. Even if the runtime is vendored, callers will depend on the Stream/AsyncStream surface (at least at runtime and in type hints), so this sentence is likely misleading.

The `Stream` / `AsyncStream` runtime (plus the JSONL / SSE decoders) is vendored at `_utils/streaming_base.py` and depends only on the released core runtime for the flavor — `azure.core.rest` for the Azure flavor and `corehttp.rest` for the unbranded flavor. These types are an internal implementation detail and are not part of the package's public API.