[issue14943] winreg OpenKey doesn't work as documented

[Glenn Linderman]

New submission from Glenn Linderman <v+python at g.nevcal.com>:

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.

----------
assignee: docs at python
components: Documentation
messages: 161822
nosy: docs at python, v+python
priority: normal
severity: normal
status: open
title: winreg OpenKey doesn't work as documented
type: behavior
versions: Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14943>
_______________________________________