classification
Title: winreg OpenKey doesn't work as documented
Type: behavior Stage: resolved
Components: Documentation, Windows Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: brian.curtin Nosy List: brian.curtin, docs@python, python-dev, v+python
Priority: normal Keywords:

Created on 2012-05-29 00:14 by v+python, last changed 2012-05-29 23:45 by brian.curtin. This issue is now closed.

Messages (2)
msg161822 - (view) Author: Glenn Linderman (v+python) * Date: 2012-05-29 00:14
My first time to use winreg and I am sure that some of this report is documentation, but depending on behavior in other versions, maybe it is a regression in code as well, but I doubt it.

I'm reading the 3.3 documentation, but using 3.2.3 for testing.  The documentation doesn't indicate any change execpt the exception thrown, between 3.2 and 3.3.

The documentation for OpenKey indicates it has 4 parameters, calling the 3rd "reserverd" and the 4th "access".  These are given default values of 0 and KEY_ALL_ACCESS, respectively, according to the function definition.

The text of the documentation does not further explain these parameters, rather it explains "res" and "sam" which may appear to correspond... (that is problem #1)

Assuming a correspondence, and a name change for those parameters somewhere along the line (perhaps between 3.1 and 3.2 when named parameters became supported, per the doc. note), then "sam" is defined to have a default value of "KEY_READ".  That conflicts with the default value shown in the function definition (this is problem #2).

The behavior of OpenKey in 3.2.2 seems to be that the access parameter actually defaults to "KEY_READ", rather than "KEY_ALL_ACCESS".  Since the documentation is inconsistent in this area, I'm not sure if there was intended to be a code change, nor what the prior behavior might have been, nor what the future behavior is intended to be.  If a change in default was intended, either it was implemented wrong, or documented wrong, and there is no indication in the documentation that a change was made, or should have been made (this is problem #3).

I suspect the changes should all be to the documentation, changing the function definition to read "KEY_READ" instead of "KEY_ALL_ACCESS", and changing the parameters in the text to be called "reserved" and "access" instead of "res" and "sam", and if so, then problem #3 is fictitious, just a result of the other inconsistencies, and speculation.
msg161920 - (view) Author: Roundup Robot (python-dev) Date: 2012-05-29 23:44
New changeset fcb6c4a4ac0e by Brian Curtin in branch '3.2':
Fix #14943. Update the proper default value and list the proper argument names in the explanation.
http://hg.python.org/cpython/rev/fcb6c4a4ac0e

New changeset 29e0f08ef065 by Brian Curtin in branch 'default':
Fix #14943. Merge 3.2
http://hg.python.org/cpython/rev/29e0f08ef065

New changeset 8ec62c9eea34 by Brian Curtin in branch '3.2':
Add news item for #14943
http://hg.python.org/cpython/rev/8ec62c9eea34
History
Date User Action Args
2012-05-29 23:45:24brian.curtinsetstatus: open -> closed
assignee: docs@python -> brian.curtin
resolution: fixed
components: + Windows
stage: resolved
2012-05-29 23:44:41python-devsetnosy: + python-dev
messages: + msg161920
2012-05-29 21:13:58r.david.murraysetnosy: + brian.curtin
2012-05-29 00:14:39v+pythoncreate