[issue9302] Distutils document problem?
New submission from Ray.Allen <ysj.ray@gmail.com>: The distutils api document for class Extension: http://docs.python.org/dev/py3k/distutils/apiref.html#distutils.core.Extensi... Among the argument, in fact, the type of the arguments "sources", "include_dirs", "library_dirs", "libraries", "runtime_library_dirs" must be list, but all of them are marked as "string". I think this is a problem. Here is a patch for this, against py3k. ---------- assignee: docs@python components: Documentation files: distutils_apiref.diff keywords: patch messages: 110724 nosy: docs@python, ysj.ray priority: normal severity: normal status: open title: Distutils document problem? versions: Python 3.2 Added file: http://bugs.python.org/file18061/distutils_apiref.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- nosy: +tarek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Thanks for the catch. Are there no similar problems in the rest of the distutils doc, or did you search in one file only? ---------- assignee: docs@python -> eric.araujo components: +Distutils, Distutils2 nosy: +alexis, eric.araujo stage: -> patch review title: Distutils document problem? -> distutils.core.Extension: list parameters documented as strings versions: +3rd party, Python 2.7, Python 3.1, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Ray.Allen <ysj.ray@gmail.com> added the comment: I searched the distutils docs for such a parameter description table and find tow more on the distutils.core.setup() function descriptions. Reflected in my updated patch. ---------- title: distutils.core.Extension: list parameters documented as strings -> distutils API Reference: setup() and Extension parameters' description not correct. Added file: http://bugs.python.org/file21323/issue_9302.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Why was this issue set to pending? No motivating comment was added. ---------- nosy: +r.david.murray status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Sorry, I thought updating the status was enough to convey “I’m about to commit this”. ---------- versions: -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Um, no. 'pending' is 'pending close', specifically meaning, 'this issue is going to be closed (with a rejected status of some sort) unless someone objects or provides more information.' Someday, pending issues will be autoclosed after N days. Quite possibly this summer, since Ezio is working on roundup this summer. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Oh, thanks for clearing a misunderstanding I’ve had for a year! I was using the pending status to prioritize issues (I have a personal “assigned to me + pending” query, now I’ll use priority instead. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: This also explains why any new message cancels the pending status, BTW. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
ysj.ray <ysj.ray@gmail.com> added the comment:
FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6
I like this solution, it seems more concise and to the point. With this the doc need only one change: --- a/Doc/distutils/apiref.rst Fri Apr 29 14:07:28 2011 +0800 +++ b/Doc/distutils/apiref.rst Thu Jun 16 23:15:12 2011 +0800 @@ -85,15 +85,15 @@ | *script_args* | Arguments to supply to the | a list of strings | | | setup script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *options* | default options for the setup | a string | + | *options* | default options for the setup | a dictionary | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Thanks for your feedback. My patch assumes that people will understand that an argument that has a plural name (like macros) can’t be a string but a list of strings; I don’t know if relying on this inference is better than your initial patch. An alternate style that I saw somewhere is to use “[str]” to describe a list of strings. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: I would not read [str] as implying a list of strings, FWIW. Nor would I assume a plural option meant a list if the text says "a string". But I'm just a bystander here and haven't even looked the docs you guys are updating :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
Nor would I assume a plural option meant a list if the text says "a string".
Especially in distutils code where we can get space-separated or comma-separated values from the command line or config files. I’m in favor of using explicit “list of strings” wording now. ysj.ray, I understand from the “Done” comments on the review page that you have an updated patch somewhere; please upload and I’ll commit. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
ysj.ray <ysj.ray@gmail.com> added the comment:
I would not read [str] as implying a list of strings, FWIW.
help() on distutils.extension.Extension gives the parameters description like this: ...... sources: [string] ...... include_dirs: [string] ...... So I guess this style can be used as somewhere.
I’m in favor of using explicit “list of strings” wording now. ysj.ray, I understand from the “Done” comments on the review page that you have an updated patch somewhere; please upload and I’ll commit.
Ok, here is it. Thanks! ---------- Added file: http://bugs.python.org/file22391/issue_9302_2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 96f0ccb9716d by Éric Araujo in branch '3.2': Fix type information in distutils API reference (#9302). http://hg.python.org/cpython/rev/96f0ccb9716d New changeset a410b857efe3 by Éric Araujo in branch 'default': Merge from 3.2 (#9302 fix and other changes) http://hg.python.org/cpython/rev/a410b857efe3 New changeset 59b3f845f7a3 by Éric Araujo in branch 'default': Synchronize packaging docs with distutils’ (includes fix for #9302) http://hg.python.org/cpython/rev/59b3f845f7a3 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 78b26e7720c0 by Éric Araujo in branch '2.7': Fix type information in distutils API reference (#9302). http://hg.python.org/cpython/rev/78b26e7720c0 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Improved and committed, thanks again! ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9302> _______________________________________
participants (5)
-
R. David Murray -
Ray.Allen
-
Roundup Robot
-
ysj.ray
-
Éric Araujo