cs-py-func 20250724__tar.gz

cs_py_func-20250724/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: cs-py-func
+Version: 20250724
+Summary: Convenience facilities related to Python functions.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Requires-Python: >=3
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/py/func.py
+
+Convenience facilities related to Python functions.
+
+*Latest release 20250724*:
+* func_a_kw_fmt: shorten long %r, widen another field.
+* Drop Python 2 support.
+
+Short summary:
+* `callif`: Call `func(*a,**kw)` if `doit` is true otherwise just print it out.
+* `callmethod_if`: Call the named `method` on the object `obj` if it exists.
+* `derived_from`: A property which must be recomputed if the revision of another property exceeds the snapshot revision.
+* `derived_property`: A property which must be recomputed if the reference revision (attached to self) exceeds the snapshot revision.
+* `func_a_kw`: Return a string representing a call to `func(*a,**kw)`.
+* `func_a_kw_fmt`: Prepare a percent-format string and associated argument list describing a call to `func(*a,**kw)`. Return `format,args`.
+* `funccite`: Return a citation for a function (name and code location).
+* `funcname`: Return a name for the supplied function `func`. Several objects do not have a __name__ attribute, such as partials.
+* `prop`: A substitute for the builtin @property.
+
+Module contents:
+- <a name="callif"></a>`callif(doit, func, *a, **kw)`: Call `func(*a,**kw)` if `doit` is true
+  otherwise just print it out.
+
+  The parameter `func` may be preceeded optionally by a `dict`
+  containing modes. The current modes are:
+  * `'print'`: the print function, default the builtin `print`
+- <a name="callmethod_if"></a>`callmethod_if(obj, method, default=None, a=None, kw=None)`: Call the named `method` on the object `obj` if it exists.
+
+  If it does not exist, return `default` (which defaults to None).
+  Otherwise call getattr(obj, method)(*a, **kw).
+  `a` defaults to ().
+  `kw` defaults to {}.
+- <a name="derived_from"></a>`derived_from(property_name)`: A property which must be recomputed
+  if the revision of another property exceeds the snapshot revision.
+- <a name="derived_property"></a>`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 (attached to self)
+  exceeds the snapshot revision.
+- <a name="func_a_kw"></a>`func_a_kw(func, *a, **kw)`: Return a string representing a call to `func(*a,**kw)`.
+- <a name="func_a_kw_fmt"></a>`func_a_kw_fmt(func, *a, **kw)`: Prepare a percent-format string and associated argument list
+  describing a call to `func(*a,**kw)`.
+  Return `format,args`.
+
+  The `func` argument can also be a string,
+  typically a prepared description of `func` such as `funccite(func)`.
+
+  *Note*: the returned `args` is a `list` for easy incorporation
+  into further arguments.  The `%` operator requires a `tuple`.
+- <a name="funccite"></a>`funccite(func)`: Return a citation for a function (name and code location).
+- <a name="funcname"></a>`funcname(func)`: Return a name for the supplied function `func`.
+  Several objects do not have a __name__ attribute, such as partials.
+- <a name="prop"></a>`prop(func)`: A substitute for the builtin @property.
+
+  The builtin @property decorator lets internal AttributeErrors escape.
+  While that can support properties that appear to exist conditionally,
+  in practice this is almost never what I want, and it masks deeper errors.
+  Hence this wrapper for @property that transmutes internal AttributeErrors
+  into RuntimeErrors.
+
+# Release Log
+
+
+
+*Release 20250724*:
+* func_a_kw_fmt: shorten long %r, widen another field.
+* Drop Python 2 support.
+
+*Release 20240630*:
+funcname: include the module name, handle functions with no __module__.
+
+*Release 20230331*:
+Drop @trace, moved to cs.debug.
+
+*Release 20230210*:
+Drop the returns_* and yields_* decorators, these days type annotations and @typechecked are the go.
+
+*Release 20221207*:
+* @trace: trace exceptions by default, previously false.
+* Late import of cs.fs.shortpath to avoid import loop.
+* New func_a_kw(func,*a,**kw) returning the formatted form of func_a_kw_fmt(func,*a,**kw).
+
+*Release 20221118*:
+@trace: add indenting.
+
+*Release 20220619*:
+@trace: rename some parameters, add with_caller.
+
+*Release 20220311.1*:
+New callif(doit[,modes],func,*a,**kw) to call or print a function, used in -n/--dry-run stuff sometimes.
+
+*Release 20220311*:
+* @trace: new pprint=False option to use pprint.pformat instead of repr for the return value.
+* @trace: bugfix use of retval parameter.
+
+*Release 20210913*:
+New func_a_kw_fmt(func,*a,**kw) imported from cs.pfx, hooked it into @trace.
+
+*Release 20210906*:
+funcname: special case functools.partial, return concise name.
+
+*Release 20210717*:
+* Move @trace from debug to py.func, defer log call imports to avoid loops.
+* Drop cs.pfx requirement, import opportunisticly with fallback.
+
+*Release 20200518*:
+funcname: prefer `func.__qualname__` over `func.__name__`
+
+*Release 20190729*:
+funccite: handle callables with no __code__ attribute.
+
+*Release 20190108*:
+Break import loop. Use cs.py3.raise_from for portability.
+
+*Release 20181231*:
+* Some type specific convenience wrappers for yields_type and returns_type.
+* Bugfix for @prop.
+
+*Release 20170906.1*:
+Minor tweaks.
+
+*Release 20170906*:
+Bugfix for @prop.
+
+*Release 20170608*:
+New decorator @prop which works just like the builtin @property, but transmutes internal AttributeError into RuntimeError, unmasking many bugs.
+
+*Release 20160828*:
+Use "install_requires" instead of "requires" in DISTINFO.
+
+*Release 20150115*:
+First PyPI release.

cs_py_func-20250724/pyproject.toml

@@ -0,0 +1,173 @@
+[project]
+name = "cs-py-func"
+description = "Convenience facilities related to Python functions."
+authors = [
+    { name = "Cameron Simpson", email = "cs@cskk.id.au" },
+]
+keywords = [
+    "python2",
+    "python3",
+]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 2",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+version = "20250724"
+requires-python = ">=3"
+
+[project.license]
+text = "GNU General Public License v3 or later (GPLv3+)"
+
+[project.urls]
+"Monorepo Hg/Mercurial Mirror" = "https://hg.sr.ht/~cameron-simpson/css"
+"Monorepo Git Mirror" = "https://github.com/cameron-simpson/css"
+"MonoRepo Commits" = "https://bitbucket.org/cameron_simpson/css/commits/branch/main"
+Source = "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/py/func.py"
+
+[project.readme]
+text = """
+Convenience facilities related to Python functions.
+
+*Latest release 20250724*:
+* func_a_kw_fmt: shorten long %r, widen another field.
+* Drop Python 2 support.
+
+Short summary:
+* `callif`: Call `func(*a,**kw)` if `doit` is true otherwise just print it out.
+* `callmethod_if`: Call the named `method` on the object `obj` if it exists.
+* `derived_from`: A property which must be recomputed if the revision of another property exceeds the snapshot revision.
+* `derived_property`: A property which must be recomputed if the reference revision (attached to self) exceeds the snapshot revision.
+* `func_a_kw`: Return a string representing a call to `func(*a,**kw)`.
+* `func_a_kw_fmt`: Prepare a percent-format string and associated argument list describing a call to `func(*a,**kw)`. Return `format,args`.
+* `funccite`: Return a citation for a function (name and code location).
+* `funcname`: Return a name for the supplied function `func`. Several objects do not have a __name__ attribute, such as partials.
+* `prop`: A substitute for the builtin @property.
+
+Module contents:
+- <a name=\"callif\"></a>`callif(doit, func, *a, **kw)`: Call `func(*a,**kw)` if `doit` is true
+  otherwise just print it out.
+
+  The parameter `func` may be preceeded optionally by a `dict`
+  containing modes. The current modes are:
+  * `'print'`: the print function, default the builtin `print`
+- <a name=\"callmethod_if\"></a>`callmethod_if(obj, method, default=None, a=None, kw=None)`: Call the named `method` on the object `obj` if it exists.
+
+  If it does not exist, return `default` (which defaults to None).
+  Otherwise call getattr(obj, method)(*a, **kw).
+  `a` defaults to ().
+  `kw` defaults to {}.
+- <a name=\"derived_from\"></a>`derived_from(property_name)`: A property which must be recomputed
+  if the revision of another property exceeds the snapshot revision.
+- <a name=\"derived_property\"></a>`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 (attached to self)
+  exceeds the snapshot revision.
+- <a name=\"func_a_kw\"></a>`func_a_kw(func, *a, **kw)`: Return a string representing a call to `func(*a,**kw)`.
+- <a name=\"func_a_kw_fmt\"></a>`func_a_kw_fmt(func, *a, **kw)`: Prepare a percent-format string and associated argument list
+  describing a call to `func(*a,**kw)`.
+  Return `format,args`.
+
+  The `func` argument can also be a string,
+  typically a prepared description of `func` such as `funccite(func)`.
+
+  *Note*: the returned `args` is a `list` for easy incorporation
+  into further arguments.  The `%` operator requires a `tuple`.
+- <a name=\"funccite\"></a>`funccite(func)`: Return a citation for a function (name and code location).
+- <a name=\"funcname\"></a>`funcname(func)`: Return a name for the supplied function `func`.
+  Several objects do not have a __name__ attribute, such as partials.
+- <a name=\"prop\"></a>`prop(func)`: A substitute for the builtin @property.
+
+  The builtin @property decorator lets internal AttributeErrors escape.
+  While that can support properties that appear to exist conditionally,
+  in practice this is almost never what I want, and it masks deeper errors.
+  Hence this wrapper for @property that transmutes internal AttributeErrors
+  into RuntimeErrors.
+
+# Release Log
+
+
+
+*Release 20250724*:
+* func_a_kw_fmt: shorten long %r, widen another field.
+* Drop Python 2 support.
+
+*Release 20240630*:
+funcname: include the module name, handle functions with no __module__.
+
+*Release 20230331*:
+Drop @trace, moved to cs.debug.
+
+*Release 20230210*:
+Drop the returns_* and yields_* decorators, these days type annotations and @typechecked are the go.
+
+*Release 20221207*:
+* @trace: trace exceptions by default, previously false.
+* Late import of cs.fs.shortpath to avoid import loop.
+* New func_a_kw(func,*a,**kw) returning the formatted form of func_a_kw_fmt(func,*a,**kw).
+
+*Release 20221118*:
+@trace: add indenting.
+
+*Release 20220619*:
+@trace: rename some parameters, add with_caller.
+
+*Release 20220311.1*:
+New callif(doit[,modes],func,*a,**kw) to call or print a function, used in -n/--dry-run stuff sometimes.
+
+*Release 20220311*:
+* @trace: new pprint=False option to use pprint.pformat instead of repr for the return value.
+* @trace: bugfix use of retval parameter.
+
+*Release 20210913*:
+New func_a_kw_fmt(func,*a,**kw) imported from cs.pfx, hooked it into @trace.
+
+*Release 20210906*:
+funcname: special case functools.partial, return concise name.
+
+*Release 20210717*:
+* Move @trace from debug to py.func, defer log call imports to avoid loops.
+* Drop cs.pfx requirement, import opportunisticly with fallback.
+
+*Release 20200518*:
+funcname: prefer `func.__qualname__` over `func.__name__`
+
+*Release 20190729*:
+funccite: handle callables with no __code__ attribute.
+
+*Release 20190108*:
+Break import loop. Use cs.py3.raise_from for portability.
+
+*Release 20181231*:
+* Some type specific convenience wrappers for yields_type and returns_type.
+* Bugfix for @prop.
+
+*Release 20170906.1*:
+Minor tweaks.
+
+*Release 20170906*:
+Bugfix for @prop.
+
+*Release 20170608*:
+New decorator @prop which works just like the builtin @property, but transmutes internal AttributeError into RuntimeError, unmasking many bugs.
+
+*Release 20160828*:
+Use \"install_requires\" instead of \"requires\" in DISTINFO.
+
+*Release 20150115*:
+First PyPI release."""
+content-type = "text/markdown"
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [
+    "flit_core >=3.2,<4",
+]
+
+[tool.flit.module]
+name = "cs.py.func"

cs_py_func-20250724/src/cs/py/func.py

@@ -0,0 +1,192 @@
+#!/usr/bin/python
+#
+# Convenience routines for python functions.
+#       - Cameron Simpson <cs@cskk.id.au> 15apr2014
+#
+
+r'''
+Convenience facilities related to Python functions.
+'''
+
+from functools import partial
+
+__version__ = '20250724'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 3",
+    ],
+    'python_requires':
+    '>=3',
+}
+
+def funcname(func):
+  ''' Return a name for the supplied function `func`.
+      Several objects do not have a __name__ attribute, such as partials.
+  '''
+  try:
+    name = func.__qualname__
+  except AttributeError:
+    try:
+      name = func.__name__
+    except AttributeError:
+      if isinstance(func, partial):
+        name = "partial(%s)" % (funcname(func.func),)
+      else:
+        name = str(func)
+  return "%s:%s" % (getattr(func, '__module__', '?'), name)
+
+def funccite(func):
+  ''' Return a citation for a function (name and code location).
+  '''
+  try:
+    code = func.__code__
+  except AttributeError:
+    return "%s[no.__code__]" % (repr(func),)
+  try:
+    from cs.fs import shortpath  # pylint: disable=import-outside-toplevel
+  except ImportError:
+    shortpath = lambda p: p  # pylint: disable=unnecessary-lambda-assignment
+  return "%s[%s:%d]" % (
+      funcname(func),
+      shortpath(code.co_filename),
+      code.co_firstlineno,
+  )
+
+def func_a_kw_fmt(func, *a, **kw):
+  ''' Prepare a percent-format string and associated argument list
+      describing a call to `func(*a,**kw)`.
+      Return `format,args`.
+
+      The `func` argument can also be a string,
+      typically a prepared description of `func` such as `funccite(func)`.
+
+      *Note*: the returned `args` is a `list` for easy incorporation
+      into further arguments.  The `%` operator requires a `tuple`.
+  '''
+  av = [
+      func if isinstance(func, str) else getattr(func, '__name__', str(func))
+  ]
+  afv = ['%.40r'] * len(a)
+  av.extend(a)
+  afv.extend(['%s=%.40r'] * len(kw))
+  for kv in kw.items():
+    av.extend(kv)
+  return '%s(' + ','.join(afv) + ')', av
+
+def func_a_kw(func, *a, **kw):
+  ''' Return a string representing a call to `func(*a,**kw)`.
+  '''
+  fmt, args = func_a_kw_fmt(func, *a, **kw)
+  return fmt % tuple(args)
+
+def callif(doit, func, *a, **kw):
+  ''' Call `func(*a,**kw)` if `doit` is true
+      otherwise just print it out.
+
+      The parameter `func` may be preceeded optionally by a `dict`
+      containing modes. The current modes are:
+      * `'print'`: the print function, default the builtin `print`
+  '''
+  if isinstance(func, dict):
+    modes = func
+    a = list(a)
+    func = a.pop(0)
+  else:
+    modes = {}
+  if doit:
+    return func(*a, **kw)
+  # just recite the function
+  modes.get('print', print)(func_a_kw(func, *a, **kw))
+  return None
+
+def callmethod_if(obj, method, default=None, a=None, kw=None):
+  ''' Call the named `method` on the object `obj` if it exists.
+
+      If it does not exist, return `default` (which defaults to None).
+      Otherwise call getattr(obj, method)(*a, **kw).
+      `a` defaults to ().
+      `kw` defaults to {}.
+  '''
+  try:
+    m = getattr(obj, method)
+  except AttributeError:
+    return default
+  if a is None:
+    a = ()
+  if kw is None:
+    kw = {}
+  return m(*a, **kw)
+
+def prop(func):
+  ''' A substitute for the builtin @property.
+
+      The builtin @property decorator lets internal AttributeErrors escape.
+      While that can support properties that appear to exist conditionally,
+      in practice this is almost never what I want, and it masks deeper errors.
+      Hence this wrapper for @property that transmutes internal AttributeErrors
+      into RuntimeErrors.
+  '''
+
+  # pylint: disable=inconsistent-return-statements
+  def prop_wrapper(*a, **kw):
+    try:
+      return func(*a, **kw)
+    except AttributeError as e:
+      raise RuntimeError("inner function %s raised %s" % (func, e)) from e
+
+  prop_wrapper.__name__ = "@prop(%s)" % (funcname(func),)
+  return property(prop_wrapper)
+
+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 (attached to self)
+      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'
+
+  def property_value(self):
+    ''' Attempt lockless fetch of property first.
+        Use lock if property is unset and up to date.
+    '''
+    # poll outside lock
+    try:
+      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:
+            p = func(self)
+            setattr(self, property_name, p)
+            setattr(self, property_revision_name, o_revision)
+    except AttributeError as e:
+      raise RuntimeError("AttributeError: %s" % (e,)) from e
+    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'
+  )