classification
Title: Create a "Superseded modules" section in standard library ToC
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, docs@python, elixir, ezio.melotti, georg.brandl, hynek, ncoghlan, python-dev
Priority: normal Keywords: easy, patch

Created on 2013-09-07 13:09 by ncoghlan, last changed 2014-10-11 13:08 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
doc_add_a_deprecated_modules_heading.patch elixir, 2013-10-24 16:03 review
doc_add_a_deprecated_modules_heading2.patch elixir, 2013-10-24 16:12 review
Messages (6)
msg197154 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-09-07 13:09
As discussed at the language summit earlier this year [1], it isn't alway easy to tell when glancing through the standard library docs which modules are merely hanging around because removing them would break backwards compatibility.

However, after reviewing the current ToC, we currently appear to only have two genuinely superseded modules: optparse (superseded by argparse) and imp (superseded by importlib).

Other cases where different modules touch on the same area are high level/low level splits (e.g. select vs selectors), or ones where the alternate modules are offering compatibility with different styles of API (e.g. etree vs DOM for XML, getopt vs argparse).

In future, asyncore/asynchat will hopefully be superseded by the PEP 3156 code (as "concurrent.events" or similar) and would also be moved under the new heading.

Marking as "easy" since the mechanics of the patch should be pretty simple: create a new heading and move the references to optparse and imp from their current locations.

[1] http://python-notes.boredomandlaziness.org/en/latest/conferences/pyconus2013/20130313-language-summit.html#legacy-modules

(I thought I had already created a bug for this, but can't find it, so I've created this new one. If I did already create an issue, we can close it as a duplicate and keep this one.)
msg201149 - (view) Author: -- (elixir) * Date: 2013-10-24 16:03
The patch adds a 'Deprecated Modules' heading in the library's ToC and moves 'imp' & 'optparse' to the new entry.
msg201150 - (view) Author: -- (elixir) * Date: 2013-10-24 16:12
I changed 'Deprecated Modules' into 'Superseded Modules', as indicated by the issue title.
msg220659 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-15 18:16
Would somebody review the attached patch please.
msg229083 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-10-11 12:47
Thanks for the patch.
msg229085 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-11 13:08
New changeset 7276bc0b0318 by Georg Brandl in branch '3.4':
Closes #18959: move optparse and imp to new "superseded modules" chapter
https://hg.python.org/cpython/rev/7276bc0b0318
History
Date User Action Args
2014-10-11 13:08:29python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg229085

resolution: fixed
stage: needs patch -> resolved
2014-10-11 12:47:23georg.brandlsetnosy: + georg.brandl
messages: + msg229083
2014-06-15 18:16:31BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220659
2013-10-24 16:12:11elixirsetfiles: + doc_add_a_deprecated_modules_heading2.patch

messages: + msg201150
2013-10-24 16:03:20elixirsetfiles: + doc_add_a_deprecated_modules_heading.patch

nosy: + elixir
messages: + msg201149

keywords: + patch
2013-09-13 20:28:45ezio.melottisetnosy: + ezio.melotti
2013-09-07 14:05:04hyneksetnosy: + hynek
2013-09-07 13:09:22ncoghlancreate