socketwrapper 0.0.1__tar.gz → 0.0.3__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: socketwrapper
-Version: 0.0.1
-Summary: high level socket and pipe wrapper
+Version: 0.0.3
+Summary: high level socket and pipe wrappers
 Author: Felipe A Hernandez
 Author-email: ergoithz@gmail.com
 License: MIT License
@@ -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
@@ -41,9 +42,12 @@ Classifier: Topic :: System :: Networking
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: typing-extensions>=4.15; python_version < "3.13"
+Requires-Dist: typing-extensions>=4.6; python_version < "3.13"
+Provides-Extra: msgpack
+Requires-Dist: msgpack; extra == "msgpack"
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
+Requires-Dist: msgpack; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
 Requires-Dist: yapf; extra == "dev"
@@ -52,24 +56,26 @@ Dynamic: license-file
 # socketwrapper
 
 This package provides high level wrappers for sockets and pipes:
-- Thread-safe within both and between threads and asyncio realms.
-- Managed sync recv and send operations with timeouts.
-- Native asyncio recv_async and send_async operations.
-- Pluggable message protocol (headered variable length data) supporting
-  header parsing, serialization and deserialization.
-- Pluggable I/O protocol (file descriptor still required due asyncio).
 
-## Motivation
+- Thread-safe within both threads and asyncio realms, and between them.
+- Managed sync `recv` and `send` operations with timeouts.
+- Native asyncio `recv_async` and `send_async` operations.
+- Pluggable message protocol (headered variable length data) supporting variable-length header parsing, payload serialization and deserialization.
+- Pluggable I/O protocol (OS file descriptor still required).
 
-There aren't a ton of high level asyncio socket wrappers out there providing
-all we need for IPC: header/payload logic and support for both sockets and pipes.
+Builtin message protocols (framing):
 
-Most implementations either don't have pluggable messaging protocols or it
-doesn't support variable-size headers.
+- `socketwrapper.framing.VarIntBytes`: varint-headered bytes (default with `framing=True`).
+- `socketwrapper.framing.MultiprocessingBytes` (if platform is supported): [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) bytes.
+- `socketwrapper.framing.Multiprocessing` (if platform is supported): [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) pickled data.
+- `socketwrapper.framing.MsgPack` (if `msgpack` is available): unheadered [msgpack](https://pypi.org/project/msgpack/) data stream.
 
-No other implementation is thread-safe across both asyncio and threading realms.
+## Motivation
 
-No other implementation directly supports wrapping multiprocessing Connections.
+- There aren't a ton of high level asyncio socket wrappers out there providing all we need for IPC: header/payload message logic and support for both sockets and pipes.
+- Most implementations got either hardcoded messaging protocols or require a fixed-size header.
+- No implementation was thread-safe between both asyncio and threading realms.
+- No implementation directly supported wrapping multiprocessing Connections into an asyncio-native interface.
 
 ## Installation
 
@@ -77,18 +83,35 @@ No other implementation directly supports wrapping multiprocessing Connections.
 uv pip install socketwrapper
 ```
 
+Or with optional [msgpack](https://pypi.org/project/msgpack/) support.
+```sh
+uv pip install 'socketwrapper[msgpack]'
+```
+
+## Changelog
+
+### 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` (removal expected in `0.1.0`).
+- Typing: `SocketWriter.send` and `SocketWriter.send_async` data is now `SizedBuffer`.
+
 ## Documentation
 
-None other than this README, life's too short and I'm too busy with real life,
-if you need better documentation consider donating to
-[my ko-fi](https://ko-fi.com/s26me) stating that as the tip message,
-check out how my docs look like at [mstache docs](https://mstache.readthedocs.io/en/latest/)
-and [uactor docs](https://mstache.readthedocs.io/en/latest/).
+None other than this README, life's too short and I'm too busy with real life, if you need better documentation consider donating to [my ko-fi](https://ko-fi.com/s26me) stating that as a tip message, check out how my docs look like at [mstache docs](https://mstache.readthedocs.io/en/latest/) and [uactor docs](https://mstache.readthedocs.io/en/latest/).
 
 ### Puggable I/O: SocketLike protocol
 
-The `socketwrapper.SocketLike` protocol, an 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
@@ -100,18 +123,19 @@ 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:
-- [fileno](https://docs.python.org/3.14/library/socket.html#socket.socket.fileno)
-  has to be a valid OS file descriptor.
-- [settimeout](https://docs.python.org/3.14/library/socket.html#socket.socket.settimeout)
-  only requires support for `settimeout(.0)` (
-  [non-blocking semantics](https://docs.python.org/3.14/library/socket.html#notes-on-socket-timeouts)
-  ), raising [ValueError](https://docs.python.org/3.14/library/exceptions.html#ValueError)
-  for any other value is fully supported in which case
-  [selectors.DefaultSelector](https://docs.python.org/3.14/library/selectors.html#selectors.DefaultSelector)
-  will be used for synchronous operations.
+- [fileno](https://docs.python.org/3.14/library/socket.html#socket.socket.fileno) has to be a valid OS file descriptor.
+- [settimeout](https://docs.python.org/3.14/library/socket.html#socket.socket.settimeout) must support `settimeout(.0)` ([non-blocking semantics](https://docs.python.org/3.14/library/socket.html#notes-on-socket-timeouts)), raising [ValueError](https://docs.python.org/3.14/library/exceptions.html#ValueError) for any other value will be handled, relying on [selectors.DefaultSelector](https://docs.python.org/3.14/library/selectors.html#selectors.DefaultSelector) for synchronous operations.
 
 ## Usage
 
@@ -131,11 +155,31 @@ with socketwrapper.pipe(framing=True) as (parent_reader, child_writer):
     else:
         child_writer.send(b'Hello world!')
 ```
-
 ```
 Message b'Hello world!' received
 ```
 
+### Simple IPC with pipe using msgpack
+
+```python
+import os
+import socketwrapper
+import socketwrapper.framing as framing
+
+with socketwrapper.pipe(framing=framing.MsgPack()) as (parent_reader, child_writer):
+    child_writer.inheritable = True
+    child_pid = os.fork()  # replace with your own process fork/spawn logic
+    child_writer.inheritable = False  # important, prevent socket leaks!
+
+    if child_pid:
+        print(f'Message {parent_reader.recv()!r} received')
+    else:
+        child_writer.send({'data': b'Hello world!'})
+```
+```
+Message {'data': b'Hello world!'} received
+```
+
 ### Simple asyncio IPC with pipe
 
 ```python
@@ -156,7 +200,6 @@ with socketwrapper.pipe(framing=True) as (parent_reader, child_writer):
 
     asyncio.run(parent(parent_reader) if child_pid else child(child_writer))
 ```
-
 ```
 Message b'Hello world!' received
 ```
@@ -180,7 +223,6 @@ with socketwrapper.socketpair(framing=True) as (parent_duplex, child_duplex):
         print(f'Message {child_duplex.recv()!r} received in child')
         child_duplex.send(b'Hello parent!')
 ```
-
 ```
 Message b'Hello child!' received in child
 Message b'Hello parent!' received in parent
@@ -204,25 +246,46 @@ def child(conn: multiprocessing.connection.Connection) -> None:
 
     asyncio.run(main())
 
-parent_conn, child_conn = multiprocessing.Pipe()
-with parent_conn, child_conn:
-    child_process = multiprocessing.Process(target=child, args=(child_conn,))
-    child_process.start()
+if __name__ == '__main__':
+    parent_conn, child_conn = multiprocessing.Pipe()
+    with parent_conn, child_conn:
+        child_process = multiprocessing.Process(target=child, args=(child_conn,))
+        child_process.start()
 
-    parent_conn.send_bytes(b'Hello child!')
-    print(f'Message {parent_conn.recv_bytes()!r} received in parent')
-    child_process.join(1)
+        parent_conn.send_bytes(b'Hello child!')
+        print(f'Message {parent_conn.recv_bytes()!r} received in parent')
+        child_process.join(1)
 ```
-
 ```
 Message b'Hello child!' received in child
 Message b'Hello parent!' received in parent
 ```
 
+### Socketwrapper for cross-interpreter communication
+
+```py
+import concurrent.futures
+import socketwrapper
+
+def child(child_fileno: int) -> None:
+    child_writer = socketwrapper.MessageWriter(child_fileno)
+    child_writer.send(b'Hello World')
+
+if __name__ == '__main__':
+    with (socketwrapper.pipe(framing=True) as (parent_reader, child_writer),
+          concurrent.futures.InterpreterPoolExecutor() as pool):
+        pool.submit(child, child_writer.fileno())
+        print(f'Message {parent_reader.recv()!r} received')
+```
+```
+Message b'Hello World' received
+```
+
 ### Custom socketwrapper framing with progress
 
 ```py
 import collections.abc
+import io
 import itertools
 import os
 import socketwrapper
@@ -246,7 +309,7 @@ def progress(arrow: str, size: int, min_chunk: int = 1024) -> collections.abc.Ge
 class ProgressFraming(socketwrapper.framing.VarIntBytes):
 
     @classmethod
-    def frames(cls, buffer: bytearray) -> collections.abc.Generator[int, None, None]:
+    def frames(cls, buffer: io.BytesIO) -> collections.abc.Generator[int, None, None]:
         frames = super().frames(buffer)
         yield from itertools.islice(frames, 2)
         yield from progress('>', next(frames))

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

@@ -1,24 +1,26 @@
 # socketwrapper
 
 This package provides high level wrappers for sockets and pipes:
-- Thread-safe within both and between threads and asyncio realms.
-- Managed sync recv and send operations with timeouts.
-- Native asyncio recv_async and send_async operations.
-- Pluggable message protocol (headered variable length data) supporting
-  header parsing, serialization and deserialization.
-- Pluggable I/O protocol (file descriptor still required due asyncio).
 
-## Motivation
+- Thread-safe within both threads and asyncio realms, and between them.
+- Managed sync `recv` and `send` operations with timeouts.
+- Native asyncio `recv_async` and `send_async` operations.
+- Pluggable message protocol (headered variable length data) supporting variable-length header parsing, payload serialization and deserialization.
+- Pluggable I/O protocol (OS file descriptor still required).
 
-There aren't a ton of high level asyncio socket wrappers out there providing
-all we need for IPC: header/payload logic and support for both sockets and pipes.
+Builtin message protocols (framing):
 
-Most implementations either don't have pluggable messaging protocols or it
-doesn't support variable-size headers.
+- `socketwrapper.framing.VarIntBytes`: varint-headered bytes (default with `framing=True`).
+- `socketwrapper.framing.MultiprocessingBytes` (if platform is supported): [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) bytes.
+- `socketwrapper.framing.Multiprocessing` (if platform is supported): [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) pickled data.
+- `socketwrapper.framing.MsgPack` (if `msgpack` is available): unheadered [msgpack](https://pypi.org/project/msgpack/) data stream.
 
-No other implementation is thread-safe across both asyncio and threading realms.
+## Motivation
 
-No other implementation directly supports wrapping multiprocessing Connections.
+- There aren't a ton of high level asyncio socket wrappers out there providing all we need for IPC: header/payload message logic and support for both sockets and pipes.
+- Most implementations got either hardcoded messaging protocols or require a fixed-size header.
+- No implementation was thread-safe between both asyncio and threading realms.
+- No implementation directly supported wrapping multiprocessing Connections into an asyncio-native interface.
 
 ## Installation
 
@@ -26,18 +28,35 @@ No other implementation directly supports wrapping multiprocessing Connections.
 uv pip install socketwrapper
 ```
 
+Or with optional [msgpack](https://pypi.org/project/msgpack/) support.
+```sh
+uv pip install 'socketwrapper[msgpack]'
+```
+
+## Changelog
+
+### 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` (removal expected in `0.1.0`).
+- Typing: `SocketWriter.send` and `SocketWriter.send_async` data is now `SizedBuffer`.
+
 ## Documentation
 
-None other than this README, life's too short and I'm too busy with real life,
-if you need better documentation consider donating to
-[my ko-fi](https://ko-fi.com/s26me) stating that as the tip message,
-check out how my docs look like at [mstache docs](https://mstache.readthedocs.io/en/latest/)
-and [uactor docs](https://mstache.readthedocs.io/en/latest/).
+None other than this README, life's too short and I'm too busy with real life, if you need better documentation consider donating to [my ko-fi](https://ko-fi.com/s26me) stating that as a tip message, check out how my docs look like at [mstache docs](https://mstache.readthedocs.io/en/latest/) and [uactor docs](https://mstache.readthedocs.io/en/latest/).
 
 ### Puggable I/O: SocketLike protocol
 
-The `socketwrapper.SocketLike` protocol, an 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
@@ -49,18 +68,19 @@ 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:
-- [fileno](https://docs.python.org/3.14/library/socket.html#socket.socket.fileno)
-  has to be a valid OS file descriptor.
-- [settimeout](https://docs.python.org/3.14/library/socket.html#socket.socket.settimeout)
-  only requires support for `settimeout(.0)` (
-  [non-blocking semantics](https://docs.python.org/3.14/library/socket.html#notes-on-socket-timeouts)
-  ), raising [ValueError](https://docs.python.org/3.14/library/exceptions.html#ValueError)
-  for any other value is fully supported in which case
-  [selectors.DefaultSelector](https://docs.python.org/3.14/library/selectors.html#selectors.DefaultSelector)
-  will be used for synchronous operations.
+- [fileno](https://docs.python.org/3.14/library/socket.html#socket.socket.fileno) has to be a valid OS file descriptor.
+- [settimeout](https://docs.python.org/3.14/library/socket.html#socket.socket.settimeout) must support `settimeout(.0)` ([non-blocking semantics](https://docs.python.org/3.14/library/socket.html#notes-on-socket-timeouts)), raising [ValueError](https://docs.python.org/3.14/library/exceptions.html#ValueError) for any other value will be handled, relying on [selectors.DefaultSelector](https://docs.python.org/3.14/library/selectors.html#selectors.DefaultSelector) for synchronous operations.
 
 ## Usage
 
@@ -80,11 +100,31 @@ with socketwrapper.pipe(framing=True) as (parent_reader, child_writer):
     else:
         child_writer.send(b'Hello world!')
 ```
-
 ```
 Message b'Hello world!' received
 ```
 
+### Simple IPC with pipe using msgpack
+
+```python
+import os
+import socketwrapper
+import socketwrapper.framing as framing
+
+with socketwrapper.pipe(framing=framing.MsgPack()) as (parent_reader, child_writer):
+    child_writer.inheritable = True
+    child_pid = os.fork()  # replace with your own process fork/spawn logic
+    child_writer.inheritable = False  # important, prevent socket leaks!
+
+    if child_pid:
+        print(f'Message {parent_reader.recv()!r} received')
+    else:
+        child_writer.send({'data': b'Hello world!'})
+```
+```
+Message {'data': b'Hello world!'} received
+```
+
 ### Simple asyncio IPC with pipe
 
 ```python
@@ -105,7 +145,6 @@ with socketwrapper.pipe(framing=True) as (parent_reader, child_writer):
 
     asyncio.run(parent(parent_reader) if child_pid else child(child_writer))
 ```
-
 ```
 Message b'Hello world!' received
 ```
@@ -129,7 +168,6 @@ with socketwrapper.socketpair(framing=True) as (parent_duplex, child_duplex):
         print(f'Message {child_duplex.recv()!r} received in child')
         child_duplex.send(b'Hello parent!')
 ```
-
 ```
 Message b'Hello child!' received in child
 Message b'Hello parent!' received in parent
@@ -153,25 +191,46 @@ def child(conn: multiprocessing.connection.Connection) -> None:
 
     asyncio.run(main())
 
-parent_conn, child_conn = multiprocessing.Pipe()
-with parent_conn, child_conn:
-    child_process = multiprocessing.Process(target=child, args=(child_conn,))
-    child_process.start()
+if __name__ == '__main__':
+    parent_conn, child_conn = multiprocessing.Pipe()
+    with parent_conn, child_conn:
+        child_process = multiprocessing.Process(target=child, args=(child_conn,))
+        child_process.start()
 
-    parent_conn.send_bytes(b'Hello child!')
-    print(f'Message {parent_conn.recv_bytes()!r} received in parent')
-    child_process.join(1)
+        parent_conn.send_bytes(b'Hello child!')
+        print(f'Message {parent_conn.recv_bytes()!r} received in parent')
+        child_process.join(1)
 ```
-
 ```
 Message b'Hello child!' received in child
 Message b'Hello parent!' received in parent
 ```
 
+### Socketwrapper for cross-interpreter communication
+
+```py
+import concurrent.futures
+import socketwrapper
+
+def child(child_fileno: int) -> None:
+    child_writer = socketwrapper.MessageWriter(child_fileno)
+    child_writer.send(b'Hello World')
+
+if __name__ == '__main__':
+    with (socketwrapper.pipe(framing=True) as (parent_reader, child_writer),
+          concurrent.futures.InterpreterPoolExecutor() as pool):
+        pool.submit(child, child_writer.fileno())
+        print(f'Message {parent_reader.recv()!r} received')
+```
+```
+Message b'Hello World' received
+```
+
 ### Custom socketwrapper framing with progress
 
 ```py
 import collections.abc
+import io
 import itertools
 import os
 import socketwrapper
@@ -195,7 +254,7 @@ def progress(arrow: str, size: int, min_chunk: int = 1024) -> collections.abc.Ge
 class ProgressFraming(socketwrapper.framing.VarIntBytes):
 
     @classmethod
-    def frames(cls, buffer: bytearray) -> collections.abc.Generator[int, None, None]:
+    def frames(cls, buffer: io.BytesIO) -> collections.abc.Generator[int, None, None]:
         frames = super().frames(buffer)
         yield from itertools.islice(frames, 2)
         yield from progress('>', next(frames))

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

@@ -4,8 +4,8 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'socketwrapper'
-description = 'high level socket and pipe wrapper'
-version = '0.0.1'
+description = 'high level socket and pipe wrappers'
+version = '0.0.3'
 requires-python = '>=3.12'
 keywords = ['socket', 'pipe', 'ipc', 'asyncio']
 readme = { file = 'README.md', content-type = 'text/markdown' }
@@ -22,7 +22,7 @@ authors = [
     { name = 'Felipe A Hernandez' },
     { email = 'ergoithz@gmail.com' },
     ]
-dependencies = ['typing-extensions >= 4.15 ; python_version < "3.13"']
+dependencies = ['typing-extensions >= 4.6 ; python_version < "3.13"']
 
 [tool.setuptools.package-data]
 socketwrapper = ["py.typed"]
@@ -37,8 +37,10 @@ exclude = [
 pythonVersion = '3.12'
 
 [project.optional-dependencies]
+msgpack = ['msgpack']
 dev = [
     'coverage',
+    'msgpack',
     'ruff',
     'wheel',
     'yapf',
@@ -46,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'