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

omextra/io/buffers/framing.py

@@ -1,187 +0,0 @@
-# ruff: noqa: UP006 UP007 UP045
-# @omlish-lite
-import typing as ta
-
-from .errors import BufferTooLarge
-from .errors import FrameTooLarge
-from .types import BytesBuffer
-
-
-##
-
-
-class LongestMatchDelimiterFramer:
-    """
-    A delimiter-based framing codec that supports *overlapping* delimiters with longest-match semantics.
-
-    This is intentionally decoupled from any I/O model: it operates purely on a `BytesBuffer`-like object (providing
-    `__len__`, `find`, `split_to`, `advance`, and `segments`/`peek`).
-
-    Key property:
-      Given overlapping delimiters like [b'\\r', b'\\r\\n'], this codec will *not* emit a frame ending at '\\r' unless
-      it can prove the next byte is not '\\n' (or the stream is finalized).
-
-    Implementation note:
-      This codec relies on `BytesBuffer.find(...)` being stream-correct and C-accelerated over the buffer's underlying
-      contiguous segments. In pure Python it is usually better to keep searching near the storage layer than to
-      re-implement scanning byte-by-byte in higher-level codecs.
-    """
-
-    def __init__(
-            self,
-            delims: ta.Sequence[bytes],
-            *,
-            keep_ends: bool = False,
-            max_size: ta.Optional[int] = None,
-    ) -> None:
-        super().__init__()
-
-        dl = list(delims)
-        if not dl:
-            raise ValueError('no delimiters')
-        if any(not isinstance(d, (bytes, bytearray)) for d in dl):
-            raise TypeError(delims)
-        if any(len(d) == 0 for d in dl):
-            raise ValueError('empty delimiter')
-
-        self._delims = tuple(bytes(d) for d in dl)
-        self._keep_ends = keep_ends
-        self._max_size = max_size
-
-        # Sort by length descending for "choose longest at same start".
-        self._delims_by_len = tuple(sorted(self._delims, key=len, reverse=True))
-
-        # Build prefix relationships for overlap deferral. For each short delimiter, store longer delimiters that start
-        # with it.
-        pref: ta.Dict[bytes, ta.List[bytes]] = {}
-        for d in self._delims:
-            for e in self._delims:
-                if d is e:
-                    continue
-                if len(e) > len(d) and e.startswith(d):
-                    pref.setdefault(d, []).append(e)
-        for k, vs in list(pref.items()):
-            pref[k] = sorted(vs, key=len, reverse=True)
-        self._prefix_longer = pref
-
-        self._max_delim_len = max(len(d) for d in self._delims)
-
-    def decode(self, buf: BytesBuffer, *, final: bool = False) -> ta.List[ta.Any]:
-        """
-        Consume as many complete frames as possible from `buf` and return them as views.
-
-        - Frames are produced without copying (via `buf.split_to(...)`) when possible.
-        - The delimiter is consumed from the buffer; it may be retained on the frame if `keep_ends=True`.
-        - If `final=True`, the codec will not defer on overlapping delimiter prefixes at the end of the buffer.
-
-        Raises:
-          - BufferTooLarge if no delimiter is present and the buffered prefix exceeds max_size.
-          - FrameTooLarge if the next frame payload (bytes before delimiter) exceeds max_size.
-
-        Note on `max_size`:
-          `max_size` is enforced as a limit on the *current* frame (bytes before the next delimiter). If the buffer
-          contains bytes for a subsequent frame that already exceed `max_size`, this codec will only raise when it would
-          otherwise need to make progress on that oversized frame. Concretely: if this call already emitted at least one
-          frame, it will return those frames rather than raising immediately on trailing oversized data, leaving the
-          remaining bytes buffered.
-        """
-
-        out: ta.List[ta.Any] = []
-
-        while True:
-            hit = self._find_next_delim(buf)
-            if hit is None:
-                if self._max_size is not None and len(buf) > self._max_size and not out:
-                    raise BufferTooLarge('buffer exceeded max_size without delimiter')
-                return out
-
-            pos, delim = hit
-
-            if self._max_size is not None and pos > self._max_size:
-                raise FrameTooLarge('frame exceeded max_size')
-
-            if not final and self._should_defer(buf, pos, delim):
-                return out
-
-            if self._keep_ends:
-                frame = buf.split_to(pos + len(delim))
-                out.append(frame)
-            else:
-                frame = buf.split_to(pos)
-                out.append(frame)
-                buf.advance(len(delim))
-
-    def _find_next_delim(self, buf: BytesBuffer) -> ta.Optional[ta.Tuple[int, bytes]]:
-        """
-        Return (pos, delim) for the earliest delimiter occurrence. If multiple delimiters occur at the same position,
-        choose the longest matching delimiter.
-        """
-
-        ln = len(buf)
-        if ln == 0:
-            return None
-
-        best_pos = None  # type: ta.Optional[int]
-        best_delim = None  # type: ta.Optional[bytes]
-
-        # First pass: find the earliest position of any delimiter (cheap, uses buf.find).
-        for d in self._delims:
-            i = buf.find(d, 0, None)
-            if i == -1:
-                continue
-            if best_pos is None or i < best_pos:
-                best_pos = i
-                best_delim = d
-                if best_pos == 0:
-                    # Can't beat position 0; still need to choose longest at this position.
-                    pass
-            elif i == best_pos and best_delim is not None and len(d) > len(best_delim):
-                best_delim = d
-
-        if best_pos is None or best_delim is None:
-            return None
-
-        # Second pass: at that position, choose the longest delimiter that actually matches there. (We can't just rely
-        # on "which delimiter found it first" when overlaps exist.)
-        pos = best_pos
-        for d in self._delims_by_len:
-            if pos + len(d) > ln:
-                continue
-            if buf.find(d, pos, pos + len(d)) == pos:
-                return pos, d
-
-        # Shouldn't happen: best_pos came from some delimiter occurrence.
-        return pos, best_delim
-
-    def _should_defer(self, buf: BytesBuffer, pos: int, matched: bytes) -> bool:
-        """
-        Return True if we must defer because a longer delimiter could still match starting at `pos` but we don't yet
-        have enough bytes to decide.
-
-        We only defer when:
-          - the current match ends at the end of the currently buffered bytes, and
-          - there exists some longer delimiter that has `matched` as a prefix, and
-          - the buffered bytes from pos match the available prefix of that longer delimiter.
-        """
-
-        ln = len(buf)
-        endpos = pos + len(matched)
-        if endpos != ln:
-            return False
-
-        longer = self._prefix_longer.get(matched)
-        if not longer:
-            return False
-
-        avail = ln - pos
-        for d2 in longer:
-            if avail >= len(d2):
-                # If we had enough bytes, we'd have matched d2 in _find_next_delim.
-                continue
-            # Check whether buffered bytes match the prefix of d2 that we have available.
-            # Use stream-correct find on the prefix.
-            prefix = d2[:avail]
-            if buf.find(prefix, pos, pos + avail) == pos:
-                return True
-
-        return False

omextra/io/buffers/linear.py

@@ -1,202 +0,0 @@
-# ruff: noqa: UP006 UP007 UP045
-# @omlish-lite
-import typing as ta
-
-from .errors import BufferTooLarge
-from .errors import NoOutstandingReserve
-from .errors import OutstandingReserve
-from .segmented import SegmentedBytesView
-from .types import BytesLike
-from .types import MutableBytesBuffer
-from .utils import _norm_slice
-
-
-##
-
-
-class LinearBytesBuffer(MutableBytesBuffer):
-    """
-    A simple contiguous (bytearray-backed) MutableBytesBuffer implementation.
-
-    Strengths:
-      - Fast `find/rfind` and contiguous peeking.
-      - Efficient reserve/commit into a single backing store.
-
-    Tradeoffs:
-      - `split_to` returns a stable view by copying the split bytes into an owned `bytes` object.
-        (A truly zero-copy split view would require pinning the underlying bytearray against compaction.)
-    """
-
-    def __init__(
-            self,
-            *,
-            max_bytes: ta.Optional[int] = None,
-            initial_capacity: int = 0,
-    ) -> None:
-        super().__init__()
-
-        self._max_bytes = None if max_bytes is None else int(max_bytes)
-
-        if initial_capacity < 0:
-            raise ValueError(initial_capacity)
-        if self._max_bytes is not None and initial_capacity > self._max_bytes:
-            raise BufferTooLarge('buffer exceeded max_bytes')
-
-        # Pre-size the backing store to encourage fewer resizes/copies on trickle-y writes.
-        # We immediately clear so readable length remains 0.
-        if initial_capacity:
-            self._ba = bytearray(initial_capacity)
-            self._ba.clear()
-        else:
-            self._ba = bytearray()
-
-    _rpos = 0
-    _wpos = 0
-
-    _resv_start: ta.Optional[int] = None
-    _resv_len = 0
-
-    _resv_buf: bytearray
-
-    def __len__(self) -> int:
-        return self._wpos - self._rpos
-
-    def peek(self) -> memoryview:
-        if self._rpos == self._wpos:
-            return memoryview(b'')
-        return memoryview(self._ba)[self._rpos:self._wpos]
-
-    def segments(self) -> ta.Sequence[memoryview]:
-        mv = self.peek()
-        return (mv,) if len(mv) else ()
-
-    def _check_no_reserve(self) -> None:
-        if self._resv_start is not None:
-            raise OutstandingReserve('outstanding reserve')
-
-    def write(self, data: BytesLike, /) -> None:
-        self._check_no_reserve()
-        if not data:
-            return
-        if isinstance(data, memoryview):
-            data = data.tobytes()
-        elif isinstance(data, bytearray):
-            data = bytes(data)
-
-        bl = len(data)
-
-        if self._max_bytes is not None and len(self) + bl > self._max_bytes:
-            raise BufferTooLarge('buffer exceeded max_bytes')
-
-        # Keep backing store "dense": if we've consumed everything, reset.
-        if self._rpos == self._wpos and self._rpos:
-            self._ba.clear()
-            self._rpos = 0
-            self._wpos = 0
-
-        self._ba.extend(data)
-        self._wpos += bl
-
-    def reserve(self, n: int, /) -> memoryview:
-        if n < 0:
-            raise ValueError(n)
-        if self._resv_start is not None:
-            raise OutstandingReserve('outstanding reserve')
-
-        # Important: do NOT reserve by extending the backing bytearray and returning a view into it. A live exported
-        # memoryview pins the bytearray against resizing, and commit() would need to shrink unused reservation space (or
-        # otherwise reshape), which would raise BufferError.
-        #
-        # Instead, reserve returns a view of a temporary bytearray, and commit() appends only what was actually written.
-        # This keeps reserve/commit safe and predictable.
-        b = bytearray(n)
-        self._resv_start = 0
-        self._resv_len = n
-        self._resv_buf = b
-        return memoryview(b)
-
-    def commit(self, n: int, /) -> None:
-        if self._resv_start is None:
-            raise NoOutstandingReserve('no outstanding reserve')
-        if n < 0 or n > self._resv_len:
-            raise ValueError(n)
-
-        b = self._resv_buf
-        self._resv_start = None
-        self._resv_len = 0
-        del self._resv_buf
-
-        if not n:
-            return
-
-        if self._max_bytes is not None and len(self) + n > self._max_bytes:
-            raise BufferTooLarge('buffer exceeded max_bytes')
-
-        # Append only what was written.
-        self.write(memoryview(b)[:n])
-
-    def advance(self, n: int, /) -> None:
-        self._check_no_reserve()
-        if n < 0 or n > len(self):
-            raise ValueError(n)
-        if n == 0:
-            return
-
-        self._rpos += n
-
-        # Compact opportunistically (content-preserving, may copy).
-        # This avoids "huge buffer pinned by small tail" for contiguous backing.
-        # Keep thresholds conservative to avoid excessive churn.
-        if self._rpos and self._rpos >= 65536 and self._rpos >= (self._wpos // 2):
-            del self._ba[:self._rpos]
-            self._wpos -= self._rpos
-            self._rpos = 0
-
-        # Fully consumed: reset.
-        if self._rpos == self._wpos:
-            self._ba.clear()
-            self._rpos = 0
-            self._wpos = 0
-
-    def split_to(self, n: int, /) -> SegmentedBytesView:
-        self._check_no_reserve()
-        if n < 0 or n > len(self):
-            raise ValueError(n)
-        if n == 0:
-            return SegmentedBytesView(())
-
-        # Copy out the split prefix to keep the view stable even if the underlying buffer compacts.
-        b = bytes(memoryview(self._ba)[self._rpos:self._rpos + n])
-        self._rpos += n
-
-        if self._rpos == self._wpos:
-            self._ba.clear()
-            self._rpos = 0
-            self._wpos = 0
-
-        return SegmentedBytesView((memoryview(b),))
-
-    def find(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        start, end = _norm_slice(len(self), start, end)
-        if len(sub) == 0:
-            return start
-        i = self._ba.find(sub, self._rpos + start, self._rpos + end)
-        return -1 if i < 0 else (i - self._rpos)
-
-    def rfind(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        start, end = _norm_slice(len(self), start, end)
-        if len(sub) == 0:
-            return end
-        i = self._ba.rfind(sub, self._rpos + start, self._rpos + end)
-        return -1 if i < 0 else (i - self._rpos)
-
-    def coalesce(self, n: int, /) -> memoryview:
-        self._check_no_reserve()
-        if n < 0:
-            raise ValueError(n)
-        if n > len(self):
-            raise ValueError(n)
-        if n == 0:
-            return memoryview(b'')
-        # Always contiguous for the readable prefix.
-        return memoryview(self._ba)[self._rpos:self._rpos + n]

omextra/io/buffers/reading.py

@@ -1,149 +0,0 @@
-# @omlish-lite
-import typing as ta
-
-from .errors import NeedMoreData
-from .types import BytesBuffer
-
-
-##
-
-
-def _coalesce_exact(buf: BytesBuffer, n: int) -> memoryview:
-    """
-    Return a contiguous view of exactly `n` readable bytes, or raise NeedMoreData.
-
-    Uses `buf.coalesce(n)` to avoid per-byte Python work and to keep copying close to the buffer backend.
-    """
-
-    if n < 0:
-        raise ValueError(n)
-    if len(buf) < n:
-        raise NeedMoreData
-    mv = buf.coalesce(n)
-    if len(mv) < n:
-        # Defensive: coalesce contract should provide >= n when len(buf) >= n.
-        raise NeedMoreData
-    return mv[:n]
-
-
-##
-
-
-def peek_u8(buf: BytesBuffer) -> int:
-    """Peek an unsigned 8-bit integer without consuming."""
-
-    mv = _coalesce_exact(buf, 1)
-    return mv[0]
-
-
-def read_u8(buf: BytesBuffer) -> int:
-    """Read and consume an unsigned 8-bit integer."""
-
-    v = peek_u8(buf)
-    buf.advance(1)
-    return v
-
-
-def peek_u16_be(buf: BytesBuffer) -> int:
-    """Peek an unsigned 16-bit big-endian integer without consuming."""
-
-    mv = _coalesce_exact(buf, 2)
-    return int.from_bytes(mv, 'big', signed=False)
-
-
-def read_u16_be(buf: BytesBuffer) -> int:
-    """Read and consume an unsigned 16-bit big-endian integer."""
-
-    v = peek_u16_be(buf)
-    buf.advance(2)
-    return v
-
-
-def peek_u16_le(buf: BytesBuffer) -> int:
-    """Peek an unsigned 16-bit little-endian integer without consuming."""
-
-    mv = _coalesce_exact(buf, 2)
-    return int.from_bytes(mv, 'little', signed=False)
-
-
-def read_u16_le(buf: BytesBuffer) -> int:
-    """Read and consume an unsigned 16-bit little-endian integer."""
-
-    v = peek_u16_le(buf)
-    buf.advance(2)
-    return v
-
-
-def peek_u32_be(buf: BytesBuffer) -> int:
-    """Peek an unsigned 32-bit big-endian integer without consuming."""
-
-    mv = _coalesce_exact(buf, 4)
-    return int.from_bytes(mv, 'big', signed=False)
-
-
-def read_u32_be(buf: BytesBuffer) -> int:
-    """Read and consume an unsigned 32-bit big-endian integer."""
-
-    v = peek_u32_be(buf)
-    buf.advance(4)
-    return v
-
-
-def peek_u32_le(buf: BytesBuffer) -> int:
-    """Peek an unsigned 32-bit little-endian integer without consuming."""
-
-    mv = _coalesce_exact(buf, 4)
-    return int.from_bytes(mv, 'little', signed=False)
-
-
-def read_u32_le(buf: BytesBuffer) -> int:
-    """Read and consume an unsigned 32-bit little-endian integer."""
-
-    v = peek_u32_le(buf)
-    buf.advance(4)
-    return v
-
-
-##
-
-
-def peek_exact(buf: BytesBuffer, n: int, /) -> memoryview:
-    """
-    Return a contiguous view of exactly `n` readable bytes without consuming.
-
-    Raises NeedMoreData if fewer than `n` bytes are currently buffered.
-    """
-
-    if n < 0:
-        raise ValueError(n)
-    if len(buf) < n:
-        raise NeedMoreData
-    mv = buf.coalesce(n)
-    if len(mv) < n:
-        raise NeedMoreData
-    return mv[:n]
-
-
-def take(buf: BytesBuffer, n: int, /) -> ta.Any:
-    """
-    Consume and return a `BytesView`-like object representing exactly `n` bytes.
-
-    Raises NeedMoreData if fewer than `n` bytes are currently buffered.
-    """
-
-    if n < 0:
-        raise ValueError(n)
-    if len(buf) < n:
-        raise NeedMoreData
-    return buf.split_to(n)
-
-
-def read_bytes(buf: BytesBuffer, n: int, /) -> bytes:
-    """
-    Consume exactly `n` bytes and return them as a contiguous `bytes` object (copy boundary).
-
-    Raises NeedMoreData if fewer than `n` bytes are currently buffered.
-    """
-
-    v = take(buf, n)
-    return ta.cast(bytes, v.tobytes())

omextra/io/buffers/scanning.py

@@ -1,110 +0,0 @@
-# ruff: noqa: UP045
-# @omlish-lite
-import typing as ta
-
-from .types import BytesLike
-from .types import MutableBytesBuffer
-
-
-##
-
-
-class ScanningBytesBuffer(MutableBytesBuffer):
-    """
-    A MutableBytesBuffer wrapper that caches negative-find progress to avoid repeated rescans in trickle scenarios.
-
-    It is intentionally conservative:
-      - It only caches progress for the default find range (start==0, end is None).
-      - It only caches *negative* results (i.e., "-1"): once a match is found, caching is not updated, to preserve the
-        property that repeated `find(sub)` on an unchanged buffer yields the same answer.
-
-    This is designed to help framing-style code that repeatedly does:
-      - buf.write(...small...)
-      - buf.find(delim)
-      - (not found) repeat
-    """
-
-    def __init__(self, buf) -> None:
-        super().__init__()
-
-        self._buf = buf
-        self._scan_from_by_sub: dict[bytes, int] = {}
-
-    #
-
-    def __len__(self) -> int:
-        return len(self._buf)
-
-    def peek(self) -> memoryview:
-        return self._buf.peek()
-
-    def segments(self) -> ta.Sequence[memoryview]:
-        return self._buf.segments()
-
-    #
-
-    def advance(self, n: int, /) -> None:
-        self._buf.advance(n)
-        self._adjust_for_consume(n)
-
-    def split_to(self, n: int, /):
-        v = self._buf.split_to(n)
-        self._adjust_for_consume(n)
-        return v
-
-    def coalesce(self, n: int, /) -> memoryview:
-        return self._buf.coalesce(n)
-
-    def find(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        if start != 0 or end is not None:
-            return self._buf.find(sub, start, end)
-
-        sub_len = len(sub)
-        if sub_len <= 0:
-            return self._buf.find(sub, start, end)
-
-        scan_from = self._scan_from_by_sub.get(sub, 0)
-
-        # Allow overlap so a match spanning old/new boundary is discoverable.
-        overlap = sub_len - 1
-        eff_start = scan_from - overlap
-        if eff_start < 0:
-            eff_start = 0
-
-        i = self._buf.find(sub, eff_start, None)
-        if i < 0:
-            self._scan_from_by_sub[sub] = len(self._buf)
-
-        return i
-
-    def rfind(self, sub: bytes, start: int = 0, end: ta.Optional[int] = None) -> int:
-        # rfind isn't the typical trickle hot-path; delegate.
-        return self._buf.rfind(sub, start, end)
-
-    #
-
-    def write(self, data: BytesLike, /) -> None:
-        self._buf.write(data)
-
-    def reserve(self, n: int, /) -> memoryview:
-        return self._buf.reserve(n)
-
-    def commit(self, n: int, /) -> None:
-        self._buf.commit(n)
-
-    #
-
-    def _adjust_for_consume(self, n: int) -> None:
-        if not self._scan_from_by_sub:
-            return
-
-        if n <= 0:
-            return
-
-        # Only front-consumption exists in this buffer model.
-        for k, v in list(self._scan_from_by_sub.items()):
-            nv = v - n
-            if nv <= 0:
-                self._scan_from_by_sub.pop(k, None)
-            else:
-                self._scan_from_by_sub[k] = nv