Replace return True/False with try/except (fixes #194)

[parth-soni07]

What was wrong?

Issue #194

How was it fixed?

• TCP listen() – Raise OpenConnectionError on missing/invalid port or failed start instead of returning False; added tcp_port_str is None check before int() for type safety.
• IListener interface – In abc.py, listen() return type changed from -> bool to -> None; docstring updated to describe raising on failure.
• All IListener implementations – TCP, QUIC, WebSocket, CircuitV2: listen() now returns None and raises on failure; removed return True.
• Mplex stream deadlines – set_deadline(), set_read_deadline(),set_write_deadline() raise ValueError for negative ttl instead of returning False; ABC set_deadline() updated to -> None.
• BasicHost set_stream_handler() – Validate input: raise HostException for empty/whitespace protocol_id or None handler.
• Docstrings – Yamux/QUIC stream set_deadline() and swarm register_notifee() docstrings updated so they no longer claim a False return.
• Tests – TCP: test missing-port raises; mplex: use pytest.raises(ValueError) for invalid ttl; host: test empty protocol_id and None handler; QUIC/websocket: drop success = await listener.listen() / assert success.
• Example – example_mplex_timeouts.py uses try/except ValueError for invalid ttl instead of checking a return value.
• Lint – E501 in tcp.py fixed by shortening the :raises docstring line; test handler made async to satisfy THandler.

Refactors selected APIs to raise exceptions on failure instead of returning True/False, so callers use try/except instead of checking return values.

Summary

• Success: Method returns nothing (implicit None).
• Failure: Method raises an exception; callers use try/except.

Changes

1. Listener listen() (IListener and all implementations)

• Before: async def listen(...) -> bool returned True on success, False on failure.
• After: async def listen(...) -> None; raises (e.g. OpenConnectionError, QUICListenError) on failure.

# Before
success = await listener.listen(maddr, nursery)
assert success

# After
await listener.listen(maddr, nursery)  # raises on failure

Updated: TCP, QUIC, WebSocket, CircuitV2 listeners + ABC IListener in libp2p/abc.py.

2. Mplex stream deadline methods

• Before: set_deadline(), set_read_deadline(), set_write_deadline() returned False for invalid ttl (e.g. negative).
• After: Return None; raise ValueError for invalid ttl.

# Before
if not stream.set_deadline(-1):
    handle_error()

# After
try:
    stream.set_deadline(5.0)
except ValueError:
    handle_error()

Updated: libp2p/stream_muxer/mplex/mplex_stream.py + ABC in libp2p/abc.py.

3. BasicHost set_stream_handler()

• Before: Accepted empty protocol_id or None handler; docstring said "return true if successful".
• After: Validates input; raises HostException for empty/whitespace protocol_id or None handler. No boolean return.

# After (caller)
host.set_stream_handler("/my/protocol", handler)  # raises HostException if invalid

Updated: libp2p/host/basic_host.py.

4. TCP transport listen()

• Before: Returned False on missing/invalid port or failed start.
• After: Raises OpenConnectionError with a clear message. Docstring shortened for line length (E501).

Updated: libp2p/transport/tcp/tcp.py.

5. Docstrings only

• Yamux/QUIC stream set_deadline() and swarm register_notifee(): docstrings updated so they no longer claim a False return.
• Mplex is_closed: docstring clarified.

Tests

• TCP: test_tcp_listener_raises_on_missing_port — asserts OpenConnectionError when port is missing.
• Mplex stream: Tests use pytest.raises(ValueError) for invalid ttl; valid calls expect no exception.
• Host: test_set_stream_handler_raises_on_empty_protocol_id, test_set_stream_handler_raises_on_null_handler.
• Listeners: QUIC/WebSocket tests no longer use success = await listener.listen(...); assert success.

News fragment

See newsfragments/194.bugfix.rst.

[parth-soni07]

CCing @seetadev @acul71 for the initial feedback