subprocess.Popen.wait() undocumented "endtime" parameter

[giampaolo]

BPO	20572
Nosy	@birkenfeld, @gpshead, @larryhastings, @giampaolo, @bitdancer, @rnk, @berkerpeksag, @vadmium, @Mariatta
PRs	[Do Not Merge] Convert Misc/NEWS so that it is managed by towncrier #552
Files	issue20572.patch issue20572v2.patch: added stacklevel=2 and test case

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-11-22.12:13:10.669>
created_at = <Date 2014-02-09.10:23:20.136>
labels = ['3.7']
title = 'subprocess.Popen.wait() undocumented "endtime" parameter'
updated_at = <Date 2017-03-31.16:36:35.477>
user = 'https://github.com/giampaolo'

bugs.python.org fields:

activity = <Date 2017-03-31.16:36:35.477>
actor = 'dstufft'
assignee = 'none'
closed = True
closed_date = <Date 2016-11-22.12:13:10.669>
closer = 'martin.panter'
components = []
creation = <Date 2014-02-09.10:23:20.136>
creator = 'giampaolo.rodola'
dependencies = []
files = ['45532', '45555']
hgrepos = []
issue_num = 20572
keywords = ['patch']
message_count = 25.0
messages = ['210740', '210742', '210770', '210771', '210789', '210832', '210833', '210835', '210840', '210978', '210979', '210981', '210983', '211006', '264082', '281074', '281085', '281102', '281193', '281254', '281255', '281310', '281311', '281312', '281320']
nosy_count = 12.0
nosy_names = ['georg.brandl', 'gregory.p.smith', 'larry', 'giampaolo.rodola', 'gps', 'r.david.murray', 'rnk', 'python-dev', 'berker.peksag', 'martin.panter', 'Daryl Luna', 'Mariatta']
pr_nums = ['552']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue20572'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[giampaolo]

http://hg.python.org/cpython/file/29d9638bf449/Lib/subprocess.py#l1144
This was introduced in revision 6b627e121573 and is currently not documented.
I'm not sure whether this is a documentation issue or "endtime" should have been "_endtime" instead.

[giampaolo]

Sorry: revision a161081e8f7c.

[bitdancer]

Indeed, there's no issue number or NEWS entry. It's not clear from the limited context why this parameter was added. It doesn't appear to be consistent with the rest of the stdlib: the application can compute timeout from its desired endtime, which is how all of the other stdlib 'wait' APIs work.

[bitdancer]

Also, the implementation as it stands is in any case flawed, since specifying both timeout and endtime is allowed by the code, and results in endtime overriding timeout silently, and in the posix version the resulting timeout error message will have the ignored timeout in it.

Unfortunately this has been in here for a while (March 2011) so people may be using it.

Based on the docs in the original commit (c4a0fa6e687c), I suspect endtime on wait was supposed to be an internal parameter....except that it is never used internally. The endtime is converted back to a timeout in order to call wait. Ideally we'd just drop it...but it may be in use in wild.

[giampaolo]

I'd be for just getting rid of it for 3.4 now that we still can.
Being that this parameter is 1) not documented and 2) it's not even clear what it does I think it's unlikely that there's people using it.

[larryhastings]

This isn't a release blocker. And it's not really viable to remove it.

Since it's been in several releases, I suspect our only option is to throw a deprecation warning. And, since deprecations aren't turned on by default, maybe the best thing would be to also document it (!) as being deprecated (!!).

Even though rc1 is already tagged and in the process of being released, I will accept a patch with the above suggested change for Python 3.4. If you want to do something else talk to me first.

[giampaolo]

Since it's been in several releases

AFAICT only 3.3.
Reid, are you willing to provide a patch?

[bitdancer]

I don't think we should document it as deprecated except in What's New. But a code deprecation in 3.4 would be a good idea.

[larryhastings]

My suggestion for documenting it was to document the fact that it's unsupported, unrecommended, deprecated, has poor semantics, etc. If a user discovers it, and finds it's not documented, they'll probably think they can get away with using it. If we explicitly document it as "don't use" I think that's better.

[python-dev]

New changeset 73793590d97b by Gregory P. Smith in branch 'default':
Deprecate Popen.wait()'s undocumented endtime parameter. bpo-20572.
http://hg.python.org/cpython/rev/73793590d97b

[gpshead]

documented with a deprecation. that's the best we can do for now. it can be considered for removal in the 3.5 or 3.6 timeframe. i doubt many people used it.

[bitdancer]

Well, a deprecation warning in the code would be nice in case anybody did use it. Personally I don't see any problem with putting that in 3.4.1 if we don't get to it for 3.4.0.