httk.core.datastream

Submodules

• httk.core.datastream.bytestream_api
• httk.core.datastream.bytestream_backend
• httk.core.datastream.bytestream_bytes
• httk.core.datastream.bytestream_bytes_view
• httk.core.datastream.bytestream_common
• httk.core.datastream.bytestream_file
• httk.core.datastream.bytestream_file_view
• httk.core.datastream.bytestream_filename
• httk.core.datastream.bytestream_filename_view
• httk.core.datastream.bytestream_like
• httk.core.datastream.bytestream_request
• httk.core.datastream.bytestream_request_view
• httk.core.datastream.bytestream_url
• httk.core.datastream.bytestream_url_view
• httk.core.datastream.bytestream_view
• httk.core.datastream.compression
• httk.core.datastream.textstream_api
• httk.core.datastream.textstream_backend
• httk.core.datastream.textstream_common
• httk.core.datastream.textstream_file
• httk.core.datastream.textstream_file_view
• httk.core.datastream.textstream_filename
• httk.core.datastream.textstream_filename_view
• httk.core.datastream.textstream_like
• httk.core.datastream.textstream_request
• httk.core.datastream.textstream_request_view
• httk.core.datastream.textstream_string
• httk.core.datastream.textstream_string_view
• httk.core.datastream.textstream_url
• httk.core.datastream.textstream_url_view
• httk.core.datastream.textstream_view

Attributes

BytestreamLike
TextstreamLike

Classes

BytestreamBackend	Abstract base class for all backends of streaming byte data.
BytestreamBytes	Backend for streaming byte data backed by an actual bytes object.
BytestreamBytesView	A view presenting underlying streaming byte data as bytes.
BytestreamCommon	Common superclass for many of the implementations of backends for streaming byte data.
BytestreamFile	Backend for file-based (io.IOBase-conforming) streaming byte data.
BytestreamFileView	A view presenting an underlying data streaming backend via an io.IOBase-like API.
BytestreamFilename	Backend for streaming byte data via operations on a file specified by a filename.
BytestreamFilenameView	A view presenting an underlying data streaming backend via a filename.
BytestreamRequest	Backend for streaming byte data fetched via a urllib.request.Request.
BytestreamRequestView	A view presenting an underlying data streaming backend via a urllib.request.Request.
BytestreamURL	Backend for streaming byte data fetched from a URL string.
BytestreamURLView	A view presenting an underlying data streaming backend via a URL string.
BytestreamView	Abstract base class for all views of streaming byte data.
CompressionCodec	A decompression codec for a single container format.
TextstreamBackend	Abstract base class for all backends of streaming text data.
TextstreamCommon	Common superclass for many of the implementations of backends for streaming text data.
TextstreamFile	Backend for file-based (io.TextIOBase-conforming) streaming text data
TextstreamFileView	A view presenting an underlying data streaming backend via the full io.TextIOBase API, which is a superset of TextstreamAPI.
TextstreamFilename	Backend for streaming text via operations on a file specfied by a filename
TextstreamFilenameView	A view presenting an underlying data streaming backend via a filename.
TextstreamRequest	Backend for streaming text fetched via a urllib.request.Request.
TextstreamRequestView	A view presenting an underlying data streaming backend via a urllib.request.Request.
TextstreamString	Backend for streaming text backed by an actual string
TextstreamStringView	A view presenting an underlying data streaming as a string.
TextstreamURL	Backend for streaming text fetched from a URL string.
TextstreamURLView	A view presenting an underlying data streaming backend via a URL string.
TextstreamView	Abstract base class for all views of streaming text data.

Functions

known_compressions(→ list[str])	Return the registered codec names, in registration order.
register_compression(→ None)	Register (or replace) a codec under its name (case-insensitive).

Package Contents

class httk.core.datastream.BytestreamBackend(backend, **hints)

Bases: httk.core.views.Backend[BytestreamBackend], httk.core.datastream.bytestream_api.BytestreamAPI

Abstract base class for all backends of streaming byte data.

backend_classes: ClassVar[list[type[httk.core.views.Backend[Any]]]]

class httk.core.datastream.BytestreamBytes(content: bytes | bytearray, **hints: Any)

Bases: httk.core.datastream.bytestream_common.BytestreamCommon, httk.core.datastream.bytestream_backend.BytestreamBackend

Backend for streaming byte data backed by an actual bytes object.

b: bytes

property name: str | None

property closed: bool

class httk.core.datastream.BytestreamBytesView(obj: httk.core.datastream.bytestream_like.BytestreamLike, **hints: Any)

Bases: httk.core.datastream.bytestream_view.BytestreamView, bytes

A view presenting underlying streaming byte data as bytes. This view can be used both to pass bytes in place of streaming data, and for reading streaming data into bytes. Note: this view is not lazy (this is impossible for views inheriting bytes, since bytes is immutable), hence all streaming data is read immediately upon creating this view.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.BytestreamCommon

Bases: abc.ABC

Common superclass for many of the implementations of backends for streaming byte data.

unwrap() → io.IOBase

read(size: int = -1) → bytes

close() → None

seek(offset: int, whence: int = os.SEEK_SET) → int

tell() → int

class httk.core.datastream.BytestreamFile(obj: io.IOBase, **hints: Any)

Bases: httk.core.datastream.bytestream_common.BytestreamCommon, httk.core.datastream.bytestream_backend.BytestreamBackend

Backend for file-based (io.IOBase-conforming) streaming byte data.

property name: str | None

property closed: bool

class httk.core.datastream.BytestreamFileView(obj: httk.core.datastream.bytestream_like.BytestreamLike, **hints: Any)

Bases: httk.core.datastream.bytestream_view.BytestreamView, io.IOBase, httk.core.datastream.bytestream_api.BytestreamAPI

A view presenting an underlying data streaming backend via an io.IOBase-like API.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

property name: str | None

property closed: bool

close() → None

Flush and close the IO object.

This method has no effect if the file is already closed.

readable() → bool

Return whether object was opened for reading.

If False, read() will raise OSError.

writable() → bool

Return whether object was opened for writing.

If False, write() will raise OSError.

seekable() → bool

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

flush() → None

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

read(size: int | None = -1) → bytes

readline(size: int | None = -1) → bytes

Read and return a line from the stream.

If size is specified, at most size bytes will be read.

The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized.

readlines(hint: int = -1) → list[bytes]

Return a list of lines from the stream.

hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.

seek(offset: int, whence: int = io.SEEK_SET) → int

Change the stream position to the given byte offset.

offset

The stream position, relative to ‘whence’.

whence

The relative position to seek from.

The offset is interpreted relative to the position indicated by whence. Values for whence are:

• os.SEEK_SET or 0 – start of stream (the default); offset should be zero or positive

• os.SEEK_CUR or 1 – current stream position; offset may be negative

• os.SEEK_END or 2 – end of stream; offset is usually negative

Return the new absolute position.

tell() → int

Return current stream position.

detach() → NoReturn

class httk.core.datastream.BytestreamFilename(filename: str | pathlib.Path, **hints: Any)

Bases: httk.core.datastream.bytestream_common.BytestreamCommon, httk.core.datastream.bytestream_backend.BytestreamBackend

Backend for streaming byte data via operations on a file specified by a filename.

property name: str | None

property closed: bool

class httk.core.datastream.BytestreamFilenameView(obj: httk.core.datastream.bytestream_like.BytestreamLike, **hints: Any)

Bases: httk.core.datastream.bytestream_view.BytestreamView, str

A view presenting an underlying data streaming backend via a filename. This view is mostly useful for providing filenames to functions that will open them. Note: this view is not lazy (this is impossible for views inheriting str, since str is immutable).

Raises TypeError if created with a streaming data source that does not come with a name.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

type httk.core.datastream.BytestreamLike = bytestream_backend.BytestreamBackend | bytestream_view.BytestreamView | io.IOBase | io.BytesIO | bytes | bytearray | str | pathlib.Path | urllib.request.Request

class httk.core.datastream.BytestreamRequest(request: urllib.request.Request, **hints: Any)

Bases: httk.core.datastream.bytestream_common.BytestreamCommon, httk.core.datastream.bytestream_backend.BytestreamBackend

Backend for streaming byte data fetched via a urllib.request.Request.

property name: str | None

property url: str

property request: urllib.request.Request

property closed: bool

class httk.core.datastream.BytestreamRequestView(obj: httk.core.datastream.bytestream_like.BytestreamLike, **hints: Any)

Bases: httk.core.datastream.bytestream_view.BytestreamView, urllib.request.Request

A view presenting an underlying data streaming backend via a urllib.request.Request. This view is mostly useful for providing a Request to functions that will open it. Note: this view is not lazy (it does not fetch); it only mirrors the underlying request/URL.

Raises TypeError if created with a streaming data source that does not come with a URL.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.BytestreamURL(url: str, **hints: Any)

Bases: httk.core.datastream.bytestream_common.BytestreamCommon, httk.core.datastream.bytestream_backend.BytestreamBackend

Backend for streaming byte data fetched from a URL string. A bare string is interpreted as a URL when its scheme is one of http, https, ftp, or file, or when an explicit kind=”url” hint is given.

property name: str | None

property url: str

property closed: bool

class httk.core.datastream.BytestreamURLView(obj: httk.core.datastream.bytestream_like.BytestreamLike, **hints: Any)

Bases: httk.core.datastream.bytestream_view.BytestreamView, str

A view presenting an underlying data streaming backend via a URL string. This view is mostly useful for providing a URL to functions that will open it. Note: this view is not lazy (this is impossible for views inheriting str, since str is immutable).

Raises TypeError if created with a streaming data source that does not come with a URL.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.BytestreamView

Bases: httk.core.views.View[httk.core.datastream.bytestream_backend.BytestreamBackend]

Abstract base class for all views of streaming byte data.

class httk.core.datastream.CompressionCodec

A decompression codec for a single container format.

A codec is an orthogonal layer below the datastream backends: it turns a compressed binary stream into an uncompressed binary stream, independently of where the compressed bytes come from (a filename, an open file, raw bytes, or a remote response).

name: str

Canonical, lower-case codec name (e.g. "gzip"); also how an explicit hint selects it.

extensions: tuple[str, Ellipsis]

Recognized filename suffixes including the leading dot (e.g. (".gz",)).

magics: tuple[bytes, Ellipsis]

Leading magic-byte signatures; an empty tuple means the format cannot be sniffed.

open_stream: collections.abc.Callable[[io.IOBase], io.IOBase]

Wrap a compressed binary stream and return a readable, decompressed binary stream.

httk.core.datastream.known_compressions() → list[str]

Return the registered codec names, in registration order.

httk.core.datastream.register_compression(codec: CompressionCodec) → None

Register (or replace) a codec under its name (case-insensitive).

class httk.core.datastream.TextstreamBackend(backend, **hints)

Bases: httk.core.views.Backend[TextstreamBackend], httk.core.datastream.textstream_api.TextstreamAPI

Abstract base class for all backends of streaming text data.

backend_classes: ClassVar[list[type[httk.core.views.Backend[Any]]]]

class httk.core.datastream.TextstreamCommon

Bases: abc.ABC

Common superclass for many of the implementations of backends for streaming text data.

unwrap() → io.TextIOBase

read(size: int = -1) → str

close() → None

seek(offset: int, whence: int = os.SEEK_SET) → int

tell() → int

class httk.core.datastream.TextstreamFile(obj: io.TextIOBase, **hints: Any)

Bases: httk.core.datastream.textstream_common.TextstreamCommon, httk.core.datastream.textstream_backend.TextstreamBackend

Backend for file-based (io.TextIOBase-conforming) streaming text data

property name: str | None

property closed: bool

class httk.core.datastream.TextstreamFileView(obj: httk.core.datastream.textstream_like.TextstreamLike, **hints: Any)

Bases: httk.core.datastream.textstream_view.TextstreamView, io.TextIOBase, httk.core.datastream.textstream_api.TextstreamAPI

A view presenting an underlying data streaming backend via the full io.TextIOBase API, which is a superset of TextstreamAPI.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

property name: str | None

property closed: bool

close() → None

Flush and close the IO object.

This method has no effect if the file is already closed.

readable() → bool

Return whether object was opened for reading.

If False, read() will raise OSError.

writable() → bool

Return whether object was opened for writing.

If False, write() will raise OSError.

seekable() → bool

Return whether object supports random access.

If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

flush() → None

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

read(size: int | None = -1) → str

Read at most size characters from stream.

Read from underlying buffer until we have size characters or we hit EOF. If size is negative or omitted, read until EOF.

readline(size: int | None = -1) → str

Read until newline or EOF.

Return an empty string if EOF is hit immediately. If size is specified, at most size characters will be read.

readlines(hint: int = -1) → list[str]

Return a list of lines from the stream.

hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.

seek(offset: int, whence: int = io.SEEK_SET) → int

Change the stream position to the given byte offset.

offset

The stream position, relative to ‘whence’.

whence

The relative position to seek from.

The offset is interpreted relative to the position indicated by whence. Values for whence are:

• os.SEEK_SET or 0 – start of stream (the default); offset should be zero or positive

• os.SEEK_CUR or 1 – current stream position; offset may be negative

• os.SEEK_END or 2 – end of stream; offset is usually negative

Return the new absolute position.

tell() → int

Return current stream position.

detach() → NoReturn

Separate the underlying buffer from the TextIOBase and return it.

After the underlying buffer has been detached, the TextIO is in an unusable state.

property encoding: str | None

Encoding of the text stream.

Subclasses should override.

property errors: str | None

The error setting of the decoder or encoder.

Subclasses should override.

property newlines: str | tuple[str, Ellipsis] | None

Line endings translated so far.

Only line endings translated during reading are considered.

Subclasses should override.

class httk.core.datastream.TextstreamFilename(filename: str | pathlib.Path, **hints: Any)

Bases: httk.core.datastream.textstream_common.TextstreamCommon, httk.core.datastream.textstream_backend.TextstreamBackend

Backend for streaming text via operations on a file specfied by a filename

property name: str | None

property closed: bool

class httk.core.datastream.TextstreamFilenameView(obj: httk.core.datastream.textstream_like.TextstreamLike, **hints: Any)

Bases: httk.core.datastream.textstream_view.TextstreamView, str

A view presenting an underlying data streaming backend via a filename. This view is probably mostly useful for providing filenames to functions that will open them. Note: this view is not lazy (this is impossible for views inherting str, since str is immutable)

Raises TypeError if created with a streaming data source that do not come with a name, in the future we may consider creating a temporary file to place the data in.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

type httk.core.datastream.TextstreamLike = textstream_backend.TextstreamBackend | textstream_view.TextstreamView | io.TextIOBase | io.StringIO | str | pathlib.Path | urllib.request.Request

class httk.core.datastream.TextstreamRequest(request: urllib.request.Request, **hints: Any)

Bases: httk.core.datastream.textstream_common.TextstreamCommon, httk.core.datastream.textstream_backend.TextstreamBackend

Backend for streaming text fetched via a urllib.request.Request.

property name: str | None

property url: str

property request: urllib.request.Request

property closed: bool

class httk.core.datastream.TextstreamRequestView(obj: httk.core.datastream.textstream_like.TextstreamLike, **hints: Any)

Bases: httk.core.datastream.textstream_view.TextstreamView, urllib.request.Request

A view presenting an underlying data streaming backend via a urllib.request.Request. This view is mostly useful for providing a Request to functions that will open it. Note: this view is not lazy (it does not fetch); it only mirrors the underlying request/URL.

Raises TypeError if created with a streaming data source that does not come with a URL.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.TextstreamString(content: str, **hints: Any)

Bases: httk.core.datastream.textstream_common.TextstreamCommon, httk.core.datastream.textstream_backend.TextstreamBackend

Backend for streaming text backed by an actual string

s: str

property name: str | None

property closed: bool

class httk.core.datastream.TextstreamStringView(obj: httk.core.datastream.textstream_like.TextstreamLike, **hints: Any)

Bases: httk.core.datastream.textstream_view.TextstreamView, str

A view presenting an underlying data streaming as a string. This view can be used both to pass a string in place of streaming data, and for reading streaming data into a string. Note: this view is not lazy (this is impossible for views inherting str, since str is immutable), hence all the streaming data is read immedately upon creating this view.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.TextstreamURL(url: str, **hints: Any)

Bases: httk.core.datastream.textstream_common.TextstreamCommon, httk.core.datastream.textstream_backend.TextstreamBackend

Backend for streaming text fetched from a URL string. A bare string is interpreted as a URL when its scheme is one of http, https, ftp, or file, or when an explicit kind=”url” hint is given.

property name: str | None

property url: str

property closed: bool

class httk.core.datastream.TextstreamURLView(obj: httk.core.datastream.textstream_like.TextstreamLike, **hints: Any)

Bases: httk.core.datastream.textstream_view.TextstreamView, str

A view presenting an underlying data streaming backend via a URL string. This view is mostly useful for providing a URL to functions that will open it. Note: this view is not lazy (this is impossible for views inheriting str, since str is immutable).

Raises TypeError if created with a streaming data source that does not come with a URL.

unwrap() → Any

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

class httk.core.datastream.TextstreamView

Bases: httk.core.views.View[httk.core.datastream.textstream_backend.TextstreamBackend]

Abstract base class for all views of streaming text data.