Metadata-Version: 1.1
Name: collective.monkeypatcher
Version: 1.1.2
Summary: Support for applying monkey patches late in the startup cycle by using ZCML configuration actions
Home-page: https://pypi.python.org/pypi/collective.monkeypatcher
Author: Martin Aspeli
Author-email: optilude@gmail.com
License: BSD
Description: ========================
        collective.monkeypatcher
        ========================
        
        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 2 product with a persistent Control_Panel entry.
        
        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 <http://pypi.python.org/pypi/Products.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
        - ``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"""
              ...
        
        
        Changelog
        =========
        
        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]
        
Keywords: zope monkey patch
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7