Module spin_sdk.wit.imports.streams

WASI I/O is an I/O abstraction API which is currently focused on providing stream types.

In the future, the component model is expected to add built-in stream types; when it does, they are expected to subsume this API.

"""
WASI I/O is an I/O abstraction API which is currently focused on providing
stream types.

In the future, the component model is expected to add built-in stream types;
when it does, they are expected to subsume this API.
"""
from typing import TypeVar, Generic, Union, Optional, Union, Protocol, Tuple, List, Any, Self
from enum import Flag, Enum, auto
from dataclasses import dataclass
from abc import abstractmethod
import weakref

from ..types import Result, Ok, Err, Some
from ..imports import poll
from ..imports import error


@dataclass
class StreamErrorLastOperationFailed:
    value: error.Error


@dataclass
class StreamErrorClosed:
    pass


StreamError = Union[StreamErrorLastOperationFailed, StreamErrorClosed]
"""
An error for input-stream and output-stream operations.
"""


class InputStream:
    """
    An input bytestream.
    
    `input-stream`s are *non-blocking* to the extent practical on underlying
    platforms. I/O operations always return promptly; if fewer bytes are
    promptly available than requested, they return the number of bytes promptly
    available, which could even be zero. To wait for data to be available,
    use the `subscribe` function to obtain a `pollable` which can be polled
    for using `wasi:io/poll`.
    """
    
    def read(self, len: int) -> bytes:
        """
        Perform a non-blocking read from the stream.
        
        When the source of a `read` is binary data, the bytes from the source
        are returned verbatim. When the source of a `read` is known to the
        implementation to be text, bytes containing the UTF-8 encoding of the
        text are returned.
        
        This function returns a list of bytes containing the read data,
        when successful. The returned list will contain up to `len` bytes;
        it may return fewer than requested, but not more. The list is
        empty when no bytes are available for reading at this time. The
        pollable given by `subscribe` will be ready when more bytes are
        available.
        
        This function fails with a `stream-error` when the operation
        encounters an error, giving `last-operation-failed`, or when the
        stream is closed, giving `closed`.
        
        When the caller gives a `len` of 0, it represents a request to
        read 0 bytes. If the stream is still open, this call should
        succeed and return an empty list, or otherwise fail with `closed`.
        
        The `len` parameter is a `u64`, which could represent a list of u8 which
        is not possible to allocate in wasm32, or not desirable to allocate as
        as a return value by the callee. The callee may return a list of bytes
        less than `len` in size while more bytes are available for reading.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_read(self, len: int) -> bytes:
        """
        Read bytes from a stream, after blocking until at least one byte can
        be read. Except for blocking, behavior is identical to `read`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def skip(self, len: int) -> int:
        """
        Skip bytes from a stream. Returns number of bytes skipped.
        
        Behaves identical to `read`, except instead of returning a list
        of bytes, returns the number of bytes consumed from the stream.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_skip(self, len: int) -> int:
        """
        Skip bytes from a stream, after blocking until at least one byte
        can be skipped. Except for blocking behavior, identical to `skip`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def subscribe(self) -> poll.Pollable:
        """
        Create a `pollable` which will resolve once either the specified stream
        has bytes available to read or the other end of the stream has been
        closed.
        The created `pollable` is a child resource of the `input-stream`.
        Implementations may trap if the `input-stream` is dropped before
        all derived `pollable`s created with this function are dropped.
        """
        raise NotImplementedError

    def __enter__(self):
        """Returns self"""
        return self
                                                                    
    def __exit__(self, *args):
        """
        Release this resource.
        """
        raise NotImplementedError


class OutputStream:
    """
    An output bytestream.
    
    `output-stream`s are *non-blocking* to the extent practical on
    underlying platforms. Except where specified otherwise, I/O operations also
    always return promptly, after the number of bytes that can be written
    promptly, which could even be zero. To wait for the stream to be ready to
    accept data, the `subscribe` function to obtain a `pollable` which can be
    polled for using `wasi:io/poll`.
    """
    
    def check_write(self) -> int:
        """
        Check readiness for writing. This function never blocks.
        
        Returns the number of bytes permitted for the next call to `write`,
        or an error. Calling `write` with more bytes than this function has
        permitted will trap.
        
        When this function returns 0 bytes, the `subscribe` pollable will
        become ready when this function will report at least 1 byte, or an
        error.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def write(self, contents: bytes) -> None:
        """
        Perform a write. This function never blocks.
        
        When the destination of a `write` is binary data, the bytes from
        `contents` are written verbatim. When the destination of a `write` is
        known to the implementation to be text, the bytes of `contents` are
        transcoded from UTF-8 into the encoding of the destination and then
        written.
        
        Precondition: check-write gave permit of Ok(n) and contents has a
        length of less than or equal to n. Otherwise, this function will trap.
        
        returns Err(closed) without writing if the stream has closed since
        the last call to check-write provided a permit.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_write_and_flush(self, contents: bytes) -> None:
        """
        Perform a write of up to 4096 bytes, and then flush the stream. Block
        until all of these operations are complete, or an error occurs.
        
        This is a convenience wrapper around the use of `check-write`,
        `subscribe`, `write`, and `flush`, and is implemented with the
        following pseudo-code:
        
        ```text
        let pollable = this.subscribe();
        while !contents.is_empty() {
        // Wait for the stream to become writable
        pollable.block();
        let Ok(n) = this.check-write(); // eliding error handling
        let len = min(n, contents.len());
        let (chunk, rest) = contents.split_at(len);
        this.write(chunk  );            // eliding error handling
        contents = rest;
        }
        this.flush();
        // Wait for completion of `flush`
        pollable.block();
        // Check for any errors that arose during `flush`
        let _ = this.check-write();         // eliding error handling
        ```
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def flush(self) -> None:
        """
        Request to flush buffered output. This function never blocks.
        
        This tells the output-stream that the caller intends any buffered
        output to be flushed. the output which is expected to be flushed
        is all that has been passed to `write` prior to this call.
        
        Upon calling this function, the `output-stream` will not accept any
        writes (`check-write` will return `ok(0)`) until the flush has
        completed. The `subscribe` pollable will become ready when the
        flush has completed and the stream can accept more writes.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_flush(self) -> None:
        """
        Request to flush buffered output, and block until flush completes
        and stream is ready for writing again.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def subscribe(self) -> poll.Pollable:
        """
        Create a `pollable` which will resolve once the output-stream
        is ready for more writing, or an error has occured. When this
        pollable is ready, `check-write` will return `ok(n)` with n>0, or an
        error.
        
        If the stream is closed, this pollable is always ready immediately.
        
        The created `pollable` is a child resource of the `output-stream`.
        Implementations may trap if the `output-stream` is dropped before
        all derived `pollable`s created with this function are dropped.
        """
        raise NotImplementedError

    def write_zeroes(self, len: int) -> None:
        """
        Write zeroes to a stream.
        
        This should be used precisely like `write` with the exact same
        preconditions (must use check-write first), but instead of
        passing a list of bytes, you simply pass the number of zero-bytes
        that should be written.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_write_zeroes_and_flush(self, len: int) -> None:
        """
        Perform a write of up to 4096 zeroes, and then flush the stream.
        Block until all of these operations are complete, or an error
        occurs.
        
        This is a convenience wrapper around the use of `check-write`,
        `subscribe`, `write-zeroes`, and `flush`, and is implemented with
        the following pseudo-code:
        
        ```text
        let pollable = this.subscribe();
        while num_zeroes != 0 {
        // Wait for the stream to become writable
        pollable.block();
        let Ok(n) = this.check-write(); // eliding error handling
        let len = min(n, num_zeroes);
        this.write-zeroes(len);         // eliding error handling
        num_zeroes -= len;
        }
        this.flush();
        // Wait for completion of `flush`
        pollable.block();
        // Check for any errors that arose during `flush`
        let _ = this.check-write();         // eliding error handling
        ```
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def splice(self, src: InputStream, len: int) -> int:
        """
        Read from one stream and write to another.
        
        The behavior of splice is equivelant to:
        1. calling `check-write` on the `output-stream`
        2. calling `read` on the `input-stream` with the smaller of the
        `check-write` permitted length and the `len` provided to `splice`
        3. calling `write` on the `output-stream` with that read data.
        
        Any error reported by the call to `check-write`, `read`, or
        `write` ends the splice and reports that error.
        
        This function returns the number of bytes transferred; it may be less
        than `len`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_splice(self, src: InputStream, len: int) -> int:
        """
        Read from one stream and write to another, with blocking.
        
        This is similar to `splice`, except that it blocks until the
        `output-stream` is ready for writing, and the `input-stream`
        is ready for reading, before performing the `splice`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def __enter__(self):
        """Returns self"""
        return self
                                                                    
    def __exit__(self, *args):
        """
        Release this resource.
        """
        raise NotImplementedError

Global variables

var StreamError

An error for input-stream and output-stream operations.

Classes

class InputStream

An input bytestream.

input-streams are non-blocking to the extent practical on underlying platforms. I/O operations always return promptly; if fewer bytes are promptly available than requested, they return the number of bytes promptly available, which could even be zero. To wait for data to be available, use the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

Expand source code

class InputStream:
    """
    An input bytestream.
    
    `input-stream`s are *non-blocking* to the extent practical on underlying
    platforms. I/O operations always return promptly; if fewer bytes are
    promptly available than requested, they return the number of bytes promptly
    available, which could even be zero. To wait for data to be available,
    use the `subscribe` function to obtain a `pollable` which can be polled
    for using `wasi:io/poll`.
    """
    
    def read(self, len: int) -> bytes:
        """
        Perform a non-blocking read from the stream.
        
        When the source of a `read` is binary data, the bytes from the source
        are returned verbatim. When the source of a `read` is known to the
        implementation to be text, bytes containing the UTF-8 encoding of the
        text are returned.
        
        This function returns a list of bytes containing the read data,
        when successful. The returned list will contain up to `len` bytes;
        it may return fewer than requested, but not more. The list is
        empty when no bytes are available for reading at this time. The
        pollable given by `subscribe` will be ready when more bytes are
        available.
        
        This function fails with a `stream-error` when the operation
        encounters an error, giving `last-operation-failed`, or when the
        stream is closed, giving `closed`.
        
        When the caller gives a `len` of 0, it represents a request to
        read 0 bytes. If the stream is still open, this call should
        succeed and return an empty list, or otherwise fail with `closed`.
        
        The `len` parameter is a `u64`, which could represent a list of u8 which
        is not possible to allocate in wasm32, or not desirable to allocate as
        as a return value by the callee. The callee may return a list of bytes
        less than `len` in size while more bytes are available for reading.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_read(self, len: int) -> bytes:
        """
        Read bytes from a stream, after blocking until at least one byte can
        be read. Except for blocking, behavior is identical to `read`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def skip(self, len: int) -> int:
        """
        Skip bytes from a stream. Returns number of bytes skipped.
        
        Behaves identical to `read`, except instead of returning a list
        of bytes, returns the number of bytes consumed from the stream.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_skip(self, len: int) -> int:
        """
        Skip bytes from a stream, after blocking until at least one byte
        can be skipped. Except for blocking behavior, identical to `skip`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def subscribe(self) -> poll.Pollable:
        """
        Create a `pollable` which will resolve once either the specified stream
        has bytes available to read or the other end of the stream has been
        closed.
        The created `pollable` is a child resource of the `input-stream`.
        Implementations may trap if the `input-stream` is dropped before
        all derived `pollable`s created with this function are dropped.
        """
        raise NotImplementedError

    def __enter__(self):
        """Returns self"""
        return self
                                                                    
    def __exit__(self, *args):
        """
        Release this resource.
        """
        raise NotImplementedError

Methods

def blocking_read(self, len: int) ‑> bytes

Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to read.

Raises: Err(StreamError)

Expand source code

def blocking_read(self, len: int) -> bytes:
    """
    Read bytes from a stream, after blocking until at least one byte can
    be read. Except for blocking, behavior is identical to `read`.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def blocking_skip(self, len: int) ‑> int

Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to skip.

Raises: Err(StreamError)

Expand source code

def blocking_skip(self, len: int) -> int:
    """
    Skip bytes from a stream, after blocking until at least one byte
    can be skipped. Except for blocking behavior, identical to `skip`.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def read(self, len: int) ‑> bytes

Perform a non-blocking read from the stream.

When the source of a read is binary data, the bytes from the source are returned verbatim. When the source of a read is known to the implementation to be text, bytes containing the UTF-8 encoding of the text are returned.

This function returns a list of bytes containing the read data, when successful. The returned list will contain up to len bytes; it may return fewer than requested, but not more. The list is empty when no bytes are available for reading at this time. The pollable given by subscribe will be ready when more bytes are available.

This function fails with a stream-error when the operation encounters an error, giving last-operation-failed, or when the stream is closed, giving closed.

When the caller gives a len of 0, it represents a request to read 0 bytes. If the stream is still open, this call should succeed and return an empty list, or otherwise fail with closed.

The len parameter is a u64, which could represent a list of u8 which is not possible to allocate in wasm32, or not desirable to allocate as as a return value by the callee. The callee may return a list of bytes less than len in size while more bytes are available for reading.

Raises: Err(StreamError)

Expand source code

def read(self, len: int) -> bytes:
    """
    Perform a non-blocking read from the stream.
    
    When the source of a `read` is binary data, the bytes from the source
    are returned verbatim. When the source of a `read` is known to the
    implementation to be text, bytes containing the UTF-8 encoding of the
    text are returned.
    
    This function returns a list of bytes containing the read data,
    when successful. The returned list will contain up to `len` bytes;
    it may return fewer than requested, but not more. The list is
    empty when no bytes are available for reading at this time. The
    pollable given by `subscribe` will be ready when more bytes are
    available.
    
    This function fails with a `stream-error` when the operation
    encounters an error, giving `last-operation-failed`, or when the
    stream is closed, giving `closed`.
    
    When the caller gives a `len` of 0, it represents a request to
    read 0 bytes. If the stream is still open, this call should
    succeed and return an empty list, or otherwise fail with `closed`.
    
    The `len` parameter is a `u64`, which could represent a list of u8 which
    is not possible to allocate in wasm32, or not desirable to allocate as
    as a return value by the callee. The callee may return a list of bytes
    less than `len` in size while more bytes are available for reading.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def skip(self, len: int) ‑> int

Skip bytes from a stream. Returns number of bytes skipped.

Behaves identical to read, except instead of returning a list of bytes, returns the number of bytes consumed from the stream.

Raises: Err(StreamError)

Expand source code

def skip(self, len: int) -> int:
    """
    Skip bytes from a stream. Returns number of bytes skipped.
    
    Behaves identical to `read`, except instead of returning a list
    of bytes, returns the number of bytes consumed from the stream.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def subscribe(self) ‑> Pollable

Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. The created pollable is a child resource of the input-stream. Implementations may trap if the input-stream is dropped before all derived pollables created with this function are dropped.

Expand source code

def subscribe(self) -> poll.Pollable:
    """
    Create a `pollable` which will resolve once either the specified stream
    has bytes available to read or the other end of the stream has been
    closed.
    The created `pollable` is a child resource of the `input-stream`.
    Implementations may trap if the `input-stream` is dropped before
    all derived `pollable`s created with this function are dropped.
    """
    raise NotImplementedError

class OutputStream

An output bytestream.

output-streams are non-blocking to the extent practical on underlying platforms. Except where specified otherwise, I/O operations also always return promptly, after the number of bytes that can be written promptly, which could even be zero. To wait for the stream to be ready to accept data, the subscribe function to obtain a pollable which can be polled for using wasi:io/poll.

Expand source code

class OutputStream:
    """
    An output bytestream.
    
    `output-stream`s are *non-blocking* to the extent practical on
    underlying platforms. Except where specified otherwise, I/O operations also
    always return promptly, after the number of bytes that can be written
    promptly, which could even be zero. To wait for the stream to be ready to
    accept data, the `subscribe` function to obtain a `pollable` which can be
    polled for using `wasi:io/poll`.
    """
    
    def check_write(self) -> int:
        """
        Check readiness for writing. This function never blocks.
        
        Returns the number of bytes permitted for the next call to `write`,
        or an error. Calling `write` with more bytes than this function has
        permitted will trap.
        
        When this function returns 0 bytes, the `subscribe` pollable will
        become ready when this function will report at least 1 byte, or an
        error.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def write(self, contents: bytes) -> None:
        """
        Perform a write. This function never blocks.
        
        When the destination of a `write` is binary data, the bytes from
        `contents` are written verbatim. When the destination of a `write` is
        known to the implementation to be text, the bytes of `contents` are
        transcoded from UTF-8 into the encoding of the destination and then
        written.
        
        Precondition: check-write gave permit of Ok(n) and contents has a
        length of less than or equal to n. Otherwise, this function will trap.
        
        returns Err(closed) without writing if the stream has closed since
        the last call to check-write provided a permit.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_write_and_flush(self, contents: bytes) -> None:
        """
        Perform a write of up to 4096 bytes, and then flush the stream. Block
        until all of these operations are complete, or an error occurs.
        
        This is a convenience wrapper around the use of `check-write`,
        `subscribe`, `write`, and `flush`, and is implemented with the
        following pseudo-code:
        
        ```text
        let pollable = this.subscribe();
        while !contents.is_empty() {
        // Wait for the stream to become writable
        pollable.block();
        let Ok(n) = this.check-write(); // eliding error handling
        let len = min(n, contents.len());
        let (chunk, rest) = contents.split_at(len);
        this.write(chunk  );            // eliding error handling
        contents = rest;
        }
        this.flush();
        // Wait for completion of `flush`
        pollable.block();
        // Check for any errors that arose during `flush`
        let _ = this.check-write();         // eliding error handling
        ```
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def flush(self) -> None:
        """
        Request to flush buffered output. This function never blocks.
        
        This tells the output-stream that the caller intends any buffered
        output to be flushed. the output which is expected to be flushed
        is all that has been passed to `write` prior to this call.
        
        Upon calling this function, the `output-stream` will not accept any
        writes (`check-write` will return `ok(0)`) until the flush has
        completed. The `subscribe` pollable will become ready when the
        flush has completed and the stream can accept more writes.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_flush(self) -> None:
        """
        Request to flush buffered output, and block until flush completes
        and stream is ready for writing again.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def subscribe(self) -> poll.Pollable:
        """
        Create a `pollable` which will resolve once the output-stream
        is ready for more writing, or an error has occured. When this
        pollable is ready, `check-write` will return `ok(n)` with n>0, or an
        error.
        
        If the stream is closed, this pollable is always ready immediately.
        
        The created `pollable` is a child resource of the `output-stream`.
        Implementations may trap if the `output-stream` is dropped before
        all derived `pollable`s created with this function are dropped.
        """
        raise NotImplementedError

    def write_zeroes(self, len: int) -> None:
        """
        Write zeroes to a stream.
        
        This should be used precisely like `write` with the exact same
        preconditions (must use check-write first), but instead of
        passing a list of bytes, you simply pass the number of zero-bytes
        that should be written.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_write_zeroes_and_flush(self, len: int) -> None:
        """
        Perform a write of up to 4096 zeroes, and then flush the stream.
        Block until all of these operations are complete, or an error
        occurs.
        
        This is a convenience wrapper around the use of `check-write`,
        `subscribe`, `write-zeroes`, and `flush`, and is implemented with
        the following pseudo-code:
        
        ```text
        let pollable = this.subscribe();
        while num_zeroes != 0 {
        // Wait for the stream to become writable
        pollable.block();
        let Ok(n) = this.check-write(); // eliding error handling
        let len = min(n, num_zeroes);
        this.write-zeroes(len);         // eliding error handling
        num_zeroes -= len;
        }
        this.flush();
        // Wait for completion of `flush`
        pollable.block();
        // Check for any errors that arose during `flush`
        let _ = this.check-write();         // eliding error handling
        ```
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def splice(self, src: InputStream, len: int) -> int:
        """
        Read from one stream and write to another.
        
        The behavior of splice is equivelant to:
        1. calling `check-write` on the `output-stream`
        2. calling `read` on the `input-stream` with the smaller of the
        `check-write` permitted length and the `len` provided to `splice`
        3. calling `write` on the `output-stream` with that read data.
        
        Any error reported by the call to `check-write`, `read`, or
        `write` ends the splice and reports that error.
        
        This function returns the number of bytes transferred; it may be less
        than `len`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def blocking_splice(self, src: InputStream, len: int) -> int:
        """
        Read from one stream and write to another, with blocking.
        
        This is similar to `splice`, except that it blocks until the
        `output-stream` is ready for writing, and the `input-stream`
        is ready for reading, before performing the `splice`.
        
        Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
        """
        raise NotImplementedError

    def __enter__(self):
        """Returns self"""
        return self
                                                                    
    def __exit__(self, *args):
        """
        Release this resource.
        """
        raise NotImplementedError

Methods

def blocking_flush(self) ‑> None

Request to flush buffered output, and block until flush completes and stream is ready for writing again.

Raises: Err(StreamError)

Expand source code

def blocking_flush(self) -> None:
    """
    Request to flush buffered output, and block until flush completes
    and stream is ready for writing again.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def blocking_splice(self, src: InputStream, len: int) ‑> int

Read from one stream and write to another, with blocking.

This is similar to splice, except that it blocks until the output-stream is ready for writing, and the input-stream is ready for reading, before performing the splice.

Raises: Err(StreamError)

Expand source code

def blocking_splice(self, src: InputStream, len: int) -> int:
    """
    Read from one stream and write to another, with blocking.
    
    This is similar to `splice`, except that it blocks until the
    `output-stream` is ready for writing, and the `input-stream`
    is ready for reading, before performing the `splice`.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def blocking_write_and_flush(self, contents: bytes) ‑> None

Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

This is a convenience wrapper around the use of check-write, subscribe, write, and flush, and is implemented with the following pseudo-code:

let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
this.write(chunk  );            // eliding error handling
contents = rest;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write();         // eliding error handling

Raises: Err(StreamError)

Expand source code

def blocking_write_and_flush(self, contents: bytes) -> None:
    """
    Perform a write of up to 4096 bytes, and then flush the stream. Block
    until all of these operations are complete, or an error occurs.
    
    This is a convenience wrapper around the use of `check-write`,
    `subscribe`, `write`, and `flush`, and is implemented with the
    following pseudo-code:
    
    ```text
    let pollable = this.subscribe();
    while !contents.is_empty() {
    // Wait for the stream to become writable
    pollable.block();
    let Ok(n) = this.check-write(); // eliding error handling
    let len = min(n, contents.len());
    let (chunk, rest) = contents.split_at(len);
    this.write(chunk  );            // eliding error handling
    contents = rest;
    }
    this.flush();
    // Wait for completion of `flush`
    pollable.block();
    // Check for any errors that arose during `flush`
    let _ = this.check-write();         // eliding error handling
    ```
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def blocking_write_zeroes_and_flush(self, len: int) ‑> None

Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

This is a convenience wrapper around the use of check-write, subscribe, write-zeroes, and flush, and is implemented with the following pseudo-code:

let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len);         // eliding error handling
num_zeroes -= len;
}
this.flush();
// Wait for completion of `flush`
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write();         // eliding error handling

Raises: Err(StreamError)

Expand source code

def blocking_write_zeroes_and_flush(self, len: int) -> None:
    """
    Perform a write of up to 4096 zeroes, and then flush the stream.
    Block until all of these operations are complete, or an error
    occurs.
    
    This is a convenience wrapper around the use of `check-write`,
    `subscribe`, `write-zeroes`, and `flush`, and is implemented with
    the following pseudo-code:
    
    ```text
    let pollable = this.subscribe();
    while num_zeroes != 0 {
    // Wait for the stream to become writable
    pollable.block();
    let Ok(n) = this.check-write(); // eliding error handling
    let len = min(n, num_zeroes);
    this.write-zeroes(len);         // eliding error handling
    num_zeroes -= len;
    }
    this.flush();
    // Wait for completion of `flush`
    pollable.block();
    // Check for any errors that arose during `flush`
    let _ = this.check-write();         // eliding error handling
    ```
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def check_write(self) ‑> int

Check readiness for writing. This function never blocks.

Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has permitted will trap.

When this function returns 0 bytes, the subscribe pollable will become ready when this function will report at least 1 byte, or an error.

Raises: Err(StreamError)

Expand source code

def check_write(self) -> int:
    """
    Check readiness for writing. This function never blocks.
    
    Returns the number of bytes permitted for the next call to `write`,
    or an error. Calling `write` with more bytes than this function has
    permitted will trap.
    
    When this function returns 0 bytes, the `subscribe` pollable will
    become ready when this function will report at least 1 byte, or an
    error.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def flush(self) ‑> None

Request to flush buffered output. This function never blocks.

This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed is all that has been passed to write prior to this call.

Upon calling this function, the output-stream will not accept any writes (check-write will return ok(0)) until the flush has completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

Raises: Err(StreamError)

Expand source code

def flush(self) -> None:
    """
    Request to flush buffered output. This function never blocks.
    
    This tells the output-stream that the caller intends any buffered
    output to be flushed. the output which is expected to be flushed
    is all that has been passed to `write` prior to this call.
    
    Upon calling this function, the `output-stream` will not accept any
    writes (`check-write` will return `ok(0)`) until the flush has
    completed. The `subscribe` pollable will become ready when the
    flush has completed and the stream can accept more writes.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def splice(self, src: InputStream, len: int) ‑> int

Read from one stream and write to another.

The behavior of splice is equivelant to: 1. calling check-write on the output-stream 2. calling read on the input-stream with the smaller of the check-write permitted length and the len provided to splice 3. calling write on the output-stream with that read data.

Any error reported by the call to check-write, read, or write ends the splice and reports that error.

This function returns the number of bytes transferred; it may be less than len.

Raises: Err(StreamError)

Expand source code

def splice(self, src: InputStream, len: int) -> int:
    """
    Read from one stream and write to another.
    
    The behavior of splice is equivelant to:
    1. calling `check-write` on the `output-stream`
    2. calling `read` on the `input-stream` with the smaller of the
    `check-write` permitted length and the `len` provided to `splice`
    3. calling `write` on the `output-stream` with that read data.
    
    Any error reported by the call to `check-write`, `read`, or
    `write` ends the splice and reports that error.
    
    This function returns the number of bytes transferred; it may be less
    than `len`.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def subscribe(self) ‑> Pollable

Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occured. When this pollable is ready, check-write will return ok(n) with n>0, or an error.

If the stream is closed, this pollable is always ready immediately.

The created pollable is a child resource of the output-stream. Implementations may trap if the output-stream is dropped before all derived pollables created with this function are dropped.

Expand source code

def subscribe(self) -> poll.Pollable:
    """
    Create a `pollable` which will resolve once the output-stream
    is ready for more writing, or an error has occured. When this
    pollable is ready, `check-write` will return `ok(n)` with n>0, or an
    error.
    
    If the stream is closed, this pollable is always ready immediately.
    
    The created `pollable` is a child resource of the `output-stream`.
    Implementations may trap if the `output-stream` is dropped before
    all derived `pollable`s created with this function are dropped.
    """
    raise NotImplementedError

def write(self, contents: bytes) ‑> None

Perform a write. This function never blocks.

When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is known to the implementation to be text, the bytes of contents are transcoded from UTF-8 into the encoding of the destination and then written.

Precondition: check-write gave permit of Ok(n) and contents has a length of less than or equal to n. Otherwise, this function will trap.

returns Err(closed) without writing if the stream has closed since the last call to check-write provided a permit.

Raises: Err(StreamError)

Expand source code

def write(self, contents: bytes) -> None:
    """
    Perform a write. This function never blocks.
    
    When the destination of a `write` is binary data, the bytes from
    `contents` are written verbatim. When the destination of a `write` is
    known to the implementation to be text, the bytes of `contents` are
    transcoded from UTF-8 into the encoding of the destination and then
    written.
    
    Precondition: check-write gave permit of Ok(n) and contents has a
    length of less than or equal to n. Otherwise, this function will trap.
    
    returns Err(closed) without writing if the stream has closed since
    the last call to check-write provided a permit.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

def write_zeroes(self, len: int) ‑> None

Write zeroes to a stream.

This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.

Raises: Err(StreamError)

Expand source code

def write_zeroes(self, len: int) -> None:
    """
    Write zeroes to a stream.
    
    This should be used precisely like `write` with the exact same
    preconditions (must use check-write first), but instead of
    passing a list of bytes, you simply pass the number of zero-bytes
    that should be written.
    
    Raises: `spin_sdk.wit.types.Err(spin_sdk.wit.imports.streams.StreamError)`
    """
    raise NotImplementedError

class StreamErrorClosed

StreamErrorClosed()

Expand source code

@dataclass
class StreamErrorClosed:
    pass

class StreamErrorLastOperationFailed (value: Error)

StreamErrorLastOperationFailed(value: spin_sdk.wit.imports.error.Error)

Expand source code

@dataclass
class StreamErrorLastOperationFailed:
    value: error.Error

Class variables

var value : Error