source: tools/caching/DOC.txt @ 364

Last change on this file since 364 was 130, checked in by ole, 19 years ago

Initial import of caching tool (from ANU cvs)
File size: 4.8 KB
Line 
1Documentation for module caching.py
2
3Ole.Nielsen@anu.edu.au
4-----------------------------------
5       
6  USAGE:
7    result = cache(func, args, kwargs, dependencies, cachedir, verbose,
8                   compression, evaluate, test, return_filename)
9
10  ARGUMENTS:
11    func --            Function object (Required)
12    args --            Arguments to func (Default: ())
13    kwargs --          Keyword arguments to func (Default: {})   
14    dependencies --    Filenames that func depends on (Default: None)
15    cachedir --        Directory for cache files (Default: options['cachedir'])
16    verbose --         Flag verbose output to stdout
17                       (Default: options['verbose'])
18    compression --     Flag zlib compression (Default: options['compression'])
19    evaluate --        Flag forced evaluation of func (Default: 0)
20    test --            Flag test for cached results (Default: 0)
21    clear --           Flag delete cached results (Default: 0)   
22    return_filename -- Flag return of cache filename (Default: 0)   
23
24  DESCRIPTION:
25    A Python function call of the form
26
27      result = func(arg1,...,argn)
28
29    can be replaced by
30
31      from caching import cache
32      result = cache(func,(arg1,...,argn))
33
34  The latter form returns the same output as the former but reuses cached
35  results if the function has been computed previously in the same context.
36  'result' and the arguments can be simple types, tuples, list, dictionaries or
37  objects, but not unhashable types such as functions or open file objects.
38  The function 'func' may be a member function of an object or a module.
39
40  This type of caching is particularly useful for computationally intensive
41  functions with few frequently used combinations of input arguments. Note that
42  if the inputs or output are very large caching might not save time because
43  disc access may dominate the execution time.
44
45  If the function definition changes after a result has been cached it will be
46  detected by examining the functions bytecode (co_code, co_consts,
47  func_defualts, co_argcount) and it will be recomputed.
48
49  LIMITATIONS:
50    1 Caching uses the apply function and will work with anything that can be
51      pickled, so any limitation in apply or pickle extends to caching.
52    2 A function to be cached should not depend on global variables
53      as wrong results may occur if globals are changed after a result has
54      been cached.
55
56  -----------------------------------------------------------------------------
57  Additional functionality:
58
59  Keyword args
60    Keyword arguments (kwargs) can be added as a dictionary of keyword: value
61    pairs, following the syntax of the built-in function apply().
62    A Python function call of the form
63   
64      result = func(arg1,...,argn, kwarg1=val1,...,kwargm=valm)   
65
66    is then cached as follows
67
68      from caching import cache
69      result = cache(func,(arg1,...,argn), {kwarg1:val1,...,kwargm:valm})
70   
71    The default value of kwargs is {} 
72
73  Explicit dependencies:
74    The call
75      cache(func,(arg1,...,argn),dependencies = <list of filenames>)
76    Checks the size, creation time and modification time of each listed file.
77    If any file has changed the function is recomputed and the results stored
78    again.
79
80  Specify caching directory:
81    The call
82      cache(func,(arg1,...,argn), cachedir = <cachedir>)
83    designates <cachedir> where cached data are stored. Use ~ to indicate users
84    home directory - not $HOME. The default is ~/.python_cache on a UNIX
85    platform and c:/.python_cache on a Win platform.
86
87  Silent operation:
88    The call
89      cache(func,(arg1,...,argn),verbose=0)
90    suppresses messages to standard output.
91
92  Compression:
93    The call
94      cache(func,(arg1,...,argn),compression=0)
95    disables compression. (Default: compression=1). If the requested compressed
96    or uncompressed file is not there, it'll try the other version.
97
98  Forced evaluation:
99    The call
100      cache(func,(arg1,...,argn),evaluate=1)
101    forces the function to evaluate even though cached data may exist.
102
103  Testing for presence of cached result:
104    The call
105      cache(func,(arg1,...,argn),test=1)
106    retrieves cached result if it exists, otherwise None. The function will not
107    be evaluated. If both evaluate and test are switched on, evaluate takes
108    precedence.
109   
110  Obtain cache filenames:
111    The call   
112      cache(func,(arg1,...,argn),return_filename=1)
113    returns the hashed base filename under which this function and its
114    arguments would be cached
115
116  Clearing cached results:
117    The call
118      cache(func,'clear')
119    clears all cached data for 'func' and
120      cache('clear')
121    clears all cached data.
122 
123    NOTE: The string 'clear' can be passed an *argument* to func using
124      cache(func,('clear',)) or cache(func,tuple(['clear'])).
125
126    New form of clear:
127      cache(func,(arg1,...,argn),clear=1)
128    clears cached data for particular combination func and args
Note: See TracBrowser for help on using the repository browser.