[Zope3-checkins] CVS: Zope3/src/zope/cachedescriptors - README.txt:1.1 __init__.py:1.1 property.py:1.1

[Jim Fulton]

Update of /cvs-repository/Zope3/src/zope/cachedescriptors
In directory cvs.zope.org:/tmp/cvs-serv11211/src/zope/cachedescriptors

Added Files:
	README.txt __init__.py property.py 
Log Message:
Added cached properties

=== Added File Zope3/src/zope/cachedescriptors/README.txt ===
See __init__.py.


=== Added File Zope3/src/zope/cachedescriptors/__init__.py ===
"""Cached descriptors

Cached descriptors cache their output.  They take into account
instance attributes that they depend on, so when the instance
attributes change, the descriptors will change the values they
return.

Cached descriptors cache their data in _v_ attributes, so they are
also useful for managing the computation of volatile attributes for
persistent objects.

Persistent descriptors:

  property

     A simple computed property

  method

     Idempotent menthod.  The return values are cached based on method
     arguments and on any instance attributes that the methods are
     defined to depend on.

     **Note**, methods haven't been implemented yet.

"""


=== Added File Zope3/src/zope/cachedescriptors/property.py ===
##############################################################################
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
# 
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
##############################################################################
"""Cached properties

See the CachedProperty class.

$Id: property.py,v 1.1 2003/01/25 15:10:22 jim Exp $
"""
__metaclass__ = type

ncaches = 0l

class CachedProperty:
    """Cached Properties

    Cached properties are computed properties that cache their computed
    values.  They take into account instance attributes that they depend
    on, so when the instance attributes change, the properties will change
    the values they return.
    
    Cached properties cache their data in _v_ attributes, so they are
    also useful for managing the computation of volatile attributes for
    persistent objects.

    Example::

      from persistence import Persistent 
      from zope.cachedescriptors.property import CachedProperty

      class FileManager(Persistent):

         def __init__(self, filename):
             self.filename = filename

         def file(self):
             return open(self.filename)

         file = CachedProperty(file, 'filename')

      file_manager = FileManager('data.txt')

      x = file_manager.file.read(10)

    """

    def __init__(self, func, *names):
        global ncaches
        ncaches += 1
        self.data = (func, names,
                     "_v_cached_property_key_%s" % ncaches,
                     "_v_cached_property_value_%s" % ncaches)

    def __get__(self, inst, class_):
        if inst is None:
            return self

        func, names, key_name, value_name = self.data

        if names:
            if len(names) == 1:
                key = getattr(inst, names[0])
            else:
                key = [getattr(inst, name) for name in names]
        else:
            key = 0

        key = names and [getattr(inst, name) for name in names]
        value = getattr(inst, value_name, self)

        if value is not self:
            # We have a cached value
            oldkey = getattr(inst, key_name, self)
            if key == oldkey:
                # Cache is still good!
                return value
            
        # We need to compute and cache the value

        value = func(inst)
        setattr(inst, key_name, key)
        setattr(inst, value_name, value)
        
        return value