registry – Registry

The registry consists of a series of roots from each of which descends a tree of keys and values. Each key has an anonymous (default) value and optionally a set of named values, each of which has a particular type (string, number etc.).

For convenience in accessing registry keys and values, the module implements the idea of a registry moniker which has the form: [\computer]HKEY[subkey path][:[value]]. For example:

from winsys import registry

#
# The value of the Version item in the HKLM\Software\Python key on SVR01
#
registry.registry(r"\SVR01\HKEY_LOCAL_MACHINE\Software\Python:Version")

#
# The Control Panel\Desktop key in HKEY_CURRENT_USER on the current machine
#
registry.registry(r"HKCU\Control Panel\Desktop")

The key function here is registry() which is a factory returning a Registry object which contains most of the useful functionality in the module. However, the same functionality is replicated at module level in many cases for convenience.

Functions

registry.create_moniker(computer, root, path, value=None)[source]

Return a valid registry moniker from component parts. Computer is optional but root and path must be specified.

Parameters:
  • computer – (optional) name of a remote computer or ”.” or None
  • root – name or value from REGISTRY_HIVE
  • path – backslash-separated registry path
  • value – name of a value on that path. An empty string refers to the default value.
Returns:

a valid moniker string

registry.registry(root, access=u'R', accept_value=True)[source]

Factory function for the Registry class.

Parameters:
  • root – any of None, a Registry instance, or a moniker string
  • access – an integer bitmask or an Registry.ACCESS string
Returns:

a Registry object

registry.values(root, ignore_access_errors=False, _want_types=False)[source]

Yield the values of a registry key as (name, value). This is convenient for, eg, populating a dictionary:

from winsys import registry

com3 = registry.registry(r"HKLM\Software\Microsoft\Com3")
com3_values = dict(com3.itervalues())
Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
  • _want_types – (internal) used when, eg, copying keys exactly
Returns:

yields (name, value) for every value under root

registry.keys(root, ignore_access_errors=False)[source]

Yield the subkeys of a registry key as Registry objects

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
Returns:

yield Registry objects for each key under root

registry.copy(from_key, to_key, use_access=u'F')[source]

Copy one registry key to another, returning the target. If the target doesn’t already exist it will be created.

Parameters:
Returns:

a Registry object for to_key

registry.delete(root, subkey=u'')[source]

Delete a registry key and all its subkeys

The common use for this will be to delete a key itself. The optional subkey param is useful when this is invoked as a method of a Registry object and it’s convenient to remove one of its subkeys:

from winsys import registry
ws = registry.registry(r"hklm\software\winsys")
ws.create()
for subkey in ["winsys1", "winsys2", "winsys3"]:
    ws.create(subkey)
for key in ws.iterkeys():
    print key
for subkey in ["winsys1", "winsys2", "winsys3"]:
    ws.delete(subkey)
ws.delete()
Parameters:
Returns:

a Registry object for root

registry.create(root, subkey=u'', sec=None)[source]

Create a key and apply specific security to it, returning the key created. Note that a colon in the key name is treated as part of the name not as a value indicator. Any parts of the path not already existing will be created as needed:

from winsys import registry, security
sec = security.Security(dacl=[("", "F", "ALLOW")])
registry.create(r"hklm\software\winsys  est", sec=sec)
registry.registry(r"hklm\software\winsys        est").dump()
Parameters:
Returns:

a Registry object for root

registry.walk(root, ignore_access_errors=False, _want_types=False)[source]

Mimic the os.walk functionality for the registry, starting at root and yielding (key, subkeys, values) for each key visited. subkeys and values are themselves generators.

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
  • _want_types – (internal) indicates whether value types are returned as well as values
Returns:

yields key, subkeys, values recursively for every key under root

registry.flat(root, ignore_access_errors=False)[source]

Yield a flattened version the tree rooted at root.

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
Returns:

yields key and then value items for each key under root

registry.parent(key)[source]

Return a registry key’s parent key if it exists

Parameters:key – anything accepted by registry()
Returns:a Registry object representing the parent of key
Raises:x_registry if no parent exists (eg for a hive)

Classes

class registry.Registry(moniker, access=u'R')[source]

Represent a registry key (including one of the roots) giving access to its subkeys and values as well as its security and walking its subtrees. The key is True if it exists, False otherwise.

When access rights are supplied to any function, they can either be an integer representing a bitmask, or one or more letters corresponding to the ACCESS mapping. The default access is “F” indicating Full Control.

Note that addition and attribute / item getting and setting are overridden for convenience in accessing subkeys and values as follows:

  • Adding a string to a Registry object will result in a new object representing

    the subkey of that name:

    from winsys import registry
    software = registry.registry(r"HKLM\Software")
    software + r"Python\Pythoncore" == registry.registry (r"HKLM\Software\Python\Pythoncore")
    
  • Getting an attribute of a Registry object will return a value

    if one exists, a key otherwise (or will raise AttributeError). For a key name this is the same as calling get_key() or adding the key name as above. For a value name, this is the same as calling get_value()

  • Setting an attribute always writes a value, even if a key of that

    name already exists. This is equivalent to calling set_value().

  • Deleting an attribute will attempts to delete a value if one exists,

    otherwise it will delete a key of that name. This is equivalent to calling del_value() or delete().

    from winsys import registry
    python = registry.registry(r"HKLM\Software\Python")
    python.testing = 4
    python.get_value("testing") == 4
    python.testing == python['testing']
    del python.testing
    
  • To create a key, call create() or the module-level create() function.

  • To delete a key, call its delete() method or the module level

    delete() function.

    from winsys import registry
    winsys = registry.registry(r"hklm\software\winsys").create()
    winsys.test_value = 4
    registry.registry(r"hklm\software\winsys:test_value") == 4
    registry.delete(winsys)
    # or winsys.delete()
    # or registry.registry(r"hklm\software").delete("winsys")
    
__add__(path)[source]

Allow a key to be added to an existing moniker.

Parameters:path – can be a simple name or a backslash-separated relative path
Returns:a Registry object for the new path
copy(from_key, to_key, use_access=u'F')

Copy one registry key to another, returning the target. If the target doesn’t already exist it will be created.

Parameters:
Returns:

a Registry object for to_key

create(root, subkey=u'', sec=None)

Create a key and apply specific security to it, returning the key created. Note that a colon in the key name is treated as part of the name not as a value indicator. Any parts of the path not already existing will be created as needed:

from winsys import registry, security
sec = security.Security(dacl=[("", "F", "ALLOW")])
registry.create(r"hklm\software\winsys  est", sec=sec)
registry.registry(r"hklm\software\winsys        est").dump()
Parameters:
Returns:

a Registry object for root

del_value(label)[source]

Removed the value identified by label from this registry key

delete(root, subkey=u'')

Delete a registry key and all its subkeys

The common use for this will be to delete a key itself. The optional subkey param is useful when this is invoked as a method of a Registry object and it’s convenient to remove one of its subkeys:

from winsys import registry
ws = registry.registry(r"hklm\software\winsys")
ws.create()
for subkey in ["winsys1", "winsys2", "winsys3"]:
    ws.create(subkey)
for key in ws.iterkeys():
    print key
for subkey in ["winsys1", "winsys2", "winsys3"]:
    ws.delete(subkey)
ws.delete()
Parameters:
Returns:

a Registry object for root

flat(root, ignore_access_errors=False)

Yield a flattened version the tree rooted at root.

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
Returns:

yields key and then value items for each key under root

classmethod from_string(string, access=u'R', accept_value=True)[source]

Treat the string param as a moniker return either a key or a value. This is mostly used via the registry() function.

get_key(name)[source]

Return a Registry instance corresponding to the key’s subkey name

Parameters:name – a registry relative path (may be a single name or a backslash-separated path
get_value(name)[source]

Return the key’s value corresponding to name

get_value_type(name)[source]

Return the type of the key’s value corresponding to name

iterkeys(root, ignore_access_errors=False)

Yield the subkeys of a registry key as Registry objects

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
Returns:

yield Registry objects for each key under root

itervalues(root, ignore_access_errors=False, _want_types=False)

Yield the values of a registry key as (name, value). This is convenient for, eg, populating a dictionary:

from winsys import registry

com3 = registry.registry(r"HKLM\Software\Microsoft\Com3")
com3_values = dict(com3.itervalues())
Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
  • _want_types – (internal) used when, eg, copying keys exactly
Returns:

yields (name, value) for every value under root

keys(root, ignore_access_errors=False)

Yield the subkeys of a registry key as Registry objects

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
Returns:

yield Registry objects for each key under root

parent(key)

Return a registry key’s parent key if it exists

Parameters:key – anything accepted by registry()
Returns:a Registry object representing the parent of key
Raises:x_registry if no parent exists (eg for a hive)
pyobject()[source]

Lazily return an internal registry key handle according to the instance’s access requirements.

Raises:x_not_found if the registry path the key refers to does not exist
security(options=u'OD')[source]

For a security request, hand off to the from_object() method of the security.Security object, specifying a registry key as the object type. Most commonly used as a context manager for security operations:

from winsys import registry
with registry.registry(r"hklm\software\python").security() as s:
    print s.owner
set_value(label, value, type=None)[source]

Attempt to set one of the key’s named values. If type is None, then if the value already exists under the key its current type is assumed; otherwise a guess is made at the datatype as follows:

  • If the value is an int, use DWORD
  • If the value is a list, use MULTI_SZ
  • If the value has an even number of percent signs, use EXPAND_SZ
  • Otherwise, use REG_SZ

This is a very naive approach, and will falter if, for example, a string is passed which can be converted into a number, or a string with 2 percent signs which don’t refer to an env var.

values(root, ignore_access_errors=False, _want_types=False)

Yield the values of a registry key as (name, value). This is convenient for, eg, populating a dictionary:

from winsys import registry

com3 = registry.registry(r"HKLM\Software\Microsoft\Com3")
com3_values = dict(com3.itervalues())
Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
  • _want_types – (internal) used when, eg, copying keys exactly
Returns:

yields (name, value) for every value under root

walk(root, ignore_access_errors=False, _want_types=False)

Mimic the os.walk functionality for the registry, starting at root and yielding (key, subkeys, values) for each key visited. subkeys and values are themselves generators.

Parameters:
  • root – anything accepted by registry()
  • ignore_access_errors – if True, will keep on iterating even if access denied
  • _want_types – (internal) indicates whether value types are returned as well as values
Returns:

yields key, subkeys, values recursively for every key under root

ACCESS = {u'C': 131103, u'D': 65536, u'F': 983103, u'Q': 1, u'S': 393216, u'R': 131097, u'W': 131078}

Mapping between characters and access rights:

  • Q - Query
  • D - Delete
  • R - Read
  • W - Write
  • C - Change (R|W)
  • F - Full Control
  • S - Security

Constants

registry.REGISTRY_HIVE = <Constants: {u'HKEY_DYN_DATA': -2147483642, u'HKEY_CURRENT_USER': -2147483647, u'HKEY_CURRENT_CONFIG': -2147483643, u'HKEY_PERFORMANCE_TEXT': -2147483568, u'HKEY_PERFORMANCE_DATA': -2147483644, u'HKEY_USERS': -2147483645, 'HKU': -2147483645, u'HKEY_LOCAL_MACHINE': -2147483646, u'HKEY_CLASSES_ROOT': -2147483648, 'HKLM': -2147483646, 'HKCR': -2147483648, 'HKCU': -2147483647, u'HKEY_PERFORMANCE_NLSTEXT': -2147483552}>

Registry hives (root keys) including common aliases (HKCU, HKLM, etc.)

Name Val Win32
HKEY_CLASSES_ROOT 0x80000000 HKCR
HKCR 0x80000000 HKCR
HKEY_CURRENT_USER 0x80000001 HKCU
HKCU 0x80000001 HKCU
HKEY_LOCAL_MACHINE 0x80000002 HKLM
HKLM 0x80000002 HKLM
HKEY_USERS 0x80000003 HKU
HKU 0x80000003 HKU
HKEY_PERFORMANCE_DATA 0x80000004 HKEY_PERFORMANCE_DATA
HKEY_CURRENT_CONFIG 0x80000005 HKEY_CURRENT_CONFIG
HKEY_DYN_DATA 0x80000006 HKEY_DYN_DATA
HKEY_PERFORMANCE_TEXT 0x80000050 HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT 0x80000060 HKEY_PERFORMANCE_NLSTEXT
registry.REGISTRY_ACCESS = <Constants: {u'KEY_ALL_ACCESS': 983103, u'KEY_EXECUTE': 131097, u'KEY_WOW64_32KEY': 512, u'KEY_WOW64_64KEY': 256, u'KEY_READ': 131097, u'KEY_QUERY_VALUE': 1, u'KEY_ENUMERATE_SUB_KEYS': 8, u'KEY_NOTIFY': 16, u'KEY_CREATE_LINK': 32, u'KEY_CREATE_SUB_KEY': 4, u'KEY_SET_VALUE': 2, u'KEY_WRITE': 131078}>

Registry-specific access rights

Name Val Win32
KEY_QUERY_VALUE 0x000001 KEY_QUERY_VALUE
KEY_SET_VALUE 0x000002 KEY_SET_VALUE
KEY_CREATE_SUB_KEY 0x000004 KEY_CREATE_SUB_KEY
KEY_ENUMERATE_SUB_KEYS 0x000008 KEY_ENUMERATE_SUB_KEYS
KEY_NOTIFY 0x000010 KEY_NOTIFY
KEY_CREATE_LINK 0x000020 KEY_CREATE_LINK
KEY_WOW64_64KEY 0x000100 KEY_WOW64_64KEY
KEY_WOW64_32KEY 0x000200 KEY_WOW64_32KEY
KEY_WRITE 0x020006 KEY_WRITE
KEY_EXECUTE 0x020019 KEY_READ
KEY_READ 0x020019 KEY_READ
KEY_ALL_ACCESS 0x0F003F KEY_ALL_ACCESS
registry.REGISTRY_VALUE_TYPE = <Constants: {u'REG_MULTI_SZ': 7, u'REG_DWORD_BIG_ENDIAN': 5, u'REG_SZ': 1, u'REG_LINK': 6, u'REG_BINARY': 3, u'REG_EXPAND_SZ': 2, u'REG_DWORD': 4, u'REG_NONE': 0, u'REG_QWORD': 11, u'REG_QWORD_LITTLE_ENDIAN': 11, u'REG_DWORD_LITTLE_ENDIAN': 4}>

Registry value data types

Name Val Win32
REG_NONE 0x000 REG_NONE
REG_SZ 0x001 REG_SZ
REG_EXPAND_SZ 0x002 REG_EXPAND_SZ
REG_BINARY 0x003 REG_BINARY
REG_DWORD 0x004 REG_DWORD_LITTLE_ENDIAN
REG_DWORD_LITTLE_ENDIAN 0x004 REG_DWORD_LITTLE_ENDIAN
REG_DWORD_BIG_ENDIAN 0x005 REG_DWORD_BIG_ENDIAN
REG_LINK 0x006 REG_LINK
REG_MULTI_SZ 0x007 REG_MULTI_SZ
REG_QWORD 0x00B REG_QWORD_LITTLE_ENDIAN
REG_QWORD_LITTLE_ENDIAN 0x00B REG_QWORD_LITTLE_ENDIAN

Exceptions

exception registry.x_registry(errno=None, errctx=None, errmsg=None)[source]

Base exception for all registry exceptions

exception registry.x_moniker(errno=None, errctx=None, errmsg=None)[source]

Base exception for problems with monikers

exception registry.x_moniker_ill_formed(errno=None, errctx=None, errmsg=None)[source]

Raised when a moniker does not match the correct format

exception registry.x_moniker_no_root(errno=None, errctx=None, errmsg=None)[source]

Raised when a moniker has no Hive in the first or second position

References

See also

Using the registry module
Cookbook examples of using the registry module

To Do

  • New Vista / 2008 Registry funcs (transactions etc.)
  • Export-a-like functionality to create a human-readable export function

Table Of Contents

Previous topic

The Pipe classes

Next topic

security

This Page