bpo-17306: Add class-level docstrings to collections.abc

[jacksonriley]

This change adds class-level docstrings to collections.abc, as requested in Issue 17306.

I'm not 100% sure if the format is exactly as desired but I tried to follow the request (close to Sequence.__doc__) as far as possible.

https://bugs.python.org/issue17306

[jacksonriley]

Hi @rhettinger, does this issue need a news item or would you be able to add the skip news label for me? Thanks!

[rhettinger]

Thanks for the PR. I was looking for something much less extensive. When I get some time, I'll provide a couple of examples and we can work from there :-)

[jacksonriley]

Whoops, apologies! Keen to amend in whatever way you see fit :)

[jacksonriley]

Hi @rhettinger, this is just a friendly bump as I don't want this to get forgotten :)

[jacksonriley]

Hi @rhettinger, sorry for the multiple bumps, but would you possibly be able to provide some examples as you suggested before, please? Thanks :)

[rhettinger]

Sorry for not getting to this sooner. I was looking for something considerably more concise that matches the existing, terse but effective style. Try modeling the new docstrings after the existing one for Set, MutableSet, Mapping, MutableMapping, Sequence, and MutableSequence.

class Set(Collection):
    """A set is a finite, iterable container.

    This class provides concrete generic implementations of all
    methods except for __contains__, __iter__ and __len__.

    To override the comparisons (presumably for speed, as the
    semantics are fixed), redefine __le__ and __ge__,
    then the other operations will automatically follow suit.
    """

class MutableSet(Set):
    """A mutable set is a finite, iterable container.

    This class provides concrete generic implementations of all
    methods except for __contains__, __iter__, __len__,
    add(), and discard().

    To override the comparisons (presumably for speed, as the
    semantics are fixed), all you have to do is redefine __le__ and
    then the other operations will automatically follow suit.
    """

class Mapping(Collection):
    """A Mapping is a generic container for associating key/value
    pairs.

    This class provides concrete generic implementations of all
    methods except for __getitem__, __iter__, and __len__.

    """

class MutableMapping(Mapping):
    """A MutableMapping is a generic container for associating
    key/value pairs.

    This class provides concrete generic implementations of all
    methods except for __getitem__, __setitem__, __delitem__,
    __iter__, and __len__.

    """

class Sequence(Reversible, Collection):
    """All the operations on a read-only sequence.

    Concrete subclasses must override __new__ or __init__,
    __getitem__, and __len__.
    """

class MutableSequence(Sequence):
    """All the operations on a read-write sequence.

    Concrete subclasses must provide __new__ or __init__,
    __getitem__, __setitem__, __delitem__, __len__, and insert().

    """

For classes that don't already have a docstring, don't try invent new wording. Instead, take the wording from the main docs. In Hashable for example, using the existing wording, "ABC for classes that provide the hash() method." instead of the current PR wording, "A Hashable is an object that can be hashed.".

Move the method descriptions in the method docstrings. Here's a good example in the existing code:

class Generator(Iterator):

    def __next__(self):
        """Return the next item from the generator.
        When exhausted, raise StopIteration.
        """
        return self.send(None)

    @abstractmethod
    def send(self, value):
        """Send a value into the generator.
        Return next yielded value or raise StopIteration.
        """
        raise StopIteration

[rhettinger]

No progress has been made on this for three months.

[LewisGaul]

@rhettinger Jackson was waiting over a year for your input on how to proceed, including multiple friendly bumps. Would it be fair to ask his input on whether he'd still like to take this on before closing after a fraction of that time?

[jacksonriley]

Hi @rhettinger, I confess that I had forgotten about this over Christmas! I'd be happy to take another stab at it using your comments if you think it's still a worthwhile PR and re-open it.