documentation of bz2 module mildly erroneous

[MattWartell]

BPO	8602
Nosy	@birkenfeld, @merwok
Files	issue-8602.diff: context diff for 2.6.5 documentation tree

^{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 2010-08-01.14:52:11.810>
created_at = <Date 2010-05-03.07:03:52.628>
labels = ['type-bug', 'docs']
title = 'documentation of bz2 module mildly erroneous'
updated_at = <Date 2010-08-01.14:52:11.809>
user = 'https://bugs.python.org/MattWartell'

bugs.python.org fields:

activity = <Date 2010-08-01.14:52:11.809>
actor = 'georg.brandl'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-08-01.14:52:11.810>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2010-05-03.07:03:52.628>
creator = 'Matt.Wartell'
dependencies = []
files = ['17253']
hgrepos = []
issue_num = 8602
keywords = ['patch']
message_count = 6.0
messages = ['104818', '105237', '105248', '107756', '107757', '112337']
nosy_count = 4.0
nosy_names = ['georg.brandl', 'eric.araujo', 'docs@python', 'Matt.Wartell']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue8602'
versions = ['Python 2.6']

[MattWartell]

This is related to http://bugs.python.org/issue8601 "bz2.BZ2File should support "with" protocol per PEP-343"

The documentation at http://docs.python.org/library/bz2.html states:

"This module provides a comprehensive interface for the bz2 compression library. It implements a complete file interface,..."

although bz2.BZ2File does not support the __enter__ and __exit__ methods so arguably doesn't implement the "complete file interface". If bpo-8601 is declined then the documentation should probably note this exception.

[merwok]

Now that bpo-8601 is closed, would you mind providing a doc patch explaining the lack of context manager protocol support and its reason?

[MattWartell]

Per request, I have attached a context diff for both bz2.txt and 3.0.txt suitable for http://docs.python.org/library/bz2.html and http://docs.python.org/release/3.0.1/whatsnew/3.0.html respectively.

The modification in bz2.txt may border on redundant and overly verbose and should be reviewed for style consistency.

I have sanity-checked the modified files with sphinx-build html which generates clean, consistent markup.

[merwok]

I’d remove the lines “Specifically it does not define the :meth:`__enter__` and :meth:`__exit__` methods required by the :keyword:`with` statement”, since they add unnecessary length to a simple note.

Please provide one patch per branch, and diff from the top level of the checkout (see http://www.python.org/dev/patches/). Thanks!

[merwok]

Also, don’t bother with 3.0: It is not supported by python-dev anymore. Make documentation patches for py3k and trunk, and they’ll be backported to the stable branches 3.1 and 2.6.

[birkenfeld]

Now present in all maintained branches.