classification
Title: Document Deprecation Warnings and how to fix
Type: enhancement Stage:
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: RusiMody, chris.jerdonek, docs@python, eric.araujo, eric.smith, ezio.melotti, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2010-12-10 05:40 by RusiMody, last changed 2012-09-26 17:23 by ezio.melotti.

Files
File name Uploaded Description Edit
unnamed RusiMody, 2010-12-10 10:26
Messages (7)
msg123716 - (view) Author: Rusi (RusiMody) Date: 2010-12-10 05:40
I am trying to port some app from 2.x to 3.x
Terry Reedy suggested using 2.7
I get deprecation warnings (with -3 flag)

I would be good to have a place to check all such and have suggested solutions
msg123721 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2010-12-10 09:35
Are the warnings originating in your code, or in the standard library, or elsewhere?

If in the standard library, please provide specific details.
msg123724 - (view) Author: Rusi (RusiMody) Date: 2010-12-10 10:26
Hi Eric
Sorry for not being clear.
This is more of a feature request than a bug report as suggested by Terry
Reedy on the python mailing list (see here

http://mail.python.org/pipermail/python-list/2010-December/1262149.html

The warnings are in my code.
The main problems are (I expect) from strings/unicode/binary-strings
I am suggesting that it would be good to have a place one could go to with
each such warnings that would give explanations and possible remedies

Rusi

On Fri, Dec 10, 2010 at 3:05 PM, Eric Smith <report@bugs.python.org> wrote:

>
> Eric Smith <eric@trueblade.com> added the comment:
>
> Are the warnings originating in your code, or in the standard library, or
> elsewhere?
>
> If in the standard library, please provide specific details.
>
> ----------
> nosy: +eric.smith
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue10669>
> _______________________________________
>
msg123776 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-12-11 04:18
The issue is not the specific warnings Rusi got but how, in general, one can get more information when the warnings are too cryptic to deal with.

One response might be that DeprecationWarnings should be much wordier than they are -- a paragraph of a few sentences rather than just a minimal sentence. Another might be that each release have a HOW-TO doc or What's New section with a paragraph for each one added to that release.

Currently, information is scattered among pydev posts, tracker issues, commit messages, News entries, and maybe What's new.
msg123780 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-12-11 06:55
The deprecation notes in the doc should be quite easy to find and can be more verbose, but there are a few cases where the deprecation is not about a specific function but something more "abstract" (e.g. some syntax change, or the "Overriding __eq__ blocks inheritance of __hash__ in 3.x" reported by the OP).
Listing new deprecations in the what's new it's a good idea, but otherwise a clear message (that also suggests how to fix the problem) and a deprecation note in the doc (using the '.. deprecated::' directive) should be enough.
msg124117 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-12-16 09:09
FWIW, whatsnew is not primary documentation -- it should not be the sole or central source of anything except a highlevel overview and examples for the author's choice of selected version differences to highlight. 

A howto document would work best as a central place to list all deprecations and advice on what to do about them.
msg124129 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-16 13:53
PEP 4 and PEP 290 are related to this subject, but not comprehensive, not on docs.python.org, and not tutorial-like.

I think we could try Ezio’s idea.  Sphinx can produce a document containing only version* directives (“make changes”).  If such a document is clear enough and has links to the longer docs, there would be no need to write separate howtos.
History
Date User Action Args
2012-09-26 17:23:55ezio.melottisetnosy: + chris.jerdonek

versions: + Python 3.3, Python 3.4
2010-12-16 13:56:22eric.araujosetnosy: rhettinger, terry.reedy, eric.smith, ezio.melotti, eric.araujo, docs@python, RusiMody
components: - 2to3 (2.x to 3.x conversion tool)
2010-12-16 13:53:19eric.araujosetnosy: + eric.araujo
messages: + msg124129
2010-12-16 09:09:00rhettingersetnosy: rhettinger, terry.reedy, eric.smith, ezio.melotti, docs@python, RusiMody
messages: + msg124117
2010-12-11 06:55:03ezio.melottisetmessages: + msg123780
2010-12-11 04:18:06terry.reedysetnosy: + terry.reedy, rhettinger
title: Remove Deprecation Warnings -> Document Deprecation Warnings and how to fix
messages: + msg123776

versions: + Python 3.2
2010-12-10 17:22:23ezio.melottisetnosy: + ezio.melotti, docs@python

components: + Documentation
assignee: docs@python
2010-12-10 10:26:44RusiModysetfiles: + unnamed

messages: + msg123724
2010-12-10 09:35:05eric.smithsetnosy: + eric.smith
messages: + msg123721
2010-12-10 05:40:46RusiModycreate