Metadata-Version: 2.4
Name: cs-py-func
Version: 20261030
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 :: 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.



Short summary:


* `akw`: A trite class to store positional and keyword arguments.


* `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.

# Functions

## 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`

## 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 {}.

## derived_from(property_name)

A property which must be recomputed
if the revision of another property exceeds the snapshot revision.

## 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.

## func_a_kw(func, *a, **kw)

Return a string representing a call to `func(*a,**kw)`.

## 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`.

## funccite(func)

Return a citation for a function (name and code location).

## funcname(func)

Return a name for the supplied function `func`.
Several objects do not have a __name__ attribute, such as partials.

## 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.

# Classes

## class akw

A trite class to store positional and keyword arguments.

It's a constant annoyance to me that there no neat way to
store a pairing of positional and keyword arguments for use
with a function.
You can eaily store a sequence, a mapping, and you can store
a function with arguments using `functools.partial`.

Example:

    >>> args = akw(1, 2, x=3, z=4)
    >>> args
    akw(*(1, 2),**{'x': 3, 'z': 4})
    >>> args.args
    (1, 2)
    >>> args.kwargs
    {'x': 3, 'z': 4}
    >>> import sys
    >>> prakw=akw(1, 2, file=sys.stdout)
    >>> prakw(print, 3)
    1 2 3

### `akw.__call__(self, func, *cargs, **ckwargs)`

Call `func` with `self.args` and `cargs` as positional
arguments and `self.kwargs` and `ckwargs` as keyword arguments.
