Support for applying monkey patches late in the startup cycle by using ZCML configuration actions
Project description
Introduction
Sometimes, a monkey patch is a necessary evil.
This package makes it easier to apply a monkey patch during Zope startup. It uses the ZCML configuration machinery to ensure that patches are loaded “late” in the startup cycle, so that the original code has had time to be fully initialised and configured. This is similar to using the initialize() method in a product’s __init__.py, except it does not require that the package be a full-blown Zope product with a persistent Control_Panel entry.
Installation
To install collective.monkeypatcher into the global Python environment (or a working environment), using a traditional Zope instance, you can do this:
When you’re reading this you have probably already run pip install collective.monkeypatcher.
Create a file called collective.monkeypatcher-configure.zcml in the /path/to/instance/etc/package-includes directory. The file should only contain this:
<include package="collective.monkeypatcher" />
Alternatively, if you are using zc.buildout and the plone.recipe.zope2instance recipe to manage your project, you can do this:
Add collective.monkeypatcher to the list of eggs to install, e.g.:
[buildout] ... eggs = ... collective.monkeypatcher
Tell the plone.recipe.zope2instance recipe to install a ZCML slug:
[instance] recipe = plone.recipe.zope2instance ... zcml = collective.monkeypatcher
Re-run buildout, e.g. with:
$ ./bin/buildout
You can skip the ZCML slug if you are going to explicitly include the package from another package’s configure.zcml file.
Applying a monkey patch
Here’s an example:
<configure xmlns="http://namespaces.zope.org/zope" xmlns:monkey="http://namespaces.plone.org/monkey" i18n_domain="collective.monkeypatcher"> <include package="collective.monkeypatcher" /> <monkey:patch description="This works around issue http://some.tracker.tld/ticket/123" class="Products.CMFPlone.CatalogTool.CatalogTool" original="searchResults" replacement=".catalog.patchedSearchResults" /> </configure>
In this example, we patch Plone’s CatalogTool’s searchResults() function, replacing it with our own version in catalog.py. To patch a module level function, you can use module instead of class. The original class and function/method name and the replacement symbol will be checked to ensure that they actually exist.
If patching happens too soon (or too late), use the order attribute to specify a higher (later) or lower (earlier) number. The default is 1000.
By default, DocFinderTab and other TTW API browsers will emphasize the monkey patched methods/functions, appending the docstring with “Monkey patched with ‘my.monkeypatched.function’”. If you don’t want this, you could set the docstringWarning attribute to false.
If you want to do more than just replace one function with another, you can provide your own patcher function via the handler attribute. This should be a callable like:
def apply_patch(scope, original, replacement): ...
Here, scope is the class/module that was specified. original is the string name of the function to replace, and replacement is the replacement function.
Full list of options:
class The class being patched
module The module being patched (see Patching module level functions)
handler A function to perform the patching. Must take three parameters: class/module, original (string), and replacement
original Method or function to replace
replacement Method or function to replace with
preservedoc Preserve docstrings?
preserveOriginal Preserve the original function so that it is reachable view prefix _old_. Only works for default handler
preconditions Preconditions (multiple, separated by space) to be satisified before applying this patch. Example: Products.LinguaPlone-=1.4.3 or Products.TextIndexNG3+=3.3.0
ignoreOriginal Ignore if the orginal function isn’t present on the class/module being patched
docstringWarning Add monkey patch warning in docstring
description Some comments about your monkey patch
order Execution order
Handling monkey patches events
Applying a monkey patch fires an event. See the interfaces.py module. If you to handle such event add this ZCML bunch:
... <subscriber for="collective.monkeypatcher.interfaces.IMonkeyPatchEvent" handler="my.component.events.myHandler" /> ...
And add such Python:
def myHandler(event): """see collective.monkeypatcher.interfaces.IMonkeyPatchEvent""" ...
Patching module level functions
If you want to patch the method do_something located in patched.package.utils which is imported in a package like this
from patched.package.utils import do_something
the reference to this function is loaded before collective.monkeypatcher will patch the original method.
See also this related thread on the plone mailing list.
Workaround
Do the patching in __init__.py of your package:
from patched.package import utils def do_it_different(): return 'foo' utils.do_something = do_it_different
Changelog
1.2.1 (2020-03-21)
Bug fixes:
Minor packaging updates. [various] (#1)
1.2 (2018-12-10)
New features:
Include installation instructions in the README.
Update test infrastructure.
1.1.6 (2018-10-31)
Bug fixes:
Prepare for Python 2 / 3 compatibility [frapell]
1.1.5 (2018-06-18)
Bug fixes:
Fix import for Python 3 in the tests module [ale-rt]
1.1.4 (2018-04-08)
Bug fixes:
Fix import for Python 3 [pbauer]
1.1.3 (2017-11-26)
New features:
Document possible problems when patching module level functions [frisi]
1.1.2 (2016-08-10)
Fixes:
Use zope.interface decorator. [gforcada]
1.1.1 (2015-03-27)
Fix typo. [gforcada]
1.1 - 2014-12-10
Fix the case where the replacement object does not have a __module__ attribute (see https://github.com/plone/collective.monkeypatcher/pull/3). [mitchellrj, fRiSi]
1.0.1 - 2011-01-25
Downgrade standard log message to debug level. [hannosch]
1.0 - 2010-07-01
Avoid a zope.app dependency. [hannosch]
Added new parameter preconditions that only patches if preconditions are met like version of a specific package. [spamsch]
Added new parameter preserveOriginal. Setting this to true makes it possible to access the patched method via _old_``name of patched method`` [spamsch]
1.0b2 - 2009-06-18
Add the possibility to ignore the error if the original function isn’t present on the class/module being patched [jfroche]
Check if the docstring exists before changing it [jfroche]
Add buildout.cfg for test & test coverage [jfroche]
1.0b1 - 2009-04-17
Fires an event when a monkey patch is applied. See interfaces.py. [glenfant]
Added ZCML attributes “docstringWarning” and “description”. [glenfant]
Added unit tests. [glenfant]
1.0a1 - 2009-03-29
Initial release [optilude]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for collective.monkeypatcher-1.2.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 781c61355053caed80d32b29669263fe8aa366e3495742749ec475fcadc339c6 |
|
MD5 | 1215821f37ab751bf6ad507fc033de44 |
|
BLAKE2b-256 | bb7c11e15752c37fa662c0ecb4a74a57b10c4b4c990822aa630fe1ffaa1a5214 |
Hashes for collective.monkeypatcher-1.2.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9eb837866a45984b068aeb93398907e8d5f3b24c2be1b35ba86eff1078767e86 |
|
MD5 | 4eea5873a01950f3682a3fe582642737 |
|
BLAKE2b-256 | de29c9135ad4429b828da4443d6c890c6455480e0d1361d43bfab16658c78cd9 |