classification
Title: distutils API Reference: setup() and Extension parameters' description not correct.
Type: Stage: resolved
Components: Distutils, Distutils2, Documentation Versions: Python 3.2, Python 3.3, Python 2.7, 3rd party
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: alexis, docs@python, eric.araujo, python-dev, r.david.murray, tarek, ysj.ray
Priority: normal Keywords: patch

Created on 2010-07-19 09:43 by ysj.ray, last changed 2011-08-26 15:20 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
distutils_apiref.diff ysj.ray, 2010-07-19 09:43 patch against py3k review
issue_9302.diff ysj.ray, 2011-03-21 13:22 review
issue_9302_2.diff ysj.ray, 2011-06-17 02:31 review
Messages (17)
msg110724 - (view) Author: ysj.ray (ysj.ray) Date: 2010-07-19 09:43
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.
msg131595 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-21 01:18
Thanks for the catch.  Are there no similar problems in the rest of the distutils doc, or did you search in one file only?
msg131646 - (view) Author: ysj.ray (ysj.ray) Date: 2011-03-21 13:22
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.
msg137780 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-06 22:55
Why was this issue set to pending?  No motivating comment was added.
msg137832 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-07 15:07
Sorry, I thought updating the status was enough to convey “I’m about to commit this”.
msg137835 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-07 15:14
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.
msg137838 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-07 15:35
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.
msg137839 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-07 15:35
This also explains why any new message cancels the pending status, BTW.
msg138446 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-16 15:07
FYI, in one packaging doc I added one note instead of changing each cell: http://docs.python.org/dev/library/packaging.compiler#id6
msg138450 - (view) Author: ysj.ray (ysj.ray) Date: 2011-06-16 15:22
> 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                         |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
msg138451 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-16 15:26
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.
msg138457 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-16 16:01
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 :)
msg138458 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-16 16:11
> 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.
msg138488 - (view) Author: ysj.ray (ysj.ray) Date: 2011-06-17 02:31
> 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!
msg143010 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-26 14:32
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
msg143011 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-26 14:37
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
msg143016 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-26 15:20
Improved and committed, thanks again!
History
Date User Action Args
2011-08-26 15:20:46eric.araujosetstatus: open -> closed
resolution: fixed
messages: + msg143016

stage: patch review -> resolved
2011-08-26 14:37:34python-devsetmessages: + msg143011
2011-08-26 14:32:42python-devsetnosy: + python-dev
messages: + msg143010
2011-06-17 02:31:41ysj.raysetfiles: + issue_9302_2.diff

messages: + msg138488
2011-06-16 16:11:51eric.araujosetmessages: + msg138458
2011-06-16 16:01:12r.david.murraysetmessages: + msg138457
2011-06-16 15:26:21eric.araujosetmessages: + msg138451
2011-06-16 15:22:26ysj.raysetmessages: + msg138450
2011-06-16 15:07:19eric.araujosetmessages: + msg138446
2011-06-07 15:35:56eric.araujosetmessages: + msg137839
2011-06-07 15:35:25eric.araujosetmessages: + msg137838
2011-06-07 15:14:29r.david.murraysetmessages: + msg137835
2011-06-07 15:07:55eric.araujosetmessages: + msg137832
versions: - Python 3.1
2011-06-06 22:55:52r.david.murraysetstatus: pending -> open
nosy: + r.david.murray
messages: + msg137780

2011-06-06 16:12:18eric.araujosetstatus: open -> pending
2011-03-21 13:22:46ysj.raysetfiles: + issue_9302.diff

title: distutils.core.Extension: list parameters documented as strings -> distutils API Reference: setup() and Extension parameters' description not correct.
messages: + msg131646
nosy: tarek, eric.araujo, ysj.ray, docs@python, alexis
2011-03-21 01:18:24eric.araujosetassignee: docs@python -> eric.araujo

components: + Distutils, Distutils2
title: Distutils document problem? -> distutils.core.Extension: list parameters documented as strings
nosy: + eric.araujo, alexis
versions: + 3rd party, Python 3.1, Python 2.7, Python 3.3
messages: + msg131595
stage: patch review
2010-07-19 12:41:35r.david.murraysetnosy: + tarek
2010-07-19 09:43:23ysj.raycreate