Changeset 257 for trunk/python/pyregfi/__init__.py

Timestamp:

06/16/11 20:13:13 (13 years ago)

Author:

tim

Message:

documentation fixes/additions

File:

• trunk/python/pyregfi/__init__.py (modified) (12 diffs)

trunk/python/pyregfi/__init__.py

@@ -11 +11 @@
 #
 # The library operates on registry hives, each of which is contained within a
-# single file.  To get started, one must first open the registry hive file with
-# the open() or file() Python built-in functions (or equivalent) and then pass
-# the resulting file object to pyregfi. For example:
+# single file.  The quickest way to get started, is to use the @ref openHive() 
+# function to obtain a Hive object.  For example:
 # @code
 # >>> import pyregfi
-# >>> fh = open('/mnt/win/c/WINDOWS/system32/config/system', 'rb')
-# >>> myHive = pyregfi.Hive(fh)
+# >>> myHive = pyregfi.openHive('/mnt/win/c/WINDOWS/system32/config/system')
 # @endcode
 #
@@ -300 +298 @@
 # 
 class Security(_StructureWrapper):
-    ## Number of keys referencing this SK record 
+    ## Number of registry Keys referencing this SK record
     ref_count = 1
 
@@ -306 +304 @@
     offset = 0xCAFEBABE
 
-    ## The @ref SecurityDescriptor for this SK record
+    ## The @ref winsec.SecurityDescriptor for this SK record
     descriptor = object()
 
@@ -314 +312 @@
         self.descriptor = winsec.SecurityDescriptor(base.contents.sec_desc.contents)
 
-    ## Loads the "previous" Security record in the hive
+    ## Loads the "next" Security record in the hive
     #
     # @note
@@ -337 +335 @@
 ## Abstract class for ValueList and SubkeyList
 class _GenericList(object):
+    # XXX: consider implementing keys(), values(), items() and other dictionary methods
     _hive = None
     _key_base = None
@@ -373 +372 @@
     ## Retrieves a list element by name
     #
+    # @param name The name of the subkey or value desired.  
+    #             This is case-sensitive.
+    #
+    # @note The registry format does inherently prevent multiple
+    #       subkeys or values from having the same name.  
+    #       This interface simply returns the first match.  
+    #       Lookups using this method could also fail due to incorrectly
+    #       encoded strings.
+    #       To identify any duplicates, use the iterator interface to 
+    #       check every list element.
+    #
     # @return the first element whose name matches, or None if the element
     #         could not be found
     def __getitem__(self, name):
+        # XXX: Consider interpreting integer names as offsets in the underlying list
         index = ctypes.c_uint32()
         if isinstance(name, str):
@@ -391 +402 @@
         raise KeyError('')
 
+
+    ## Fetches the requested element by name, or the default value if the lookup
+    #  fails.
+    # 
     def get(self, name, default):
         try:
@@ -426 +441 @@
 # @endcode
 #
-# @note SubkeyLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       SubkeyLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a subkeys list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class SubkeyList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_subkeys
@@ -447 +462 @@
 # @endcode
 #
-# @note ValueLists should never be accessed directly and only exist
-#       in association with a parent Key object.  Do not retain references to 
-#       ValueLists.  Instead, access them via their parent Key at all times.
+# You may also request the len() of a values list. 
+# However keys(), values(), items() and similar methods are not currently 
+# implemented.
 class ValueList(_GenericList):
     _fetch_num = regfi.regfi_fetch_num_values
@@ -460 +475 @@
 # access to their subkeys, values, and other metadata.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Key instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute 
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Key(_StructureWrapper):
     ## A @ref ValueList object representing the list of Values 
@@ -558 +573 @@
         return None
 
+
+    ## Checks to see if this Key is the root of its Hive
+    #
+    #  @return True if it is, False otherwise
     def is_root(self):
         return (self._hive.root == self)
@@ -567 +586 @@
 # access to their associated data.
 #
-# @note Value instances may provide access to more than the attributes
+# @note Value instances may provide access to more attributes than are
 #       documented here.  However, undocumented attributes may change over time
 #       and are not officially supported.  If you need access to an attribute
-#       not shown here, see pyregfi.structures.
+#       not shown here, see @ref pyregfi.structures.
 class Value(_StructureWrapper):
     ## The raw Value name as an uninterpreted bytearray