Overview

A utility module that treats the Win32 registry like a Python Dictionary.

The purpose of this module is to make it easier to store and retrieve information from the Win32 registry.

Terms and Definitions

It is important to distinguish between the following terms when working with this module.

folder

A location like \SOFTWARE\MineSight where other folders (keys) and values reside.

keys

This the Window terminology for a folder, and is also a WinRegistry object.

tag

The name of a value, in the above example "win_pos" was a tag.

value

The value stored in a "tag" under a "key", in the above example, the geometry was a value.

Details

An example of using this class would be to store information you would like to save from one application run to another. In this case will will store the window layout.

Later you can always retrieve that information like this,

Off course the key, "window_pos" may not be defined because this may the first time the application executes. In this case you would get a WinRegistryError if did what is shown above. However, if you have a default value, you can do something like this when accessing the "window_pos",

The get() method basically attempts to retrieve the "window_pos" value, and if it can not find it the function returns the otherwise value. In essence its equivalent to rolling your own function,

There you go, the basics for working in the Window's registry.

Now, what is this "hkey_current_user" stuff? In Window's terminology this is referred to as the basekey. In this module the available basekeys are described by the BASE_KEY data member. Two of the most useful ones are,

• HKEY_CURRENT_USER

  The registry for the active user, where each user gets their own unique area to save values into.

• HKEY_LOCAL_MACHINE

  A registry that allows you to save values for all users.

Typically you will use the \SOFTWARE folder of each of the above registry locations. An example would be generic dialogs that Grail generates. All these dialogs have there windows locations stored inside the registry under the HKEY_CURRENT_USER's \Software\Minesight\Grail\Dialog folder.

The typical layout is \SOFTWARE\mycompany\myapplication\myfolders.

Another note, the WinRegistry object represents one location in the registry. In the above examples, it represented the "hkey_current_user\SOFTWARE\Minesight\MyApplication" location. If you wished to retrieve the parent folder (in this case "hkey_current_user\SOFTWARE\Minesight") you could use the parent() method to get a parent WinRegistry object. Just as equally, if you where in the Minesight location you can retrieve the children (a list of other WinRegistry objects) representing the various folders.

If you want to inspect the registry on your machine go to the start menu and type: "regedit.exe". This will start the registry editor program that allows you to navigate through the folders and keys.

If you execute the following source code and look into your registry using regedit.exe you will probably get a better understanding of how the registry works,

Finally, all values are treated as strings to make working with the registry easier. If you wish to store an integer you must convert that integer to a string prior to saving, and re-convert that same string to an integer after you have loaded it from the registry.

The WinRegistry Class

class WinRegistry(basekey, key)

An abstraction on the Window's registry.

This class treats the Window's registry like a dictionary.

Arguments:

basekey : string

On of the Window's base keys defined in the BASE_KEYS data member also defined in this module.

key : string

The location you wish to open up a WinRegistry object inside, if the location does not exist it will be created.

children()

Returns a list of children WinRegistry objects.

close()

Explicitly close a registry.

Python will eventually close the registry for you as part of its automatic garbage collection. However if you are concerned about not having control on the closing "time", this method will provide you that control.

deletekey(keyname)

Attempts to delete a sub-key (child).

This function CAN NOT delete sub-keys (children) that also contain children. Using this method is fairly tricky. You should prefer to use the removeregistry function in this module.

Arguments:

keyname : string

Name of a sub-key you wish to delete.

deletetag(tag)

Removes a entry (tag-value pair) from the WinRegistry location.

Argument:

tag : string

Name of the tag-value pair you wish to remove.

get(tag[, otherwise])

Retrieves a value if it exists, or returns the otherwise value.

Arguments:

tag : string

Name of the value you are looking for in the WinRegistry object.

otherwise : string

A value you wish to have returned if the tag does not exist in the registry.

Note

The otherwise value is not saved to the registry under the tag value.

keys()

Returns a list of all keys in the WinRegistry object.

numkeys()

Returns the number of keys in the WinRegistry object.

numtags()

Returns the number of tags in this WinRegistry object.

parent()

Returns the parent WinRegistry object to this object.

set([**kws])

Allows you to set multiple tag-value pairs in one call.

For example,

registry.set(win_geom="200x200+100+100",
             win_state="minimized")

Is equivalent to,

registry["win_geom"] = "200x200+100+100"
registry["win_state"] = "minimized"

Arguments:

kws

A dictionary of keywords.

tags()

Returns a list of all tags in the WinRegistry object.

Exception

exception WinRegistryError

Defines a WinRegistry error

Functions

removeregistry(basekey, path)

Completely cleans the registry with the given path.

Data

BASE_KEYS

A dictionary listing the values and Window's constants that can be used for the WinRegistry object. As a user you should only know something about the keys. The values are irrelevant.