[Python-Dev] winreg

[Paul Prescod]

Mark, Thomas and whoever, thanks for your input and I hope you can spare
some more...

Thomas Heller wrote:
> 

This is similar to what I have implemented...

> ----------------------------------------------------------------------
> winreg - windows registry access module
> 
> Exception:
>   error - raised when a function fails. Will contain
>     a windows error code and a textual description.

As an aside, I notice that the winreg documentation says it will raise
an EnvironmentError but it actually raises a WindowsError. 

> Objects:
>   regkey object - represents a open key in the
>   registry.

Right. Even the same name.

My stance was that keys would always be created from keys, so you would
start with

HKEY_LOCAL_MACHINE.CreateKey("Software\Python")

That mirrors the underlying API a little closer and reduces the number
of functions to 0.

The question is whether the CreateKey and OpenKey functions are
important enough as "convenience functions".

> regkey object methods:
>   Standard Mapping protocol:
>   len (r)
>   r[k]
>   r[k] = x
>   del r[k]
>   r.clear()
>   r.has_key(k)
>   r.items()
>   r.keys()
>   r.update(dict)
>   r.values()
>   r.get(k[, x])

I had a separate object for values. I couldn't really justify elevating
either the Subkeys or the Values. I tried to treat them as alike as
possible.

>   todict() -> dictionary
>     Returns a dictionary mapping value names to values.

I called this getValues() and it returned an object that was both a
mapping and a sequence and allowed read/write/delete of values.

>   SubKeys () -> sequence
>     Returns a sequence containing the names of all subkeys.
> 
>   DeleteKey (name [,recursive=0])
>     If recursive is 0, deletes the named key if no subkeys exist.
>     If there are subkeys an error is raised.
>     If recursive is not 0, the named key is deleted
>     including subkeys.

I may or may not get around to implementing the recursive version. You
have to be VERY CAREFUL when you test such a thing. :)

>   OpenKey (name) -> regkey object
>     Openes an existing subkey and returns a regkey
>     object pointing to it.

Okay.

>   CreateKey (name) -> regkey object
>     Creates a new or openes an existing subkey and
>     returns a regkey object pointing to it.

Okay.

> regkey objects have the following properties:
>   name - the name of the RegistryKey, something
>     like "HKLM\Software\Python"

Okay.

>   hkey - the integer keyhandle

Is this really useful? Better to use the low-level API in that case...

> If we change the name of the low level api module, we have to change
> Distutils,
> because it is used there. Maybe we would better use the high level api then,
> but there is still this 1.5 compatibility using the win32api module.

The high level could probably be made compatible with 1.5 like this:

try:
    import _winreg
except ImportError:
    import win32api
    winreg=win32api

It would probably be good for DistUtils to use the high level API as
soon as it is possible for testing purposes.

I am considering doing away with the two enumeration interfaces. The
cost/benefit of having two more objects is probably low.

We can simplify the whole thing by just using methods on the regkey
object:

deleteValue(name) 
getValue(name)-> (type, value)
setValue(name,(type,value))
getValueNames() -> List of strings

getSubkey(name) -> regkey
deleteSubkey(name)
getSubkeyNames( ) -> List of strings

Iterating will be slightly less efficient because it will loop twice,
once to gather the names and once to do whatever you need to do but
that's not the typical registry use case anyhow. Anyone who needs
absolute performance can use the low-level API.

Recursive iteration under the existing model:

def doit( key ):
    for subkey in key.getSubkeyNames():
        doit( subkey )

Recursive iteration under the proposed model:

def doit( key ):
    for keyname in key.getSubkeyNames():
        doit( key.getSubkey( name ))

-- 
 Paul Prescod - Not encumbered by corporate consensus
When George Bush entered office, a Washington Post-ABC News poll found
that 62 percent of Americans "would be willing to give up a few of the
freedoms we have" for the war effort. They have gotten their wish.
	- "This is your bill of rights...on drugs", Harpers, Dec. 1999