##
4.3 Timed-refresh placeholder

The template:

      Timed cache:  $*.5m*voom

The command line and the output:

      % voom='Voom!' python x.py --env
      Timed cache:  Voom!

The generated method's docstring:

      """
      This is the main method generated by Cheetah
      This cache will be refreshed every 30.0 seconds.
      """

The generated code:

       1  write('Timed cache:  ')
       2  ## START CACHE REGION: at line, col (1, 15) in the source.
       3  RECACHE = True
       4  if not self._cacheData.has_key('55048032'):
       5      self.__cache55048032__refreshTime = currentTime() + 30.0
       6  elif currentTime() > self.__cache55048032__refreshTime:
       7      self.__cache55048032__refreshTime = currentTime() + 30.0
       8  else:
       9      RECACHE = False
      10  if RECACHE:
      11      orig_trans = trans
      12      trans = cacheCollector = DummyTransaction()
      13      write = cacheCollector.response().write
      14      write(filter(VFS(SL,"voom",1))) # generated from '$*.5m*voom' at
                  # line 1, col 15.
      15      trans = orig_trans
      16      write = trans.response().write
      17      self._cacheData['55048032'] = cacheCollector.response().getvalue()
      18      del cacheCollector
      19  write(self._cacheData['55048032'])
      20  ## END CACHE REGION

      21  write('\n')

This code is identical to the static cache example except for the docstring and the first if-block. (OK, so the cache ID is different and the comment on line 14 is different too. Big deal.)

Each timed-refresh cache item has a corrsponding private attribute `.__cache########__refreshTime` giving the refresh time in ticks (=seconds since January 1, 1970). The first if-block (lines 3-9) checks whether the cache value is missing or its update time has passed, and if so, sets `RECHARGE` to true and also schedules another refresh at the next interval.

The method docstring reminds the user how often the cache will be refreshed. This information is unfortunately not as robust as it could be. Each timed-cache placeholder blindly generates a line in the docstring. If all refreshes are at the same interval, there will be multiple identical lines in the docstring. If the refreshes are at different intervals, you get a situation like this:

      """
      This is the main method generated by Cheetah
      This cache will be refreshed every 30.0 seconds.
      This cache will be refreshed every 60.0 seconds.
      This cache will be refreshed every 120.0 seconds.
      """

The docstring tells only that ``something'' will be refreshed every 60.0 seconds, but doesn't reveal which placeholder that is. Only if you know the relative order of the placeholders in the template can you figure that out.