Issue #24878: Add docstrings to selected namedtuples

diff --git a/Lib/aifc.py b/Lib/aifc.py
index 7ebdbeb68c1093e387046a8c616b6f41d3bce07e..1556b53019fc367787f1da851146d919e95d4831 100644 (file)
--- a/Lib/aifc.py
+++ b/Lib/aifc.py
@@ -257,6 +257,14 @@ from collections import namedtuple
 _aifc_params = namedtuple('_aifc_params',
                           'nchannels sampwidth framerate nframes comptype compname')
 
+_aifc_params.nchannels.__doc__ = 'Number of audio channels (1 for mono, 2 for stereo)'
+_aifc_params.sampwidth.__doc__ = 'Ample width in bytes'
+_aifc_params.framerate.__doc__ = 'Sampling frequency'
+_aifc_params.nframes.__doc__ = 'Number of audio frames'
+_aifc_params.comptype.__doc__ = 'Compression type ("NONE" for AIFF files)'
+_aifc_params.compname.__doc__ = ("""A human-readable version ofcompression type
+('not compressed' for AIFF files)'""")
+
 
 class Aifc_read:
     # Variables used in this class:

diff --git a/Lib/dis.py b/Lib/dis.py
index af37cdf0c67e4e45c6c68c02ef31149ff3ef65cd..3540b4714d9af477b7e49cc185f529e66e608df1 100644 (file)
--- a/Lib/dis.py
+++ b/Lib/dis.py
@@ -162,6 +162,15 @@ def show_code(co, *, file=None):
 _Instruction = collections.namedtuple("_Instruction",
      "opname opcode arg argval argrepr offset starts_line is_jump_target")
 
+_Instruction.opname.__doc__ = "Human readable name for operation"
+_Instruction.opcode.__doc__ = "Numeric code for operation"
+_Instruction.arg.__doc__ = "Numeric argument to operation (if any), otherwise None"
+_Instruction.argval.__doc__ = "Resolved arg value (if known), otherwise same as arg"
+_Instruction.argrepr.__doc__ = "Human readable description of operation argument"
+_Instruction.offset.__doc__ = "Start index of operation within bytecode sequence"
+_Instruction.starts_line.__doc__ = "Line started by this opcode (if any), otherwise None"
+_Instruction.is_jump_target.__doc__ = "True if other code jumps to here, otherwise False"
+
 class Instruction(_Instruction):
     """Details for a bytecode operation
 

diff --git a/Lib/sched.py b/Lib/sched.py
index b47648d973a954129174c15110f020d2474f44ac..bd7c0f1b6ff382dc106e7b5fc1ac4de60d6bf2da 100644 (file)
--- a/Lib/sched.py
+++ b/Lib/sched.py
@@ -46,6 +46,17 @@ class Event(namedtuple('Event', 'time, priority, action, argument, kwargs')):
     def __gt__(s, o): return (s.time, s.priority) >  (o.time, o.priority)
     def __ge__(s, o): return (s.time, s.priority) >= (o.time, o.priority)
 
+Event.time.__doc__ = ('''Numeric type compatible with the return value of the
+timefunc function passed to the constructor.''')
+Event.priority.__doc__ = ('''Events scheduled for the same time will be executed
+in the order of their priority.''')
+Event.action.__doc__ = ('''Executing the event means executing
+action(*argument, **kwargs)''')
+Event.argument.__doc__ = ('''argument is a sequence holding the positional
+arguments for the action.''')
+Event.kwargs.__doc__ = ('''kwargs is a dictionary holding the keyword
+arguments for the action.''')
+
 _sentinel = object()
 
 class scheduler:

diff --git a/Lib/selectors.py b/Lib/selectors.py
index 6d569c30adff871c2346fb05d6ef0359432f7c54..ecd8632d7048acb86ca25b29cfe39552e0796ff1 100644 (file)
--- a/Lib/selectors.py
+++ b/Lib/selectors.py
@@ -43,9 +43,17 @@ def _fileobj_to_fd(fileobj):
 
 
 SelectorKey = namedtuple('SelectorKey', ['fileobj', 'fd', 'events', 'data'])
-"""Object used to associate a file object to its backing file descriptor,
-selected event mask and attached data."""
 
+SelectorKey.__doc__ = """SelectorKey(fileobj, fd, events, data)
+
+    Object used to associate a file object to its backing
+    file descriptor, selected event mask, and attached data.
+"""
+SelectorKey.fileobj.__doc__ = 'File object registered.'
+SelectorKey.fd.__doc__ = 'Underlying file descriptor.'
+SelectorKey.events.__doc__ = 'Events that must be waited for on this file object.'
+SelectorKey.data.__doc__ = ('''Optional opaque data associated to this file object.
+For example, this could be used to store a per-client session ID.''')
 
 class _SelectorMapping(Mapping):
     """Mapping of file objects to selector keys."""

diff --git a/Lib/shutil.py b/Lib/shutil.py
index a5da58790ecf8ec7d18d00c455145fec6b2d888f..8edabdb332942c4319e4dee6a5d7235602dd6c78 100644 (file)
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -965,6 +965,9 @@ if hasattr(os, 'statvfs'):
 
     __all__.append('disk_usage')
     _ntuple_diskusage = collections.namedtuple('usage', 'total used free')
+    _ntuple_diskusage.total.__doc__ = 'Total space in bytes'
+    _ntuple_diskusage.used.__doc__ = 'Used space in bytes'
+    _ntuple_diskusage.free.__doc__ = 'Free space in bytes'
 
     def disk_usage(path):
         """Return disk usage statistics about the given path.

diff --git a/Lib/sndhdr.py b/Lib/sndhdr.py
index e5901ec58338aaae1ed33d56573b4ca0ecc0cfa1..7ecafb40e821cdf082a2977ab2383ba2a9ac6c62 100644 (file)
--- a/Lib/sndhdr.py
+++ b/Lib/sndhdr.py
@@ -37,6 +37,18 @@ from collections import namedtuple
 SndHeaders = namedtuple('SndHeaders',
                         'filetype framerate nchannels nframes sampwidth')
 
+SndHeaders.filetype.__doc__ = ("""The value for type indicates the data type
+and will be one of the strings 'aifc', 'aiff', 'au','hcom',
+'sndr', 'sndt', 'voc', 'wav', '8svx', 'sb', 'ub', or 'ul'.""")
+SndHeaders.framerate.__doc__ = ("""The sampling_rate will be either the actual
+value or 0 if unknown or difficult to decode.""")
+SndHeaders.nchannels.__doc__ = ("""The number of channels or 0 if it cannot be
+determined or if the value is difficult to decode.""")
+SndHeaders.nframes.__doc__ = ("""The value for frames will be either the number
+of frames or -1.""")
+SndHeaders.sampwidth.__doc__ = ("""Either the sample size in bits or
+'A' for A-LAW or 'U' for u-LAW.""")
+
 def what(filename):
     """Guess the type of a sound file."""
     res = whathdr(filename)