io.py: Improve docstrings for classes

[akuchling]

BPO	21225
Nosy	@akuchling, @pitrou, @vstinner, @bitdancer, @berkerpeksag
Files	io-copy-docstrings.patch: Copy doc from parent class

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-04-28.22:21:36.304>
created_at = <Date 2014-04-14.20:50:46.187>
labels = ['easy', 'type-feature', 'expert-IO']
title = 'io.py: Improve docstrings for classes'
updated_at = <Date 2014-04-28.22:21:36.303>
user = 'https://github.com/akuchling'

bugs.python.org fields:

activity = <Date 2014-04-28.22:21:36.303>
actor = 'pitrou'
assignee = 'none'
closed = True
closed_date = <Date 2014-04-28.22:21:36.304>
closer = 'pitrou'
components = ['IO']
creation = <Date 2014-04-14.20:50:46.187>
creator = 'akuchling'
dependencies = []
files = ['34847']
hgrepos = []
issue_num = 21225
keywords = ['patch', 'easy']
message_count = 6.0
messages = ['216210', '216970', '217159', '217263', '217427', '217428']
nosy_count = 6.0
nosy_names = ['akuchling', 'pitrou', 'vstinner', 'r.david.murray', 'python-dev', 'berker.peksag']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21225'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[akuchling]

io.py contains the following to declare ABCs for some of its classes:

class IOBase(_io._IOBase, metaclass=abc.ABCMeta):
    pass

(and similarly for RawIOBase, BufferedIOBase, TextIOBase).

_io._IOBase has an extensive docstring, but IOBase doesn't. (Python doesn't inherit parent-class docstrings, on the theory that the subclass may change things that make the docstring invalid.)

I propose the attached patch.

[bitdancer]

Looks good to me.

[python-dev]

New changeset e33a036fd784 by Andrew Kuchling in branch '3.4':
bpo-21225: copy docstrings from base classes
http://hg.python.org/cpython/rev/e33a036fd784

[berkerpeksag]

Can this be closed? (or needs backport to 2.7? http://hg.python.org/cpython/file/2.7/Lib/io.py#l69)

[python-dev]

New changeset 6e23afdee4e4 by Andrew Kuchling in branch '2.7':
bpo-21225: copy docstrings from base classes
http://hg.python.org/cpython/rev/6e23afdee4e4

[pitrou]

I've backported Andrew's change.