socketwrapper 0.0.3__tar.gz → 0.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketwrapper
-Version: 0.0.3
+Version: 0.1.0
 Summary: high level socket and pipe wrappers
 Author: Felipe A Hernandez
 Author-email: ergoithz@gmail.com
@@ -32,7 +32,7 @@ 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
 Project-URL: donations, https://ko-fi.com/s26me
-Keywords: socket,pipe,ipc,asyncio
+Keywords: socket,pipe,ipc,asyncio,multiprocessing
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -50,30 +50,49 @@ 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"
+Requires-Dist: uvloop; sys_platform != "win32" and extra == "dev"
 Dynamic: license-file
 
 # socketwrapper
 
-This package provides high level wrappers for sockets and pipes:
+High level wrappers for socket and pipe IO, thread-safe, asyncio-native and supporting multiprocessing.
+
+Features:
 
 - 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).
+- Pluggable message frame and serialization protocols for stream sockets, and serialization for pipes, datagram sockets and Windows message pipes.
+- Pluggable I/O (backed by supported OS descriptors).
 
-Builtin message protocols (framing):
+Built-in message protocols (framing):
 
 - `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.
+- `socketwrapper.framing.MultiprocessingBytes`: [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) bytes.
+- `socketwrapper.framing.Multiprocessing`: [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) pickled data.
+- `socketwrapper.framing.MultiprocessingPipeBytes`: framing for undocumented windows-only `multiprocessing.connection.PipeConnection` bytes, or alias of `socketwrapper.framing.MultiprocessingBytes` in other platforms.
+- `socketwrapper.framing.MultiprocessingPipe`: framing for undocumented windows-only `multiprocessing.connection.PipeConnection` pickled data, or alias of `socketwrapper.framing.Multiprocessing` in other platforms.
+- `socketwrapper.framing.MsgPack` (if `msgpack` is available): unheadered [msgpack](https://pypi.org/project/msgpack/) data.
+
+## Limitations on Windows
+
+> 🛈 Due platform limitations, `sockerwrapper` has to resort on polling for non-overlapped pipes, and also [overlapped](https://learn.microsoft.com/en-us/windows/win32/sync/synchronization-and-overlapped-input-and-output) named pipes when not using [asyncio.ProactorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.ProactorEventLoop). See [Python documentation about asyncio Platform Support](https://docs.python.org/3/library/asyncio-platforms.html#asyncio-platform-support) for details.
+
+> ⚠ Due performance considerations, avoid:
+> - Wrapping anonymous pipes (as returned by [os.pipe](https://docs.python.org/3/library/os.html#os.pipe)) whenever possible.
+> - Asynchronous operations on overlapped named pipes when using [asyncio.SelectorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.SelectorEventLoop).
+
+For your convenience, `socketwrapper.pipe` will create overlapped named pipes on Windows.
+
+[asyncio.ProactorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.ProactorEventLoop) (default on Windows) works with both sockets and [overlapped](https://learn.microsoft.com/en-us/windows/win32/sync/synchronization-and-overlapped-input-and-output) named pipes. Non-overlapped pipes will use polling.
+
+[asyncio.SelectorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.SelectorEventLoop) only natively supports wrapping sockets when manually configured as event loop, all pipes will use polling.
 
 ## Motivation
 
+- I just wanted to send/recv from sockets (and pipes) for IPC without having to dig up 40 years worth of quirks, with and without asyncio.
 - 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.
+- Most implementations got either hardcoded messaging protocols or require a fixed-size header, or just hardcode their own socket initialization like [asyncio.streams](https://docs.python.org/3.14/library/asyncio-stream.html).
 - No implementation was thread-safe between both asyncio and threading realms.
 - No implementation directly supported wrapping multiprocessing Connections into an asyncio-native interface.
 
@@ -90,18 +109,66 @@ uv pip install 'socketwrapper[msgpack]'
 
 ## Changelog
 
+### 0.1.0 - 2026.01.22
+
+#### Breaking
+
+- Type `SendPayload` is no longer exposed.
+- `SizedBuffer` protocol is removed, as it was causing typing annoyances.
+- `SocketLike` protocol now requires `recv_into`, `get_inheritable` and `set_inheritable` implementations.
+
+#### Features
+
+- Added support for Windows sockets and pipes.
+- Added support for datagram sockets.
+- Added support for blind `recv` operations without explicit size (omitted or `None`), returning the first chunk of data for stream sockets, or a whole datagram for datagram sockets whatever its size.
+- Added `asyncio` event loop feature detection with multiple strategies.
+- Added `StreamEOFError` exception (inheriting and replacing [EOFError](https://docs.python.org/3.14/library/exceptions.html#EOFError)), with a `data` attribute exposing partial result.
+- Added `StreamTimeoutError` exception (inheriting and replacing [TimeoutError](https://docs.python.org/3.14/library/exceptions.html#TimeoutError)), with a `data` attribute exposing partial result.
+- Added `StreamCancelledError`: exception (inheriting and replacing [asyncio.CancelledError](https://docs.python.org/3.14/library/asyncio-exceptions.html#asyncio.CancelledError)), with `data` attribute exposing partial result.
+  - For **Python 3.12** this is an alias of [asyncio.CancelledError](https://docs.python.org/3.14/library/asyncio-exceptions.html#asyncio.CancelledError) due [cpython#113848](https://github.com/python/cpython/issues/113848).
+
+
+#### Changes
+
+- For datagram socket-likes (`protocols.ExtendedSocketLike.type` defined as anything other than `socket.SOCK_STREAM`):
+  - Protocol `protocols.SocketLike.recv` requires handing new `flags=socket.MSG_PEEK` parameter.
+  - Protocol `protocols.SocketLike.recv_into` requires handing both new `bufsize=0` and `flags=socket.MSG_PEEK` parameters.
+- Helper `socketwrapper.pipe`creates overlapped named pipes on **Windows** instead of `os.pipe` anonymous pipes to support asynchronous IO.
+- Improved compatibility for third party asyncio event loops ([uvloop](https://github.com/MagicStack/uvloop) tested).
+- SocketWrappers are now serializable by [multiprocessing](https://docs.python.org/3/library/multiprocessing.html).
+- Optimize `framing.MsgPack` headless stream read operation logic.
+
+#### Bugfixes
+
+- `SocketWriter.send` and `SocketWriter.send_async` now return its written byte count.
+- Synchronous recv zero timeout `recv(..., timeout=0)` is now handled consistently.
+- `socketwrapper.socketpair` now always returns full duplex socketwrappers.
+
 ### 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.
+#### Features
+
+- Optional protocol `protocols.ExtendedSocketLike.recv_into`.
+- `recv` operations can 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`.
+#### Breaking
+
+- `MessageFraming.frames` and `MessageFraming.loads` now receive `io.BytesIO` instead of `bytearray`.
+
+#### Features
+- Optional msgpack support (`msgpack` extra).
+
+#### Changes
+
+- `SizedBuffer` type is now exposed and deprecate `SendPayload` (removal expected in `0.1.0`).
+- `SocketWriter.send` and `SocketWriter.send_async` parameter `data` type is now `SizedBuffer`.
+
+#### Bugfixes
+
+- Busy reads no longer blocking asyncio event loop.
 
 ## Documentation
 
@@ -111,31 +178,26 @@ None other than this README, life's too short and I'm too busy with real life, i
 
 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
 class SocketLike(typing.Protocol):
     """Protocol for socket-like objects accepted by socketwrapper socket classes."""
 
+    def close(self) -> None: ...
     def fileno(self) -> int: ...
+    def recv(self, bufsize: int, flags: int = 0, /) -> bytes: ...
+    def recv_into(self, buffer: collections.abc.Buffer, nbytes: int = 0, flags: int = 0, /) -> int: ...
     def send(self, data: collections.abc.Buffer, /) -> int: ...
-    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: ...
+    def get_inheritable(self) -> bool: ...
+    def set_inheritable(self, inheritable: bool, /) -> None: ...
 
 ```
 
 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) 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.
+- Unless `SocketLike.type` is [socket.SOCK_STREAM](https://docs.python.org/3.14/library/socket.html#socket.SOCK_STREAM) (or missing), [recv](https://docs.python.org/3.14/library/socket.html#socket.socket.recv) and [recv_into](https://docs.python.org/3.14/library/socket.html#socket.socket.recv_into) `flags` must support `socket.MSG_PEEK`.
 
 ## Usage
 
@@ -355,3 +417,46 @@ Sending 1048576 bytes!
 > 100%
 Received 1048576 bytes!
 ```
+
+#### Connection handling (`socket.accept`)
+
+The connection concept is purposely left out of this library (may change in the future), reasoning:
+- Already existing methods for accepting connections: [socket.accept](https://docs.python.org/3/library/socket.html#socket.socket.accept) and [loop.sock_accept](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.loop.sock_accept), both simple and standard.
+- `socketwrapper` can be already used to wrap the connected socket (thread safe and way simpler than [asyncio Streaming Protocols](https://docs.python.org/3.14/library/asyncio-protocol.html#streaming-protocols)).
+- Server sockets aren't usually shared outside the connection loop between sync and async contexts (unnecessary `CrossLock`).
+
+So just wrap accepted connection sockets with `socketwrapper.SocketDuplex`.
+
+```python
+import asyncio
+import socket
+import socketwrapper
+
+async def listen(server: socket.socket) -> None:
+    loop = asyncio.get_running_loop()
+    while True:
+        sock, addr = await loop.sock_accept(server)
+        with socketwrapper.SocketDuplex(sock) as sock:
+            await sock.send_async(b'message')
+
+async def main() -> None:
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind(('localhost', 8080))
+    server.listen(2)
+    server.setblocking(False)  # asyncio requires a non-blocking server
+    listener = asyncio.create_task(listen(server))
+
+    client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    client.connect(('localhost', 8080))
+    with socketwrapper.SocketDuplex(client) as client:
+        print(await client.recv_async())
+
+    listener.cancel()  # stop connection handler
+    await asyncio.gather(listener, return_exceptions=True)
+    server.close()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```

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

@@ -1,24 +1,43 @@
 # socketwrapper
 
-This package provides high level wrappers for sockets and pipes:
+High level wrappers for socket and pipe IO, thread-safe, asyncio-native and supporting multiprocessing.
+
+Features:
 
 - 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).
+- Pluggable message frame and serialization protocols for stream sockets, and serialization for pipes, datagram sockets and Windows message pipes.
+- Pluggable I/O (backed by supported OS descriptors).
 
-Builtin message protocols (framing):
+Built-in message protocols (framing):
 
 - `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.
+- `socketwrapper.framing.MultiprocessingBytes`: [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) bytes.
+- `socketwrapper.framing.Multiprocessing`: [multiprocessing.connection.Connection](https://docs.python.org/3.14/library/multiprocessing.html#connection-objects) pickled data.
+- `socketwrapper.framing.MultiprocessingPipeBytes`: framing for undocumented windows-only `multiprocessing.connection.PipeConnection` bytes, or alias of `socketwrapper.framing.MultiprocessingBytes` in other platforms.
+- `socketwrapper.framing.MultiprocessingPipe`: framing for undocumented windows-only `multiprocessing.connection.PipeConnection` pickled data, or alias of `socketwrapper.framing.Multiprocessing` in other platforms.
+- `socketwrapper.framing.MsgPack` (if `msgpack` is available): unheadered [msgpack](https://pypi.org/project/msgpack/) data.
+
+## Limitations on Windows
+
+> 🛈 Due platform limitations, `sockerwrapper` has to resort on polling for non-overlapped pipes, and also [overlapped](https://learn.microsoft.com/en-us/windows/win32/sync/synchronization-and-overlapped-input-and-output) named pipes when not using [asyncio.ProactorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.ProactorEventLoop). See [Python documentation about asyncio Platform Support](https://docs.python.org/3/library/asyncio-platforms.html#asyncio-platform-support) for details.
+
+> ⚠ Due performance considerations, avoid:
+> - Wrapping anonymous pipes (as returned by [os.pipe](https://docs.python.org/3/library/os.html#os.pipe)) whenever possible.
+> - Asynchronous operations on overlapped named pipes when using [asyncio.SelectorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.SelectorEventLoop).
+
+For your convenience, `socketwrapper.pipe` will create overlapped named pipes on Windows.
+
+[asyncio.ProactorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.ProactorEventLoop) (default on Windows) works with both sockets and [overlapped](https://learn.microsoft.com/en-us/windows/win32/sync/synchronization-and-overlapped-input-and-output) named pipes. Non-overlapped pipes will use polling.
+
+[asyncio.SelectorEventLoop](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.SelectorEventLoop) only natively supports wrapping sockets when manually configured as event loop, all pipes will use polling.
 
 ## Motivation
 
+- I just wanted to send/recv from sockets (and pipes) for IPC without having to dig up 40 years worth of quirks, with and without asyncio.
 - 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.
+- Most implementations got either hardcoded messaging protocols or require a fixed-size header, or just hardcode their own socket initialization like [asyncio.streams](https://docs.python.org/3.14/library/asyncio-stream.html).
 - No implementation was thread-safe between both asyncio and threading realms.
 - No implementation directly supported wrapping multiprocessing Connections into an asyncio-native interface.
 
@@ -35,18 +54,66 @@ uv pip install 'socketwrapper[msgpack]'
 
 ## Changelog
 
+### 0.1.0 - 2026.01.22
+
+#### Breaking
+
+- Type `SendPayload` is no longer exposed.
+- `SizedBuffer` protocol is removed, as it was causing typing annoyances.
+- `SocketLike` protocol now requires `recv_into`, `get_inheritable` and `set_inheritable` implementations.
+
+#### Features
+
+- Added support for Windows sockets and pipes.
+- Added support for datagram sockets.
+- Added support for blind `recv` operations without explicit size (omitted or `None`), returning the first chunk of data for stream sockets, or a whole datagram for datagram sockets whatever its size.
+- Added `asyncio` event loop feature detection with multiple strategies.
+- Added `StreamEOFError` exception (inheriting and replacing [EOFError](https://docs.python.org/3.14/library/exceptions.html#EOFError)), with a `data` attribute exposing partial result.
+- Added `StreamTimeoutError` exception (inheriting and replacing [TimeoutError](https://docs.python.org/3.14/library/exceptions.html#TimeoutError)), with a `data` attribute exposing partial result.
+- Added `StreamCancelledError`: exception (inheriting and replacing [asyncio.CancelledError](https://docs.python.org/3.14/library/asyncio-exceptions.html#asyncio.CancelledError)), with `data` attribute exposing partial result.
+  - For **Python 3.12** this is an alias of [asyncio.CancelledError](https://docs.python.org/3.14/library/asyncio-exceptions.html#asyncio.CancelledError) due [cpython#113848](https://github.com/python/cpython/issues/113848).
+
+
+#### Changes
+
+- For datagram socket-likes (`protocols.ExtendedSocketLike.type` defined as anything other than `socket.SOCK_STREAM`):
+  - Protocol `protocols.SocketLike.recv` requires handing new `flags=socket.MSG_PEEK` parameter.
+  - Protocol `protocols.SocketLike.recv_into` requires handing both new `bufsize=0` and `flags=socket.MSG_PEEK` parameters.
+- Helper `socketwrapper.pipe`creates overlapped named pipes on **Windows** instead of `os.pipe` anonymous pipes to support asynchronous IO.
+- Improved compatibility for third party asyncio event loops ([uvloop](https://github.com/MagicStack/uvloop) tested).
+- SocketWrappers are now serializable by [multiprocessing](https://docs.python.org/3/library/multiprocessing.html).
+- Optimize `framing.MsgPack` headless stream read operation logic.
+
+#### Bugfixes
+
+- `SocketWriter.send` and `SocketWriter.send_async` now return its written byte count.
+- Synchronous recv zero timeout `recv(..., timeout=0)` is now handled consistently.
+- `socketwrapper.socketpair` now always returns full duplex socketwrappers.
+
 ### 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.
+#### Features
+
+- Optional protocol `protocols.ExtendedSocketLike.recv_into`.
+- `recv` operations can 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`.
+#### Breaking
+
+- `MessageFraming.frames` and `MessageFraming.loads` now receive `io.BytesIO` instead of `bytearray`.
+
+#### Features
+- Optional msgpack support (`msgpack` extra).
+
+#### Changes
+
+- `SizedBuffer` type is now exposed and deprecate `SendPayload` (removal expected in `0.1.0`).
+- `SocketWriter.send` and `SocketWriter.send_async` parameter `data` type is now `SizedBuffer`.
+
+#### Bugfixes
+
+- Busy reads no longer blocking asyncio event loop.
 
 ## Documentation
 
@@ -56,31 +123,26 @@ None other than this README, life's too short and I'm too busy with real life, i
 
 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
 class SocketLike(typing.Protocol):
     """Protocol for socket-like objects accepted by socketwrapper socket classes."""
 
+    def close(self) -> None: ...
     def fileno(self) -> int: ...
+    def recv(self, bufsize: int, flags: int = 0, /) -> bytes: ...
+    def recv_into(self, buffer: collections.abc.Buffer, nbytes: int = 0, flags: int = 0, /) -> int: ...
     def send(self, data: collections.abc.Buffer, /) -> int: ...
-    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: ...
+    def get_inheritable(self) -> bool: ...
+    def set_inheritable(self, inheritable: bool, /) -> None: ...
 
 ```
 
 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) 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.
+- Unless `SocketLike.type` is [socket.SOCK_STREAM](https://docs.python.org/3.14/library/socket.html#socket.SOCK_STREAM) (or missing), [recv](https://docs.python.org/3.14/library/socket.html#socket.socket.recv) and [recv_into](https://docs.python.org/3.14/library/socket.html#socket.socket.recv_into) `flags` must support `socket.MSG_PEEK`.
 
 ## Usage
 
@@ -300,3 +362,46 @@ Sending 1048576 bytes!
 > 100%
 Received 1048576 bytes!
 ```
+
+#### Connection handling (`socket.accept`)
+
+The connection concept is purposely left out of this library (may change in the future), reasoning:
+- Already existing methods for accepting connections: [socket.accept](https://docs.python.org/3/library/socket.html#socket.socket.accept) and [loop.sock_accept](https://docs.python.org/3.14/library/asyncio-eventloop.html#asyncio.loop.sock_accept), both simple and standard.
+- `socketwrapper` can be already used to wrap the connected socket (thread safe and way simpler than [asyncio Streaming Protocols](https://docs.python.org/3.14/library/asyncio-protocol.html#streaming-protocols)).
+- Server sockets aren't usually shared outside the connection loop between sync and async contexts (unnecessary `CrossLock`).
+
+So just wrap accepted connection sockets with `socketwrapper.SocketDuplex`.
+
+```python
+import asyncio
+import socket
+import socketwrapper
+
+async def listen(server: socket.socket) -> None:
+    loop = asyncio.get_running_loop()
+    while True:
+        sock, addr = await loop.sock_accept(server)
+        with socketwrapper.SocketDuplex(sock) as sock:
+            await sock.send_async(b'message')
+
+async def main() -> None:
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind(('localhost', 8080))
+    server.listen(2)
+    server.setblocking(False)  # asyncio requires a non-blocking server
+    listener = asyncio.create_task(listen(server))
+
+    client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    client.connect(('localhost', 8080))
+    with socketwrapper.SocketDuplex(client) as client:
+        print(await client.recv_async())
+
+    listener.cancel()  # stop connection handler
+    await asyncio.gather(listener, return_exceptions=True)
+    server.close()
+
+if __name__ == '__main__':
+    asyncio.run(main())
+
+```

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

@@ -5,9 +5,9 @@ build-backend = 'setuptools.build_meta'
 [project]
 name = 'socketwrapper'
 description = 'high level socket and pipe wrappers'
-version = '0.0.3'
+version = '0.1.0'
 requires-python = '>=3.12'
-keywords = ['socket', 'pipe', 'ipc', 'asyncio']
+keywords = ['socket', 'pipe', 'ipc', 'asyncio', 'multiprocessing']
 readme = { file = 'README.md', content-type = 'text/markdown' }
 license = { file = 'LICENSE' }
 classifiers = [
@@ -43,7 +43,7 @@ dev = [
     'msgpack',
     'ruff',
     'wheel',
-    'yapf',
+    'uvloop ; sys_platform != "win32"',
     ]
 
 [project.urls]
@@ -61,9 +61,22 @@ packages = [
 zip-safe = true
 
 [tool.ruff]
+exclude = [
+    'examples/*',
+    ]
 line-length = 120
 target-version = "py312"
 
+[tool.coverage.run]
+source = [
+    "socketwrapper",
+    ]
+branch = true
+relative_files = true
+
+[tool.coverage.report]
+fail_under = 90
+
 [tool.ruff.lint]
 preview = true
 select = [
@@ -136,6 +149,7 @@ ignore = [
     'SIM105',  # replacing every except/pass with contextlib.suppress
     # Maintainability
     'RUF022',  # unordered __all__ for annotated groups
+    'RUF067',  # reexport-only __init__ (WTF!)
     ]
 
 [tool.ruff.lint.flake8-errmsg]
@@ -161,6 +175,9 @@ convention = 'pep257'
 inline-quotes = 'single'
 multiline-quotes = 'single'
 
+[tool.ruff.format]
+quote-style = 'single'
+
 [tool.yapf]
 indent_closing_brackets = true
 join_multiple_lines = false