omextra 0.0.0.dev513__py3-none-any.whl → 0.0.0.dev515__py3-none-any.whl

omextra/io/buffers/types.py

@@ -1,263 +0,0 @@
-# ruff: noqa: UP007 UP045
-# @omlish-lite
-import abc
-import typing as ta
-
-from omlish.lite.abstract import Abstract
-
-
-BytesLike = ta.Union[bytes, bytearray, memoryview]  # ta.TypeAlias
-
-
-##
-
-
-class BytesViewLike(Abstract):
-    @abc.abstractmethod
-    def __len__(self) -> int:
-        """
-        Return the number of readable bytes.
-
-        This is expected to be O(1). Many drivers and codecs use `len(buf)` in tight loops to decide whether more data
-        is needed before attempting to parse a frame.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def peek(self) -> memoryview:
-        """
-        Return a contiguous, read-only `memoryview` of the first available bytes.
-
-        This is the "next chunk" fast-path: for segmented views, the returned memoryview may represent only the first
-        segment (and thus may be shorter than `len(self)`), but it must be non-copying. This is the fast-path for codecs
-        that can parse headers from an initial contiguous region.
-
-        The returned view should be treated as ephemeral: callers must assume it may be invalidated by subsequent buffer
-        mutations (advance/write/reserve/commit), depending on the implementation.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def segments(self) -> ta.Sequence[memoryview]:
-        """
-        Return the readable contents as an ordered sequence of non-copying `memoryview` segments.
-
-        This method is required because efficient operations in pure Python typically depend on delegating work to
-        CPython's optimized implementations for searching/slicing within contiguous regions. By exposing
-        already-contiguous segments, the buffer enables implementations of `find/rfind` and higher-level framing to
-        avoid Python-level per-byte iteration.
-
-        The returned segments must:
-          - collectively represent exactly the readable bytes, in order,
-          - be 1-D, byte-oriented views (itemsize 1),
-          - be non-copying views of the underlying storage.
-
-        Callers must assume that the returned views may be invalidated by subsequent mutations of the originating
-        buffer/view (e.g., advancing, writing, reserving, committing), depending on the implementation's rules.
-        """
-
-        raise NotImplementedError
-
-
-class BytesView(BytesViewLike, Abstract):
-    """
-    A read-only, possibly non-contiguous view of bytes.
-
-    This is the result type of operations like `BytesBuffer.split_to()`: it represents a *logical* byte sequence without
-    requiring a copy. A `BytesView` is intentionally minimal: it is not a general-purpose container API, not a
-    random-access sequence, and not intended for arbitrary indexing/slicing-heavy use.
-
-    `BytesView` exists to make copy boundaries explicit:
-      - Use `segments()` / `peek()` to access data without copying.
-      - Use `tobytes()` (or `bytes(view)`) to intentionally materialize a contiguous `bytes` object.
-
-    Implementations may be backed by one or many `memoryview` segments; the semantics are defined as if all readable
-    bytes were concatenated in order.
-    """
-
-    @abc.abstractmethod
-    def tobytes(self) -> bytes:
-        """
-        Materialize this view as a contiguous `bytes` object (copying).
-
-        This is the explicit copy boundary: callers should prefer `peek()` / `segments()` for zero-copy-ish access when
-        feasible, and use `tobytes()` only when a contiguous owned `bytes` is required.
-        """
-
-        raise NotImplementedError
-
-
-class BytesBuffer(BytesViewLike, Abstract):
-    """
-    An incremental, consumption-oriented byte accumulator intended for protocol parsing.
-
-    A `BytesBuffer` is a *stream buffer*: bytes are appended by a driver/transport and then consumed by codecs via
-    peeking, searching, splitting, and advancing-without forcing repeated concatenation or reallocation. It is
-    explicitly designed to support segmented storage (to avoid "a huge buffer pinned by a tiny tail") and to enable
-    low-copy pipeline-style decoding (Netty/Tokio-inspired).
-
-    What it is for:
-      - buffering raw bytes between I/O and protocol codecs,
-      - framing (delimiters/length-prefixed) using split/advance,
-      - efficient searching over buffered bytes using C-accelerated primitives via `memoryview` segments.
-
-    What it is *not* for:
-      - a general-purpose replacement for `bytes`/`bytearray`,
-      - a `collections.abc.Sequence` or random-access container abstraction,
-      - arbitrary indexing/slicing-heavy workloads (use `bytes`/`bytearray`/`memoryview` directly).
-
-    `BytesBuffer` deliberately exposes `memoryview` at its boundary. This is foundational: it allows both immutable
-    (`bytes`) and mutable (`bytearray`) internal storage to be viewed in O(1) without copying. It also avoids relying
-    on `io.BytesIO` as a core backing store: while `BytesIO.getbuffer()` can expose a view, exported views pin the
-    underlying buffer against resizing, which makes it awkward as a general-purpose buffer substrate.
-
-    Semantics note:
-      Many methods describe behavior in terms of the *conceptual concatenation* of readable bytes, even if the buffer
-      is physically segmented. This is what "stream-correct" means here: results must be correct regardless of how the
-      buffered bytes are chunked internally.
-    """
-
-    @abc.abstractmethod
-    def advance(self, n: int, /) -> None:
-        """
-        Consume (discard) exactly `n` readable bytes from the front of the buffer.
-
-        This operation must not copy remaining bytes unnecessarily. For segmented buffers, this typically adjusts a head
-        offset and drops exhausted segments.
-
-        Implementations must raise if `n` is negative or greater than `len(self)`.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def split_to(self, n: int, /) -> BytesView:
-        """
-        Split off and return a read-only view of the first `n` readable bytes, consuming them from this buffer.
-
-        This is the core "low-copy framing" primitive:
-          - codecs can `split_to(frame_len)` to obtain a view of an entire frame without copying,
-          - then immediately continue parsing subsequent frames from the remaining bytes.
-
-        Implementations should strive for O(1) or amortized O(1) behavior, returning a view that references underlying
-        segments rather than materializing a new contiguous `bytes`.
-
-        Implementations must raise if `n` is negative or greater than `len(self)`.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def coalesce(self, n: int, /) -> memoryview:
-        """
-        Ensure the first `n` readable bytes are available contiguously and return a view of them.
-
-        Semantics:
-          - Non-consuming: does not advance.
-          - May restructure internal segments (content-preserving) to make the prefix contiguous.
-          - Returns a read-only-ish `memoryview` (callers must not mutate readable bytes).
-
-        Copying behavior:
-          - If `peek()` already exposes >= n contiguous bytes, this is zero-copy.
-          - Otherwise, it copies exactly the first `n` bytes into a new contiguous segment and rewrites the internal
-            segment list so that segment[0] contains that prefix.
-
-        Reserve interaction:
-          - Disallowed while an outstanding reservation exists, since reserve() hands out a view that must not be
-            invalidated by internal reshaping.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def find(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        """
-        Find the first occurrence of `sub` within the readable bytes and return its offset, or -1 if not found.
-
-        This operation is "stream-correct": it must behave as if searching within the conceptual concatenation of all
-        readable bytes, even if the buffer is physically segmented. In particular, matches that span segment boundaries
-        must be detected.
-
-        `start` and `end` are offsets into the readable region, matching the semantics of `bytes.find()`:
-          - `start` defaults to 0 (the beginning of readable bytes),
-          - `end` defaults to `len(self)`.
-
-        Rationale for being part of the core interface:
-          In pure Python, higher-level codecs cannot efficiently implement correct cross-segment searching byte-by-byte.
-          Keeping `find` near the owning storage allows implementations to exploit contiguous segments and CPython's
-          optimized search within each segment while still providing correct stream semantics.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def rfind(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        """
-        Find the last occurrence of `sub` within the readable bytes and return its offset, or -1 if not found.
-
-        This operation is also stream-correct and matches `bytes.rfind()` semantics for `start`/`end`, interpreted as
-        offsets into the readable region of this buffer.
-        """
-
-        raise NotImplementedError
-
-
-class MutableBytesBuffer(BytesBuffer, Abstract):
-    """
-    A writable `BytesBuffer`: supports appending bytes and (optionally) reserving writable space.
-
-    `MutableBytesBuffer` is the primary target for drivers/transports feeding data into protocol pipelines, and for
-    encoders building outbound byte sequences. It intentionally does not imply any particular I/O model (blocking,
-    asyncio, custom reactors); it is simply the mutable byte substrate.
-
-    Implementations may be linear (single `bytearray` + indices), segmented (multiple chunks), or adaptive.
-    """
-
-    @abc.abstractmethod
-    def write(self, data: BytesLike, /) -> None:
-        """
-        Append `data` to the end of the readable region (after any existing unread bytes).
-
-        Implementations should avoid needless copying; e.g., segmented buffers may store large `bytes` chunks directly,
-        while linear buffers may copy into a `bytearray`.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def reserve(self, n: int, /) -> memoryview:
-        """
-        Reserve writable space for at least `n` bytes and return a writable `memoryview` into that space.
-
-        This method exists to support "close to the metal" drivers that can fill buffers directly (e.g., `recv_into`,
-        `readinto`) without allocating temporary `bytes` objects.
-
-        The returned view represents capacity that is not yet part of the readable region. The caller must write into
-        some prefix of the view and then call `commit(written)` to make those bytes readable.
-
-        Implementations should document their rules regarding outstanding reservations; a simple and robust rule is:
-          - only one active reservation may exist at a time,
-          - mutations that would reallocate storage are forbidden while a reservation is outstanding.
-        """
-
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def commit(self, n: int, /) -> None:
-        """
-        Commit `n` bytes from the most recent reservation, making them readable.
-
-        Conceptually, `reserve()` may provide more capacity than the caller actually uses; `commit(n)` "shrinks" that
-        over-reservation by only publishing the first `n` bytes as readable.
-
-        Implementations must validate:
-          - that a reservation is outstanding,
-          - that `0 <= n <= reserved_length`.
-
-        After commit, the reservation is considered consumed; subsequent reads and searches must include the committed
-        bytes as part of the readable region.
-        """
-
-        raise NotImplementedError

omextra/io/buffers/utils.py

@@ -1,76 +0,0 @@
-# ruff: noqa: UP006 UP045
-# @omlish-lite
-import typing as ta
-
-from .types import BytesView
-from .types import BytesViewLike
-
-
-##
-
-
-def _norm_slice(length: int, start: int, end: ta.Optional[int]) -> ta.Tuple[int, int]:
-    if start < 0:
-        start += length
-    if start < 0:
-        start = 0
-    if start > length:
-        start = length
-
-    if end is None:
-        end = length
-    else:
-        if end < 0:
-            end += length
-        if end < 0:
-            end = 0
-        if end > length:
-            end = length
-
-    if end < start:
-        end = start
-
-    return start, end
-
-
-##
-
-
-def can_bytes(obj: ta.Any) -> bool:
-    return isinstance(obj, (bytes, bytearray, memoryview, BytesViewLike))
-
-
-def iter_bytes_segments(obj: ta.Any) -> ta.Iterator[memoryview]:
-    if isinstance(obj, memoryview):
-        yield obj
-    elif isinstance(obj, (bytes, bytearray)):
-        yield memoryview(obj)
-    elif isinstance(obj, BytesViewLike):
-        yield from obj.segments()
-    else:
-        raise TypeError(obj)
-
-
-def to_bytes(obj: ta.Any) -> bytes:
-    if isinstance(obj, bytes):
-        return obj
-    elif isinstance(obj, bytearray):
-        return bytes(obj)
-    elif isinstance(obj, memoryview):
-        return obj.tobytes()
-    elif isinstance(obj, BytesView):
-        return obj.tobytes()
-    elif isinstance(obj, BytesViewLike):
-        return b''.join(bytes(mv) for mv in obj.segments())
-    else:
-        raise TypeError(obj)
-
-
-def bytes_len(obj: ta.Any) -> int:
-    if isinstance(obj, (bytes, bytearray, memoryview)):
-        return len(obj)
-    elif isinstance(obj, BytesViewLike):
-        return sum(len(mv) for mv in obj.segments())
-    else:
-        # Not bytes-like
-        return 0