Guidelines for writing fixers

compat_patcher_core.PatchingRegistry.

  • Follow PEP8 as much as you can, or use Black to solve the problem once and for all.

  • Fixers have to be registered with the register_compatibility_fixer() method of a patching registry. Hint: you can be DRY by using functools.partial() to preconfigure a set of similar fixers.

  • Fixers must have a docstring explaining what they do (what breaking changes they deal with), and tests checking that both old and new behaviour keep working. These tests must have a name matching the form “test_<fixer-name>()” to be recognized.

  • Fixers should have a signature following the convention fix_<kind>_<path>_<element>(utils), where:

    • <kind> is one of the following:

      • “deletion” (when an element was removed from sources and must be put back)

      • “behavior” (when a signature changed, when an optional arguments became mandatory…)

      • “outsourcing” (when a whole submodule was turned into an external python package)

    • <path> is the trail of submodules leading to the patched element (with dots replaced by underscores), not including the root module of the library

    • <element> is the element to be patched ; for clarity you should use the same character casing as the real element name

    • utils is the injected parameter, which exposes patching utilities

  • Fixers should be coded quite defensively, since they are highly expected to repair breakages, not introduce new ones.

  • Fixers should follow these rules of good behaviour:

    • Use monkey-patching utilities from the injected utils object, not direct assignments

    • Not do logging or warnings by themselves either, but use the injected utils object once again (or a dedicated WarningsProxy instance)

    • Not do global imports of software submodules or external libraries, but import them locally inside the fixer function

  • Fixers should not reintroduce code which raises security issues (like XSS attacks…), unless these fixers are OFF by default, deeply documented, and risks can be properly mitigated by project maintainers.

  • Fixers should not be created to modify project-level code, like framework settings, since these are supposed to be easily updatable by project maintainers.