`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¶

create_moniker(computer, root, path, value=None)¶

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(root, access=u'F', accept_value=True)¶

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

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`

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

copy(from_key, to_key)¶

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

Parameters:	from_key – anything accepted by `registry()` to_key – anything accepted by `registry()`
Returns:	a `Registry` object for to_key

delete(root, subkey='')¶

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:	root – anything accepted by `registry()` subkey – anything accepted by `Registry.get_key()`
Returns:	a `Registry` object for root

create(root, subkey='', 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:	root – anything accepted by `registry()` subkey – anything accepted by `Registry.get_key()` sec – a `security.Security` instance or None
Returns:	a `Registry` object for 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

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

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)

Classes¶

class Registry(moniker, access=u'F')¶

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)¶

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)¶

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

Parameters:	from_key – anything accepted by `registry()` to_key – anything accepted by `registry()`
Returns:	a `Registry` object for to_key

create(root, subkey='', 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:	root – anything accepted by `registry()` subkey – anything accepted by `Registry.get_key()` sec – a `security.Security` instance or None
Returns:	a `Registry` object for root

del_value(label)¶: Removed the value identified by label from this registry key

delete(root, subkey='')¶

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:	root – anything accepted by `registry()` subkey – anything accepted by `Registry.get_key()`
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'F', accept_value=True)¶: 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)¶

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)¶: Return the key’s value corresponding to name

get_value_type(name)¶: 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()¶

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')¶

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)¶

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¶

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_HIVE¶

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

Name	Val	Win32
HKEY_PERFORMANCE_NLSTEXT	-2147483552	HKEY_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT	-2147483568	HKEY_PERFORMANCE_TEXT
HKEY_DYN_DATA	-2147483642	HKEY_DYN_DATA
HKEY_CURRENT_CONFIG	-2147483643	HKEY_CURRENT_CONFIG
HKEY_PERFORMANCE_DATA	-2147483644	HKEY_PERFORMANCE_DATA
HKEY_USERS	-2147483645	HKU
HKU	-2147483645	HKU
HKEY_LOCAL_MACHINE	-2147483646	HKLM
HKLM	-2147483646	HKLM
HKEY_CURRENT_USER	-2147483647	HKCU
HKCU	-2147483647	HKCU
HKEY_CLASSES_ROOT	-2147483648	HKCR
HKCR	-2147483648	HKCR

REGISTRY_ACCESS¶

Registry-specific access rights

Name	Val	Win32
KEY_QUERY_VALUE	1	KEY_QUERY_VALUE
KEY_WRITE	131078	KEY_WRITE
KEY_EXECUTE	131097	KEY_READ
KEY_READ	131097	KEY_READ
KEY_NOTIFY	16	KEY_NOTIFY
KEY_SET_VALUE	2	KEY_SET_VALUE
KEY_WOW64_64KEY	256	KEY_WOW64_64KEY
KEY_CREATE_LINK	32	KEY_CREATE_LINK
KEY_CREATE_SUB_KEY	4	KEY_CREATE_SUB_KEY
KEY_WOW64_32KEY	512	KEY_WOW64_32KEY
KEY_ENUMERATE_SUB_KEYS	8	KEY_ENUMERATE_SUB_KEYS
KEY_ALL_ACCESS	983103	KEY_ALL_ACCESS

REGISTRY_VALUE_TYPE¶

Registry value data types

Name	Val	Win32
REG_NONE	0	REG_NONE
REG_SZ	1	REG_SZ
REG_QWORD	11	REG_QWORD_LITTLE_ENDIAN
REG_QWORD_LITTLE_ENDIAN	11	REG_QWORD_LITTLE_ENDIAN
REG_EXPAND_SZ	2	REG_EXPAND_SZ
REG_BINARY	3	REG_BINARY
REG_DWORD	4	REG_DWORD_LITTLE_ENDIAN
REG_DWORD_LITTLE_ENDIAN	4	REG_DWORD_LITTLE_ENDIAN
REG_DWORD_BIG_ENDIAN	5	REG_DWORD_BIG_ENDIAN
REG_LINK	6	REG_LINK
REG_MULTI_SZ	7	REG_MULTI_SZ

Exceptions¶

exception x_registry(errno=None, errctx=None, errmsg=None)¶: Base exception for all registry exceptions

exception x_moniker(errno=None, errctx=None, errmsg=None)¶: Base exception for problems with monikers

exception x_moniker_ill_formed(errno=None, errctx=None, errmsg=None)¶: Raised when a moniker does not match the correct format

exception x_moniker_no_root(errno=None, errctx=None, errmsg=None)¶: Raised when a moniker has no Hive in the first or second position

References¶

To Do¶

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

`registry` – Registry¶

Functions¶

Classes¶

Constants¶

Exceptions¶

References¶

To Do¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

registry – Registry¶

Functions¶

Classes¶

Constants¶

Exceptions¶

References¶

To Do¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation

`registry` – Registry¶