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 _______________________________________
-
R. David Murray -
Ray.Allen
-
Roundup Robot
-
ysj.ray
-
Éric Araujo