diff --git a/docs/source/conf.py b/docs/source/conf.py index 925c31e8ef..217927161a 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -172,13 +172,7 @@ def autodoc_process_signature( # currently undocumented things logger = getLogger("trio") -UNDOCUMENTED = { - "trio.MemorySendChannel", - "trio.MemoryReceiveChannel", - "trio.MemoryChannelStatistics", - "trio._subprocess.HasFileno.fileno", - "trio.lowlevel.ParkingLot.broken_by", -} +UNDOCUMENTED: set[str] = set() def autodoc_process_docstring( diff --git a/docs/source/reference-lowlevel.rst b/docs/source/reference-lowlevel.rst index 077f21cd27..315665105d 100644 --- a/docs/source/reference-lowlevel.rst +++ b/docs/source/reference-lowlevel.rst @@ -482,6 +482,12 @@ Wait queue abstraction .. autoclass:: ParkingLot :members: :undoc-members: + :exclude-members: broken_by + + .. attribute:: broken_by + + The tasks that broke this parking lot. This list is empty until + :meth:`break_lot` is called. .. autoclass:: ParkingLotStatistics :members: diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 0000000000..f0a3c0dabc --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1 @@ +Document `MemorySendChannel`, `MemoryReceiveChannel`, and `MemoryChannelStatistics` in the API reference. diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 05037d8131..b6b4986f52 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -118,6 +118,26 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 @attrs.frozen class MemoryChannelStatistics: + """Statistics for a memory channel. + + This is returned by `MemorySendChannel.statistics` and + `MemoryReceiveChannel.statistics`. + + Attributes: + current_buffer_used: The number of values currently stored in the + channel buffer. + max_buffer_size: The maximum number of values allowed in the buffer, as + passed to `open_memory_channel`. + open_send_channels: The number of open `MemorySendChannel` endpoints + pointing to this channel. + open_receive_channels: The number of open `MemoryReceiveChannel` + endpoints pointing to this channel. + tasks_waiting_send: The number of tasks blocked in + `MemorySendChannel.send` on this channel, across all clones. + tasks_waiting_receive: The number of tasks blocked in + `MemoryReceiveChannel.receive` on this channel, across all clones. + """ + current_buffer_used: int max_buffer_size: int | float open_send_channels: int @@ -152,6 +172,14 @@ def statistics(self) -> MemoryChannelStatistics: @final @attrs.define(eq=False, repr=False, slots=False) class MemorySendChannel(SendChannel[SendType], metaclass=NoPublicConstructor): + """The sending side of an in-memory channel. + + A `MemorySendChannel` is created by `open_memory_channel`. Values sent on + it are delivered to the matching `MemoryReceiveChannel`. Send channels can + be cloned to give multiple producers independent endpoints that all feed + the same underlying channel. + """ + _state: MemoryChannelState[SendType] _closed: bool = False # This is just the tasks waiting on *this* object. As compared to @@ -300,6 +328,14 @@ async def aclose(self) -> None: @final @attrs.define(eq=False, repr=False, slots=False) class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstructor): + """The receiving side of an in-memory channel. + + A `MemoryReceiveChannel` is created by `open_memory_channel`. It receives + values from the matching `MemorySendChannel`. Receive channels can be + cloned to give multiple consumers independent endpoints that share the + same underlying channel. + """ + _state: MemoryChannelState[ReceiveType] _closed: bool = False _tasks: set[trio._core._run.Task] = attrs.Factory(set) diff --git a/src/trio/_subprocess.py b/src/trio/_subprocess.py index d73ba3dc23..7b5293d8e2 100644 --- a/src/trio/_subprocess.py +++ b/src/trio/_subprocess.py @@ -98,7 +98,9 @@ def pidfd_open(fd: int, flags: int) -> int: class HasFileno(Protocol): """Represents any file-like object that has a file descriptor.""" - def fileno(self) -> int: ... + def fileno(self) -> int: + """Return the integer file descriptor for this object.""" + ... @final diff --git a/src/trio/_tests/_check_type_completeness.json b/src/trio/_tests/_check_type_completeness.json index 6e8c54ea8b..309b4e13f3 100644 --- a/src/trio/_tests/_check_type_completeness.json +++ b/src/trio/_tests/_check_type_completeness.json @@ -18,12 +18,6 @@ ], "Windows": [], "all": [ - "No docstring found for class \"trio.MemoryReceiveChannel\"", - "No docstring found for class \"trio._channel.MemoryReceiveChannel\"", - "No docstring found for class \"trio.MemoryChannelStatistics\"", - "No docstring found for class \"trio._channel.MemoryChannelStatistics\"", - "No docstring found for class \"trio.MemorySendChannel\"", - "No docstring found for class \"trio._channel.MemorySendChannel\"", "No docstring found for class \"trio._core._run.Task\"", "No docstring found for class \"trio._socket.SocketType\"", "No docstring found for function \"trio._highlevel_socket.SocketStream.send_all\"", @@ -31,7 +25,6 @@ "No docstring found for function \"trio._highlevel_socket.SocketStream.send_eof\"", "No docstring found for function \"trio._highlevel_socket.SocketStream.receive_some\"", "No docstring found for function \"trio._highlevel_socket.SocketStream.aclose\"", - "No docstring found for function \"trio._subprocess.HasFileno.fileno\"", "No docstring found for class \"trio._sync.AsyncContextManagerMixin\"", "No docstring found for function \"trio._sync._HasAcquireRelease.acquire\"", "No docstring found for function \"trio._sync._HasAcquireRelease.release\"",