The distutils api document for class Extension:

http://docs.python.org/dev/py3k/distutils/apiref.html#distutils.core.Extension

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.

Thanks for the catch.  Are there no similar problems in the rest of the distutils doc, or did you search in one file only?

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.

Why was this issue set to pending?  No motivating comment was added.

Sorry, I thought updating the status was enough to convey “I’m about to commit this”.

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.

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.

This also explains why any new message cancels the pending status, BTW.

FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6

> 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                         |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+

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.

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 :)

> 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.

> 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!

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

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

Improved and committed, thanks again!