| Name | fake-winreg JSON |
| Version |
1.6.3
JSON |
| download |
| home_page | |
| Summary | fake winreg, in order to test registry related functions on linux |
| upload_time | 2023-07-20 09:38:14 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
fake_winreg
===========
Version v1.6.3 as of 2023-07-20 see `Changelog`_
|build_badge| |codeql| |license| |jupyter| |pypi|
|pypi-downloads| |black| |codecov| |cc_maintain| |cc_issues| |cc_coverage| |snyk|
.. |build_badge| image:: https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml/badge.svg
:target: https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml
.. |codeql| image:: https://github.com/bitranox/fake_winreg/actions/workflows/codeql-analysis.yml/badge.svg?event=push
:target: https://github.com//bitranox/fake_winreg/actions/workflows/codeql-analysis.yml
.. |license| image:: https://img.shields.io/github/license/webcomics/pywine.svg
:target: http://en.wikipedia.org/wiki/MIT_License
.. |jupyter| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/bitranox/fake_winreg/master?filepath=fake_winreg.ipynb
.. for the pypi status link note the dashes, not the underscore !
.. |pypi| image:: https://img.shields.io/pypi/status/fake-winreg?label=PyPI%20Package
:target: https://badge.fury.io/py/fake_winreg
.. |codecov| image:: https://img.shields.io/codecov/c/github/bitranox/fake_winreg
:target: https://codecov.io/gh/bitranox/fake_winreg
.. |cc_maintain| image:: https://img.shields.io/codeclimate/maintainability-percentage/bitranox/fake_winreg?label=CC%20maintainability
:target: https://codeclimate.com/github/bitranox/fake_winreg/maintainability
:alt: Maintainability
.. |cc_issues| image:: https://img.shields.io/codeclimate/issues/bitranox/fake_winreg?label=CC%20issues
:target: https://codeclimate.com/github/bitranox/fake_winreg/maintainability
:alt: Maintainability
.. |cc_coverage| image:: https://img.shields.io/codeclimate/coverage/bitranox/fake_winreg?label=CC%20coverage
:target: https://codeclimate.com/github/bitranox/fake_winreg/test_coverage
:alt: Code Coverage
.. |snyk| image:: https://snyk.io/test/github/bitranox/fake_winreg/badge.svg
:target: https://snyk.io/test/github/bitranox/fake_winreg
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/fake-winreg
:target: https://pypi.org/project/fake-winreg/
:alt: PyPI - Downloads
FUNCTION
========
test winreg functions on a fake registry on windows and linux, without messing up Your real registry.
Fully type annotated and documented, so You can enjoy the type hints in Your favorite IDE
This is perfect for TDD, creating registry related code and covering most issues before You hit a real registry with Your tests.
If You want to see real life examples, check out `lib_registry <https://github.com/bitranox/lib_registry>`_
- get all winreg function names, type hints and constants, even on linux in Your favorite IDE
- you plug in this "fake _winreg" and can test all Your Registry related functions on linux, wine, windows
- all the predefined HKEY\_*, REG\_*, KEY\_* constants are there.
- You might even test against a set of different fake registries
- you can use (almost) all winreg functions against a "fake" registry
- it behaves very much like the real "winreg" (version 3.3),
like not accepting keyword arguments for most functions,
accepting sub_keys to be "None" or "blank" in some, but not all functions, etc.
- it raises the same Exceptions like winreg
- read, write registry values and keys, etc.
LIMITATIONS
===========
- there are no access rights - sam is not supported.
That means You can read/write/delete Keys and values in the fake registry,
even if You opened the key with access right "KEY_READ".
You can Delete Keys and Values in HKEY_LOCAL_MACHINE and so on, even if You dont have Admin Rights.
This is not an security issue, since You test against a fake registry - and You test mostly Your own software.
If You need it, contributions are welcome ! (somehow it would make sense for TDD to have it)
- at the moment you can not dump a real registry and save it, in order to use it as a fake registry - that means
all the keys You need, You have to set manually at the moment.
if I catch the time, I will polish up my old project "fingerprint" and make a compatible file format to dump / read / write registry branches.
- some (few) winreg functions are not implemented - if You miss out something, give me a note, i will integrate it
- obviously we can not connect to the registry of another windows computer over the network
- KEY_WOW64_32KEY is not supported. We show always the same ...
- auditing event's are not supported
----
automated tests, Github Actions, Documentation, Badges, etc. are managed with `PizzaCutter <https://github
.com/bitranox/PizzaCutter>`_ (cookiecutter on steroids)
Python version required: 3.8.0 or newer
tested on recent linux with python 3.8, 3.9, 3.10, 3.11, 3.12-dev, pypy-3.9, pypy-3.10 - architectures: amd64
`100% code coverage <https://codeclimate.com/github/bitranox/fake_winreg/test_coverage>`_, flake8 style checking ,mypy static type checking ,tested under `Linux, macOS, Windows <https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml>`_, automatic daily builds and monitoring
----
- `Try it Online`_
- `Usage`_
- `Usage from Commandline`_
- `Installation and Upgrade`_
- `Requirements`_
- `Acknowledgements`_
- `Contribute`_
- `Report Issues <https://github.com/bitranox/fake_winreg/blob/master/ISSUE_TEMPLATE.md>`_
- `Pull Request <https://github.com/bitranox/fake_winreg/blob/master/PULL_REQUEST_TEMPLATE.md>`_
- `Code of Conduct <https://github.com/bitranox/fake_winreg/blob/master/CODE_OF_CONDUCT.md>`_
- `License`_
- `Changelog`_
----
Try it Online
-------------
You might try it right away in Jupyter Notebook by using the "launch binder" badge, or click `here <https://mybinder.org/v2/gh/{{rst_include.
repository_slug}}/master?filepath=fake_winreg.ipynb>`_
Usage
-----------
.. code-block:: python
import fake_winreg as winreg
# setup a fake registry for windows
fake_registry = winreg.fake_reg_tools.get_minimal_windows_testregistry()
# load the fake registry into fake winreg
winreg.load_fake_registry(fake_registry)
# try the fake registry
reg_handle = winreg.ConnectRegistry(None, winreg.HKEY_LOCAL_MACHINE)
# Open Key
reg_key = winreg.OpenKey(reg_handle, r'SOFTWARE\Microsoft\Windows NT\CurrentVersion')
winreg.QueryValueEx(reg_key, 'CurrentBuild')
here a more comprehensive description of the winreg methods (which are implemented by fake registry)
following custom data types are defined:
.. code-block:: python
# the possible types of a handle that can be passed to winreg functions
Handle = Union[int, HKEYType, PyHKEY]
.. code-block:: python
# the possible types of data that we can receive or write to registry values
RegData = Union[None, bytes, int, str, List[str]]
ConnectRegistry
---------------
.. code-block:: python
def ConnectRegistry(computer_name: Optional[str], key: Handle) -> PyHKEY: # noqa
"""
Establishes a connection to a predefined registry handle on another computer, and returns a new handle object.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
computer_name:
the name of the remote computer, of the form r"\\computername" or simply "computername"
If None or '', the local computer is used.
if the computer name can not be resolved on the network,fake_winreg will deliver:
"OSError: [WinError 1707] The network address is invalid"
if the computer_name given can be reached, we finally raise:
"SystemError: System error 53 has occurred. The network path was not found"
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
Returns
-------
the handle of the opened key. If the function fails, an OSError exception is raised.
Exceptions
----------
OSError: [WinError 1707] The network address is invalid
if the computer name can not be resolved
FileNotFoundError: [WinError 53] The network path was not found
if the network path is invalid
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: ConnectRegistry() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
winreg.ConnectRegistry auditing event (NOT IMPLEMENTED), with arguments computer_name, key.
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> # Connect
>>> ConnectRegistry(None, HKEY_LOCAL_MACHINE)
<...PyHKEY object at ...>
>>> # Try to connect to computer
>>> ConnectRegistry('HAL', HKEY_LOCAL_MACHINE)
Traceback (most recent call last):
...
OSError: [WinError 1707] The network address is invalid
>>> # Try connect to computer, but invalid network path
>>> ConnectRegistry(r'localhost\\invalid\\path', HKEY_LOCAL_MACHINE)
Traceback (most recent call last):
...
FileNotFoundError: [WinError 53] The network path was not found
>>> # provoke wrong key type Error
>>> ConnectRegistry('fake_registry_test_computer', 'fake_registry_key') # noqa
Traceback (most recent call last):
...
TypeError: The object is not a PyHKEY object
>>> # provoke Invalid Handle Error
>>> ConnectRegistry(None, 42)
Traceback (most recent call last):
...
OSError: [WinError 6] The handle is invalid
>>> # must not accept keyword parameters
>>> ConnectRegistry(computer_name=None, key=HKEY_LOCAL_MACHINE)
Traceback (most recent call last):
...
TypeError: ConnectRegistry() got some positional-only arguments passed as keyword arguments: 'computer_name, key'
"""
CloseKey
---------------
.. code-block:: python
def CloseKey(hkey: Union[int, HKEYType]) -> None: # noqa
"""
Closes a previously opened registry key.
the function does NOT accept named parameters, only positional parameters
Note: If hkey is not closed using this method (or via hkey.Close()), it is closed when the hkey object is destroyed by Python.
Parameter
---------
hkey:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
Exceptions
----------
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: CloseKey() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> # Test
>>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> CloseKey(HKEY_LOCAL_MACHINE)
>>> # Test hkey = None
>>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> CloseKey(None) # noqa
>>> # does not accept keyword parameters
>>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> CloseKey(hkey=HKEY_LOCAL_MACHINE)
Traceback (most recent call last):
...
TypeError: CloseKey() got some positional-only arguments passed as keyword arguments: 'hkey'
"""
CreateKey
---------------
.. code-block:: python
def CreateKey(key: Handle, sub_key: Optional[str]) -> PyHKEY: # noqa
"""
Creates or opens the specified key.
The sub_key can contain a directory structure like r'Software\\xxx\\yyy' - all the parents to yyy will be created
the function does NOT accept named parameters, only positional parameters
Result
------
If key is one of the predefined keys, sub_key may be None or empty string,
and a new handle will be returned with access KEY_WRITE
If the key already exists, this function opens the existing key.
otherwise it will return the handle to the new created key with access KEY_WRITE
From original winreg description (this is wrong):
If key is one of the predefined keys, sub_key may be None.
In that case, the handle returned is the same key handle passed in to the function.
I always get back a different handle, this seems to be wrong (needs testing)
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
a string that names the key this method opens or creates.
sub_key can be None or empty string when the key is one of the predefined hkeys
Exceptions
----------
PermissionError: [WinError 5] Access is denied
if You dont have the right to Create the Key (at least KEY_CREATE_SUBKEY)
OSError: [WinError 1010] The configuration registry key is invalid
if the function fails to create the Key
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: CreateKey() argument 2 must be str or None, not <type>
if the subkey is anything else then str or None
OSError: [WinError 1010] The configuration registry key is invalid
if the subkey is None or empty string, and key is not one of the predefined HKEY Constants
TypeError: CreateKey() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.CreateKey with arguments key, sub_key, access. (NOT IMPLEMENTED)
Raises an auditing event winreg.OpenKey/result with argument key. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> # Connect
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> # create key
>>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy')
>>> # create an existing key - we should NOT get the same handle back
>>> key_handle_existing = CreateKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy')
>>> assert key_handle_existing != key_handle_created
>>> # provoke Error key None
>>> CreateKey(None, r'SOFTWARE\\xxxx\\yyyy') # noqa
Traceback (most recent call last):
...
TypeError: None is not a valid HKEY in this context
>>> # provoke Error key wrong type
>>> CreateKey('test_fake_key_invalid', r'SOFTWARE\\xxxx\\yyyy') # noqa
Traceback (most recent call last):
...
TypeError: The object is not a PyHKEY object
>>> # provoke Error key >= 2 ** 64
>>> CreateKey(2 ** 64, r'SOFTWARE\\xxxx\\yyyy')
Traceback (most recent call last):
...
OverflowError: int too big to convert
>>> # provoke invalid handle
>>> CreateKey(42, r'SOFTWARE\\xxxx\\yyyy')
Traceback (most recent call last):
...
OSError: [WinError 6] The handle is invalid
>>> # provoke Error on empty subkey
>>> key_handle_existing = CreateKey(key_handle_created, r'')
Traceback (most recent call last):
...
OSError: [WinError 1010] The configuration registry key is invalid
>>> # provoke Error subkey wrong type
>>> key_handle_existing = CreateKey(reg_handle, 1) # noqa
Traceback (most recent call last):
...
TypeError: CreateKey() argument 2 must be str or None, not int
>>> # Test subkey=None with key as predefined HKEY - that should pass
>>> # the actual behaviour is different to the winreg documentation !
>>> key_handle_hkcu = CreateKey(HKEY_CURRENT_USER, None)
>>> key_handle_hkcu2 = CreateKey(key_handle_hkcu, None)
>>> assert key_handle_hkcu != key_handle_hkcu2
>>> # Test subkey='' with key as predefined HKEY - that should pass
>>> # the actual behaviour is different to the winreg documentation !
>>> key_handle_hkcu = CreateKey(HKEY_CURRENT_USER, '')
>>> key_handle_hkcu2 = CreateKey(key_handle_hkcu, '')
>>> assert key_handle_hkcu != key_handle_hkcu2
>>> # Teardown
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy')
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx')
"""
CreateKeyEx
---------------
.. code-block:: python
def CreateKeyEx(key: Handle, sub_key: str, reserved: int = 0, access: int = KEY_WRITE) -> PyHKEY: # noqa
"""
Creates or opens the specified key, returning a handle object with access as passed in the parameter
The sub_key can contain a directory structure like r'Software\\xxx\\yyy' - all the parents to yyy will be created
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
a string (can be empty) that names the key this method opens or creates.
the sub_key must not be None.
reserved:
reserved is a reserved integer, and has to be zero. The default is zero.
access:
a integer that specifies an access mask that describes the desired security access for returned key handle
Default is KEY_WRITE. See Access Rights for other allowed values.
(any integer is accepted here in original winreg, bit masked against KEY_* access parameters)
Returns
-------
the handle of the opened key.
Exceptions
----------
OSError: [WinError 1010] The configuration registry key is invalid
if the function fails to create the Key
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
OSError: [WinError 1010] The configuration registry key is invalid
if the subkey is None
TypeError: CreateKeyEx() argument 2 must be str or None, not <type>
if the subkey is anything else then str
TypeError: CreateKeyEx() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.CreateKey with arguments key, sub_key, access. (NOT IMPLEMENTED)
Raises an auditing event winreg.OpenKey/result with argument key. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> # Connect
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> # create key
>>> key_handle_created = CreateKeyEx(reg_handle, r'SOFTWARE\\xxxx\\yyyy', 0, KEY_WRITE)
>>> # create an existing key - we get a new handle back
>>> key_handle_existing = CreateKeyEx(reg_handle, r'SOFTWARE\\xxxx\\yyyy', 0, KEY_WRITE)
>>> assert key_handle_existing != key_handle_created
>>> # provoke Error key None
>>> CreateKeyEx(None, r'SOFTWARE\\xxxx\\yyyy', 0 , KEY_WRITE) # noqa
Traceback (most recent call last):
...
TypeError: None is not a valid HKEY in this context
>>> # provoke Error key wrong type
>>> CreateKeyEx('test_fake_key_invalid', r'SOFTWARE\\xxxx\\yyyy', 0 , KEY_WRITE) # noqa
Traceback (most recent call last):
...
TypeError: The object is not a PyHKEY object
>>> # provoke Error key >= 2 ** 64
>>> CreateKeyEx(2 ** 64, r'SOFTWARE\\xxxx\\yyyy', 0 , KEY_WRITE)
Traceback (most recent call last):
...
OverflowError: int too big to convert
>>> # provoke invalid handle
>>> CreateKeyEx(42, r'SOFTWARE\\xxxx\\yyyy', 0 , KEY_WRITE)
Traceback (most recent call last):
...
OSError: [WinError 6] The handle is invalid
>>> # subkey empty is valid
>>> discard = key_handle_existing = CreateKeyEx(reg_handle, r'', 0 , KEY_WRITE)
>>> # subkey None is invalid
>>> discard = key_handle_existing = CreateKeyEx(reg_handle, None, 0 , KEY_WRITE) # noqa
Traceback (most recent call last):
...
OSError: [WinError 1010] The configuration registry key is invalid
>>> # provoke Error subkey wrong type
>>> key_handle_existing = CreateKeyEx(reg_handle, 1, 0 , KEY_WRITE) # noqa
Traceback (most recent call last):
...
TypeError: CreateKeyEx() argument 2 must be str or None, not int
>>> # Teardown
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy')
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx')
"""
DeleteKey
---------------
.. code-block:: python
def DeleteKey(key: Handle, sub_key: str) -> None: # noqa
"""
Deletes the specified key. This method can not delete keys with subkeys.
If the method succeeds, the entire key, including all of its values, is removed.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
a string that must be a subkey of the key identified by the key parameter or ''.
sub_key must not be None, and the key may not have subkeys.
Exceptions
----------
OSError ...
if it fails to Delete the Key
PermissionError: [WinError 5] Access is denied
if the key specified to be deleted have subkeys
FileNotFoundError: [WinError 2] The system cannot find the file specified
if the Key specified to be deleted does not exist
TypeError: DeleteKey() argument 2 must be str, not <type>
if parameter sub_key type is anything else but string
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: DeleteKey() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy\\zzz')
>>> # Delete key without subkeys
>>> # assert __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\SOFTWARE\\xxxx\\yyyy\\zzz')
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy\\zzz')
>>> # assert not __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\SOFTWARE\\xxxx\\yyyy\\zzz')
>>> # try to delete non existing key (it was deleted before)
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy\\zzz')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> # try to delete key with subkey
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx')
Traceback (most recent call last):
...
PermissionError: [WinError 5] Access is denied
>>> # provoke error subkey = None
>>> DeleteKey(reg_handle, None) # noqa
Traceback (most recent call last):
...
TypeError: DeleteKey() argument 2 must be str, not None
>>> # subkey = '' is allowed here
>>> reg_handle_sub = OpenKey(reg_handle, r'SOFTWARE\\xxxx\\yyyy')
>>> DeleteKey(reg_handle_sub, '')
>>> # Teardown
>>> DeleteKey(reg_handle, r'SOFTWARE\\xxxx')
"""
DeleteKeyEx
---------------
.. code-block:: python
def DeleteKeyEx(key: Handle, sub_key: str, access: int = KEY_WOW64_64KEY, reserved: int = 0) -> None: # noqa
"""
Deletes the specified key. This method can not delete keys with subkeys.
If the method succeeds, the entire key, including all of its values, is removed.
the function does NOT accept named parameters, only positional parameters
Note The DeleteKeyEx() function is implemented with the RegDeleteKeyEx Windows API function,
which is specific to 64-bit versions of Windows. See the RegDeleteKeyEx documentation.
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
a string that must be a subkey of the key identified by the key parameter or ''.
sub_key must not be None, and the key may not have subkeys.
access:
a integer that specifies an access mask that describes the desired security access for the key.
Default is KEY_WOW64_64KEY. See Access Rights for other allowed values. (NOT IMPLEMENTED)
(any integer is accepted here in original winreg
reserved:
reserved is a reserved integer, and must be zero. The default is zero.
Exceptions
----------
OSError: ...
if it fails to Delete the Key
PermissionError: [WinError 5] Access is denied
if the key specified to be deleted have subkeys
FileNotFoundError: [WinError 2] The system cannot find the file specified
if the Key specified to be deleted does not exist
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
NotImplementedError:
On unsupported Windows versions (NOT IMPLEMENTED)
TypeError: DeleteKeyEx() argument 2 must be str, not <type>
if parameter sub_key type is anything else but string
TypeError: an integer is required (got NoneType)
if parameter access is None
TypeError: an integer is required (got type <type>)
if parameter access is not int
OverflowError: Python int too large to convert to C long
if parameter access is > 64 Bit Integer Value
TypeError: an integer is required (got type <type>)
if parameter reserved is not int
OverflowError: Python int too large to convert to C long
if parameter reserved is > 64 Bit Integer Value
OSError: WinError 87 The parameter is incorrect
if parameter reserved is not 0
TypeError: DeleteKeyEx() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> key_handle_created = CreateKey(reg_handle, r'Software\\xxxx\\yyyy\\zzz')
>>> # Delete key without subkeys
>>> # assert __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\SOFTWARE\\xxxx\\yyyy\\zzz')
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx\\yyyy\\zzz')
>>> # assert not __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\SOFTWARE\\xxxx\\yyyy\\zzz')
>>> # try to delete non existing key (it was deleted before)
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx\\yyyy\\zzz')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> # try to delete key with subkey
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx')
Traceback (most recent call last):
...
PermissionError: [WinError 5] Access is denied
>>> # try to delete key with subkey = None
>>> DeleteKeyEx(reg_handle, None) # noqa
Traceback (most recent call last):
...
TypeError: DeleteKeyEx() argument 2 must be str, not None
>>> # try to delete key with access = KEY_WOW64_32KEY
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx\\yyyy', KEY_WOW64_32KEY)
Traceback (most recent call last):
...
NotImplementedError: we only support KEY_WOW64_64KEY
>>> # Teardown
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx\\yyyy')
>>> DeleteKeyEx(reg_handle, r'Software\\xxxx')
"""
DeleteValue
---------------
.. code-block:: python
def DeleteValue(key: Handle, value: Optional[str]) -> None: # noqa
"""
Removes a named value from a registry key.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
value:
None, or a string that identifies the value to remove.
if value is None, or '' it deletes the default Value of the Key
Exceptions
----------
FileNotFoundError: [WinError 2] The system cannot find the file specified'
if the Value specified to be deleted does not exist
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: DeleteValue() argument 2 must be str or None, not <type>
if parameter value type is anything else but string or None
TypeError: DeleteValue() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.DeleteValue with arguments key, value. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value')
>>> # Delete Default Value, value_name NONE (not set, therefore Error
>>> DeleteValue(key_handle, None)
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> # Delete Default Value, value_name '' (not set, therefore Error
>>> DeleteValue(key_handle, '')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> # Delete Non Existing Value
>>> DeleteValue(key_handle, 'some_test')
"""
EnumKey
---------------
.. code-block:: python
def EnumKey(key: Handle, index: int) -> str: # noqa
"""
Enumerates subkeys of an open registry key, returning a string.
The function retrieves the name of one subkey each time it is called.
It is typically called repeatedly until an OSError exception is raised,
indicating, no more values are available.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
index:
an integer that identifies the index of the key to retrieve.
Exceptions:
-----------
OSError: [WinError 259] No more data is available
if the index is out of Range
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: an integer is required (got type <type>)
if parameter index is type different from int
OverflowError: Python int too large to convert to C int
if parameter index is > 64 Bit Integer Value
TypeError: EnumKey() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.EnumKey with arguments key, index. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> # test get the first profile in the profile list
>>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList')
>>> assert isinstance(EnumKey(key_handle, 0), str)
>>> # provoke error test out of index
>>> EnumKey(key_handle, 100000000)
Traceback (most recent call last):
...
OSError: [WinError 259] No more data is available
>>> # provoke error wrong key handle
>>> EnumKey(42, 0)
Traceback (most recent call last):
...
OSError: [WinError 6] The handle is invalid
>>> # no check for overflow here !
>>> EnumKey(2 ** 64, 0)
Traceback (most recent call last):
...
OverflowError: int too big to convert
"""
EnumValue
---------------
.. code-block:: python
def EnumValue(key: Handle, index: int) -> Tuple[str, RegData, int]: # noqa
"""
Enumerates values of an open registry key, returning a tuple.
The function retrieves the name of one value each time it is called.
It is typically called repeatedly, until an OSError exception is raised, indicating no more values.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
index:
an integer that identifies the index of the key to retrieve.
Result
------
The result is a tuple of 3 items:
======== ==============================================================================================
Index Meaning
======== ==============================================================================================
0 A string that identifies the value name
1 An object that holds the value data, and whose type depends on the underlying registry type
2 An integer giving the registry type for this value (see table in docs for SetValueEx())
======== ==============================================================================================
Exceptions
----------
OSError: [WinError 259] No more data is available
if the index is out of Range
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: an integer is required (got type <type>)
if parameter index is type different from int
OverflowError: Python int too large to convert to C int
if parameter index is > 64 Bit Integer Value
TypeError: EnumValue() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.EnumValue with arguments key, index. (NOT IMPLEMENTED)
Registry Types
--------------
============== ============================== ============================== ==========================================================================
type(int) type name accepted python Types Description
============== ============================== ============================== ==========================================================================
0 REG_NONE None, bytes No defined value type.
1 REG_SZ None, str A null-terminated string.
2 REG_EXPAND_SZ None, str Null-terminated string containing references to
environment variables (%PATH%).
(Python handles this termination automatically.)
3 REG_BINARY None, bytes Binary data in any form.
4 REG_DWORD None, int A 32-bit number.
4 REG_DWORD_LITTLE_ENDIAN None, int A 32-bit number in little-endian format.
5 REG_DWORD_BIG_ENDIAN None, bytes A 32-bit number in big-endian format.
6 REG_LINK None, bytes A Unicode symbolic link.
7 REG_MULTI_SZ None, List[str] A sequence of null-terminated strings, terminated by two null characters.
8 REG_RESOURCE_LIST None, bytes A device-driver resource list.
9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.
10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.
11 REG_QWORD None, bytes A 64 - bit number.
11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.
============== ============================== ============================== ==========================================================================
* all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.
by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> # Read the current Version
>>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> EnumValue(key_handle, 0)
(...)
>>> # test out of index
>>> EnumValue(key_handle, 100000000)
Traceback (most recent call last):
...
OSError: [WinError 259] No more data is available
"""
OpenKey
---------------
.. code-block:: python
def OpenKey(key: Handle, sub_key: Union[str, None], reserved: int = 0, access: int = KEY_READ) -> PyHKEY: # noqa
"""
Opens the specified key, the result is a new handle to the specified key.
one of the few functions of winreg that accepts named parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
None, or a string that names the key this method opens or creates.
If key is one of the predefined keys, sub_key may be None.
reserved:
reserved is a reserved integer, and should be zero. The default is zero.
access:
a integer that specifies an access mask that describes the desired security access for the key.
Default is KEY_READ. See Access Rights for other allowed values.
(any integer is accepted here in original winreg, bit masked against KEY_* access parameters)
Exceptions
----------
OSError: ...
if it fails to open the key
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: OpenKey() argument 2 must be str or None, not <type>
if the sub_key is anything else then str or None
TypeError: an integer is required (got NoneType)
if parameter reserved is None
TypeError: an integer is required (got type <type>)
if parameter reserved is not int
PermissionError: [WinError 5] Access denied
if parameter reserved is > 3)
OverflowError: Python int too large to convert to C long
if parameter reserved is > 64 Bit Integer Value
OSError: [WinError 87] The parameter is incorrect
on some values for reserved (for instance 455565) NOT IMPLEMENTED
TypeError: an integer is required (got type <type>)
if parameter access is not int
OverflowError: Python int too large to convert to C long
if parameter access is > 64 Bit Integer Value
Events
------
Raises an auditing event winreg.OpenKey with arguments key, sub_key, access. # not implemented
Raises an auditing event winreg.OpenKey/result with argument key. # not implemented
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> # Open Key
>>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> assert key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion'
>>> # Open Key mit subkey=None
>>> reg_open1 = OpenKey(key_handle, None)
>>> # Open Key mit subkey=''
>>> reg_open2 = OpenKey(key_handle, '')
>>> # Open the same kay again, but we get a different Handle
>>> reg_open3 = OpenKey(key_handle, '')
>>> assert reg_open2 != reg_open3
>>> # Open non existing Key
>>> OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\DoesNotExist')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
"""
OpenKeyEx
---------------
.. code-block:: python
def OpenKeyEx(key: Handle, sub_key: Optional[str], reserved: int = 0, access: int = KEY_READ) -> PyHKEY: # noqa
"""
Opens the specified key, the result is a new handle to the specified key with the given access.
one of the few functions of winreg that accepts named parameters
Parameter
---------
key:
an already open key, or one of the predefined HKEY_* constants.
sub_key:
None, or a string that names the key this method opens or creates.
If key is one of the predefined keys, sub_key may be None.
reserved:
reserved is a reserved integer, and should be zero. The default is zero.
access:
a integer that specifies an access mask that describes the desired security access for the key.
Default is KEY_READ. See Access Rights for other allowed values.
(any integer is accepted here in original winreg, bit masked against KEY_* access parameters)
Exceptions
----------
OSError: ...
if it fails to open the key
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: OpenKeyEx() argument 2 must be str or None, not <type>
if the subkey is anything else then str or None
TypeError: an integer is required (got NoneType)
if parameter reserved is None
TypeError: an integer is required (got type <type>)
if parameter reserved is not int
PermissionError: [WinError 5] Access denied
if parameter reserved is > 3)
OverflowError: Python int too large to convert to C long
if parameter reserved is > 64 Bit Integer Value
OSError: [WinError 87] The parameter is incorrect
on some values for reserved (for instance 455565) NOT IMPLEMENTED
TypeError: an integer is required (got type <type>)
if parameter access is not int
OverflowError: Python int too large to convert to C long
if parameter access is > 64 Bit Integer Value
Events
------
Raises an auditing event winreg.OpenKey with arguments key, sub_key, access. # not implemented
Raises an auditing event winreg.OpenKey/result with argument key. # not implemented
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> # Open Key
>>> my_key_handle = OpenKeyEx(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> assert my_key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion'
>>> # Open Key with Context Manager
>>> with OpenKeyEx(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion') as my_key_handle:
... assert my_key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion'
>>> # Open non existing Key
>>> OpenKeyEx(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\DoesNotExist')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
"""
QueryInfoKey
---------------
.. code-block:: python
def QueryInfoKey(key: Handle) -> Tuple[int, int, int]: # noqa
"""
Returns information about a key, as a tuple.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
Result
------
The result is a tuple of 3 items:
====== =============================================================================================================
Index, Meaning
====== =============================================================================================================
0 An integer giving the number of sub keys this key has.
1 An integer giving the number of values this key has.
2 An integer giving when the key was last modified (if available) as 100’s of nanoseconds since Jan 1, 1601.
====== =============================================================================================================
Exceptions
----------
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: QueryInfoKey() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.QueryInfoKey with argument key.
Examples and Tests:
-------------------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> # Open Key
>>> key_handle = OpenKeyEx(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> new_reg_key_without_values = CreateKey(key_handle, 'test_without_values')
>>> new_reg_key_with_subkeys_and_values = CreateKey(key_handle, 'test_with_subkeys_and_values')
>>> SetValueEx(new_reg_key_with_subkeys_and_values, 'test_value_name', 0, REG_SZ, 'test_value')
>>> new_reg_key_with_subkeys_subkey = CreateKey(new_reg_key_with_subkeys_and_values, 'subkey_of_test_with_subkeys')
>>> # Test
>>> QueryInfoKey(new_reg_key_without_values)
(0, 0, ...)
>>> QueryInfoKey(new_reg_key_with_subkeys_and_values)
(1, 1, ...)
>>> # Teardown
>>> DeleteKey(key_handle, 'test_without_values')
>>> DeleteKey(new_reg_key_with_subkeys_and_values, 'subkey_of_test_with_subkeys')
>>> DeleteKey(key_handle, 'test_with_subkeys_and_values')
"""
QueryValue
---------------
.. code-block:: python
def QueryValue(key: Handle, sub_key: Union[str, None]) -> str: # noqa
"""
Retrieves the unnamed value (the default value*) for a key, as string.
* Remark : this is the Value what is shown in Regedit as "(Standard)" or "(Default)"
it is usually not set. Nethertheless, even if the value is not set, QueryValue will deliver ''
Values in the registry have name, type, and data components.
This method retrieves the data for a key’s first value that has a NULL name.
But the underlying API call doesn’t return the type, so always use QueryValueEx() if possible.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
sub_key:
None, or a string that names the key this method opens or creates.
If key is one of the predefined keys, sub_key may be None. In that case,
the handle returned is the same key handle passed in to the function.
If the key already exists, this function opens the existing key.
Result
------
the unnamed value as string (if possible)
Exceptions
----------
OSError: [WinError 13] The data is invalid
if the data in the unnamed value is not string
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: QueryValue() argument 2 must be str or None, not <type>
if the subkey is anything else then str or None
TypeError: QueryValue() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events:
-------
Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\lib_registry_test')
>>> # read Default Value, which is ''
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == ''
>>> # sub key can be here None or empty !
>>> assert QueryValue(key_handle_created, '') == ''
>>> assert QueryValue(key_handle_created, None) == ''
>>> # set and get default value
>>> SetValueEx(key_handle_created, '', 0, REG_SZ, 'test1')
>>> assert QueryValueEx(key_handle_created, '') == ('test1', REG_SZ)
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == 'test1'
>>> # set the default value to non-string type, and try to get it with Query Value
>>> SetValueEx(key_handle_created, '', 0, REG_DWORD, 42)
>>> assert QueryValueEx(key_handle_created, '') == (42, REG_DWORD)
>>> QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test')
Traceback (most recent call last):
...
OSError: [WinError 13] The data is invalid
>>> # Teardown
>>> DeleteKey(reg_handle, r'SOFTWARE\\lib_registry_test')
"""
QueryValueEx
---------------
.. code-block:: python
def QueryValueEx(key: Handle, value_name: Optional[str]) -> Tuple[RegData, int]: # noqa
"""
Retrieves data and type for a specified value name associated with an open registry key.
If Value_name is '' or None, it queries the Default Value* of the Key - this will Fail if the Default Value for the Key is not Present.
* Remark : this is the Value what is shown in Regedit as "(Standard)" or "(Default)"
it is usually not set.
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
value_name:
None, or a string that identifies the value to Query
if value is None, or '' it queries the default Value of the Key
Result
------
The result is a tuple of 2 items:
========== =====================================================================================================
Index Meaning
========== =====================================================================================================
0 The value of the registry item.
1 An integer giving the registry type for this value see table
========== =====================================================================================================
Registry Types
--------------
============== ============================== ============================== ==========================================================================
type(int) type name accepted python Types Description
============== ============================== ============================== ==========================================================================
0 REG_NONE None, bytes No defined value type.
1 REG_SZ None, str A null-terminated string.
2 REG_EXPAND_SZ None, str Null-terminated string containing references to
environment variables (%PATH%).
(Python handles this termination automatically.)
3 REG_BINARY None, bytes Binary data in any form.
4 REG_DWORD None, int A 32-bit number.
4 REG_DWORD_LITTLE_ENDIAN None, int A 32-bit number in little-endian format.
5 REG_DWORD_BIG_ENDIAN None, bytes A 32-bit number in big-endian format.
6 REG_LINK None, bytes A Unicode symbolic link.
7 REG_MULTI_SZ None, List[str] A sequence of null-terminated strings, terminated by two null characters.
8 REG_RESOURCE_LIST None, bytes A device-driver resource list.
9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.
10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.
11 REG_QWORD None, bytes A 64 - bit number.
11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.
============== ============================== ============================== ==========================================================================
* all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.
by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.
Exceptions
----------
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: QueryValueEx() argument 2 must be str or None, not <type>
if the value_name is anything else then str or None
TypeError: QueryValueEx() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name. (NOT Implemented)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)
>>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
>>> # Read the current Version
>>> QueryValueEx(key_handle, 'CurrentBuild')
('...', 1)
>>> # Attempt to read a non Existing Default Value
>>> QueryValueEx(key_handle, '')
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> QueryValueEx(key_handle, None)
Traceback (most recent call last):
...
FileNotFoundError: [WinError 2] The system cannot find the file specified
>>> # Set a Default Value
>>> SetValueEx(key_handle, '',0 , REG_SZ, 'test_default_value')
>>> QueryValueEx(key_handle, '')
('test_default_value', 1)
>>> # Delete a Default Value
>>> DeleteValue(key_handle, None)
"""
SetValue
---------------
.. code-block:: python
def SetValue(key: Handle, sub_key: Union[str, None], type: int, value: str) -> None: # noqa
"""
Associates a value with a specified key. (the Default Value* of the Key, usually not set)
* Remark : this is the Value what is shown in Regedit as "(Standard)" or "(Default)"
it is usually not set. Nethertheless, even if the value is not set, QueryValue will deliver ''
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
sub_key:
None, or a string that names the key this method sets the default value
If the key specified by the sub_key parameter does not exist, the SetValue function creates it.
type:
an integer that specifies the type of the data. Currently this must be REG_SZ,
meaning only strings are supported. Use the SetValueEx() function for support for other data types.
value:
a string that specifies the new value.
Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored
as files with the filenames stored in the configuration registry. This helps the registry perform efficiently.
The key identified by the key parameter must have been opened with KEY_SET_VALUE access. (NOT IMPLEMENTED)
Exceptions
----------
TypeError: Could not convert the data to the specified type.
for REG_SZ and REG_EXPAND_SZ, if the data is not NoneType or str,
for REG_DWORD and REG_EXPREG_QWORDAND_SZ, if the data is not NoneType or int,
for REG_MULTI_SZ, if the data is not List[str]:
TypeError: Objects of type '<data_type>' can not be used as binary registry values
for all other REG_* types, if the data is not NoneType or bytes
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: SetValue() argument 2 must be str or None, not <type>
if the subkey is anything else then str or None
TypeError: SetValue() argument 3 must be int not None
if the type is None
TypeError: SetValue() argument 3 must be int not <type>
if the type is anything else but int
TypeError: type must be winreg.REG_SZ
if the type is not string (winreg.REG_SZ)
TypeError: SetValue() argument 4 must be str not None
if the value is None
TypeError: SetValue() argument 4 must be str not <type>
if the value is anything else but str
TypeError: SetValue() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> key_handle = CreateKey(reg_handle, r'SOFTWARE\\lib_registry_test')
>>> # read Default Value, which is ''
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == ''
>>> # sub key can be ''
>>> SetValue(key_handle, '', REG_SZ, 'test1')
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == 'test1'
>>> # sub key can be None
>>> SetValue(key_handle, None, REG_SZ, 'test2')
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == 'test2'
>>> # use sub key
>>> reg_handle_software = OpenKey(reg_handle, 'SOFTWARE')
>>> SetValue(reg_handle_software, 'lib_registry_test', REG_SZ, 'test3')
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test') == 'test3'
>>> # SetValue creates keys on the fly if they do not exist
>>> reg_handle_software = OpenKey(reg_handle, 'SOFTWARE')
>>> SetValue(reg_handle_software, r'lib_registry_test\\ham\\spam', REG_SZ, 'wonderful spam')
>>> assert QueryValue(reg_handle, r'SOFTWARE\\lib_registry_test\\ham\\spam') == 'wonderful spam'
>>> # You can not use other types as string here
>>> SetValue(key_handle, '', REG_DWORD, "42") # noqa
Traceback (most recent call last):
...
TypeError: type must be winreg.REG_SZ
>>> # Tear Down
>>> DeleteKey(reg_handle,r'SOFTWARE\\lib_registry_test\\ham\\spam')
>>> DeleteKey(reg_handle,r'SOFTWARE\\lib_registry_test\\ham')
>>> DeleteKey(reg_handle,r'SOFTWARE\\lib_registry_test')
"""
SetValueEx
---------------
.. code-block:: python
def SetValueEx(key: Handle, value_name: Optional[str], reserved: int, type: int, value: RegData) -> None: # noqa
"""
Stores data in the value field of an open registry key.
value_name is a string that names the subkey with which the value is associated.
if value is None, or '' it sets the default value* of the Key
the function does NOT accept named parameters, only positional parameters
Parameter
---------
key:
the predefined handle to connect to, or one of the predefined HKEY_* constants.
The key identified by the key parameter must have been opened with KEY_SET_VALUE access. (NOT IMPLEMENTED))
To open the key, use the CreateKey() or OpenKey() methods.
value_name:
None, or a string that identifies the value to set
if value is None, or '' it sets the default value* of the Key
* Remark : this is the Value what is shown in Regedit as "(Standard)" or "(Default)"
it is usually not set, but You can set it to any data and datatype - but then it will
only be readable with QueryValueEX, not with QueryValue
reserved:
reserved is a reserved integer, and should be zero. reserved can be anything – zero is always passed to the API.
type:
type is an integer that specifies the type of the data. (see table)
value:
value is a new value.
Value lengths are limited by available memory. Long values (more than 2048 bytes)
should be stored as files with the filenames stored in the configuration registry. This helps the registry perform efficiently.
Registry Types
============== ============================== ============================== ==========================================================================
type(int) type name accepted python Types Description
============== ============================== ============================== ==========================================================================
0 REG_NONE None, bytes No defined value type.
1 REG_SZ None, str A null-terminated string.
2 REG_EXPAND_SZ None, str Null-terminated string containing references to
environment variables (%PATH%).
(Python handles this termination automatically.)
3 REG_BINARY None, bytes Binary data in any form.
4 REG_DWORD None, int A 32-bit number.
4 REG_DWORD_LITTLE_ENDIAN None, int A 32-bit number in little-endian format.
5 REG_DWORD_BIG_ENDIAN None, bytes A 32-bit number in big-endian format.
6 REG_LINK None, bytes A Unicode symbolic link.
7 REG_MULTI_SZ None, List[str] A sequence of null-terminated strings, terminated by two null characters.
8 REG_RESOURCE_LIST None, bytes A device-driver resource list.
9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.
10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.
11 REG_QWORD None, bytes A 64 - bit number.
11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.
============== ============================== ============================== ==========================================================================
* all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.
by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.
Exceptions
----------
OSError: [WinError 6] The handle is invalid
if parameter key is invalid
TypeError: None is not a valid HKEY in this context
if parameter key is None
TypeError: The object is not a PyHKEY object
if parameter key is not integer or PyHKEY type
OverflowError: int too big to convert
if parameter key is > 64 Bit Integer Value
TypeError: SetValueEx() argument 2 must be str or None, not <type>
if the value_name is anything else then str or None
TypeError: SetValueEx() argument 4 must be int not None
if the type is None
TypeError: SetValueEx() argument 4 must be int not <type>
if the type is anything else but int
TypeError: SetValueEx() got some positional-only arguments passed as keyword arguments: '<key>'
if a keyword (named) parameter was passed
Events
------
Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value. (NOT IMPLEMENTED)
Examples
--------
>>> # Setup
>>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()
>>> load_fake_registry(fake_registry)
>>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)
>>> key_handle = CreateKey(reg_handle, r'Software\\lib_registry_test')
>>> # Test
>>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value')
>>> assert QueryValueEx(key_handle, 'some_test') == ('some_test_value', REG_SZ)
>>> # Test Overwrite
>>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value2')
>>> assert QueryValueEx(key_handle, 'some_test') == ('some_test_value2', REG_SZ)
>>> # Test write Default Value of the Key, with value_name None
>>> SetValueEx(key_handle, None, 0, REG_SZ, 'default_value')
>>> assert QueryValue(key_handle, '') == 'default_value'
>>> # Test write Default Value of the Key, with value_name ''
>>> SetValueEx(key_handle, '', 0, REG_SZ, 'default_value_overwritten')
>>> assert QueryValue(key_handle, '') == 'default_value_overwritten'
>>> # Teardown
>>> DeleteValue(key_handle, 'some_test')
>>> DeleteKey(key_handle, '')
"""
Usage from Commandline
------------------------
.. code-block::
Usage: fake_winreg [OPTIONS] COMMAND [ARGS]...
fake winreg, in order to test registry related functions on linux
Options:
--version Show the version and exit.
--traceback / --no-traceback return traceback information on cli
-h, --help Show this message and exit.
Commands:
info get program informations
Installation and Upgrade
------------------------
- Before You start, its highly recommended to update pip and setup tools:
.. code-block::
python -m pip --upgrade pip
python -m pip --upgrade setuptools
- to install the latest release from PyPi via pip (recommended):
.. code-block::
python -m pip install --upgrade fake_winreg
- to install the latest release from PyPi via pip, including test dependencies:
.. code-block::
python -m pip install --upgrade fake_winreg[test]
- to install the latest version from github via pip:
.. code-block::
python -m pip install --upgrade git+https://github.com/bitranox/fake_winreg.git
- include it into Your requirements.txt:
.. code-block::
# Insert following line in Your requirements.txt:
# for the latest Release on pypi:
fake_winreg
# for the latest development version :
fake_winreg @ git+https://github.com/bitranox/fake_winreg.git
# to install and upgrade all modules mentioned in requirements.txt:
python -m pip install --upgrade -r /<path>/requirements.txt
- to install the latest development version, including test dependencies from source code:
.. code-block::
# cd ~
$ git clone https://github.com/bitranox/fake_winreg.git
$ cd fake_winreg
python -m pip install -e .[test]
- via makefile:
makefiles are a very convenient way to install. Here we can do much more,
like installing virtual environments, clean caches and so on.
.. code-block:: shell
# from Your shell's homedirectory:
$ git clone https://github.com/bitranox/fake_winreg.git
$ cd fake_winreg
# to run the tests:
$ make test
# to install the package
$ make install
# to clean the package
$ make clean
# uninstall the package
$ make uninstall
Requirements
------------
following modules will be automatically installed :
.. code-block:: bash
## Project Requirements
click
cli_exit_tools
lib_detect_testenv
wrapt
Acknowledgements
----------------
- special thanks to "uncle bob" Robert C. Martin, especially for his books on "clean code" and "clean architecture"
Contribute
----------
I would love for you to fork and send me pull request for this project.
- `please Contribute <https://github.com/bitranox/fake_winreg/blob/master/CONTRIBUTING.md>`_
License
-------
This software is licensed under the `MIT license <http://en.wikipedia.org/wiki/MIT_License>`_
---
Changelog
=========
- new MAJOR version for incompatible API changes,
- new MINOR version for added functionality in a backwards compatible manner
- new PATCH version for backwards compatible bug fixes
planned:
- KEY_* Permissions on SetValue, ReadValue, etc ...
- test matrix on windows to compare fake and original winreg in detail
- auditing events
- investigate SYSWOW32/64 Views
- Admin Permissions
v1.6.3
---------
2023-07-20:
- require minimum python 3.8
- remove python 3.7 tests
- introduce PEP517 packaging standard
- introduce pyproject.toml build-system
- remove mypy.ini
- remove pytest.ini
- remove setup.cfg
- remove setup.py
- remove .bettercodehub.yml
- remove .travis.yml
- update black config
- clean ./tests/test_cli.py
- add codeql badge
- move 3rd_party_stubs outside the src directory to ``./.3rd_party_stubs``
- add pypy 3.10 tests
- add python 3.12-dev tests
v1.6.2.2
--------
2022-06-01: update to github actions checkout@v3 and setup-python@v3
v1.6.2.1
--------
2022-06-01: update github actions test matrix
v1.6.2
--------
2022-03-29: remedy mypy Untyped decorator makes function "cli_info" untyped
v1.6.1
--------
2022-03-25: fix github actions windows test
v1.6.0
--------
2021-12-19: feature release
- update github actions
- fix "setup.py test"
- fix typing
v1.5.7
--------
2021-12-18: feature release
- allow PyHKEY to act as a context manager, thanks to Ben Rowland
v1.5.6
--------
2020-10-09: service release
- update travis build matrix for linux 3.9-dev
- update travis build matrix (paths) for windows 3.9 / 3.10
v1.5.5
--------
2020-08-08: service release
- fix documentation
- fix travis
- deprecate pycodestyle
- implement flake8
v1.5.4
---------
2020-08-01: fix pypi deploy
v1.5.3
--------
2020-07-31: fix travis build
v0.5.2
--------
2020-07-29: feature release
- use the new pizzacutter template
- use cli_exit_tools
v0.5.1
--------
2020-07-16 : patch release
- fix cli test
- enable traceback option on cli errors
v0.5.0
--------
2020-07-13 : feature release
- CreateKeyEx added
- access rights on CreateKey, CreateKeyEx, OpenKey, OpenKeyEX added
v0.4.1
--------
2020-07-13 : patch release
- 100% coverage
- raise correct Exception when try to connect to Network Computer
v0.4.0
--------
2020-07-13 : feature release
- raise [WinError 1707] The network address is invalid if computername is given
- make HKEYType int convertible
- make type aliases for better readability
- coverage
v0.3.1
--------
2020-07-12 : patch release
- corrected types
v0.3.0
--------
2020-07-12 : feature release
- raise Errors on SetValueEx if type is not appropriate
- raise Errors on wrong parameter types like original winreg
- comprehensive documentation
v0.2.0
--------
2020-07-11 : feature release
- added EnumValue
- added Close() and Detach() for PyHKEY Class
- more consistent naming in internal methods
- added winerror attributes and values in exceptions
- corrected handling of default key values
- corrected race condition when deleting keys
- corrected decorator to check for names arguments
- added stub file for wrapt
- added more REG_* Types
v0.1.1
--------
2020-07-08 : patch release
- new click CLI
- use PizzaCutter Template
- added jupyter notebook
- reorganized modules and import
- updated documentation
v0.1.0
--------
2020-06-17: initial public release
- with all docs in place
Raw data
{
"_id": null,
"home_page": "",
"name": "fake-winreg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Robert Nowotny <bitranox@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e0/50/279ad473416837aecd6adaee518817ce577188d3bea4fc8b3fedaa3ecf5e/fake_winreg-1.6.3.tar.gz",
"platform": null,
"description": "fake_winreg\n===========\n\n\nVersion v1.6.3 as of 2023-07-20 see `Changelog`_\n\n|build_badge| |codeql| |license| |jupyter| |pypi|\n|pypi-downloads| |black| |codecov| |cc_maintain| |cc_issues| |cc_coverage| |snyk|\n\n\n\n.. |build_badge| image:: https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml/badge.svg\n :target: https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml\n\n\n.. |codeql| image:: https://github.com/bitranox/fake_winreg/actions/workflows/codeql-analysis.yml/badge.svg?event=push\n :target: https://github.com//bitranox/fake_winreg/actions/workflows/codeql-analysis.yml\n\n.. |license| image:: https://img.shields.io/github/license/webcomics/pywine.svg\n :target: http://en.wikipedia.org/wiki/MIT_License\n\n.. |jupyter| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/bitranox/fake_winreg/master?filepath=fake_winreg.ipynb\n\n.. for the pypi status link note the dashes, not the underscore !\n.. |pypi| image:: https://img.shields.io/pypi/status/fake-winreg?label=PyPI%20Package\n :target: https://badge.fury.io/py/fake_winreg\n\n.. |codecov| image:: https://img.shields.io/codecov/c/github/bitranox/fake_winreg\n :target: https://codecov.io/gh/bitranox/fake_winreg\n\n.. |cc_maintain| image:: https://img.shields.io/codeclimate/maintainability-percentage/bitranox/fake_winreg?label=CC%20maintainability\n :target: https://codeclimate.com/github/bitranox/fake_winreg/maintainability\n :alt: Maintainability\n\n.. |cc_issues| image:: https://img.shields.io/codeclimate/issues/bitranox/fake_winreg?label=CC%20issues\n :target: https://codeclimate.com/github/bitranox/fake_winreg/maintainability\n :alt: Maintainability\n\n.. |cc_coverage| image:: https://img.shields.io/codeclimate/coverage/bitranox/fake_winreg?label=CC%20coverage\n :target: https://codeclimate.com/github/bitranox/fake_winreg/test_coverage\n :alt: Code Coverage\n\n.. |snyk| image:: https://snyk.io/test/github/bitranox/fake_winreg/badge.svg\n :target: https://snyk.io/test/github/bitranox/fake_winreg\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/fake-winreg\n :target: https://pypi.org/project/fake-winreg/\n :alt: PyPI - Downloads\n\nFUNCTION\n========\n\ntest winreg functions on a fake registry on windows and linux, without messing up Your real registry.\n\nFully type annotated and documented, so You can enjoy the type hints in Your favorite IDE\n\nThis is perfect for TDD, creating registry related code and covering most issues before You hit a real registry with Your tests.\n\nIf You want to see real life examples, check out `lib_registry <https://github.com/bitranox/lib_registry>`_\n\n- get all winreg function names, type hints and constants, even on linux in Your favorite IDE\n- you plug in this \"fake _winreg\" and can test all Your Registry related functions on linux, wine, windows\n- all the predefined HKEY\\_*, REG\\_*, KEY\\_* constants are there.\n- You might even test against a set of different fake registries\n- you can use (almost) all winreg functions against a \"fake\" registry\n- it behaves very much like the real \"winreg\" (version 3.3),\n like not accepting keyword arguments for most functions,\n accepting sub_keys to be \"None\" or \"blank\" in some, but not all functions, etc.\n- it raises the same Exceptions like winreg\n- read, write registry values and keys, etc.\n\nLIMITATIONS\n===========\n\n- there are no access rights - sam is not supported.\n That means You can read/write/delete Keys and values in the fake registry,\n even if You opened the key with access right \"KEY_READ\".\n You can Delete Keys and Values in HKEY_LOCAL_MACHINE and so on, even if You dont have Admin Rights.\n This is not an security issue, since You test against a fake registry - and You test mostly Your own software.\n If You need it, contributions are welcome ! (somehow it would make sense for TDD to have it)\n- at the moment you can not dump a real registry and save it, in order to use it as a fake registry - that means\n all the keys You need, You have to set manually at the moment.\n if I catch the time, I will polish up my old project \"fingerprint\" and make a compatible file format to dump / read / write registry branches.\n- some (few) winreg functions are not implemented - if You miss out something, give me a note, i will integrate it\n- obviously we can not connect to the registry of another windows computer over the network\n- KEY_WOW64_32KEY is not supported. We show always the same ...\n- auditing event's are not supported\n\n----\n\nautomated tests, Github Actions, Documentation, Badges, etc. are managed with `PizzaCutter <https://github\n.com/bitranox/PizzaCutter>`_ (cookiecutter on steroids)\n\nPython version required: 3.8.0 or newer\n\ntested on recent linux with python 3.8, 3.9, 3.10, 3.11, 3.12-dev, pypy-3.9, pypy-3.10 - architectures: amd64\n\n`100% code coverage <https://codeclimate.com/github/bitranox/fake_winreg/test_coverage>`_, flake8 style checking ,mypy static type checking ,tested under `Linux, macOS, Windows <https://github.com/bitranox/fake_winreg/actions/workflows/python-package.yml>`_, automatic daily builds and monitoring\n\n----\n\n- `Try it Online`_\n- `Usage`_\n- `Usage from Commandline`_\n- `Installation and Upgrade`_\n- `Requirements`_\n- `Acknowledgements`_\n- `Contribute`_\n- `Report Issues <https://github.com/bitranox/fake_winreg/blob/master/ISSUE_TEMPLATE.md>`_\n- `Pull Request <https://github.com/bitranox/fake_winreg/blob/master/PULL_REQUEST_TEMPLATE.md>`_\n- `Code of Conduct <https://github.com/bitranox/fake_winreg/blob/master/CODE_OF_CONDUCT.md>`_\n- `License`_\n- `Changelog`_\n\n----\n\nTry it Online\n-------------\n\nYou might try it right away in Jupyter Notebook by using the \"launch binder\" badge, or click `here <https://mybinder.org/v2/gh/{{rst_include.\nrepository_slug}}/master?filepath=fake_winreg.ipynb>`_\n\nUsage\n-----------\n\n.. code-block:: python\n\n import fake_winreg as winreg\n\n # setup a fake registry for windows\n fake_registry = winreg.fake_reg_tools.get_minimal_windows_testregistry()\n\n # load the fake registry into fake winreg\n winreg.load_fake_registry(fake_registry)\n\n # try the fake registry\n reg_handle = winreg.ConnectRegistry(None, winreg.HKEY_LOCAL_MACHINE)\n\n # Open Key\n reg_key = winreg.OpenKey(reg_handle, r'SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')\n winreg.QueryValueEx(reg_key, 'CurrentBuild')\n\n\nhere a more comprehensive description of the winreg methods (which are implemented by fake registry)\n\nfollowing custom data types are defined:\n\n.. code-block:: python\n\n # the possible types of a handle that can be passed to winreg functions\n Handle = Union[int, HKEYType, PyHKEY]\n\n.. code-block:: python\n\n # the possible types of data that we can receive or write to registry values\n RegData = Union[None, bytes, int, str, List[str]]\n\nConnectRegistry\n---------------\n\n.. code-block:: python\n\n def ConnectRegistry(computer_name: Optional[str], key: Handle) -> PyHKEY: # noqa\n \"\"\"\n Establishes a connection to a predefined registry handle on another computer, and returns a new handle object.\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n computer_name:\n the name of the remote computer, of the form r\"\\\\computername\" or simply \"computername\"\n If None or '', the local computer is used.\n\n if the computer name can not be resolved on the network,fake_winreg will deliver:\n \"OSError: [WinError 1707] The network address is invalid\"\n\n if the computer_name given can be reached, we finally raise:\n \"SystemError: System error 53 has occurred. The network path was not found\"\n\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n\n\n Returns\n -------\n\n the handle of the opened key. If the function fails, an OSError exception is raised.\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 1707] The network address is invalid\n if the computer name can not be resolved\n\n FileNotFoundError: [WinError 53] The network path was not found\n if the network path is invalid\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: ConnectRegistry() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n winreg.ConnectRegistry auditing event (NOT IMPLEMENTED), with arguments computer_name, key.\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> # Connect\n >>> ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n <...PyHKEY object at ...>\n\n >>> # Try to connect to computer\n >>> ConnectRegistry('HAL', HKEY_LOCAL_MACHINE)\n Traceback (most recent call last):\n ...\n OSError: [WinError 1707] The network address is invalid\n\n >>> # Try connect to computer, but invalid network path\n >>> ConnectRegistry(r'localhost\\\\invalid\\\\path', HKEY_LOCAL_MACHINE)\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 53] The network path was not found\n\n >>> # provoke wrong key type Error\n >>> ConnectRegistry('fake_registry_test_computer', 'fake_registry_key') # noqa\n Traceback (most recent call last):\n ...\n TypeError: The object is not a PyHKEY object\n\n >>> # provoke Invalid Handle Error\n >>> ConnectRegistry(None, 42)\n Traceback (most recent call last):\n ...\n OSError: [WinError 6] The handle is invalid\n\n >>> # must not accept keyword parameters\n >>> ConnectRegistry(computer_name=None, key=HKEY_LOCAL_MACHINE)\n Traceback (most recent call last):\n ...\n TypeError: ConnectRegistry() got some positional-only arguments passed as keyword arguments: 'computer_name, key'\n\n \"\"\"\n\nCloseKey\n---------------\n\n.. code-block:: python\n\n def CloseKey(hkey: Union[int, HKEYType]) -> None: # noqa\n \"\"\"\n Closes a previously opened registry key.\n\n the function does NOT accept named parameters, only positional parameters\n\n Note: If hkey is not closed using this method (or via hkey.Close()), it is closed when the hkey object is destroyed by Python.\n\n\n\n Parameter\n ---------\n\n hkey:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: CloseKey() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> # Test\n >>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n >>> CloseKey(HKEY_LOCAL_MACHINE)\n\n >>> # Test hkey = None\n >>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n >>> CloseKey(None) # noqa\n\n >>> # does not accept keyword parameters\n >>> hive_key = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n >>> CloseKey(hkey=HKEY_LOCAL_MACHINE)\n Traceback (most recent call last):\n ...\n TypeError: CloseKey() got some positional-only arguments passed as keyword arguments: 'hkey'\n\n \"\"\"\n\nCreateKey\n---------------\n\n.. code-block:: python\n\n def CreateKey(key: Handle, sub_key: Optional[str]) -> PyHKEY: # noqa\n \"\"\"\n Creates or opens the specified key.\n\n The sub_key can contain a directory structure like r'Software\\\\xxx\\\\yyy' - all the parents to yyy will be created\n\n the function does NOT accept named parameters, only positional parameters\n\n\n Result\n ------\n\n If key is one of the predefined keys, sub_key may be None or empty string,\n and a new handle will be returned with access KEY_WRITE\n\n If the key already exists, this function opens the existing key.\n otherwise it will return the handle to the new created key with access KEY_WRITE\n\n\n From original winreg description (this is wrong):\n If key is one of the predefined keys, sub_key may be None.\n In that case, the handle returned is the same key handle passed in to the function.\n I always get back a different handle, this seems to be wrong (needs testing)\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n a string that names the key this method opens or creates.\n sub_key can be None or empty string when the key is one of the predefined hkeys\n\n\n Exceptions\n ----------\n\n PermissionError: [WinError 5] Access is denied\n if You dont have the right to Create the Key (at least KEY_CREATE_SUBKEY)\n\n OSError: [WinError 1010] The configuration registry key is invalid\n if the function fails to create the Key\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: CreateKey() argument 2 must be str or None, not <type>\n if the subkey is anything else then str or None\n\n OSError: [WinError 1010] The configuration registry key is invalid\n if the subkey is None or empty string, and key is not one of the predefined HKEY Constants\n\n TypeError: CreateKey() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.CreateKey with arguments key, sub_key, access. (NOT IMPLEMENTED)\n\n Raises an auditing event winreg.OpenKey/result with argument key. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> # Connect\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n\n >>> # create key\n >>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy')\n\n >>> # create an existing key - we should NOT get the same handle back\n >>> key_handle_existing = CreateKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy')\n >>> assert key_handle_existing != key_handle_created\n\n >>> # provoke Error key None\n >>> CreateKey(None, r'SOFTWARE\\\\xxxx\\\\yyyy') # noqa\n Traceback (most recent call last):\n ...\n TypeError: None is not a valid HKEY in this context\n\n >>> # provoke Error key wrong type\n >>> CreateKey('test_fake_key_invalid', r'SOFTWARE\\\\xxxx\\\\yyyy') # noqa\n Traceback (most recent call last):\n ...\n TypeError: The object is not a PyHKEY object\n\n >>> # provoke Error key >= 2 ** 64\n >>> CreateKey(2 ** 64, r'SOFTWARE\\\\xxxx\\\\yyyy')\n Traceback (most recent call last):\n ...\n OverflowError: int too big to convert\n\n >>> # provoke invalid handle\n >>> CreateKey(42, r'SOFTWARE\\\\xxxx\\\\yyyy')\n Traceback (most recent call last):\n ...\n OSError: [WinError 6] The handle is invalid\n\n >>> # provoke Error on empty subkey\n >>> key_handle_existing = CreateKey(key_handle_created, r'')\n Traceback (most recent call last):\n ...\n OSError: [WinError 1010] The configuration registry key is invalid\n\n >>> # provoke Error subkey wrong type\n >>> key_handle_existing = CreateKey(reg_handle, 1) # noqa\n Traceback (most recent call last):\n ...\n TypeError: CreateKey() argument 2 must be str or None, not int\n\n >>> # Test subkey=None with key as predefined HKEY - that should pass\n >>> # the actual behaviour is different to the winreg documentation !\n >>> key_handle_hkcu = CreateKey(HKEY_CURRENT_USER, None)\n >>> key_handle_hkcu2 = CreateKey(key_handle_hkcu, None)\n >>> assert key_handle_hkcu != key_handle_hkcu2\n\n >>> # Test subkey='' with key as predefined HKEY - that should pass\n >>> # the actual behaviour is different to the winreg documentation !\n >>> key_handle_hkcu = CreateKey(HKEY_CURRENT_USER, '')\n >>> key_handle_hkcu2 = CreateKey(key_handle_hkcu, '')\n >>> assert key_handle_hkcu != key_handle_hkcu2\n\n >>> # Teardown\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy')\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx')\n\n \"\"\"\n\nCreateKeyEx\n---------------\n\n.. code-block:: python\n\n def CreateKeyEx(key: Handle, sub_key: str, reserved: int = 0, access: int = KEY_WRITE) -> PyHKEY: # noqa\n \"\"\"\n Creates or opens the specified key, returning a handle object with access as passed in the parameter\n\n The sub_key can contain a directory structure like r'Software\\\\xxx\\\\yyy' - all the parents to yyy will be created\n\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n a string (can be empty) that names the key this method opens or creates.\n the sub_key must not be None.\n\n reserved:\n reserved is a reserved integer, and has to be zero. The default is zero.\n\n access:\n a integer that specifies an access mask that describes the desired security access for returned key handle\n Default is KEY_WRITE. See Access Rights for other allowed values.\n (any integer is accepted here in original winreg, bit masked against KEY_* access parameters)\n\n\n Returns\n -------\n\n the handle of the opened key.\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 1010] The configuration registry key is invalid\n if the function fails to create the Key\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n OSError: [WinError 1010] The configuration registry key is invalid\n if the subkey is None\n\n TypeError: CreateKeyEx() argument 2 must be str or None, not <type>\n if the subkey is anything else then str\n\n TypeError: CreateKeyEx() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.CreateKey with arguments key, sub_key, access. (NOT IMPLEMENTED)\n\n Raises an auditing event winreg.OpenKey/result with argument key. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> # Connect\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n\n >>> # create key\n >>> key_handle_created = CreateKeyEx(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy', 0, KEY_WRITE)\n\n >>> # create an existing key - we get a new handle back\n >>> key_handle_existing = CreateKeyEx(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy', 0, KEY_WRITE)\n >>> assert key_handle_existing != key_handle_created\n\n >>> # provoke Error key None\n >>> CreateKeyEx(None, r'SOFTWARE\\\\xxxx\\\\yyyy', 0 , KEY_WRITE) # noqa\n Traceback (most recent call last):\n ...\n TypeError: None is not a valid HKEY in this context\n\n >>> # provoke Error key wrong type\n >>> CreateKeyEx('test_fake_key_invalid', r'SOFTWARE\\\\xxxx\\\\yyyy', 0 , KEY_WRITE) # noqa\n Traceback (most recent call last):\n ...\n TypeError: The object is not a PyHKEY object\n\n >>> # provoke Error key >= 2 ** 64\n >>> CreateKeyEx(2 ** 64, r'SOFTWARE\\\\xxxx\\\\yyyy', 0 , KEY_WRITE)\n Traceback (most recent call last):\n ...\n OverflowError: int too big to convert\n\n >>> # provoke invalid handle\n >>> CreateKeyEx(42, r'SOFTWARE\\\\xxxx\\\\yyyy', 0 , KEY_WRITE)\n Traceback (most recent call last):\n ...\n OSError: [WinError 6] The handle is invalid\n\n >>> # subkey empty is valid\n >>> discard = key_handle_existing = CreateKeyEx(reg_handle, r'', 0 , KEY_WRITE)\n\n >>> # subkey None is invalid\n >>> discard = key_handle_existing = CreateKeyEx(reg_handle, None, 0 , KEY_WRITE) # noqa\n Traceback (most recent call last):\n ...\n OSError: [WinError 1010] The configuration registry key is invalid\n\n\n >>> # provoke Error subkey wrong type\n >>> key_handle_existing = CreateKeyEx(reg_handle, 1, 0 , KEY_WRITE) # noqa\n Traceback (most recent call last):\n ...\n TypeError: CreateKeyEx() argument 2 must be str or None, not int\n\n >>> # Teardown\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy')\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx')\n\n \"\"\"\n\nDeleteKey\n---------------\n\n.. code-block:: python\n\n def DeleteKey(key: Handle, sub_key: str) -> None: # noqa\n \"\"\"\n Deletes the specified key. This method can not delete keys with subkeys.\n If the method succeeds, the entire key, including all of its values, is removed.\n the function does NOT accept named parameters, only positional parameters\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n a string that must be a subkey of the key identified by the key parameter or ''.\n sub_key must not be None, and the key may not have subkeys.\n\n\n\n Exceptions\n ----------\n\n OSError ...\n if it fails to Delete the Key\n\n PermissionError: [WinError 5] Access is denied\n if the key specified to be deleted have subkeys\n\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n if the Key specified to be deleted does not exist\n\n TypeError: DeleteKey() argument 2 must be str, not <type>\n if parameter sub_key type is anything else but string\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: DeleteKey() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n >>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n\n >>> # Delete key without subkeys\n >>> # assert __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\\\SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n >>> # assert not __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\\\SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n\n >>> # try to delete non existing key (it was deleted before)\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> # try to delete key with subkey\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx')\n Traceback (most recent call last):\n ...\n PermissionError: [WinError 5] Access is denied\n\n >>> # provoke error subkey = None\n >>> DeleteKey(reg_handle, None) # noqa\n Traceback (most recent call last):\n ...\n TypeError: DeleteKey() argument 2 must be str, not None\n\n >>> # subkey = '' is allowed here\n >>> reg_handle_sub = OpenKey(reg_handle, r'SOFTWARE\\\\xxxx\\\\yyyy')\n >>> DeleteKey(reg_handle_sub, '')\n\n >>> # Teardown\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\xxxx')\n\n \"\"\"\n\nDeleteKeyEx\n---------------\n\n.. code-block:: python\n\n def DeleteKeyEx(key: Handle, sub_key: str, access: int = KEY_WOW64_64KEY, reserved: int = 0) -> None: # noqa\n \"\"\"\n Deletes the specified key. This method can not delete keys with subkeys.\n If the method succeeds, the entire key, including all of its values, is removed.\n the function does NOT accept named parameters, only positional parameters\n\n Note The DeleteKeyEx() function is implemented with the RegDeleteKeyEx Windows API function,\n which is specific to 64-bit versions of Windows. See the RegDeleteKeyEx documentation.\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n a string that must be a subkey of the key identified by the key parameter or ''.\n sub_key must not be None, and the key may not have subkeys.\n\n access:\n a integer that specifies an access mask that describes the desired security access for the key.\n Default is KEY_WOW64_64KEY. See Access Rights for other allowed values. (NOT IMPLEMENTED)\n (any integer is accepted here in original winreg\n\n reserved:\n reserved is a reserved integer, and must be zero. The default is zero.\n\n\n\n Exceptions\n ----------\n\n OSError: ...\n if it fails to Delete the Key\n\n PermissionError: [WinError 5] Access is denied\n if the key specified to be deleted have subkeys\n\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n if the Key specified to be deleted does not exist\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n NotImplementedError:\n On unsupported Windows versions (NOT IMPLEMENTED)\n\n TypeError: DeleteKeyEx() argument 2 must be str, not <type>\n if parameter sub_key type is anything else but string\n\n TypeError: an integer is required (got NoneType)\n if parameter access is None\n\n TypeError: an integer is required (got type <type>)\n if parameter access is not int\n\n OverflowError: Python int too large to convert to C long\n if parameter access is > 64 Bit Integer Value\n\n TypeError: an integer is required (got type <type>)\n if parameter reserved is not int\n\n OverflowError: Python int too large to convert to C long\n if parameter reserved is > 64 Bit Integer Value\n\n OSError: WinError 87 The parameter is incorrect\n if parameter reserved is not 0\n\n TypeError: DeleteKeyEx() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.DeleteKey with arguments key, sub_key, access. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n >>> key_handle_created = CreateKey(reg_handle, r'Software\\\\xxxx\\\\yyyy\\\\zzz')\n\n >>> # Delete key without subkeys\n >>> # assert __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\\\SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx\\\\yyyy\\\\zzz')\n >>> # assert not __key_in_py_hive_handles(r'HKEY_CURRENT_USER\\\\SOFTWARE\\\\xxxx\\\\yyyy\\\\zzz')\n\n >>> # try to delete non existing key (it was deleted before)\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx\\\\yyyy\\\\zzz')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> # try to delete key with subkey\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx')\n Traceback (most recent call last):\n ...\n PermissionError: [WinError 5] Access is denied\n\n >>> # try to delete key with subkey = None\n >>> DeleteKeyEx(reg_handle, None) # noqa\n Traceback (most recent call last):\n ...\n TypeError: DeleteKeyEx() argument 2 must be str, not None\n\n >>> # try to delete key with access = KEY_WOW64_32KEY\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx\\\\yyyy', KEY_WOW64_32KEY)\n Traceback (most recent call last):\n ...\n NotImplementedError: we only support KEY_WOW64_64KEY\n\n >>> # Teardown\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx\\\\yyyy')\n >>> DeleteKeyEx(reg_handle, r'Software\\\\xxxx')\n\n \"\"\"\n\nDeleteValue\n---------------\n\n.. code-block:: python\n\n def DeleteValue(key: Handle, value: Optional[str]) -> None: # noqa\n \"\"\"\n Removes a named value from a registry key.\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n value:\n None, or a string that identifies the value to remove.\n if value is None, or '' it deletes the default Value of the Key\n\n\n\n Exceptions\n ----------\n\n FileNotFoundError: [WinError 2] The system cannot find the file specified'\n if the Value specified to be deleted does not exist\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: DeleteValue() argument 2 must be str or None, not <type>\n if parameter value type is anything else but string or None\n\n TypeError: DeleteValue() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.DeleteValue with arguments key, value. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n >>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n >>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value')\n\n >>> # Delete Default Value, value_name NONE (not set, therefore Error\n >>> DeleteValue(key_handle, None)\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> # Delete Default Value, value_name '' (not set, therefore Error\n >>> DeleteValue(key_handle, '')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> # Delete Non Existing Value\n >>> DeleteValue(key_handle, 'some_test')\n\n \"\"\"\n\nEnumKey\n---------------\n\n.. code-block:: python\n\n def EnumKey(key: Handle, index: int) -> str: # noqa\n \"\"\"\n Enumerates subkeys of an open registry key, returning a string.\n The function retrieves the name of one subkey each time it is called.\n It is typically called repeatedly until an OSError exception is raised,\n indicating, no more values are available.\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n index:\n an integer that identifies the index of the key to retrieve.\n\n\n\n Exceptions:\n -----------\n\n OSError: [WinError 259] No more data is available\n if the index is out of Range\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: an integer is required (got type <type>)\n if parameter index is type different from int\n\n OverflowError: Python int too large to convert to C int\n if parameter index is > 64 Bit Integer Value\n\n TypeError: EnumKey() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.EnumKey with arguments key, index. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n\n >>> # test get the first profile in the profile list\n >>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion\\\\ProfileList')\n >>> assert isinstance(EnumKey(key_handle, 0), str)\n\n >>> # provoke error test out of index\n >>> EnumKey(key_handle, 100000000)\n Traceback (most recent call last):\n ...\n OSError: [WinError 259] No more data is available\n\n >>> # provoke error wrong key handle\n >>> EnumKey(42, 0)\n Traceback (most recent call last):\n ...\n OSError: [WinError 6] The handle is invalid\n\n >>> # no check for overflow here !\n >>> EnumKey(2 ** 64, 0)\n Traceback (most recent call last):\n ...\n OverflowError: int too big to convert\n\n \"\"\"\n\nEnumValue\n---------------\n\n.. code-block:: python\n\n def EnumValue(key: Handle, index: int) -> Tuple[str, RegData, int]: # noqa\n \"\"\"\n Enumerates values of an open registry key, returning a tuple.\n The function retrieves the name of one value each time it is called.\n It is typically called repeatedly, until an OSError exception is raised, indicating no more values.\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n index:\n an integer that identifies the index of the key to retrieve.\n\n\n\n Result\n ------\n\n The result is a tuple of 3 items:\n\n ======== ==============================================================================================\n Index Meaning\n ======== ==============================================================================================\n 0 A string that identifies the value name\n 1 An object that holds the value data, and whose type depends on the underlying registry type\n 2 An integer giving the registry type for this value (see table in docs for SetValueEx())\n ======== ==============================================================================================\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 259] No more data is available\n if the index is out of Range\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: an integer is required (got type <type>)\n if parameter index is type different from int\n\n OverflowError: Python int too large to convert to C int\n if parameter index is > 64 Bit Integer Value\n\n TypeError: EnumValue() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.EnumValue with arguments key, index. (NOT IMPLEMENTED)\n\n\n\n Registry Types\n --------------\n\n ============== ============================== ============================== ==========================================================================\n type(int) type name accepted python Types Description\n ============== ============================== ============================== ==========================================================================\n 0 REG_NONE\t None, bytes No defined value type.\n 1 REG_SZ\t None, str A null-terminated string.\n 2 REG_EXPAND_SZ\t None, str Null-terminated string containing references to\n environment variables (%PATH%).\n (Python handles this termination automatically.)\n 3 REG_BINARY\t None, bytes Binary data in any form.\n 4 REG_DWORD\t None, int A 32-bit number.\n 4 REG_DWORD_LITTLE_ENDIAN\t None, int A 32-bit number in little-endian format.\n 5 REG_DWORD_BIG_ENDIAN\t None, bytes A 32-bit number in big-endian format.\n 6 REG_LINK\t None, bytes A Unicode symbolic link.\n 7 REG_MULTI_SZ\t None, List[str] A sequence of null-terminated strings, terminated by two null characters.\n 8 REG_RESOURCE_LIST\t None, bytes A device-driver resource list.\n 9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.\n 10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.\n 11 REG_QWORD None, bytes A 64 - bit number.\n 11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.\n ============== ============================== ============================== ==========================================================================\n\n * all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.\n by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n\n >>> # Read the current Version\n >>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n >>> EnumValue(key_handle, 0)\n (...)\n\n >>> # test out of index\n >>> EnumValue(key_handle, 100000000)\n Traceback (most recent call last):\n ...\n OSError: [WinError 259] No more data is available\n\n \"\"\"\n\nOpenKey\n---------------\n\n.. code-block:: python\n\n def OpenKey(key: Handle, sub_key: Union[str, None], reserved: int = 0, access: int = KEY_READ) -> PyHKEY: # noqa\n \"\"\"\n Opens the specified key, the result is a new handle to the specified key.\n one of the few functions of winreg that accepts named parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n None, or a string that names the key this method opens or creates.\n If key is one of the predefined keys, sub_key may be None.\n\n reserved:\n reserved is a reserved integer, and should be zero. The default is zero.\n\n access:\n a integer that specifies an access mask that describes the desired security access for the key.\n Default is KEY_READ. See Access Rights for other allowed values.\n (any integer is accepted here in original winreg, bit masked against KEY_* access parameters)\n\n\n\n Exceptions\n ----------\n\n OSError: ...\n if it fails to open the key\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: OpenKey() argument 2 must be str or None, not <type>\n if the sub_key is anything else then str or None\n\n TypeError: an integer is required (got NoneType)\n if parameter reserved is None\n\n TypeError: an integer is required (got type <type>)\n if parameter reserved is not int\n\n PermissionError: [WinError 5] Access denied\n if parameter reserved is > 3)\n\n OverflowError: Python int too large to convert to C long\n if parameter reserved is > 64 Bit Integer Value\n\n OSError: [WinError 87] The parameter is incorrect\n on some values for reserved (for instance 455565) NOT IMPLEMENTED\n\n TypeError: an integer is required (got type <type>)\n if parameter access is not int\n\n OverflowError: Python int too large to convert to C long\n if parameter access is > 64 Bit Integer Value\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.OpenKey with arguments key, sub_key, access. # not implemented\n Raises an auditing event winreg.OpenKey/result with argument key. # not implemented\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n\n >>> # Open Key\n >>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n >>> assert key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion'\n\n >>> # Open Key mit subkey=None\n >>> reg_open1 = OpenKey(key_handle, None)\n\n >>> # Open Key mit subkey=''\n >>> reg_open2 = OpenKey(key_handle, '')\n\n >>> # Open the same kay again, but we get a different Handle\n >>> reg_open3 = OpenKey(key_handle, '')\n\n >>> assert reg_open2 != reg_open3\n\n >>> # Open non existing Key\n >>> OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\DoesNotExist')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n \"\"\"\n\nOpenKeyEx\n---------------\n\n.. code-block:: python\n\n def OpenKeyEx(key: Handle, sub_key: Optional[str], reserved: int = 0, access: int = KEY_READ) -> PyHKEY: # noqa\n \"\"\"\n Opens the specified key, the result is a new handle to the specified key with the given access.\n one of the few functions of winreg that accepts named parameters\n\n\n\n Parameter\n ---------\n\n key:\n an already open key, or one of the predefined HKEY_* constants.\n\n sub_key:\n None, or a string that names the key this method opens or creates.\n If key is one of the predefined keys, sub_key may be None.\n\n reserved:\n reserved is a reserved integer, and should be zero. The default is zero.\n\n access:\n a integer that specifies an access mask that describes the desired security access for the key.\n Default is KEY_READ. See Access Rights for other allowed values.\n (any integer is accepted here in original winreg, bit masked against KEY_* access parameters)\n\n\n\n Exceptions\n ----------\n\n OSError: ...\n if it fails to open the key\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: OpenKeyEx() argument 2 must be str or None, not <type>\n if the subkey is anything else then str or None\n\n TypeError: an integer is required (got NoneType)\n if parameter reserved is None\n\n TypeError: an integer is required (got type <type>)\n if parameter reserved is not int\n\n PermissionError: [WinError 5] Access denied\n if parameter reserved is > 3)\n\n OverflowError: Python int too large to convert to C long\n if parameter reserved is > 64 Bit Integer Value\n\n OSError: [WinError 87] The parameter is incorrect\n on some values for reserved (for instance 455565) NOT IMPLEMENTED\n\n TypeError: an integer is required (got type <type>)\n if parameter access is not int\n\n OverflowError: Python int too large to convert to C long\n if parameter access is > 64 Bit Integer Value\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.OpenKey with arguments key, sub_key, access. # not implemented\n Raises an auditing event winreg.OpenKey/result with argument key. # not implemented\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n\n >>> # Open Key\n >>> my_key_handle = OpenKeyEx(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n >>> assert my_key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion'\n\n >>> # Open Key with Context Manager\n >>> with OpenKeyEx(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion') as my_key_handle:\n ... assert my_key_handle.handle.full_key == r'HKEY_LOCAL_MACHINE\\\\SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion'\n\n >>> # Open non existing Key\n >>> OpenKeyEx(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\DoesNotExist')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n \"\"\"\n\nQueryInfoKey\n---------------\n\n.. code-block:: python\n\n def QueryInfoKey(key: Handle) -> Tuple[int, int, int]: # noqa\n \"\"\"\n Returns information about a key, as a tuple.\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n\n\n Result\n ------\n\n The result is a tuple of 3 items:\n\n ====== =============================================================================================================\n Index, Meaning\n ====== =============================================================================================================\n 0 An integer giving the number of sub keys this key has.\n 1 An integer giving the number of values this key has.\n 2 An integer giving when the key was last modified (if available) as 100\u2019s of nanoseconds since Jan 1, 1601.\n ====== =============================================================================================================\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: QueryInfoKey() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.QueryInfoKey with argument key.\n\n\n\n Examples and Tests:\n -------------------\n\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n\n >>> # Open Key\n >>> key_handle = OpenKeyEx(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n\n >>> new_reg_key_without_values = CreateKey(key_handle, 'test_without_values')\n >>> new_reg_key_with_subkeys_and_values = CreateKey(key_handle, 'test_with_subkeys_and_values')\n >>> SetValueEx(new_reg_key_with_subkeys_and_values, 'test_value_name', 0, REG_SZ, 'test_value')\n >>> new_reg_key_with_subkeys_subkey = CreateKey(new_reg_key_with_subkeys_and_values, 'subkey_of_test_with_subkeys')\n\n >>> # Test\n >>> QueryInfoKey(new_reg_key_without_values)\n (0, 0, ...)\n >>> QueryInfoKey(new_reg_key_with_subkeys_and_values)\n (1, 1, ...)\n\n >>> # Teardown\n >>> DeleteKey(key_handle, 'test_without_values')\n >>> DeleteKey(new_reg_key_with_subkeys_and_values, 'subkey_of_test_with_subkeys')\n >>> DeleteKey(key_handle, 'test_with_subkeys_and_values')\n\n \"\"\"\n\nQueryValue\n---------------\n\n.. code-block:: python\n\n def QueryValue(key: Handle, sub_key: Union[str, None]) -> str: # noqa\n \"\"\"\n Retrieves the unnamed value (the default value*) for a key, as string.\n\n * Remark : this is the Value what is shown in Regedit as \"(Standard)\" or \"(Default)\"\n it is usually not set. Nethertheless, even if the value is not set, QueryValue will deliver ''\n\n Values in the registry have name, type, and data components.\n\n This method retrieves the data for a key\u2019s first value that has a NULL name.\n But the underlying API call doesn\u2019t return the type, so always use QueryValueEx() if possible.\n\n the function does NOT accept named parameters, only positional parameters\n\n\n Parameter\n ---------\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n sub_key:\n None, or a string that names the key this method opens or creates.\n If key is one of the predefined keys, sub_key may be None. In that case,\n the handle returned is the same key handle passed in to the function.\n If the key already exists, this function opens the existing key.\n\n\n\n Result\n ------\n\n the unnamed value as string (if possible)\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 13] The data is invalid\n if the data in the unnamed value is not string\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: QueryValue() argument 2 must be str or None, not <type>\n if the subkey is anything else then str or None\n\n TypeError: QueryValue() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events:\n -------\n\n Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n >>> key_handle_created = CreateKey(reg_handle, r'SOFTWARE\\\\lib_registry_test')\n\n >>> # read Default Value, which is ''\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == ''\n\n >>> # sub key can be here None or empty !\n >>> assert QueryValue(key_handle_created, '') == ''\n >>> assert QueryValue(key_handle_created, None) == ''\n\n >>> # set and get default value\n >>> SetValueEx(key_handle_created, '', 0, REG_SZ, 'test1')\n >>> assert QueryValueEx(key_handle_created, '') == ('test1', REG_SZ)\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == 'test1'\n\n >>> # set the default value to non-string type, and try to get it with Query Value\n >>> SetValueEx(key_handle_created, '', 0, REG_DWORD, 42)\n >>> assert QueryValueEx(key_handle_created, '') == (42, REG_DWORD)\n >>> QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test')\n Traceback (most recent call last):\n ...\n OSError: [WinError 13] The data is invalid\n\n >>> # Teardown\n >>> DeleteKey(reg_handle, r'SOFTWARE\\\\lib_registry_test')\n\n \"\"\"\n\nQueryValueEx\n---------------\n\n.. code-block:: python\n\n def QueryValueEx(key: Handle, value_name: Optional[str]) -> Tuple[RegData, int]: # noqa\n \"\"\"\n Retrieves data and type for a specified value name associated with an open registry key.\n\n If Value_name is '' or None, it queries the Default Value* of the Key - this will Fail if the Default Value for the Key is not Present.\n * Remark : this is the Value what is shown in Regedit as \"(Standard)\" or \"(Default)\"\n it is usually not set.\n\n the function does NOT accept named parameters, only positional parameters\n\n\n\n Parameter\n ---------\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n value_name:\n None, or a string that identifies the value to Query\n if value is None, or '' it queries the default Value of the Key\n\n\n\n Result\n ------\n\n The result is a tuple of 2 items:\n\n ========== =====================================================================================================\n Index Meaning\n ========== =====================================================================================================\n 0 The value of the registry item.\n 1 An integer giving the registry type for this value see table\n ========== =====================================================================================================\n\n\n\n Registry Types\n --------------\n\n ============== ============================== ============================== ==========================================================================\n type(int) type name accepted python Types Description\n ============== ============================== ============================== ==========================================================================\n 0 REG_NONE\t None, bytes No defined value type.\n 1 REG_SZ\t None, str A null-terminated string.\n 2 REG_EXPAND_SZ\t None, str Null-terminated string containing references to\n environment variables (%PATH%).\n (Python handles this termination automatically.)\n 3 REG_BINARY\t None, bytes Binary data in any form.\n 4 REG_DWORD\t None, int A 32-bit number.\n 4 REG_DWORD_LITTLE_ENDIAN\t None, int A 32-bit number in little-endian format.\n 5 REG_DWORD_BIG_ENDIAN\t None, bytes A 32-bit number in big-endian format.\n 6 REG_LINK\t None, bytes A Unicode symbolic link.\n 7 REG_MULTI_SZ\t None, List[str] A sequence of null-terminated strings, terminated by two null characters.\n 8 REG_RESOURCE_LIST\t None, bytes A device-driver resource list.\n 9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.\n 10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.\n 11 REG_QWORD None, bytes A 64 - bit number.\n 11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.\n ============== ============================== ============================== ==========================================================================\n\n * all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.\n by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: QueryValueEx() argument 2 must be str or None, not <type>\n if the value_name is anything else then str or None\n\n TypeError: QueryValueEx() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.QueryValue with arguments key, sub_key, value_name. (NOT Implemented)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_LOCAL_MACHINE)\n >>> key_handle = OpenKey(reg_handle, r'SOFTWARE\\\\Microsoft\\\\Windows NT\\\\CurrentVersion')\n\n >>> # Read the current Version\n >>> QueryValueEx(key_handle, 'CurrentBuild')\n ('...', 1)\n\n >>> # Attempt to read a non Existing Default Value\n >>> QueryValueEx(key_handle, '')\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> QueryValueEx(key_handle, None)\n Traceback (most recent call last):\n ...\n FileNotFoundError: [WinError 2] The system cannot find the file specified\n\n >>> # Set a Default Value\n >>> SetValueEx(key_handle, '',0 , REG_SZ, 'test_default_value')\n >>> QueryValueEx(key_handle, '')\n ('test_default_value', 1)\n\n >>> # Delete a Default Value\n >>> DeleteValue(key_handle, None)\n\n \"\"\"\n\nSetValue\n---------------\n\n.. code-block:: python\n\n def SetValue(key: Handle, sub_key: Union[str, None], type: int, value: str) -> None: # noqa\n \"\"\"\n Associates a value with a specified key. (the Default Value* of the Key, usually not set)\n\n * Remark : this is the Value what is shown in Regedit as \"(Standard)\" or \"(Default)\"\n it is usually not set. Nethertheless, even if the value is not set, QueryValue will deliver ''\n\n the function does NOT accept named parameters, only positional parameters\n\n\n Parameter\n ---------\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n\n sub_key:\n None, or a string that names the key this method sets the default value\n If the key specified by the sub_key parameter does not exist, the SetValue function creates it.\n\n type:\n an integer that specifies the type of the data. Currently this must be REG_SZ,\n meaning only strings are supported. Use the SetValueEx() function for support for other data types.\n\n value:\n a string that specifies the new value.\n Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored\n as files with the filenames stored in the configuration registry. This helps the registry perform efficiently.\n The key identified by the key parameter must have been opened with KEY_SET_VALUE access. (NOT IMPLEMENTED)\n\n\n\n Exceptions\n ----------\n\n TypeError: Could not convert the data to the specified type.\n for REG_SZ and REG_EXPAND_SZ, if the data is not NoneType or str,\n for REG_DWORD and REG_EXPREG_QWORDAND_SZ, if the data is not NoneType or int,\n for REG_MULTI_SZ, if the data is not List[str]:\n\n TypeError: Objects of type '<data_type>' can not be used as binary registry values\n for all other REG_* types, if the data is not NoneType or bytes\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: SetValue() argument 2 must be str or None, not <type>\n if the subkey is anything else then str or None\n\n TypeError: SetValue() argument 3 must be int not None\n if the type is None\n\n TypeError: SetValue() argument 3 must be int not <type>\n if the type is anything else but int\n\n TypeError: type must be winreg.REG_SZ\n if the type is not string (winreg.REG_SZ)\n\n TypeError: SetValue() argument 4 must be str not None\n if the value is None\n\n TypeError: SetValue() argument 4 must be str not <type>\n if the value is anything else but str\n\n TypeError: SetValue() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n >>> key_handle = CreateKey(reg_handle, r'SOFTWARE\\\\lib_registry_test')\n\n >>> # read Default Value, which is ''\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == ''\n\n >>> # sub key can be ''\n >>> SetValue(key_handle, '', REG_SZ, 'test1')\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == 'test1'\n\n >>> # sub key can be None\n >>> SetValue(key_handle, None, REG_SZ, 'test2')\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == 'test2'\n\n >>> # use sub key\n >>> reg_handle_software = OpenKey(reg_handle, 'SOFTWARE')\n >>> SetValue(reg_handle_software, 'lib_registry_test', REG_SZ, 'test3')\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test') == 'test3'\n\n >>> # SetValue creates keys on the fly if they do not exist\n >>> reg_handle_software = OpenKey(reg_handle, 'SOFTWARE')\n >>> SetValue(reg_handle_software, r'lib_registry_test\\\\ham\\\\spam', REG_SZ, 'wonderful spam')\n >>> assert QueryValue(reg_handle, r'SOFTWARE\\\\lib_registry_test\\\\ham\\\\spam') == 'wonderful spam'\n\n >>> # You can not use other types as string here\n >>> SetValue(key_handle, '', REG_DWORD, \"42\") # noqa\n Traceback (most recent call last):\n ...\n TypeError: type must be winreg.REG_SZ\n\n >>> # Tear Down\n >>> DeleteKey(reg_handle,r'SOFTWARE\\\\lib_registry_test\\\\ham\\\\spam')\n >>> DeleteKey(reg_handle,r'SOFTWARE\\\\lib_registry_test\\\\ham')\n >>> DeleteKey(reg_handle,r'SOFTWARE\\\\lib_registry_test')\n\n \"\"\"\n\nSetValueEx\n---------------\n\n.. code-block:: python\n\n def SetValueEx(key: Handle, value_name: Optional[str], reserved: int, type: int, value: RegData) -> None: # noqa\n \"\"\"\n Stores data in the value field of an open registry key.\n\n value_name is a string that names the subkey with which the value is associated.\n if value is None, or '' it sets the default value* of the Key\n\n the function does NOT accept named parameters, only positional parameters\n\n Parameter\n ---------\n\n key:\n the predefined handle to connect to, or one of the predefined HKEY_* constants.\n The key identified by the key parameter must have been opened with KEY_SET_VALUE access. (NOT IMPLEMENTED))\n To open the key, use the CreateKey() or OpenKey() methods.\n\n value_name:\n None, or a string that identifies the value to set\n if value is None, or '' it sets the default value* of the Key\n\n * Remark : this is the Value what is shown in Regedit as \"(Standard)\" or \"(Default)\"\n it is usually not set, but You can set it to any data and datatype - but then it will\n only be readable with QueryValueEX, not with QueryValue\n\n reserved:\n reserved is a reserved integer, and should be zero. reserved can be anything \u2013 zero is always passed to the API.\n\n type:\n type is an integer that specifies the type of the data. (see table)\n\n value:\n value is a new value.\n Value lengths are limited by available memory. Long values (more than 2048 bytes)\n should be stored as files with the filenames stored in the configuration registry. This helps the registry perform efficiently.\n\n\n Registry Types\n\n ============== ============================== ============================== ==========================================================================\n type(int) type name accepted python Types Description\n ============== ============================== ============================== ==========================================================================\n 0 REG_NONE\t None, bytes No defined value type.\n 1 REG_SZ\t None, str A null-terminated string.\n 2 REG_EXPAND_SZ\t None, str Null-terminated string containing references to\n environment variables (%PATH%).\n (Python handles this termination automatically.)\n 3 REG_BINARY\t None, bytes Binary data in any form.\n 4 REG_DWORD\t None, int A 32-bit number.\n 4 REG_DWORD_LITTLE_ENDIAN\t None, int A 32-bit number in little-endian format.\n 5 REG_DWORD_BIG_ENDIAN\t None, bytes A 32-bit number in big-endian format.\n 6 REG_LINK\t None, bytes A Unicode symbolic link.\n 7 REG_MULTI_SZ\t None, List[str] A sequence of null-terminated strings, terminated by two null characters.\n 8 REG_RESOURCE_LIST\t None, bytes A device-driver resource list.\n 9 REG_FULL_RESOURCE_DESCRIPTOR None, bytes A hardware setting.\n 10 REG_RESOURCE_REQUIREMENTS_LIST None, bytes A hardware resource list.\n 11 REG_QWORD None, bytes A 64 - bit number.\n 11 REG_QWORD_LITTLE_ENDIAN None, bytes A 64 - bit number in little - endian format.Equivalent to REG_QWORD.\n ============== ============================== ============================== ==========================================================================\n\n * all other integers for REG_TYPE are accepted, and written to the registry. The value is handled as binary.\n by that way You would be able to encode data in the REG_TYPE for stealth data not easy to spot - who would expect it.\n\n\n\n Exceptions\n ----------\n\n OSError: [WinError 6] The handle is invalid\n if parameter key is invalid\n\n TypeError: None is not a valid HKEY in this context\n if parameter key is None\n\n TypeError: The object is not a PyHKEY object\n if parameter key is not integer or PyHKEY type\n\n OverflowError: int too big to convert\n if parameter key is > 64 Bit Integer Value\n\n TypeError: SetValueEx() argument 2 must be str or None, not <type>\n if the value_name is anything else then str or None\n\n TypeError: SetValueEx() argument 4 must be int not None\n if the type is None\n\n TypeError: SetValueEx() argument 4 must be int not <type>\n if the type is anything else but int\n\n TypeError: SetValueEx() got some positional-only arguments passed as keyword arguments: '<key>'\n if a keyword (named) parameter was passed\n\n\n\n Events\n ------\n\n Raises an auditing event winreg.SetValue with arguments key, sub_key, type, value. (NOT IMPLEMENTED)\n\n\n\n Examples\n --------\n\n >>> # Setup\n >>> fake_registry = fake_reg_tools.get_minimal_windows_testregistry()\n >>> load_fake_registry(fake_registry)\n >>> reg_handle = ConnectRegistry(None, HKEY_CURRENT_USER)\n >>> key_handle = CreateKey(reg_handle, r'Software\\\\lib_registry_test')\n\n >>> # Test\n >>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value')\n >>> assert QueryValueEx(key_handle, 'some_test') == ('some_test_value', REG_SZ)\n\n >>> # Test Overwrite\n >>> SetValueEx(key_handle, 'some_test', 0, REG_SZ, 'some_test_value2')\n >>> assert QueryValueEx(key_handle, 'some_test') == ('some_test_value2', REG_SZ)\n\n >>> # Test write Default Value of the Key, with value_name None\n >>> SetValueEx(key_handle, None, 0, REG_SZ, 'default_value')\n >>> assert QueryValue(key_handle, '') == 'default_value'\n\n >>> # Test write Default Value of the Key, with value_name ''\n >>> SetValueEx(key_handle, '', 0, REG_SZ, 'default_value_overwritten')\n >>> assert QueryValue(key_handle, '') == 'default_value_overwritten'\n\n >>> # Teardown\n >>> DeleteValue(key_handle, 'some_test')\n >>> DeleteKey(key_handle, '')\n\n \"\"\"\n\nUsage from Commandline\n------------------------\n\n.. code-block::\n\n Usage: fake_winreg [OPTIONS] COMMAND [ARGS]...\n\n fake winreg, in order to test registry related functions on linux\n\n Options:\n --version Show the version and exit.\n --traceback / --no-traceback return traceback information on cli\n -h, --help Show this message and exit.\n\n Commands:\n info get program informations\n\nInstallation and Upgrade\n------------------------\n\n- Before You start, its highly recommended to update pip and setup tools:\n\n\n.. code-block::\n\n python -m pip --upgrade pip\n python -m pip --upgrade setuptools\n\n- to install the latest release from PyPi via pip (recommended):\n\n.. code-block::\n\n python -m pip install --upgrade fake_winreg\n\n\n- to install the latest release from PyPi via pip, including test dependencies:\n\n.. code-block::\n\n python -m pip install --upgrade fake_winreg[test]\n\n- to install the latest version from github via pip:\n\n\n.. code-block::\n\n python -m pip install --upgrade git+https://github.com/bitranox/fake_winreg.git\n\n\n- include it into Your requirements.txt:\n\n.. code-block::\n\n # Insert following line in Your requirements.txt:\n # for the latest Release on pypi:\n fake_winreg\n\n # for the latest development version :\n fake_winreg @ git+https://github.com/bitranox/fake_winreg.git\n\n # to install and upgrade all modules mentioned in requirements.txt:\n python -m pip install --upgrade -r /<path>/requirements.txt\n\n\n- to install the latest development version, including test dependencies from source code:\n\n.. code-block::\n\n # cd ~\n $ git clone https://github.com/bitranox/fake_winreg.git\n $ cd fake_winreg\n python -m pip install -e .[test]\n\n- via makefile:\n makefiles are a very convenient way to install. Here we can do much more,\n like installing virtual environments, clean caches and so on.\n\n.. code-block:: shell\n\n # from Your shell's homedirectory:\n $ git clone https://github.com/bitranox/fake_winreg.git\n $ cd fake_winreg\n\n # to run the tests:\n $ make test\n\n # to install the package\n $ make install\n\n # to clean the package\n $ make clean\n\n # uninstall the package\n $ make uninstall\n\nRequirements\n------------\nfollowing modules will be automatically installed :\n\n.. code-block:: bash\n\n ## Project Requirements\n click\n cli_exit_tools\n lib_detect_testenv\n wrapt\n\nAcknowledgements\n----------------\n\n- special thanks to \"uncle bob\" Robert C. Martin, especially for his books on \"clean code\" and \"clean architecture\"\n\nContribute\n----------\n\nI would love for you to fork and send me pull request for this project.\n- `please Contribute <https://github.com/bitranox/fake_winreg/blob/master/CONTRIBUTING.md>`_\n\nLicense\n-------\n\nThis software is licensed under the `MIT license <http://en.wikipedia.org/wiki/MIT_License>`_\n\n---\n\nChangelog\n=========\n\n- new MAJOR version for incompatible API changes,\n- new MINOR version for added functionality in a backwards compatible manner\n- new PATCH version for backwards compatible bug fixes\n\nplanned:\n - KEY_* Permissions on SetValue, ReadValue, etc ...\n - test matrix on windows to compare fake and original winreg in detail\n - auditing events\n - investigate SYSWOW32/64 Views\n - Admin Permissions\n\nv1.6.3\n---------\n2023-07-20:\n - require minimum python 3.8\n - remove python 3.7 tests\n - introduce PEP517 packaging standard\n - introduce pyproject.toml build-system\n - remove mypy.ini\n - remove pytest.ini\n - remove setup.cfg\n - remove setup.py\n - remove .bettercodehub.yml\n - remove .travis.yml\n - update black config\n - clean ./tests/test_cli.py\n - add codeql badge\n - move 3rd_party_stubs outside the src directory to ``./.3rd_party_stubs``\n - add pypy 3.10 tests\n - add python 3.12-dev tests\n\nv1.6.2.2\n--------\n2022-06-01: update to github actions checkout@v3 and setup-python@v3\n\nv1.6.2.1\n--------\n2022-06-01: update github actions test matrix\n\nv1.6.2\n--------\n2022-03-29: remedy mypy Untyped decorator makes function \"cli_info\" untyped\n\nv1.6.1\n--------\n2022-03-25: fix github actions windows test\n\nv1.6.0\n--------\n2021-12-19: feature release\n - update github actions\n - fix \"setup.py test\"\n - fix typing\n\nv1.5.7\n--------\n2021-12-18: feature release\n - allow PyHKEY to act as a context manager, thanks to Ben Rowland\n\nv1.5.6\n--------\n2020-10-09: service release\n - update travis build matrix for linux 3.9-dev\n - update travis build matrix (paths) for windows 3.9 / 3.10\n\nv1.5.5\n--------\n2020-08-08: service release\n - fix documentation\n - fix travis\n - deprecate pycodestyle\n - implement flake8\n\nv1.5.4\n---------\n2020-08-01: fix pypi deploy\n\nv1.5.3\n--------\n2020-07-31: fix travis build\n\n\nv0.5.2\n--------\n2020-07-29: feature release\n - use the new pizzacutter template\n - use cli_exit_tools\n\nv0.5.1\n--------\n2020-07-16 : patch release\n - fix cli test\n - enable traceback option on cli errors\n\nv0.5.0\n--------\n2020-07-13 : feature release\n - CreateKeyEx added\n - access rights on CreateKey, CreateKeyEx, OpenKey, OpenKeyEX added\n\nv0.4.1\n--------\n2020-07-13 : patch release\n - 100% coverage\n - raise correct Exception when try to connect to Network Computer\n\nv0.4.0\n--------\n2020-07-13 : feature release\n - raise [WinError 1707] The network address is invalid if computername is given\n - make HKEYType int convertible\n - make type aliases for better readability\n - coverage\n\nv0.3.1\n--------\n2020-07-12 : patch release\n - corrected types\n\nv0.3.0\n--------\n2020-07-12 : feature release\n - raise Errors on SetValueEx if type is not appropriate\n - raise Errors on wrong parameter types like original winreg\n - comprehensive documentation\n\nv0.2.0\n--------\n2020-07-11 : feature release\n - added EnumValue\n - added Close() and Detach() for PyHKEY Class\n - more consistent naming in internal methods\n - added winerror attributes and values in exceptions\n - corrected handling of default key values\n - corrected race condition when deleting keys\n - corrected decorator to check for names arguments\n - added stub file for wrapt\n - added more REG_* Types\n\nv0.1.1\n--------\n2020-07-08 : patch release\n - new click CLI\n - use PizzaCutter Template\n - added jupyter notebook\n - reorganized modules and import\n - updated documentation\n\nv0.1.0\n--------\n2020-06-17: initial public release\n - with all docs in place\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "fake winreg, in order to test registry related functions on linux",
"version": "1.6.3",
"project_urls": {
"Changelog": "https://github.com/bitranox/fake_winreg/blob/master/CHANGES.rst",
"Documentation": "https://github.com/bitranox/fake_winreg/blob/master/README.rst",
"Homepage": "https://github.com/bitranox/fake_winreg",
"Repository": "https://github.com/bitranox/fake_winreg.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8043b5ceb383d1319bfcf59ca74f505a6217748ca5abd8cf85fcf989a5fbc97",
"md5": "34fbe2a3e395771e106bcfe8e7f31daf",
"sha256": "d0d5d742990b9416b3d68485bee35e405ce49666356392c337e7b653bd4c780f"
},
"downloads": -1,
"filename": "fake_winreg-1.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34fbe2a3e395771e106bcfe8e7f31daf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 35673,
"upload_time": "2023-07-20T09:38:13",
"upload_time_iso_8601": "2023-07-20T09:38:13.467803Z",
"url": "https://files.pythonhosted.org/packages/e8/04/3b5ceb383d1319bfcf59ca74f505a6217748ca5abd8cf85fcf989a5fbc97/fake_winreg-1.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e050279ad473416837aecd6adaee518817ce577188d3bea4fc8b3fedaa3ecf5e",
"md5": "e834f02952a675b5b09528e9ed9d384c",
"sha256": "09f44aafaddd7e5d0205d73c16b02496755b10b01d46d5408c4e61ae2c571697"
},
"downloads": -1,
"filename": "fake_winreg-1.6.3.tar.gz",
"has_sig": false,
"md5_digest": "e834f02952a675b5b09528e9ed9d384c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 78914,
"upload_time": "2023-07-20T09:38:14",
"upload_time_iso_8601": "2023-07-20T09:38:14.961207Z",
"url": "https://files.pythonhosted.org/packages/e0/50/279ad473416837aecd6adaee518817ce577188d3bea4fc8b3fedaa3ecf5e/fake_winreg-1.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-20 09:38:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bitranox",
"github_project": "fake_winreg",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "fake-winreg"
}
