socketwrapper 0.0.2__tar.gz → 0.0.3__tar.gz

{socketwrapper-0.0.2/socketwrapper.egg-info → socketwrapper-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketwrapper
-Version: 0.0.2
+Version: 0.0.3
 Summary: high level socket and pipe wrappers
 Author: Felipe A Hernandez
 Author-email: ergoithz@gmail.com
@@ -27,6 +27,7 @@ License: MIT License
         SOFTWARE.
         
 Project-URL: homepage, https://gitlab.com/ergoithz/socketwrapper
+Project-URL: repository, https://gitlab.com/ergoithz/socketwrapper
 Project-URL: issue-tracker, https://gitlab.com/ergoithz/socketwrapper/-/issues
 Project-URL: release-notes, https://gitlab.com/ergoithz/socketwrapper/-/releases
 Project-URL: issue-new, https://gitlab.com/ergoithz/socketwrapper/-/issues/new
@@ -89,12 +90,17 @@ uv pip install 'socketwrapper[msgpack]'
 
 ## Changelog
 
-### v0.0.2 - 2025.11.05
+### 0.0.3 - 2025.11.08
+
+- New: optional support for `recv_into` in socket-like objects.
+- Optimization: recv operations will now use `sock.recv_into` (if available) to reduce memory allocation overhead.
+
+### 0.0.2 - 2025.11.05
 
 - Breaking: `MessageFraming.frames` and `MessageFraming.loads` now receive `io.BytesIO` instead of `bytearray`.
 - New: optional msgpack support (`msgpack` extra).
 - Fix: busy reads no longer blocking asyncio event loop.
-- Typing: expose `SizedBuffer` and deprecate `SendPayload`.
+- Typing: expose `SizedBuffer` and deprecate `SendPayload` (removal expected in `0.1.0`).
 - Typing: `SocketWriter.send` and `SocketWriter.send_async` data is now `SizedBuffer`.
 
 ## Documentation
@@ -103,7 +109,9 @@ None other than this README, life's too short and I'm too busy with real life, i
 
 ### Puggable I/O: SocketLike protocol
 
-The `socketwrapper.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+The `protocols.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+
+Additional methods defined in `protocols.OptionalSocketLike` can be optionally implemented enabling optimized code paths.
 
 ```py
 @typing.runtime_checkable
@@ -115,6 +123,14 @@ class SocketLike(typing.Protocol):
     def recv(self, bufsize: int, /) -> bytes: ...
     def settimeout(self, timeout: float | None, /) -> None: ...
     def close(self) -> None: ...
+
+
+@typing.runtime_checkable
+class OptionalSocketLike(SocketLike, typing.Protocol):
+    """Protocol for optional socket-like object methods accepted by socketwrapper socket classes."""
+
+    def recv_into(self, buffer: collections.abc.Buffer, /) -> bytes: ...
+
 ```
 
 Special attention to:

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/README.md

@@ -35,12 +35,17 @@ uv pip install 'socketwrapper[msgpack]'
 
 ## Changelog
 
-### v0.0.2 - 2025.11.05
+### 0.0.3 - 2025.11.08
+
+- New: optional support for `recv_into` in socket-like objects.
+- Optimization: recv operations will now use `sock.recv_into` (if available) to reduce memory allocation overhead.
+
+### 0.0.2 - 2025.11.05
 
 - Breaking: `MessageFraming.frames` and `MessageFraming.loads` now receive `io.BytesIO` instead of `bytearray`.
 - New: optional msgpack support (`msgpack` extra).
 - Fix: busy reads no longer blocking asyncio event loop.
-- Typing: expose `SizedBuffer` and deprecate `SendPayload`.
+- Typing: expose `SizedBuffer` and deprecate `SendPayload` (removal expected in `0.1.0`).
 - Typing: `SocketWriter.send` and `SocketWriter.send_async` data is now `SizedBuffer`.
 
 ## Documentation
@@ -49,7 +54,9 @@ None other than this README, life's too short and I'm too busy with real life, i
 
 ### Puggable I/O: SocketLike protocol
 
-The `socketwrapper.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+The `protocols.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+
+Additional methods defined in `protocols.OptionalSocketLike` can be optionally implemented enabling optimized code paths.
 
 ```py
 @typing.runtime_checkable
@@ -61,6 +68,14 @@ class SocketLike(typing.Protocol):
     def recv(self, bufsize: int, /) -> bytes: ...
     def settimeout(self, timeout: float | None, /) -> None: ...
     def close(self) -> None: ...
+
+
+@typing.runtime_checkable
+class OptionalSocketLike(SocketLike, typing.Protocol):
+    """Protocol for optional socket-like object methods accepted by socketwrapper socket classes."""
+
+    def recv_into(self, buffer: collections.abc.Buffer, /) -> bytes: ...
+
 ```
 
 Special attention to:

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = 'setuptools.build_meta'
 [project]
 name = 'socketwrapper'
 description = 'high level socket and pipe wrappers'
-version = '0.0.2'
+version = '0.0.3'
 requires-python = '>=3.12'
 keywords = ['socket', 'pipe', 'ipc', 'asyncio']
 readme = { file = 'README.md', content-type = 'text/markdown' }
@@ -48,6 +48,7 @@ dev = [
 
 [project.urls]
 homepage = 'https://gitlab.com/ergoithz/socketwrapper'
+repository = 'https://gitlab.com/ergoithz/socketwrapper'
 issue-tracker = 'https://gitlab.com/ergoithz/socketwrapper/-/issues'
 release-notes = 'https://gitlab.com/ergoithz/socketwrapper/-/releases'
 issue-new = 'https://gitlab.com/ergoithz/socketwrapper/-/issues/new'

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/socketwrapper/__init__.py

@@ -23,7 +23,7 @@ from . import _utils, framing, protocols
 __all__ = (
     # type aliases and protocols
     'MessageFraming',
-    'SendPayload',  # FIXME(docs): deprecated since 0.0.2
+    'SendPayload',  # TODO(0.1.0): remove, deprecated since 0.0.2
     'SizedBuffer',
     'SocketLike',
     'SocketOrDescriptor',
@@ -50,7 +50,7 @@ DEFAULT_FRAMING = framing.VarIntBytes
 
 SocketLike = protocols.SocketLike
 MessageFraming = protocols.MessageFraming
-SocketOrDescriptor = SocketLike | protocols.HasFileno | int
+SocketOrDescriptor = protocols.SocketLike | protocols.ExtendedSocketLike | protocols.HasFileno | int
 SizedBuffer = protocols.SizedBuffer
 
 RecvSize = _utils.RecvSize
@@ -58,7 +58,7 @@ SendPayload = _utils.SendPayload
 
 
 class DescriptorSocket:
-    """Generic socket-like accepting any file descriptor (usualy pipes) as input."""
+    """Generic socket-like accepting any file descriptor (usually pipes) as input."""
 
     def __init__(self, fd: int) -> None:
         """Initialize."""
@@ -76,6 +76,16 @@ class DescriptorSocket:
         """Read data from descriptor."""
         return os.read(self._fd, bufsize)
 
+    if sys.version_info < (3, 14):
+        def recv_into(self, buffer: collections.abc.Buffer) -> int:
+            """Read data from descriptor into buffer."""
+            return os.readv(self._fd, (buffer,))
+
+    else:
+        def recv_into(self, buffer: collections.abc.Buffer) -> int:
+            """Read data from descriptor into buffer."""
+            return os.readinto(self._fd, buffer)
+
     def settimeout(self, timeout: float | None) -> None:
         """Set blocking or non-blocking based on timeout being 0 or None."""
         if timeout:
@@ -262,7 +272,7 @@ KSW = typing_extensions.TypeVar('KSW', bound=SocketWriter, default=SocketWriter)
 class MessageWrapper(_utils.ClosingContext, typing_extensions.Generic[R, W, KS]):
     """Base class for message socket wrappers supporting asynchronous operations."""
 
-    _wrapper: typing.ClassVar[type[SocketWrapper]] = SocketWrapper
+    _wrapper = SocketWrapper
     _raw: KS
     framing: MessageFraming[R, W]
 
@@ -293,7 +303,7 @@ class MessageWrapper(_utils.ClosingContext, typing_extensions.Generic[R, W, KS])
 class MessageReader(MessageWrapper[R, typing.Any, KSR], typing_extensions.Generic[R, KSR]):
     """Readable message socket wrapper."""
 
-    _wrapper: typing.ClassVar = SocketReader
+    _wrapper = SocketReader
 
     def recv(self, timeout: float | None = None) -> R:
         """Receive data from socket."""
@@ -307,7 +317,7 @@ class MessageReader(MessageWrapper[R, typing.Any, KSR], typing_extensions.Generi
 class MessageWriter(MessageWrapper[typing.Any, W, KSW], typing_extensions.Generic[W, KSW]):
     """Writable message socket wrapper."""
 
-    _wrapper: typing.ClassVar = SocketWriter
+    _wrapper = SocketWriter
 
     def send(self, data: W, timeout: float | None = None) -> None:
         """Send data to socket."""
@@ -321,7 +331,7 @@ class MessageWriter(MessageWrapper[typing.Any, W, KSW], typing_extensions.Generi
 class MessageDuplex[R, W](MessageWriter[W, SocketDuplex], MessageReader[R, SocketDuplex]):
     """Duplex (both readable and writable) message socket wrapper."""
 
-    _wrapper: typing.ClassVar = SocketDuplex
+    _wrapper = SocketDuplex
 
 
 # TODO: move to namespace
@@ -445,9 +455,9 @@ def _framing(framing: MessageFraming[DR, DW] | bool) -> MessageFraming[DR, DW] |
     return DEFAULT_FRAMING if framing is True else framing if framing else None
 
 
-def _socketlike(sock: SocketOrDescriptor) -> SocketLike:
+def _socketlike[S: SocketLike](sock: S | protocols.HasFileno | int) -> S | socket.socket | DescriptorSocket:
     """Use or initialize socketlike, reporting if it's native or not."""
-    if isinstance(sock, SocketLike):
+    if isinstance(sock, protocols.SocketLike):
         return sock  # socket object, use straight
 
     fd, dup = (sock, False) if isinstance(sock, int) else (sock.fileno(), True)
@@ -459,18 +469,18 @@ def _socketlike(sock: SocketOrDescriptor) -> SocketLike:
         maybe_socket = False
 
     if maybe_socket:
-        sock = socket.socket(fileno=fd)
+        sck = socket.socket(fileno=fd)
         try:
-            sock.getsockopt(socket.SOL_SOCKET, socket.SO_TYPE)
+            sck.getsockopt(socket.SOL_SOCKET, socket.SO_TYPE)
             if dup:  # obj backed by socket, duplicate to not interfere with original ref lifetime
-                sock2 = sock.dup()
-                sock.detach()
-                return sock2
+                sck2 = sck.dup()
+                sck.detach()
+                return sck2
 
         except OSError:
-            sock.detach()
+            sck.detach()
 
         else:
-            return sock  # socket descriptor, use directly
+            return sck  # socket descriptor, use directly
 
     return DescriptorSocket(fd)  # assume pipe-like

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/socketwrapper/_utils.py

@@ -8,6 +8,7 @@ import errno
 import io
 import os
 import socket
+import sys
 import threading
 import time
 import types
@@ -20,6 +21,9 @@ from . import protocols
 RecvSize = collections.abc.Callable[[io.BytesIO], collections.abc.Iterable[int]] | int
 SendPayload = collections.abc.Iterable[protocols.SizedBuffer] | protocols.SizedBuffer
 
+COPY_BUFFER_MINSIZE = 65536  # 64KB
+COPY_BUFFER_THRESHOLD = 512 if os.getenv('PYTHONMALLOC') in {None, 'default', 'pymalloc'} else 0
+
 
 class ClosingContext(abc.ABC):
 
@@ -103,7 +107,7 @@ class ContextPair[A: contextlib.AbstractContextManager, B: contextlib.AbstractCo
 class CrossLock:
     """A higher level lock for both sync and async."""
 
-    __slots__: typing.ClassVar = '_aiolocks', '_aiowaits', '_busy', '_lock'
+    __slots__ = '_aiolocks', '_aiowaits', '_busy', '_lock'
 
     _aiolocks: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Lock]
     _aiowaits: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Future]
@@ -190,41 +194,79 @@ def safe_timeout(sock: protocols.SocketLike, timeout: float | None) -> bool:
     """Check if timeout if supported by setting it and handling ValueError."""
     try:
         sock.settimeout(timeout)
+
     except ValueError:
         return False
+
     return True
 
 
-def reader(
-        sock: protocols.SocketLike, buffer: io.BytesIO, size: RecvSize, *,
+def reader(  # noqa: C901
+        sock: protocols.SocketLike | protocols.ExtendedSocketLike, buffer: io.BytesIO, size: RecvSize, *,
         throttle: bool = False,
         ) -> collections.abc.Iterator[bool]:
-    """Fully consume bytes from the socket."""
+    r"""
+    Fully consume bytes from the socket.
+
+    Implementation notes
+    ====================
+
+    1. We yield `True` for when the consumer should wait for data.
+    2. We rely on ``pymalloc`` speed for small strings (512B) and whenever
+       :meth:`protocols.OptionalSocketLike.recv_into` isn't available.
+    3. We use a copy buffer for bigger reads instead of writing directly via
+       :meth:`io.BytesIO.getbuffer` because of issues with preallocation:
+       - :meth:`io.BytesIO.truncate` doesn't extend https://github.com/python/cpython/issues/71448
+       - ``buffer.write(b'\0' * size)`` is slower.
+       - ``buffer.seek(size - 1, os.SEEK_END) + buffer.write(b'\0')`` breaks smart resizing.
+    4. Our copy buffer can grow by duplicating its size on each partial read
+       until its size is above the source socket-like buffer size.
+
+    """
     buff_write = buffer.write
     sock_recv = sock.recv
+    sock_recv_into = getattr(sock, 'recv_into', None)  # optional
     tell = buffer.tell
     seek = buffer.seek
     seek_end = os.SEEK_END
     sizes = (size,) if isinstance(size, int) else size(buffer)
+    bufskip, bufview = (
+        (COPY_BUFFER_THRESHOLD, memoryview(bytearray(COPY_BUFFER_MINSIZE))) if sock_recv_into else
+        (sys.maxsize, b'')
+        )
     for sz in sizes:
-        if sz > 0:
-            pos = tell()
-            seek(0, seek_end)
-            while True:
-                try:
-                    if not (data := sock_recv(sz)):
+        if sz < 1:
+            continue
+
+        # FIXME: rework implementation if cpython ever fixes https://github.com/python/cpython/issues/71448
+        pos = tell()
+        seek(0, seek_end)
+        while True:
+            try:
+                if sz > bufskip:  # use buffer for long strings (if recv_into is available)
+                    written = sock_recv_into(bufview[:sz])
+                    if written == len(bufview):
+                        chunk, bufview = bufview, memoryview(bytearray(len(bufview) * 2))
+
+                    elif written:
+                        chunk = bufview[:written]
+
+                    else:
                         raise EOFError
 
-                    if (sz := sz - buff_write(data)) < 1:
-                        break
+                elif not (chunk := sock_recv(sz)):  # use pymalloc (faster than buffers for small strings)
+                    raise EOFError
 
-                    if throttle:
-                        yield False
+                if (sz := sz - buff_write(chunk)) < 1:
+                    break
 
-                except BlockingIOError:
-                    yield True
+                if throttle:
+                    yield False
+
+            except BlockingIOError:
+                yield True
 
-            seek(pos)
+        seek(pos)
 
 
 def writer(  # noqa: C901
@@ -244,22 +286,27 @@ def writer(  # noqa: C901
     sock_send = sock.send
     chunks = (data,) if isinstance(data, protocols.SizedBuffer) else data
     for chunk in chunks:
-        if chunk:
-            offset = 0
-            while (offset := safe_write(chunk)) < 1:  # write first chunk without slicing
-                yield True
+        if not chunk:
+            continue
 
-            if offset < len(chunk):  # finished
-                buffer = memoryview(chunk)[offset:]  # turn slicing into zero-copy
-                while True:
-                    if (offset := safe_write(buffer)) < 1:
-                        yield True
+        written = 0
+        while (written := safe_write(chunk)) < 1:  # write first chunk without slicing
+            yield True
+
+        sz = len(chunk) - written
+        if sz < 1:
+            continue
+
+        with memoryview(chunk) as buffer:  # turn slicing into zero-copy
+            while True:
+                if (written := safe_write(buffer[-sz:])) < 1:
+                    yield True
 
-                    elif not (buffer := buffer[offset:]):
-                        break
+                elif (sz := sz - written) < 1:
+                    break
 
-                    elif throttle:
-                        yield False
+                elif throttle:
+                    yield False
 
 
 @contextlib.contextmanager

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/socketwrapper/framing.py

@@ -4,7 +4,6 @@ import abc
 import collections.abc
 import io
 import os
-import typing
 
 from . import _varint, protocols
 
@@ -178,7 +177,7 @@ try:
         packer: PackerTypes
         unpacker: UnpackerTypes
 
-        _typedefs: typing.ClassVar = (
+        _typedefs = (
             # headsize, headskip, varsized, recurse, factor
             *((0, 0, False, False, 1) for _ in range(0x80)),  # 0x00-0x80: fixint (+)
             *((i, 0, False, True, 2) for i in range(16)),  # 0x80-0x90: fixmap

{socketwrapper-0.0.2 → socketwrapper-0.0.3}/socketwrapper/protocols.py

@@ -24,6 +24,13 @@ class SocketLike(typing.Protocol):
     def close(self) -> None: ...
 
 
+@typing.runtime_checkable
+class ExtendedSocketLike(SocketLike, typing.Protocol):
+    """Protocol for optional socket-like object methods accepted by socketwrapper socket classes."""
+
+    def recv_into(self, buffer: collections.abc.Buffer, /) -> bytes: ...
+
+
 @typing.runtime_checkable
 class HasFileno(typing.Protocol):
     """Protocol for objects backed by a file descriptor."""

{socketwrapper-0.0.2 → socketwrapper-0.0.3/socketwrapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketwrapper
-Version: 0.0.2
+Version: 0.0.3
 Summary: high level socket and pipe wrappers
 Author: Felipe A Hernandez
 Author-email: ergoithz@gmail.com
@@ -27,6 +27,7 @@ License: MIT License
         SOFTWARE.
         
 Project-URL: homepage, https://gitlab.com/ergoithz/socketwrapper
+Project-URL: repository, https://gitlab.com/ergoithz/socketwrapper
 Project-URL: issue-tracker, https://gitlab.com/ergoithz/socketwrapper/-/issues
 Project-URL: release-notes, https://gitlab.com/ergoithz/socketwrapper/-/releases
 Project-URL: issue-new, https://gitlab.com/ergoithz/socketwrapper/-/issues/new
@@ -89,12 +90,17 @@ uv pip install 'socketwrapper[msgpack]'
 
 ## Changelog
 
-### v0.0.2 - 2025.11.05
+### 0.0.3 - 2025.11.08
+
+- New: optional support for `recv_into` in socket-like objects.
+- Optimization: recv operations will now use `sock.recv_into` (if available) to reduce memory allocation overhead.
+
+### 0.0.2 - 2025.11.05
 
 - Breaking: `MessageFraming.frames` and `MessageFraming.loads` now receive `io.BytesIO` instead of `bytearray`.
 - New: optional msgpack support (`msgpack` extra).
 - Fix: busy reads no longer blocking asyncio event loop.
-- Typing: expose `SizedBuffer` and deprecate `SendPayload`.
+- Typing: expose `SizedBuffer` and deprecate `SendPayload` (removal expected in `0.1.0`).
 - Typing: `SocketWriter.send` and `SocketWriter.send_async` data is now `SizedBuffer`.
 
 ## Documentation
@@ -103,7 +109,9 @@ None other than this README, life's too short and I'm too busy with real life, i
 
 ### Puggable I/O: SocketLike protocol
 
-The `socketwrapper.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+The `protocols.SocketLike` protocol, a small subset the socket interface, is all what's required for any object to be wrap-able by `socketwrapper`.
+
+Additional methods defined in `protocols.OptionalSocketLike` can be optionally implemented enabling optimized code paths.
 
 ```py
 @typing.runtime_checkable
@@ -115,6 +123,14 @@ class SocketLike(typing.Protocol):
     def recv(self, bufsize: int, /) -> bytes: ...
     def settimeout(self, timeout: float | None, /) -> None: ...
     def close(self) -> None: ...
+
+
+@typing.runtime_checkable
+class OptionalSocketLike(SocketLike, typing.Protocol):
+    """Protocol for optional socket-like object methods accepted by socketwrapper socket classes."""
+
+    def recv_into(self, buffer: collections.abc.Buffer, /) -> bytes: ...
+
 ```
 
 Special attention to: