Metadata-Version: 2.1
Name: funcwrap
Version: 0.0.1
Summary: Helps function wrappers/decorators with perfect forwarding
Home-page: https://github.com/coldfix/funcwrap
Author: Thomas Gläßle
Author-email: thomas@coldfix.de
License: Unlicense
Description: funcwrap
        ========
        
        |Tests| |Version| |Unlicense|
        
        Simple helper for function wrappers or decorators that makes the wrapper
        function look indistinguishable from the original.
        
        
        Installation
        ------------
        
        Using ``pip``::
        
            pip install funcwrap
        
        Alternatively, you can redistribute the ``funcwrap.py`` module or even the
        ``funcwrap.wrap`` function by itself as part of your code or program without
        any license ramifications.
        
        
        Usage
        -----
        
        ``funcwrap.wrap`` is similar to the standard ``functools.wraps`` function.
        However, it returns a wrapper that imitates the wrapped function's signature
        exactly on the python syntax level.
        
        .. code-block:: python
        
            >>> from funcwrap import wraps
        
            >>> def func(a='Hello,', *, b='World!'):
            ...     pass
        
            >>> @wraps(func)
            ... def wrapper(*args, **kwargs):
            ...     return (args, kwargs)
        
            >>> wrapper()
            (('Hello,',), {'b': 'World!'})
        
            >>> wrapper('Bye,', b='Quentin!')
            (('Bye,',), {'b': 'Quentin!'})
        
        
        **IMPORTANT:** If you're planning to wrap callables other than python
        functions or lambdas (e.g. partials, methods, objects), be advised that the
        results may be surprising. Make absolutely sure that the wrapper function
        behaves as expected before using *funcwrap*!
        
        
        Why (not) use decorator_?
        -------------------------
        
        *funcwrap* is a lighter alternative to the decorator_ module. There are many
        reasons to stick with *decorator* and some for trying *funcwrap*.
        
        Reasons to stick with *decorator*:
        
        - more well tested and empirically proven, mature package
        - has a different API that is more directly designed toward writing decorators
        - supports generator and coroutine functions
        - supports python versions below 3.5
        - and probably many more
        
        Reasons to use *funcwrap*:
        
        - support for python 3.8's `positional-only parameters`_
        - simpler, shorter code that is easier to understand and modify if you need to
        - license: you can redistribute this module as part of your code or program
          without having to retain any license notice
        - has a different API that fits your needs better
          (``@wraps(func)`` vs ``@decorator``)
        
        .. _decorator: https://pypi.python.org/pypi/decorator
        .. _positional-only parameters: https://www.python.org/dev/peps/pep-0570/
        
        
        .. Badges:
        
        .. |Tests| image::      https://github.com/coldfix/funcwrap/workflows/Tests/badge.svg
           :target:             https://github.com/coldfix/funcwrap/actions?query=Tests
           :alt:                GitHub Actions Status
        
        .. |Version| image::    https://img.shields.io/pypi/v/funcwrap.svg
           :target:             https://pypi.python.org/pypi/funcwrap/
           :alt:                Latest Version
        
        .. |Unlicense| image::  https://img.shields.io/pypi/l/funcwrap.svg
           :target:             https://unlicense.org/
           :alt:                Unlicense
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: License :: Public Domain
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
