======
Patchy
======
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/patchy/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/patchy/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/patchy/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/patchy.svg?style=for-the-badge
:target: https://pypi.org/project/patchy/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
.. figure:: https://raw.githubusercontent.com/adamchainz/patchy/main/pirate.png
:alt: A patchy pirate.
..
Patch the inner source of python functions at runtime.
A quick example, making a function that returns 1 instead return 9001:
.. code-block:: pycon
>>> def sample():
... return 1
...
>>> patchy.patch(
... sample,
... """\
... @@ -1,2 +1,2 @@
... def sample():
... - return 1
... + return 9001
... """,
... )
>>> sample()
9001
Patchy works by replacing the code attribute of the function, leaving the
function object itself the same. It's thus more versatile than monkey patching,
since if the function has been imported in multiple places they'll also call
the new behaviour.
Installation
============
Use **pip**:
.. code-block:: bash
python -m pip install patchy
Python 3.7 to 3.12 supported.
----
**Hacking on a Django project?**
Check out my book `Boost Your Django DX <https://adamchainz.gumroad.com/l/byddx>`__ which covers many ways to improve your development experience.
----
Why?
====
If you’re monkey-patching an external library to add or fix some functionality,
you will probably forget to check the monkey patch when you upgrade it. By
using a patch against its source code, you can specify some context that you
expect to remain the same in the function that will be checked before the
source is applied.
I found this with some small but important patches to Django for a project.
Since it takes a lot of energy to maintain a fork, writing monkey patches was
the chosen quick solution, but then writing actual patches would be better.
The patches are applied with the standard ``patch`` commandline utility.
Why not?
========
There are of course a lot of reasons against:
* It’s (relatively) slow (since it writes the source to disk and calls the
``patch`` command)
* If you have a patch file, why not just fork the library and apply it?
* At least with monkey-patching you know what end up with, rather than having
the changes being done at runtime to source that may have changed.
All are valid arguments. However once in a while this might be the right
solution.
How?
====
The standard library function ``inspect.getsource()`` is used to retrieve the
source code of the function, the patch is applied with the commandline utility
``patch``, the code is recompiled, and the function’s code object is replaced
the new one. Because nothing tends to poke around at code objects apart from
dodgy hacks like this, you don’t need to worry about chasing any references
that may exist to the function, unlike ``mock.patch``.
A little special treatment is given to ``instancemethod``, ``classmethod``, and
``staticmethod`` objects to make sure the underlying function is what gets
patched and that you don't have to worry about the details.
API
===
``patch(func, patch_text)``
---------------------------
Apply the patch ``patch_text`` to the source of function ``func``. ``func`` may
be either a function, or a string providing the dotted path to import a
function.
If the patch is invalid, for example the context lines don’t match,
``ValueError`` will be raised, with a message that includes all the output from
the ``patch`` utility.
Note that ``patch_text`` will be ``textwrap.dedent()``’ed, but leading
whitespace will not be removed. Therefore the correct way to include the patch
is with a triple-quoted string with a backslash - ``"""\`` - which starts the
string and avoids including the first newline. A final newline is not required
and will be automatically added if not present.
Example:
.. code-block:: python
import patchy
def sample():
return 1
patchy.patch(
sample,
"""\
@@ -2,2 +2,2 @@
- return 1
+ return 2""",
)
print(sample()) # prints 2
``mc_patchface(func, patch_text)``
----------------------------------
An alias for ``patch``, so you can meme it up by calling
``patchy.mc_patchface()``.
``unpatch(func, patch_text)``
-----------------------------
Unapply the patch ``patch_text`` from the source of function ``func``. This is
the reverse of ``patch()``\ing it, and calls ``patch --reverse``.
The same error and formatting rules apply as in ``patch()``.
Example:
.. code-block:: python
import patchy
def sample():
return 2
patchy.unpatch(
sample,
"""\
@@ -2,2 +2,2 @@
- return 1
+ return 2""",
)
print(sample()) # prints 1
``temp_patch(func, patch_text)``
--------------------------------
Takes the same arguments as ``patch``. Usable as a context manager or function
decorator to wrap code with a call to ``patch`` before and ``unpatch`` after.
Context manager example:
.. code-block:: python
def sample():
return 1234
patch_text = """\
@@ -1,2 +1,2 @@
def sample():
- return 1234
+ return 5678
"""
with patchy.temp_patch(sample, patch_text):
print(sample()) # prints 5678
Decorator example, using the same ``sample`` and ``patch_text``:
.. code-block:: python
@patchy.temp_patch(sample, patch_text)
def my_func():
return sample() == 5678
print(my_func()) # prints True
``replace(func, expected_source, new_source)``
----------------------------------------------
Check that function or dotted path to function ``func`` has an AST matching
``expected_source``, then replace its inner code object with source compiled
from ``new_source``. If the AST check fails, ``ValueError`` will be raised with
current/expected source code in the message. In the author's opinion it's
preferable to call ``patch()`` so your call makes it clear to see what is being
changed about ``func``, but using ``replace()`` is simpler as you don't have to
make a patch and there is no subprocess call to the ``patch`` utility.
Note both ``expected_source`` and ``new_source`` will be
``textwrap.dedent()``’ed, so the best way to include their source is with a
triple quoted string with a backslash escape on the first line, as per the
example below.
If you want, you can pass ``expected_source=None`` to avoid the guard against
your target changing, but this is highly unrecommended as it means if the
original function changes, the call to ``replace()`` will continue to silently
succeed.
Example:
.. code-block:: python
import patchy
def sample():
return 1
patchy.replace(
sample,
"""\
def sample():
return 1
""",
"""\
def sample():
return 42
""",
)
print(sample()) # prints 42
How to Create a Patch
=====================
1. Save the source of the function of interest (and nothing else) in a ``.py``
file, e.g. ``before.py``:
.. code-block:: python
def foo():
print("Change me")
Make sure you dedent it so there is no whitespace before the ``def``, i.e.
``d`` is the first character in the file. For example if you wanted to patch
the ``bar()`` method below:
.. code-block:: python
class Foo:
def bar(self, x):
return x * 2
...you would put just the method in a file like so:
.. code-block:: python
def bar(self, x):
return x * 2
However we'll continue with the first example ``before.py`` since it's
simpler.
2. Copy that ``.py`` file, to e.g. ``after.py``, and make the changes you
want, such as:
.. code-block:: python
def foo():
print("Changed")
3. Run ``diff``, e.g. ``diff -u before.py after.py``. You will get output like:
.. code-block:: diff
diff --git a/Users/chainz/tmp/before.py b/Users/chainz/tmp/after.py
index e6b32c6..31fe8d9 100644
--- a/Users/chainz/tmp/before.py
+++ b/Users/chainz/tmp/after.py
@@ -1,2 +1,2 @@
def foo():
- print("Change me")
+ print("Changed")
4. The filenames are not necessary for ``patchy`` to work. Take only from the
first ``@@`` line onwards into the multiline string you pass to
``patchy.patch()``:
.. code-block:: python
patchy.patch(
foo,
"""\
@@ -1,2 +1,2 @@
def foo():
- print("Change me")
+ print("Changed")
""",
)
Raw data
{
"_id": null,
"home_page": "https://github.com/adamchainz/patchy",
"name": "patchy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "patchy",
"author": "Adam Johnson",
"author_email": "me@adamj.eu",
"download_url": "https://files.pythonhosted.org/packages/d9/0c/b0cf016d2ca860ec4fb1ad227577cd668d5686abacd203edee9135fac8c1/patchy-2.7.0.tar.gz",
"platform": null,
"description": "======\nPatchy\n======\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/patchy/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/patchy/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/patchy/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/patchy.svg?style=for-the-badge\n :target: https://pypi.org/project/patchy/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\n.. figure:: https://raw.githubusercontent.com/adamchainz/patchy/main/pirate.png\n :alt: A patchy pirate.\n\n..\n\nPatch the inner source of python functions at runtime.\n\nA quick example, making a function that returns 1 instead return 9001:\n\n.. code-block:: pycon\n\n >>> def sample():\n ... return 1\n ...\n >>> patchy.patch(\n ... sample,\n ... \"\"\"\\\n ... @@ -1,2 +1,2 @@\n ... def sample():\n ... - return 1\n ... + return 9001\n ... \"\"\",\n ... )\n >>> sample()\n 9001\n\nPatchy works by replacing the code attribute of the function, leaving the\nfunction object itself the same. It's thus more versatile than monkey patching,\nsince if the function has been imported in multiple places they'll also call\nthe new behaviour.\n\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: bash\n\n python -m pip install patchy\n\nPython 3.7 to 3.12 supported.\n\n----\n\n**Hacking on a Django project?**\nCheck out my book `Boost Your Django DX <https://adamchainz.gumroad.com/l/byddx>`__ which covers many ways to improve your development experience.\n\n----\n\nWhy?\n====\n\nIf you\u2019re monkey-patching an external library to add or fix some functionality,\nyou will probably forget to check the monkey patch when you upgrade it. By\nusing a patch against its source code, you can specify some context that you\nexpect to remain the same in the function that will be checked before the\nsource is applied.\n\nI found this with some small but important patches to Django for a project.\nSince it takes a lot of energy to maintain a fork, writing monkey patches was\nthe chosen quick solution, but then writing actual patches would be better.\n\nThe patches are applied with the standard ``patch`` commandline utility.\n\n\nWhy not?\n========\n\nThere are of course a lot of reasons against:\n\n* It\u2019s (relatively) slow (since it writes the source to disk and calls the\n ``patch`` command)\n* If you have a patch file, why not just fork the library and apply it?\n* At least with monkey-patching you know what end up with, rather than having\n the changes being done at runtime to source that may have changed.\n\nAll are valid arguments. However once in a while this might be the right\nsolution.\n\n\nHow?\n====\n\nThe standard library function ``inspect.getsource()`` is used to retrieve the\nsource code of the function, the patch is applied with the commandline utility\n``patch``, the code is recompiled, and the function\u2019s code object is replaced\nthe new one. Because nothing tends to poke around at code objects apart from\ndodgy hacks like this, you don\u2019t need to worry about chasing any references\nthat may exist to the function, unlike ``mock.patch``.\n\nA little special treatment is given to ``instancemethod``, ``classmethod``, and\n``staticmethod`` objects to make sure the underlying function is what gets\npatched and that you don't have to worry about the details.\n\n\nAPI\n===\n\n``patch(func, patch_text)``\n---------------------------\n\nApply the patch ``patch_text`` to the source of function ``func``. ``func`` may\nbe either a function, or a string providing the dotted path to import a\nfunction.\n\nIf the patch is invalid, for example the context lines don\u2019t match,\n``ValueError`` will be raised, with a message that includes all the output from\nthe ``patch`` utility.\n\nNote that ``patch_text`` will be ``textwrap.dedent()``\u2019ed, but leading\nwhitespace will not be removed. Therefore the correct way to include the patch\nis with a triple-quoted string with a backslash - ``\"\"\"\\`` - which starts the\nstring and avoids including the first newline. A final newline is not required\nand will be automatically added if not present.\n\nExample:\n\n.. code-block:: python\n\n import patchy\n\n\n def sample():\n return 1\n\n\n patchy.patch(\n sample,\n \"\"\"\\\n @@ -2,2 +2,2 @@\n - return 1\n + return 2\"\"\",\n )\n\n print(sample()) # prints 2\n\n\n``mc_patchface(func, patch_text)``\n----------------------------------\n\nAn alias for ``patch``, so you can meme it up by calling\n``patchy.mc_patchface()``.\n\n\n``unpatch(func, patch_text)``\n-----------------------------\n\nUnapply the patch ``patch_text`` from the source of function ``func``. This is\nthe reverse of ``patch()``\\ing it, and calls ``patch --reverse``.\n\nThe same error and formatting rules apply as in ``patch()``.\n\nExample:\n\n.. code-block:: python\n\n import patchy\n\n\n def sample():\n return 2\n\n\n patchy.unpatch(\n sample,\n \"\"\"\\\n @@ -2,2 +2,2 @@\n - return 1\n + return 2\"\"\",\n )\n\n print(sample()) # prints 1\n\n\n``temp_patch(func, patch_text)``\n--------------------------------\n\nTakes the same arguments as ``patch``. Usable as a context manager or function\ndecorator to wrap code with a call to ``patch`` before and ``unpatch`` after.\n\nContext manager example:\n\n.. code-block:: python\n\n def sample():\n return 1234\n\n\n patch_text = \"\"\"\\\n @@ -1,2 +1,2 @@\n def sample():\n - return 1234\n + return 5678\n \"\"\"\n\n with patchy.temp_patch(sample, patch_text):\n print(sample()) # prints 5678\n\nDecorator example, using the same ``sample`` and ``patch_text``:\n\n.. code-block:: python\n\n @patchy.temp_patch(sample, patch_text)\n def my_func():\n return sample() == 5678\n\n\n print(my_func()) # prints True\n\n\n``replace(func, expected_source, new_source)``\n----------------------------------------------\n\nCheck that function or dotted path to function ``func`` has an AST matching\n``expected_source``, then replace its inner code object with source compiled\nfrom ``new_source``. If the AST check fails, ``ValueError`` will be raised with\ncurrent/expected source code in the message. In the author's opinion it's\npreferable to call ``patch()`` so your call makes it clear to see what is being\nchanged about ``func``, but using ``replace()`` is simpler as you don't have to\nmake a patch and there is no subprocess call to the ``patch`` utility.\n\nNote both ``expected_source`` and ``new_source`` will be\n``textwrap.dedent()``\u2019ed, so the best way to include their source is with a\ntriple quoted string with a backslash escape on the first line, as per the\nexample below.\n\nIf you want, you can pass ``expected_source=None`` to avoid the guard against\nyour target changing, but this is highly unrecommended as it means if the\noriginal function changes, the call to ``replace()`` will continue to silently\nsucceed.\n\nExample:\n\n.. code-block:: python\n\n import patchy\n\n\n def sample():\n return 1\n\n\n patchy.replace(\n sample,\n \"\"\"\\\n def sample():\n return 1\n \"\"\",\n \"\"\"\\\n def sample():\n return 42\n \"\"\",\n )\n\n print(sample()) # prints 42\n\n\nHow to Create a Patch\n=====================\n\n1. Save the source of the function of interest (and nothing else) in a ``.py``\n file, e.g. ``before.py``:\n\n .. code-block:: python\n\n def foo():\n print(\"Change me\")\n\n Make sure you dedent it so there is no whitespace before the ``def``, i.e.\n ``d`` is the first character in the file. For example if you wanted to patch\n the ``bar()`` method below:\n\n .. code-block:: python\n\n class Foo:\n def bar(self, x):\n return x * 2\n\n ...you would put just the method in a file like so:\n\n .. code-block:: python\n\n def bar(self, x):\n return x * 2\n\n However we'll continue with the first example ``before.py`` since it's\n simpler.\n\n2. Copy that ``.py`` file, to e.g. ``after.py``, and make the changes you\n want, such as:\n\n .. code-block:: python\n\n def foo():\n print(\"Changed\")\n\n3. Run ``diff``, e.g. ``diff -u before.py after.py``. You will get output like:\n\n .. code-block:: diff\n\n diff --git a/Users/chainz/tmp/before.py b/Users/chainz/tmp/after.py\n index e6b32c6..31fe8d9 100644\n --- a/Users/chainz/tmp/before.py\n +++ b/Users/chainz/tmp/after.py\n @@ -1,2 +1,2 @@\n def foo():\n - print(\"Change me\")\n + print(\"Changed\")\n\n4. The filenames are not necessary for ``patchy`` to work. Take only from the\n first ``@@`` line onwards into the multiline string you pass to\n ``patchy.patch()``:\n\n .. code-block:: python\n\n patchy.patch(\n foo,\n \"\"\"\\\n @@ -1,2 +1,2 @@\n def foo():\n - print(\"Change me\")\n + print(\"Changed\")\n \"\"\",\n )\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Patch the inner source of python functions at runtime.",
"version": "2.7.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/patchy/blob/main/CHANGELOG.rst",
"Homepage": "https://github.com/adamchainz/patchy",
"Mastodon": "https://fosstodon.org/@adamchainz",
"Twitter": "https://twitter.com/adamchainz"
},
"split_keywords": [
"patchy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5e685f53220383b387b7aa6c1a2862a62a199304c205fed14257454d9d531545",
"md5": "89f47a71ccd345aad9a657c73a795b49",
"sha256": "f0e56290905dddb6d9bc88d6deca9450afc0e34eca03b18aec3caf6cf7c7f899"
},
"downloads": -1,
"filename": "patchy-2.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89f47a71ccd345aad9a657c73a795b49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9665,
"upload_time": "2023-06-16T15:01:52",
"upload_time_iso_8601": "2023-06-16T15:01:52.528864Z",
"url": "https://files.pythonhosted.org/packages/5e/68/5f53220383b387b7aa6c1a2862a62a199304c205fed14257454d9d531545/patchy-2.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d90cb0cf016d2ca860ec4fb1ad227577cd668d5686abacd203edee9135fac8c1",
"md5": "b48711b72fdf211de314a01c577d40b1",
"sha256": "2fe0aae56420ab72eaac446c5159c18218b7270c2e11fbe498a5bcc48357739b"
},
"downloads": -1,
"filename": "patchy-2.7.0.tar.gz",
"has_sig": false,
"md5_digest": "b48711b72fdf211de314a01c577d40b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 50153,
"upload_time": "2023-06-16T15:01:54",
"upload_time_iso_8601": "2023-06-16T15:01:54.495683Z",
"url": "https://files.pythonhosted.org/packages/d9/0c/b0cf016d2ca860ec4fb1ad227577cd668d5686abacd203edee9135fac8c1/patchy-2.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-16 15:01:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "patchy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "patchy"
}
JSON
