[Python-Dev] New winreg module really an improvement?

[Paul Prescod]

(reorganizing the important stuff to the top)

Mark Hammond wrote:
> Still-can't-see-the-added-value-ly,

I had no personal interest in an API for the windows registry but I
could not, in good conscience, let the original one become the 
standard Python registry API. 

Here are some examples:

(num_subkeys, num_values, last_modified ) = winreg.QueryInfoKey( key )
for i in range( num_values ):
	(name,value)=winreg.EnumValue( key, i )
		if name==valuename: print "found"

Why am I enumerating but not using the Python enumeration protocol? Why
do I have to get a bogus 3-tuple before I begin enumerating? Where else
are the words "Query" and "Enum" used in Python APIs?

and

winreg.SetValueEx( key, "ProgramFilesDir", None, winreg.REG_SZ,
r"c:\programs" )

Note that the first argument is the key object (so why isn't this a
method?) and the third argument is documented as bogus. In fact, in
the OpenKey documentation you are requested to "always pass 0 please".

All of that was appropriate when winreg was documented "by reference" to
the Microsoft documentation but if it is going to be a real, documented
module in the Python library then the bogus MS junk should go.

The truth is I would prefer NOT to work on winreg and leave both 
versions out of the library. But Unless someone else is willing to 
design and implement a decent API, I took that burden upon myself 
rather than see more weird stuff in the Python API.

So the value add is:

 * uses Python iteration protocol
 * uses Python mapping protocol
 * uses Python method invocation syntax
 * uses only features that will be documented
 * does not expose integers as object handles (even for HKLM etc.)
 * uses inspectable, queryable objects even as docstrings
 * has a much more organized module dictionary (do a dir( _winreg))

If you disagree with those principles then we are in trouble. If you
have quibbles about specifics then let's talk.

> Ive just updated the test suite so that test_winreg2.py actually works.
> 
> It appears that the new winreg.py module is still in a state of flux, but
> all work has ceased.  The test for this module has lots of placeholders
> that are not filled in. Worse, the test code was checked in an obviously
> broken state (presumably "to be done", but guess who the bunny who had to
> do it was :-(

The tests ran fine on my machine. Fred had to make minor changes before
he checked it in for me because of module name changes. It's possible
that he mistyped a search and replace or something...or that I had a 
system dependency. Since I changed jobs I no longer have access to 
Visual C++ and have not had luck getting GCC to compile _winreg. This
makes further testing difficult until someone cuts a Windows binary 
build of Python (which is perpetually imminent).

The test cases are not all filled in. The old winreg test tested each
method on average one time. The new winreg tries harder to test each in
a variety of situations. Rather than try to keep all cases in my head I
created empty function bodies. Now we have clear documentation of what
is done and tested and what is to be tested still. Once an alpha is cut,
(or I fix my compiler situation) I can finish that process.

> Browsing the source made it clear that the module docstrings are still
> incomplete (eg "For information on the key API, open a key and look at its
> docstring.").  

The docstrings are not complete, but they are getting better and the old
winreg documentation was certainly not complete either! I admit I got
into a little bit of recursive projects wherein I didn't want to write
the winreg, minidom, SAX, etc. documentation twice so I started working
on stuff that would extract the docstrings and generate LaTeX. That's
almost done and I'll finish up the documentation. That's what the beta
period is for, right?

> Eg, the specific example I had a problem with was:
> 
> key[value]
> 
> Returns a result that includes the key index!  This would be similar to a
> dictionary index _always_ returning the tuple, and the first element of the
> tuple is _always_ the key you just indexed.

There is a very clearly labelled (and docstring-umented) getValueData
method:

key.getValueData("FOO") 

That gets only the value. Surely that's no worse than the original:

winreg.QueryValue( key, "FOO" )

If this is your only design complaint then I don't see cause for alarm
yet.

Here's why I did it that way:

You can fetch data values by their names or by their indexes. If
you've just indexed by the name then of course you know it. If you've
just fetched by the numeric index then you don't. I thought it was more
consistent to have the same value no matter how you indexed. Also, when
you get a value, you should also get a type, because the types can be
important. In that case it still has to be a tuple, so it's just a
question of a two-tuple or a three-tuple. Again, I thought that the
three-tuple was more consistent. Also, this is the same return value
returned by the existing EnumValue function.

> Has anyone else actually looked at or played with this, and still believe
> it is an improvement over _winreg?  I personally find it unintuitive, and
> will personally continue to use _winreg.  If we can't find anyone to
> complete it, document it, and stand up and say they really like it, I
> suggest we pull it.

I agree that it needs more review. I could not get anyone interested in
a discussion of how the API should look, other than pointing at old
threads.

You are, of course, welcome to use whatever you want but I think it
would be productive to give the new API a workout in real code and then
report specific design complaints. If others concur, we can change it.

-- 
 Paul Prescod - Not encumbered by corporate consensus
"I don't want you to describe to me -- not ever -- what you were doing
to that poor boy to make him sound like that; but if you ever do it
again, please cover his mouth with your hand," Grandmother said.
	-- John Irving, "A Prayer for Owen Meany"