Module Registry

Source Code for Module Registry

  1  # Blender.Registry module 
  2   
  3  """ 
  4  The Blender.Registry submodule. 
  5   
  6  B{New}: L{GetKey} and L{SetKey} have been updated to save and load scripts 
  7  *configuration data* to files. 
  8   
  9  Registry 
 10  ======== 
 11   
 12  This module provides a way to create, retrieve and edit B{persistent data} in 
 13  Blender. 
 14   
 15  When a script is executed it has its own private global dictionary, 
 16  which is deleted when the script exits. This is done to avoid problems with 
 17  name clashes and garbage collecting.  But because of this, the data created by 
 18  a script isn't kept after it leaves: the data is not persistent.  The Registry 
 19  module was created to give programmers a way around this limitation. 
 20   
 21  Possible uses: 
 22          - saving arbitrary data from a script that itself or another one will need 
 23                  to access later. 
 24          - saving configuration data for a script: users can view and edit this data 
 25                  using the "Scripts Configuration Editor" script. 
 26          - saving the current state of a script's GUI (its button values) to restore it 
 27                  when the script is executed again. 
 28   
 29  Example:: 
 30   
 31          import Blender 
 32          from Blender import Registry 
 33   
 34          # this function updates the Registry when we need to: 
 35          def update_Registry(): 
 36                  d = {} 
 37                  d['myvar1'] = myvar1 
 38                  d['myvar2'] = myvar2 
 39                  d['mystr'] = mystr 
 40                  # cache = True: data is also saved to a file 
 41                  Blender.Registry.SetKey('MyScript', d, True) 
 42   
 43          # first declare global variables that should go to the Registry: 
 44          myvar1 = 0 
 45          myvar2 = 3.2 
 46          mystr = "hello" 
 47   
 48          # then check if they are already there (saved on a 
 49          # previous execution of this script): 
 50          rdict = Registry.GetKey('MyScript', True) # True to check on disk also 
 51          if rdict: # if found, get the values saved there 
 52                  try: 
 53                          myvar1 = rdict['myvar1'] 
 54                          myvar2 = rdict['myvar2'] 
 55                          mystr = rdict['mystr'] 
 56                  except: update_Registry() # if data isn't valid rewrite it 
 57   
 58          # ... 
 59          # here goes the main part of the script ... 
 60          # ... 
 61   
 62          # if at some point the data is changed, we update the Registry: 
 63          update_Registry() 
 64   
 65  @note: In Python terms, the Registry holds a dictionary of dictionaries. 
 66          Technically any Python or BPython object can be stored: there are no 
 67          restrictions, but ... 
 68   
 69  @note: We have a few recommendations: 
 70   
 71          Data saved to the Registry is kept in memory, so if you decide to store large 
 72          amounts your script users should be clearly informed about it -- 
 73          always keep in mind that you have no idea about their resources and the 
 74          applications they are running at a given time (unless you are the only 
 75          user), so let them decide. 
 76   
 77          There are restrictions to the data that gets automatically saved to disk by 
 78          L{SetKey}(keyname, dict, True):  this feature is only meant for simple data 
 79          (bools, ints, floats, strings and dictionaries or sequences of these types). 
 80   
 81          For more demanding needs, it's of course trivial to save data to another  
 82          file or to a L{Blender Text<Text>}. 
 83  """ 
 84   
85 -def Keys ():
86 """ 87 Get all keys currently in the Registry's dictionary. 88 """
89
90 -def GetKey (key, cached = False):
91 """ 92 Get key 'key' from the Registry. 93 @type key: string 94 @param key: a key from the Registry dictionary. 95 @type cached: bool 96 @param cached: if True and the requested key isn't already loaded in the 97 Registry, it will also be searched on the user or default scripts config 98 data dir (config subdir in L{Blender.Get}('datadir')). 99 @return: the dictionary called 'key'. 100 """
101
102 -def SetKey (key, dict, cache = False):
103 """ 104 Store a new entry in the Registry. 105 @type key: string 106 @param key: the name of the new entry, tipically your script's name. 107 @type dict: dictionary 108 @param dict: a dict with all data you want to save in the Registry. 109 @type cache: bool 110 @param cache: if True the given key data will also be saved as a file 111 in the config subdir of the scripts user or default data dir (see 112 L{Blender.Get}). 113 @warn: as stated in the notes above, there are restrictions to what can 114 be automatically stored in config files. 115 """
116
117 -def RemoveKey (key):
118 """ 119 Remove the dictionary with key 'key' from the Registry. 120 @type key: string 121 @param key: the name of an existing Registry key. 122 """
123