Re: [Python-Dev] [Python-checkins] cpython: Issue #11223: Add threading._info() function providing informations about the
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Well, I suppose that this function might be specific to CPython. Do you think that this function can/should be implemented in PyPy, Jython and IronPython?
Victor
On Wed, Apr 20, 2011 at 6:20 PM, Victor Stinner victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Well, I suppose that this function might be specific to CPython. Do you think that this function can/should be implemented in PyPy, Jython and IronPython?
I agree with your reasoning (and the leading underscore), but I suggest marking the docs with the implementation detail flag.
Cheers, Nick.
Le mercredi 20 avril 2011 à 20:24 +1000, Nick Coghlan a écrit :
On Wed, Apr 20, 2011 at 6:20 PM, Victor Stinner victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Well, I suppose that this function might be specific to CPython. Do you think that this function can/should be implemented in PyPy, Jython and IronPython?
I agree with your reasoning (and the leading underscore), but I suggest marking the docs with the implementation detail flag.
I chose to return a dict to be flexible: any thread implementation may add new specific keys. There is just one mandatory key: 'name', name of the thread implementation (nt, os2, pthread or solaris for CPython 3.3).
http://docs.python.org/dev/py3k/library/threading.html#threading._info
After thinking twice, PyPy, Jython and IronPython should be able to fill the only required key (name).
PyPy reuses the code from CPython, so it can just reuse the same names (pthread or nt). I suppose that IronPython uses Windows threads and semaphores, so it can use the name 'nt'. For Jython, I don't know if Jython is able to get the name of the thread implementation used by the JVM. If it is not, something like 'jvm' can be used.
threading._info() is a function: it can call other functions to retrieve informations (it is not hardcoded or initialized at startup).
What do you think? Can I remove the leading underscore? :-)
Victor
2011/4/20 Victor Stinner victor.stinner@haypocalc.com:
Le mercredi 20 avril 2011 à 20:24 +1000, Nick Coghlan a écrit :
On Wed, Apr 20, 2011 at 6:20 PM, Victor Stinner victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Well, I suppose that this function might be specific to CPython. Do you think that this function can/should be implemented in PyPy, Jython and IronPython?
I agree with your reasoning (and the leading underscore), but I suggest marking the docs with the implementation detail flag.
I chose to return a dict to be flexible: any thread implementation may add new specific keys. There is just one mandatory key: 'name', name of the thread implementation (nt, os2, pthread or solaris for CPython 3.3).
How about using a structseq ala sys.float_info or sys.long_info? (In fact, we might want to put this in sys.)
On 4/20/2011 12:57 PM, Benjamin Peterson wrote:
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about thethread implementation.
How about using a structseq ala sys.float_info or sys.long_info? (In fact, we might want to put this in sys.)
sys.thread_info strikes me as a good idea too. The only thing required should be 'name' with '' at the default indicating no threading.
Le mercredi 20 avril 2011 à 11:57 -0500, Benjamin Peterson a écrit :
2011/4/20 Victor Stinner victor.stinner@haypocalc.com:
Le mercredi 20 avril 2011 à 20:24 +1000, Nick Coghlan a écrit :
On Wed, Apr 20, 2011 at 6:20 PM, Victor Stinner victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Well, I suppose that this function might be specific to CPython. Do you think that this function can/should be implemented in PyPy, Jython and IronPython?
I agree with your reasoning (and the leading underscore), but I suggest marking the docs with the implementation detail flag.
I chose to return a dict to be flexible: any thread implementation may add new specific keys. There is just one mandatory key: 'name', name of the thread implementation (nt, os2, pthread or solaris for CPython 3.3).
How about using a structseq ala sys.float_info or sys.long_info? (In fact, we might want to put this in sys.)
Would you prefer something like the following example?
sys.thread_info
sys.threadinfo(name='pthread', 'lock_implementation': 'semaphore', version: 'NPTL 2.11.2')
sys.thread_info
sys.threadinfo(name='nt', 'lock_implementation': 'semaphore', version: '')
sys.thread_info
sys.threadinfo(name='os2', 'lock_implementation': '', version: '')
Victor
2011/4/20 Victor Stinner victor.stinner@haypocalc.com:
Le mercredi 20 avril 2011 à 11:57 -0500, Benjamin Peterson a écrit :
How about using a structseq ala sys.float_info or sys.long_info? (In fact, we might want to put this in sys.)
Would you prefer something like the following example?
sys.thread_info
sys.threadinfo(name='pthread', 'lock_implementation': 'semaphore', version: 'NPTL 2.11.2')
sys.thread_info
sys.threadinfo(name='nt', 'lock_implementation': 'semaphore', version: '')
sys.thread_info
sys.threadinfo(name='os2', 'lock_implementation': '', version: '')
The only things that would improve that beautiful sight would be s/threadinfo/thread_info/. :)
On Wed, 20 Apr 2011 17:03:19 -0500 Benjamin Peterson benjamin@python.org wrote:
2011/4/20 Victor Stinner victor.stinner@haypocalc.com:
Le mercredi 20 avril 2011 à 11:57 -0500, Benjamin Peterson a écrit :
How about using a structseq ala sys.float_info or sys.long_info? (In fact, we might want to put this in sys.)
Would you prefer something like the following example?
sys.thread_info
sys.threadinfo(name='pthread', 'lock_implementation': 'semaphore', version: 'NPTL 2.11.2')
sys.thread_info
sys.threadinfo(name='nt', 'lock_implementation': 'semaphore', version: '')
sys.thread_info
sys.threadinfo(name='os2', 'lock_implementation': '', version: '')
The only things that would improve that beautiful sight would be s/threadinfo/thread_info/. :)
And None instead of the empty string when a value is unknown/irrelevant.
Regards
Antoine.
On 08:20 am, victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 � 22:42 -0400, Terry Reedy a �crit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing
informations about the
thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Can I propose something wildly radical? Maybe the guarantees made about whether an API will be available in future versions of Python (ostensibly what "public" vs "private" is for) should not be tightly coupled to the decision about whether to bother to explain what an API does?
Jean-Paul
2011/4/20 exarkun@twistedmatrix.com:
On 08:20 am, victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Can I propose something wildly radical? Maybe the guarantees made about whether an API will be available in future versions of Python (ostensibly what "public" vs "private" is for) should not be tightly coupled to the decision about whether to bother to explain what an API does?
With what criteria would you propose to replace it with?
On 01:11 pm, benjamin@python.org wrote:
2011/4/20 exarkun@twistedmatrix.com:
On 08:20 am, victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 � 22:42 -0400, Terry Reedy a �crit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
� �Issue #11223: Add threading._info() function providing
informations
about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Can I propose something wildly radical? �Maybe the guarantees made about whether an API will be available in future versions of Python (ostensibly what "public" vs "private" is for) should not be tightly coupled to the decision about whether to bother to explain what an API does?
With what criteria would you propose to replace it with?
I'm not sure what kind of criteria you're thinking of. I'm only suggesting that:
1) Document whatever you want (preferably as much as possible)
2) Make "privateness" defined by whether there is a leading underscore
It is a big mistake to think that documentation isn't necessary for things just because you don't want application developers to use them. Maintainers benefit from it just as much.
Jean-Paul
On 4/20/2011 10:11 AM, exarkun@twistedmatrix.com wrote:
On 01:11 pm, benjamin@python.org wrote:
It is a big mistake to think that documentation isn't necessary for things just because you don't want application developers to use them. Maintainers benefit from it just as much.
Maintainers can and will read the doc string.
On Wed, 20 Apr 2011 08:11:48 -0500, Benjamin Peterson benjamin@python.org wrote:
2011/4/20 exarkun@twistedmatrix.com:
On 08:20 am, victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Can I propose something wildly radical? Maybe the guarantees made about whether an API will be available in future versions of Python (ostensibly what "public" vs "private" is for) should not be tightly coupled to the decision about whether to bother to explain what an API does?
With what criteria would you propose to replace it with?
I believe Jean-Paul was suggesting that just because an interface is marked as "private" and might go away or change in the future does not automatically mean it must also be undocumented. To which I say +1. (Note that we already have a whole module like that: test.support.)
-- R. David Murray http://www.bitdance.com
2011/4/20 R. David Murray rdmurray@bitdance.com:
On Wed, 20 Apr 2011 08:11:48 -0500, Benjamin Peterson benjamin@python.org wrote:
2011/4/20 exarkun@twistedmatrix.com:
On 08:20 am, victor.stinner@haypocalc.com wrote:
Hi,
Le mardi 19 avril 2011 à 22:42 -0400, Terry Reedy a écrit :
On 4/19/2011 5:59 PM, victor.stinner wrote:
Issue #11223: Add threading._info() function providing informations about the thread implementation.
Since this is being documented, making it part of the public api, why does it have a leading underscore?
Can I propose something wildly radical? Maybe the guarantees made about whether an API will be available in future versions of Python (ostensibly what "public" vs "private" is for) should not be tightly coupled to the decision about whether to bother to explain what an API does?
With what criteria would you propose to replace it with?
I believe Jean-Paul was suggesting that just because an interface is marked as "private" and might go away or change in the future does not automatically mean it must also be undocumented. To which I say +1. (Note that we already have a whole module like that: test.support.)
I think that test.* as a special case is private stuff.
-
Antoine Pitrou -
Benjamin Peterson -
exarkun＠twistedmatrix.com -
Nick Coghlan -
R. David Murray -
Terry Reedy -
Victor Stinner