classification
Title: extra_path kwarg to setup() undocumented
Type: Stage: patch review
Components: Distutils Versions: Python 3.1, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: alexis, bob.ippolito, docs@python, eric.araujo, georg.brandl, jason.coombs, ronaldoussoren, tarek, theller
Priority: normal Keywords: needs review, patch

Created on 2004-02-21 15:04 by bob.ippolito, last changed 2016-09-01 18:13 by jason.coombs. This issue is now closed.

Files
File name Uploaded Description Edit
apiref.patch ronaldoussoren, 2010-07-29 19:35 review
apiref-followup.diff eric.araujo, 2011-03-20 22:34
Messages (12)
msg20098 - (view) Author: Bob Ippolito (bob.ippolito) * (Python committer) Date: 2004-02-21 15:04
I can't find documentation for extra_path anywhere.. but this is the 
documentation I found by searching google ( http://
mail.python.org/pipermail/distutils-sig/2000-March/000803.html ), 
from an old USAGE.txt that sits in the CVS attic now:

extra_path:
     information about extra intervening directories to put between
     'install_lib' and 'install_sitelib', along with a .pth file to
     ensure that those directories wind up in sys.path.  Can be a 1- 
or
     2-tuple, or a comma-delimited string with 1 or 2 parts.  The
     1-element case is simpler: the .pth file and directory have the 
same
    name (except for ".pth").  Eg. if extra_path is "foo" or ("foo",),
     then Distutils sets 'install_site_lib' to 'install_lib' +
     "site-packages/foo", and puts foo.path in the "site-packages"
     directory; it contains just "foo".  The 2-element case allows the
     .pth file and intervening directories to be named differently; 
eg.
    if 'extra_path' is ("foo","foo/bar/baz") (or "foo,foo/bar/baz"),
     then Distutils will set 'install_site_lib' to 'install_lib' +
     "site-packages/foo/bar/baz", and put "foo.pth" containing
     "foo/bar/baz" in the "site-packages" directory.
msg20099 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2005-05-17 16:16
Logged In: YES 
user_id=580910

extra_path also doesn't have a command-line equivalent.
msg20100 - (view) Author: Thomas Heller (theller) * (Python committer) Date: 2007-01-24 20:36
Unassign, I won't work on this.
msg111991 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2010-07-29 19:35
I've attached a documentation patch for this (for py3k)
msg114345 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-19 11:42
The patch has some words missing (“to put between”), but I can add them. I’m also going to include the example that was in Bob’s message, since the bit of doc in the table alone is not enough to understand clearly what this does IMO.

I’m reassigning this to distutils2. distutils only gets bug fixes, and its doc is changed only when it says something that doesn’t work. This lets us put energy on distutils2.

I’ll get to it this week-end or later.
msg114351 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2010-08-19 12:10
I don't understand why distutils won't even get documentation updates.

Bob's report is about undocumented functionality that is used in real life and was the best way to install python distributions in a self-contained way before setuptools was invented.

AFAIK The "options" argument to setup is also not documented an that one is also used (both py2exe and py2app mention this feature in their documentation).
msg116258 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-09-13 00:19
This strict freeze policy has been decided by Tarek.  The less work there is on distutils’ side, the less synchronization we’ll have to do in distutils2.  We do fix doc bugs, we can also fix markup or add links, but that’s it.  Improving docs is for distutils2.

Note that at first I wanted to improve distutils docs even though the code was frozen, but I now agree with Tarek that it would take up a lot of time that is better spent in distutils2.  (Regarding the options parameter, a Montreal-Python contributor added a test for it and a TODO note about lack of documentation.  See, things get better one step at a time :)

I hope this answers your question without sounding too dictatorial.  I understand your viewpoint but ultimately agree with the freeze.
msg128501 - (view) Author: Alexis Metaireau (alexis) * Date: 2011-02-13 14:36
I've applied the patch on distutils2. This can now be closed.
msg128511 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-02-13 15:44
You shouldn’t have :)  apiref.rst is very outdated in d2, because the setup function does not exist.  The docs could be adjusted to document Distribution instead of setup, but we’re not even sure Distribution will stay.

I think I will make a compromise here and apply the patch to distutils1 doc, so that the information is found on the official docs.
msg128513 - (view) Author: Alexis Metaireau (alexis) * Date: 2011-02-13 15:46
Still, the extra_path argument exists and can be used, it's worth to
have it documented somewhere, especially if someone have done it.

That's also true that apiref.rst is outdated in d2, and will need a
complete reshape :)
msg131556 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-20 22:34
I added the missing words and reworded a few lines in the attached patch.

That said, I find that the new doc is barely helpful; it describes what the code does, but does not explain why one would want to use it.  Comments in the source suggest it’s a hack to support some corner case.  This is still obscure to me after reading about it and looking at the code :(
msg274160 - (view) Author: Jason R. Coombs (jason.coombs) * (Python committer) Date: 2016-09-01 18:13
Given the progression in issue27919, I suggest this documentation effort can be dropped, but feel free to revive the conversation if you disagree.
History
Date User Action Args
2016-09-01 18:13:57jason.coombssetstatus: open -> closed

nosy: + jason.coombs
messages: + msg274160

resolution: wont fix
2011-03-20 22:34:33eric.araujosetfiles: + apiref-followup.diff
nosy: theller, georg.brandl, bob.ippolito, ronaldoussoren, tarek, eric.araujo, docs@python, alexis
messages: + msg131556
2011-02-13 15:46:43alexissetnosy: theller, georg.brandl, bob.ippolito, ronaldoussoren, tarek, eric.araujo, docs@python, alexis
messages: + msg128513
2011-02-13 15:44:18eric.araujosetnosy: theller, georg.brandl, bob.ippolito, ronaldoussoren, tarek, eric.araujo, docs@python, alexis
messages: + msg128511
components: + Distutils, - Distutils2
versions: + Python 3.1, Python 2.7, Python 3.2, Python 3.3, - 3rd party
2011-02-13 14:36:42alexissetnosy: + alexis
messages: + msg128501
2010-09-29 23:43:42eric.araujosetversions: + 3rd party, - Python 2.6, Python 2.5, Python 3.1, Python 2.7, Python 3.2
2010-09-13 00:19:40eric.araujosetmessages: + msg116258
2010-08-19 12:10:28ronaldoussorensetmessages: + msg114351
2010-08-19 11:44:37eric.araujosetversions: + Python 3.2
2010-08-19 11:42:44eric.araujosetversions: + Python 2.6, Python 2.5, Python 2.7, - Python 3.2
nosy: + eric.araujo

messages: + msg114345

assignee: docs@python -> eric.araujo
components: + Distutils2, - Distutils, Documentation
2010-08-19 06:01:10BreamoreBoysetassignee: tarek -> docs@python
stage: patch review

nosy: + docs@python
versions: + Python 3.2, - Python 2.6, Python 3.0, Python 2.7
2010-07-29 19:35:34ronaldoussorensetkeywords: + patch, needs review
files: + apiref.patch
messages: + msg111991
2009-02-05 10:31:56georg.brandlsetassignee: georg.brandl -> tarek
2009-02-04 16:50:18akitadasetnosy: + georg.brandl, tarek
assignee: georg.brandl
components: + Documentation
versions: + Python 2.6, Python 3.0, Python 3.1, Python 2.7
2004-02-21 15:04:07bob.ippolitocreate