Issue 9302: distutils API Reference: setup() and Extension parameters' description not correct. (original) (raw)

Created on 2010-07-19 09:43 by ysj.ray, last changed 2022-04-11 14:57 by admin. This issue is now closed.

| 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) * | 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) * | 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) * | 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) * | 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) * | 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) * | 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) * | 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) * | 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) * | 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) * | 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) | 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) | 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) * | Date: 2011-08-26 15:20 | | | | | | | | | | | | | | | | | | | Improved and committed, thanks again! | | | | | | | | | | | | | | | | | | | |