diff --git a/docs/source/conf.py b/docs/source/conf.py index eb278bf65f..a1df00736b 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -172,8 +172,9 @@ def autodoc_process_signature( # currently undocumented things logger = getLogger("trio") -UNDOCUMENTED = { - "trio._subprocess.HasFileno.fileno", +# ``ParkingLot.broken_by`` is a slotted attrs field; its documentation lives +# in the ``ParkingLot`` class docstring's ``Attributes:`` block. +UNDOCUMENTED: set[str] = { "trio.lowlevel.ParkingLot.broken_by", } diff --git a/docs/source/reference-lowlevel.rst b/docs/source/reference-lowlevel.rst index 077f21cd27..d2da0ae05d 100644 --- a/docs/source/reference-lowlevel.rst +++ b/docs/source/reference-lowlevel.rst @@ -482,6 +482,7 @@ Wait queue abstraction .. autoclass:: ParkingLot :members: :undoc-members: + :exclude-members: broken_by .. autoclass:: ParkingLotStatistics :members: diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 0000000000..319649286e --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1,3 @@ +Filled in the missing documentation for ``trio._subprocess.HasFileno.fileno`` +and ``trio.lowlevel.ParkingLot.broken_by``, which completes the checklist in +issue #3221. diff --git a/src/trio/_core/_parking_lot.py b/src/trio/_core/_parking_lot.py index ddf6276117..3f4d6bb710 100644 --- a/src/trio/_core/_parking_lot.py +++ b/src/trio/_core/_parking_lot.py @@ -146,6 +146,10 @@ class ParkingLot: the number of parked tasks, and ``if parking_lot: ...`` to check whether there are any parked tasks. + Attributes: + broken_by: The tasks that broke this parking lot, most recent + last. See :meth:`break_lot`. + """ # {task: None}, we just want a deque where we can quickly delete random diff --git a/src/trio/_subprocess.py b/src/trio/_subprocess.py index d73ba3dc23..9d5dbc7cc8 100644 --- a/src/trio/_subprocess.py +++ b/src/trio/_subprocess.py @@ -98,7 +98,12 @@ 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: + """Returns the file descriptor of this file-like object, as an + integer. It is passed to the child process, e.g. when a + :class:`HasFileno` object is used as ``stdin``, ``stdout`` or + ``stderr`` of a spawned process.""" + ... @final diff --git a/src/trio/_tests/_check_type_completeness.json b/src/trio/_tests/_check_type_completeness.json index d8a2948cd9..a44f90dfe0 100644 --- a/src/trio/_tests/_check_type_completeness.json +++ b/src/trio/_tests/_check_type_completeness.json @@ -12,7 +12,6 @@ "all": [ "No docstring found for class \"trio._core._run.Task\"", "No docstring found for class \"trio._socket.SocketType\"", - "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\"",