Metadata-Version: 2.1
Name: intercepts
Version: 0.4.0
Summary: Intercept function and method calls
Author-email: David Shriver <davidshriver@outlook.com>
License: MIT
Project-URL: Source, https://github.com/dlshriver/intercepts
Project-URL: Documentation, https://intercepts.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/dlshriver/intercepts/issues
Keywords: development,intercepts,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: mypy (~=1.0.0) ; extra == 'dev'
Requires-Dist: black (~=23.1.0) ; extra == 'dev'
Requires-Dist: isort (~=5.12.0) ; extra == 'dev'
Requires-Dist: coverage (~=7.1.0) ; extra == 'dev'
Requires-Dist: pytest (~=7.2.1) ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo (~=2022.12.7) ; extra == 'docs'
Requires-Dist: sphinx (~=6.1.3) ; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy (~=1.0.0) ; extra == 'lint'
Provides-Extra: style
Requires-Dist: black (~=23.1.0) ; extra == 'style'
Requires-Dist: isort (~=5.12.0) ; extra == 'style'
Provides-Extra: test
Requires-Dist: coverage (~=7.1.0) ; extra == 'test'
Requires-Dist: pytest (~=7.2.1) ; extra == 'test'

Intercepts
==========

[![CI Status](https://github.com/dlshriver/intercepts/actions/workflows/ci.yml/badge.svg)](https://github.com/dlshriver/intercepts/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/dlshriver/intercepts/branch/main/graph/badge.svg?token=zsQBFINrdo)](https://codecov.io/gh/dlshriver/intercepts)
[![PyPI](https://img.shields.io/pypi/v/intercepts.svg)](https://pypi.org/project/intercepts/)
[![License](https://img.shields.io/github/license/dlshriver/intercepts.svg)](https://github.com/dlshriver/intercepts/blob/master/LICENSE)

Intercepts allows you to intercept function calls in Python and handle them in 
any manner you choose. For example, you can pre-process the inputs to a 
function, or apply post-processing on its output. Intercepts also allows you 
to completely replace a function with a custom implementation.

```python
>>> increment(41)
42
>>> intercepts.register(increment, handler)
>>> increment(41)
40
>>> intercepts.unregister(increment)
>>> intercepts.register(increment, handler2)
>>> increment(41)
'The answer is: 42'
>>> intercepts.unregister_all()
```

Handler functions receive all paramters to the intercepted function call and 
can access the intercepted function through the variable `_`.

```python
>>> def handler(num):
...   result = _(num)
...   return num - (result - num)
>>> def handler2(*args, **kwargs):
...   result = _(*args, **kwargs)
...   return f"The answer is: {result}"
```

The intercepts module also allows intercepting python built-in functions, such 
as `print` and `sorted`. For best results, the intercepts module should be the 
first module imported.

```python
>>> def print_handler(message):
...     return _(''.join(reversed(message)))
>>> print("Hello world")
Hello world
>>> intercepts.register(print, print_handler)
>>> print("Hello world")
dlrow olleH
```

Installation
------------

Intercepts requires Python 3.7+ on Linux or Windows and can be installed using `pip`.

    $ pip install intercepts

Or, use `pip` to install the latest version from the github source.

    $ pip install -U git+https://github.com/dlshriver/intercepts.git@main

Documentation
-------------

Some documentation is available [here](https://intercepts.readthedocs.io/en/latest/).
