cs-py-func 20150115__tar.gz

cs.py.func-20150115/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 1.1
+Name: cs.py.func
+Version: 20150115
+Summary: convenience facilities related to Python functions
+Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
+Author: Cameron Simpson
+Author-email: cs@zip.com.au
+License: UNKNOWN
+Description: Convenience facilities related to Python functions.
+        ===================================================
+        
+        funcname(func)
+        --------------
+        
+        Returns a string to name `func`. I use this instead of func.__name__ because several things do not have a .__name__. It tries to use .__name__, but falls back to ..__str__().
+        
+        @derived_property
+        -----------------
+        
+        Decorator for property functions which must be recomputed if another property is updated.
+        
+        @derived_from(property_name)
+        ----------------------------
+        
+        Convenience wrapper of derived_property which names the parent property.
+        
+        @returns_type(func, basetype)
+        -----------------------------
+        
+        Basis for decorators to do type checking of function return values. Example::
+        
+          def returns_bool(func):
+            ''' Decorator for functions which should return Booleans.
+            '''
+            return returns_type(func, bool)
+        
+          @returns_bool
+          def f(x):
+            return x == 1
+        
+        This has been used for debugging functions called far from their definitions.
+        
+Keywords: python2,python3
+Platform: UNKNOWN
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Intended Audience :: Developers
+Requires: cs.excutils

cs.py.func-20150115/README.rst

@@ -0,0 +1,33 @@
+Convenience facilities related to Python functions.
+===================================================
+
+funcname(func)
+--------------
+
+Returns a string to name `func`. I use this instead of func.__name__ because several things do not have a .__name__. It tries to use .__name__, but falls back to ..__str__().
+
+@derived_property
+-----------------
+
+Decorator for property functions which must be recomputed if another property is updated.
+
+@derived_from(property_name)
+----------------------------
+
+Convenience wrapper of derived_property which names the parent property.
+
+@returns_type(func, basetype)
+-----------------------------
+
+Basis for decorators to do type checking of function return values. Example::
+
+  def returns_bool(func):
+    ''' Decorator for functions which should return Booleans.
+    '''
+    return returns_type(func, bool)
+
+  @returns_bool
+  def f(x):
+    return x == 1
+
+This has been used for debugging functions called far from their definitions.

cs.py.func-20150115/lib/python/cs/py/func.py

@@ -0,0 +1,127 @@
+#!/usr/bin/python
+#
+# Convenience routines for python functions.
+#       - Cameron Simpson <cs@zip.com.au> 15apr2014
+#
+
+DISTINFO = {
+    'description': "convenience facilities related to Python functions",
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 3",
+        ],
+    'requires': ['cs.excutils'],
+}
+
+from cs.excutils import transmute
+
+def funcname(func):
+  ''' Return a name for the supplied function `func`.
+      Several objects do not have a __name__ attribute, such as partials.
+  '''
+  try:
+    return func.__name__
+  except AttributeError:
+    return str(func)
+
+def funccite(func):
+  code = func.__code__
+  return "%s[%s:%d]" % (funcname(func), code.co_filename, code.co_firstlineno)
+
+def callmethod_if(o, method, default=None, a=None, kw=None):
+  ''' Call the named `method` on the object `o` if it exists.
+      If it does not exist, return `default` (which defaults to None).
+      Otherwise call getattr(o, method)(*a, **kw).
+      `a` defaults to ().
+      `kw` defaults to {}.
+  '''
+  try:
+    m = getattr(o, method)
+  except AttributeError:
+    return default
+  if a is None:
+    a = ()
+  if kw is None:
+    kw = {}
+  return m(*a, **kw)
+
+def derived_property(func, original_revision_name='_revision', lock_name='_lock', property_name=None, unset_object=None):
+  ''' A property which must be recomputed if the reference revision exceeds the snapshot revision.
+  '''
+  if property_name is None:
+    property_name = '_' + func.__name__
+  # the property used to track the reference revision
+  property_revision_name = property_name + '__revision'
+
+  from cs.logutils import X
+
+  @transmute(AttributeError)
+  def property_value(self):
+    ''' Attempt lockless fetch of property first.
+        Use lock if property is unset and up to date.
+    '''
+    # poll outside lock
+    p = getattr(self, property_name, unset_object)
+    p_revision = getattr(self, property_revision_name, 0)
+    o_revision = getattr(self, original_revision_name)
+    if p is unset_object or p_revision < o_revision:
+      with getattr(self, lock_name):
+        # repoll value inside lock
+        p = getattr(self, property_name, unset_object)
+        p_revision = getattr(self, property_revision_name, 0)
+        o_revision = getattr(self, original_revision_name)
+        if p is unset_object or p_revision < o_revision:
+          X("COMPUTE .%s... [p_revision=%s, o_revision=%s]", property_name, p_revision, o_revision)
+          p = func(self)
+          setattr(self, property_name, p)
+          ##X("COMPUTE .%s: set .%s to %s", self, property_revision_name, o_revision)
+          setattr(self, property_revision_name, o_revision)
+        else:
+          ##debug("inside lock, already computed up to date %s", property_name)
+          pass
+    else:
+      ##debug("outside lock, already computed up to date %s", property_name)
+      pass
+    return p
+  return property(property_value)
+
+def derived_from(property_name):
+  ''' A property which must be recomputed if the revision of another property exceeds the snapshot revision.
+  '''
+  return partial(derived_property, original_revision_name='_' + property_name + '__revision')
+
+def yields_type(func, basetype):
+  ''' Decrator which checks that a generator yields values of type `basetype`.
+  '''
+  funcname = funccite(func)
+  def check_yields_type(*a, **kw):
+    for item in func(*a, **kw):
+      if not isinstance(item, basetype):
+        raise TypeError(
+                "wrong type yielded from func %s: expected subclass of %s, got %s: %r"
+                % (funcname, basetype, type(item), item)
+              )
+      yield item
+  check_yields_type.__name__ = ( 'check_yields_type[%s,basetype=%s]'
+                                 % (funcname, basetype)
+                               )
+  return check_yields_type
+
+def returns_type(func, basetype):
+  ''' Decrator which checks that a function returns values of type `basetype`.
+  '''
+  funcname = funccite(func)
+  def check_returns_type(*a, **kw):
+    retval = func(*a, **kw)
+    if not isinstance(retval, basetype):
+      raise TypeError(
+              "wrong type returned from func %s: expected subclass of %s, got %s: %r"
+              % (funcname, basetype, type(retval), retval)
+            )
+    return retval
+  check_returns_type.__name__ = ( 'check_returns_type[%s,basetype=%s]'
+                                  % (funcname, basetype)
+                                )
+  return check_returns_type

cs.py.func-20150115/setup.py

@@ -0,0 +1,16 @@
+#!/usr/bin/python
+from distutils.core import setup
+setup(
+  name = 'cs.py.func',
+  description = 'convenience facilities related to Python functions',
+  author = 'Cameron Simpson',
+  author_email = 'cs@zip.com.au',
+  version = '20150115',
+  url = 'https://bitbucket.org/cameron_simpson/css/commits/all',
+  classifiers = ['Programming Language :: Python', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 3', 'Topic :: Software Development :: Libraries :: Python Modules', 'Operating System :: OS Independent', 'Development Status :: 4 - Beta', 'License :: OSI Approved :: GNU General Public License v3 (GPLv3)', 'Intended Audience :: Developers'],
+  keywords = ['python2', 'python3'],
+  long_description = u"Convenience facilities related to Python functions.\n===================================================\n\nfuncname(func)\n--------------\n\nReturns a string to name `func`. I use this instead of func.__name__ because several things do not have a .__name__. It tries to use .__name__, but falls back to ..__str__().\n\n@derived_property\n-----------------\n\nDecorator for property functions which must be recomputed if another property is updated.\n\n@derived_from(property_name)\n----------------------------\n\nConvenience wrapper of derived_property which names the parent property.\n\n@returns_type(func, basetype)\n-----------------------------\n\nBasis for decorators to do type checking of function return values. Example::\n\n  def returns_bool(func):\n    ''' Decorator for functions which should return Booleans.\n    '''\n    return returns_type(func, bool)\n\n  @returns_bool\n  def f(x):\n    return x == 1\n\nThis has been used for debugging functions called far from their definitions.\n",
+  package_dir = {'': 'lib/python'},
+  py_modules = ['cs.py.func'],
+  requires = ['cs.excutils'],
+)