Skip to content

Commit f3dbe7c

Browse files
bitranoxbitranox
committed
refractor
1 parent b3c8da6 commit f3dbe7c

File tree

3 files changed

+494
-194
lines changed

3 files changed

+494
-194
lines changed

‎.docs/usage.rst‎

Lines changed: 21 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,31 @@
1-
.. code-block:: py
1+
python methods:
22

3-
>>> from lib_registry import *
3+
- Registry Object
44

5-
>>> # Read a Value from the Registry
6-
>>> key = 'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\S-1-5-20'
7-
>>> get_value(key_name=key, value_name='ProfileImagePath')
8-
'%systemroot%\\\\ServiceProfiles\\\\NetworkService'
5+
.. include:: ../lib_registry/lib_registry.py
6+
:code: python
7+
:start-after: # Registry{{{
8+
:end-before: # Registry}}}
99

10-
>>> # Create a Key
11-
>>> create_key(r'HKCU\\Software\\lib_registry_test')
10+
- create_key
1211

13-
>>> # Delete a Key
14-
>>> delete_key(r'HKCU\\Software\\lib_registry_test')
12+
.. include:: ../lib_registry/lib_registry.py
13+
:code: python
14+
:start-after: # create_key{{{
15+
:end-before: # create_key}}}
1516

17+
- delete_key
1618

17-
>>> # Write a Value to the Registry
18-
>>> create_key(r'HKCU\\Software\\lib_registry_test')
19-
>>> set_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name', value='test_string', value_type=REG_SZ)
20-
>>> result = get_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name')
21-
>>> assert result == 'test_string'
19+
.. include:: ../lib_registry/lib_registry.py
20+
:code: python
21+
:start-after: # delete_key{{{
22+
:end-before: # delete_key}}}
2223

23-
>>> # Delete a Value from the Registry
24-
>>> delete_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name')
25-
>>> delete_key(r'HKCU\\Software\\lib_registry_test')
2624

27-
>>> # Check if a key exists
28-
>>> key_exist('HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\S-1-5-20'
29-
True
30-
>>> key_exist('HKEY_LOCAL_MACHINE\\Software\\DoesNotExist')
31-
False
25+
- key_exists
3226

33-
>>> # get the SIDs of all Windows users
34-
>>> get_ls_user_sids()
35-
['.DEFAULT', 'S-1-5-18', 'S-1-5-19', 'S-1-5-20', ...]
27+
.. include:: ../lib_registry/lib_registry.py
28+
:code: python
29+
:start-after: # key_exist{{{
30+
:end-before: # key_exist}}}
3631

37-
>>> # get the Username from SID
38-
>>> get_username_from_sid(sid='S-1-5-20')
39-
'NetworkService'

‎README.rst‎

Lines changed: 213 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -84,45 +84,225 @@ repository_slug}}/master?filepath=lib_registry.ipynb>`_
8484
Usage
8585
-----------
8686

87-
.. code-block:: py
87+
python methods:
8888

89-
>>> from lib_registry import *
89+
- Registry Object
90+
91+
.. code-block:: python
9092
91-
>>> # Read a Value from the Registry
92-
>>> key = 'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\S-1-5-20'
93-
>>> get_value(key_name=key, value_name='ProfileImagePath')
94-
'%systemroot%\\\\ServiceProfiles\\\\NetworkService'
93+
class Registry(object):
94+
def __init__(self, key: Union[None, str, int] = None, computer_name: Optional[str] = None):
95+
"""
96+
The Registry Class, to create the registry object.
97+
If a key is passed, a connection to the hive is established.
98+
99+
Parameter
100+
---------
101+
102+
key:
103+
the predefined handle to connect to,
104+
or a key string with the hive as the first part (everything else but the hive will be ignored)
105+
or None (then no connection will be established)
106+
computer_name:
107+
the name of the remote computer, of the form r"\\computer_name" or "computer_name". If None, the local computer is used.
108+
109+
Exceptions
110+
----------
111+
RegistryNetworkConnectionError if can not reach target computer
112+
RegistryHKeyError if can not connect to the hive
113+
winreg.ConnectRegistry auditing event
95114
96-
>>> # Create a Key
97-
>>> create_key(r'HKCU\\Software\\lib_registry_test')
115+
Examples
116+
--------
98117
99-
>>> # Delete a Key
100-
>>> delete_key(r'HKCU\\Software\\lib_registry_test')
118+
>>> # just create the instance without connection
119+
>>> registry = Registry()
101120
121+
>>> # test connect at init:
122+
>>> registry = Registry('HKCU')
102123
103-
>>> # Write a Value to the Registry
104-
>>> create_key(r'HKCU\\Software\\lib_registry_test')
105-
>>> set_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name', value='test_string', value_type=REG_SZ)
106-
>>> result = get_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name')
107-
>>> assert result == 'test_string'
108-
109-
>>> # Delete a Value from the Registry
110-
>>> delete_value(key_name=r'HKCU\\Software\\lib_registry_test', value_name='test_name')
111-
>>> delete_key(r'HKCU\\Software\\lib_registry_test')
112-
113-
>>> # Check if a key exists
114-
>>> key_exist('HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\S-1-5-20'
115-
True
116-
>>> key_exist('HKEY_LOCAL_MACHINE\\Software\\DoesNotExist')
117-
False
118-
119-
>>> # get the SIDs of all Windows users
120-
>>> get_ls_user_sids()
121-
['.DEFAULT', 'S-1-5-18', 'S-1-5-19', 'S-1-5-20', ...]
122-
123-
>>> # get the Username from SID
124-
>>> get_username_from_sid(sid='S-1-5-20')
125-
'NetworkService'
124+
>>> # test invalid hive as string
125+
>>> Registry()._reg_connect('SPAM')
126+
Traceback (most recent call last):
127+
...
128+
lib_registry.RegistryHKeyError: invalid KEY: "SPAM"
129+
130+
>>> # test invalid hive as integer
131+
>>> Registry()._reg_connect(42)
132+
Traceback (most recent call last):
133+
...
134+
lib_registry.RegistryHKeyError: invalid HIVE KEY: "42"
135+
136+
>>> # test invalid computer to connect
137+
>>> Registry()._reg_connect(winreg.HKEY_LOCAL_MACHINE, computer_name='some_unknown_machine')
138+
Traceback (most recent call last):
139+
...
140+
lib_registry.RegistryNetworkConnectionError: The network address "some_unknown_machine" is invalid
141+
142+
>>> # test invalid network Path
143+
>>> Registry()._reg_connect(winreg.HKEY_LOCAL_MACHINE, computer_name=r'localhost\\ham\\spam')
144+
Traceback (most recent call last):
145+
...
146+
lib_registry.RegistryNetworkConnectionError: The network path to "localhost\\ham\\spam" was not found
147+
148+
"""
149+
150+
- create_key
151+
152+
.. code-block:: python
153+
154+
def create_key(self, key: Union[str, int], sub_key: str = '', exist_ok: bool = True, parents: bool = False) -> winreg.HKEYType:
155+
"""
156+
Creates a Key, and returns a Handle to the new key
157+
158+
159+
Parameter
160+
---------
161+
key
162+
either a predefined HKEY_* constant,
163+
a string containing the root key,
164+
or an already open key
165+
sub_key
166+
a string with the desired subkey relative to the key
167+
exist_ok
168+
bool, default = True
169+
parents
170+
bool, default = false
171+
172+
173+
Exceptions
174+
----------
175+
RegistryKeyCreateError
176+
if can not create the key
177+
178+
179+
Examples
180+
--------
181+
182+
>>> # Setup
183+
>>> registry = Registry()
184+
>>> # create a key
185+
>>> registry.create_key(r'HKCU\\Software')
186+
<...PyHKEY object at ...>
187+
188+
>>> # create an existing key, with exist_ok = True
189+
>>> registry.create_key(r'HKCU\\Software\\lib_registry_test', exist_ok=True)
190+
<...PyHKEY object at ...>
191+
192+
>>> # create an existing key, with exist_ok = False (parent existing)
193+
>>> registry.create_key(r'HKCU\\Software\\lib_registry_test', exist_ok=False)
194+
Traceback (most recent call last):
195+
...
196+
lib_registry.RegistryKeyCreateError: can not create key, it already exists: HKEY_CURRENT_USER...lib_registry_test
197+
198+
>>> # create a key, parent not existing, with parents = False
199+
>>> registry.create_key(r'HKCU\\Software\\lib_registry_test\\a\\b', parents=False)
200+
Traceback (most recent call last):
201+
...
202+
lib_registry.RegistryKeyCreateError: can not create key, the parent key to "HKEY_CURRENT_USER...b" does not exist
203+
204+
>>> # create a key, parent not existing, with parents = True
205+
>>> registry.create_key(r'HKCU\\Software\\lib_registry_test\\a\\b', parents=True)
206+
<...PyHKEY object at ...>
207+
208+
>>> # TEARDOWN
209+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test', delete_subkeys=True)
210+
211+
"""
212+
213+
- delete_key
214+
215+
.. code-block:: python
216+
217+
def delete_key(self, key: Union[str, int], sub_key: str = '', missing_ok: bool = False, delete_subkeys: bool = False) -> None:
218+
"""
219+
deletes the specified key, this method can delete keys with subkeys.
220+
If the method succeeds, the entire key, including all of its values, is removed.
221+
222+
Parameter
223+
---------
224+
key
225+
either a predefined HKEY_* constant,
226+
a string containing the root key,
227+
or an already open key
228+
sub_key
229+
a string with the desired subkey relative to the key
230+
missing_ok
231+
bool, default = False
232+
delete_subkeys
233+
bool, default = False
234+
235+
Exceptions
236+
----------
237+
RegistryKeyDeleteError If the key does not exist,
238+
RegistryKeyDeleteError If the key has subkeys and delete_subkeys = False
239+
240+
>>> # Setup
241+
>>> registry = Registry()
242+
>>> # create a key, parent not existing, with parents = True
243+
>>> registry.create_key(r'HKCU\\Software\\lib_registry_test\\a\\b', parents=True)
244+
<...PyHKEY object at ...>
245+
246+
>>> # Delete a Key
247+
>>> assert registry.key_exist(r'HKCU\\Software\\lib_registry_test\\a\\b') == True
248+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test\\a\\b')
249+
>>> assert registry.key_exist(r'HKCU\\Software\\lib_registry_test\\a\\b') == False
250+
251+
>>> # Try to delete a missing Key
252+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test\\a\\b')
253+
Traceback (most recent call last):
254+
...
255+
lib_registry.RegistryKeyDeleteError: can not delete key none existing key ...
256+
257+
>>> # Try to delete a missing Key, missing_ok = True
258+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test\\a\\b')
259+
Traceback (most recent call last):
260+
...
261+
lib_registry.RegistryKeyDeleteError: can not delete key none existing key ...
262+
263+
>>> # Try to delete a Key with subkeys
264+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test')
265+
Traceback (most recent call last):
266+
...
267+
lib_registry.RegistryKeyDeleteError: can not delete none empty key ...
268+
269+
>>> # Try to delete a Key with subkeys, delete_subkeys = True
270+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test', delete_subkeys=True)
271+
>>> assert registry.key_exist(r'HKCU\\Software\\lib_registry_test') == False
272+
273+
>>> # Try to delete a Key with missing_ok = True
274+
>>> registry.delete_key(r'HKCU\\Software\\lib_registry_test', missing_ok=True)
275+
276+
"""
277+
278+
- key_exists
279+
280+
.. code-block:: python
281+
282+
def key_exist(self, key: Union[str, int], sub_key: str = '') -> bool:
283+
"""
284+
True if the given key exists
285+
286+
Parameter
287+
---------
288+
key
289+
either a predefined HKEY_* constant,
290+
a string containing the root key,
291+
or an already open key
292+
293+
sub_key
294+
a string with the desired subkey relative to the key
295+
296+
297+
Examples
298+
--------
299+
300+
>>> Registry().key_exist(r'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')
301+
True
302+
>>> Registry().key_exist(r'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\DoesNotExist')
303+
False
304+
305+
"""
126306
127307
Usage from Commandline
128308
------------------------

0 commit comments

Comments
 (0)