pusher-debug 1.0.0__py3-none-any.whl

pusher_debug/__init__.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+author = "Douglas Sojourner <doug@sojournings.org>"
+
+copyright = f"""
+debug-tools, a few tools to make debugging easier
+Copyright (C) 2026  {author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from .monkeypatching import *
+from .tracing import *
+from project_version_finder import get_version
+from packaging.version import Version
+
+_full_version_ = Version(get_version('pusher_debug'))
+
+__version__ = str(_full_version_)
+
+__doc__ = """
+Functions to facillitate debugging:
+
+Monkeypatching functions (add_to_class and add_new_class are decorators)
+add_to_class, backup_member, restore_member, backup_new_member, restore_new_member
+monkeypatch member functions and move between original and new versions
+
+add_new_class, backup_class, restore_class, backup_new_class, restore_new_class
+do the same for entire classes
+
+Tracing functions
+ObjWatch (from objwatch library) and DetailWrapper permit detailled monitoring
+of calls/returns from a class or set of classes
+
+fn_name, fn_entry, and fn_exit
+make easy documentation of function enter/exit with more focus that ObjWatch
+
+"""
+
+__all__ = [
+    # Class member function manipulation
+    'add_to_class', 'backup_member', 'restore_member',
+    'restore_new_member',
+    # Class manipulation
+    'add_new_class', 'backup_class', 'restore_class',
+    'restore_new_class',
+    # ObjWatch functions and classes:
+    'ObjWatch', 'DetailWrapper', 'labelest',
+    # Debug logging
+    'fn_name', 'fn_entry', 'fn_exit',
+]

pusher_debug/monkeypatching/__init__.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+author = "Douglas Sojourner <doug@sojournings.org>"
+
+copyright = f"""
+debug-tools, a few tools to make debugging easier
+Copyright (C) 2026  {author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from .monkeypatching import add_to_class, backup_member, restore_member, restore_new_member, add_new_class, backup_class, restore_class, restore_new_class, backup_new_member, backup_new_member
+
+
+__all__ = [
+    # Class member function manipulation
+    'add_to_class', 'backup_member', 'restore_member',
+    'restore_new_member',
+    # Class manipulation
+    'add_new_class', 'backup_class', 'restore_class',
+    'restore_new_class',
+]

pusher_debug/monkeypatching/monkeypatching.py

@@ -0,0 +1,418 @@
+#!/usr/bin/env python
+from inspect import currentframe, signature, isclass, isfunction, unwrap, getmodule
+import regex as re
+from typing import Callable, overload, Any, Literal, Final
+from types import FrameType, NoneType
+
+from ..util import qualname_context, fix_locals_qualname, find_in_dicts
+
+def add_to_class(cls:type) -> Any :
+    """
+    Decorator w/ 1 argument:
+    Takes a class (cls), and modifies the following function to
+    (1) have an appropriate __qualname__ to be in class cls, and
+    (2) add it as a member to cls
+
+    Works with @classmethod, @staticmethod and @property (and if you
+    add a property p, works with @p to add other access functions)
+    @add_to_class(MyClass)
+    @classmethod
+    def MyFn(cls, arg1, arg2):
+        # do stuff
+        return result
+
+    will add a new class method to MyClass:
+    MyClass.MyFn() which takes two (other) arguments.
+    """
+    assert(isclass(cls))
+    @overload
+    def decorator(_fn_: Callable[...,Any|None]) -> Callable[...,Any|None]: ...
+    @overload
+    def decorator(_fn_: property) -> property: ...
+    def decorator(_fn_: Callable[...,Any|None]|property) -> Callable[...,Any|None]|property:
+        """
+        internal decorator function to actually decorate _fn_
+        """
+        #
+        # Can probaby add properties since we now use setattr
+        #
+        # sanity checks
+        cleanup = True
+        frame = currentframe()
+        assert(isinstance(frame, FrameType) and isinstance(frame.f_back, FrameType))
+        local = frame.f_back.f_locals
+        cls_qualname = fix_locals_qualname(cls.__qualname__)
+        if isinstance(_fn_, property) :
+            cleanup = False
+            check_fns = [_fn_.fget, _fn_.fset, _fn_.fdel]
+            is_property = True
+            for f in check_fns :
+                if f :
+                    fn_name = fix_locals_qualname(f.__name__)
+                    break
+                pass
+            for f in check_fns :
+                if f :
+                    f.__qualname__ = f'{cls_qualname}.{fn_name}'
+                    f.__name__ = f'{fn_name}'
+                    pass
+                pass
+            if fn_name in cls.__dict__ : # are we changing or replacing or new
+                c_prop = cls.__dict__[fn_name]
+                same = True
+                for f_old, f in zip([c_prop.fget, c_prop.fset, c_prop.fdel], check_fns) :
+                    if f_old and f_old != f :
+                        same = False
+                        break
+                    pass
+                if same :
+                    save = False # adding an access function
+                else:
+                    save = True # different property in local
+                    pass
+            else :
+                save = False # nothing to save
+                pass
+        else :
+            check_fns = [_fn_]
+            fn_name = fix_locals_qualname(_fn_.__name__)
+            is_property = False
+            pass
+        if isinstance(_fn_, classmethod) :
+            for fn in check_fns : # type: ignore[unreachable]
+                if fn :
+                    _fn_unwrap_ = unwrap(fn)
+                    assert(list(signature(_fn_unwrap_).parameters.keys())[0] == 'cls')
+                    assert(isfunction(_fn_unwrap_))
+                    pass
+                pass
+            pass
+        elif isinstance(_fn_, staticmethod):
+            for fn in check_fns :
+                if fn :
+                    _fn_unwrap_ = unwrap(fn)
+                    assert(isfunction(_fn_unwrap_))
+                    cleanup = False
+                    pass
+                pass
+            pass
+        else :
+            for fn in check_fns :
+                if fn :
+                    assert(list(signature(fn).parameters.keys())[0] == 'self')
+                    pass
+                pass
+            pass
+        for fn in check_fns :
+            if fn :
+                fn.__qualname__ = f'{cls_qualname}.{fn_name}'
+                pass
+            pass
+        orig_name = "orig_"+fn_name
+        new_name = "new_"+fn_name
+        base_name = fn_name
+        if fn_name[0:4] == 'new_' :
+            base_name = fn_name[4:]
+            orig_name = 'orig_' + base_name
+            new_name = fn_name
+            pass
+        if (base_name in cls.__dict__
+            and (orig_name not in cls.__dict__
+                 or (is_property and save))):
+            setattr(cls, orig_name, cls.__dict__[base_name])
+            pass
+        setattr(cls, new_name, _fn_)
+        setattr(cls, base_name, _fn_)
+        if _fn_.__doc__ :
+            if not re.search('monkeypatched',_fn_.__doc__) :
+                _fn_.__doc__ += f'\nmonkeypatched into {cls.__name__}'
+                pass
+        elif (orig_name in cls.__dict__
+              and cls.__dict__[orig_name].__doc__) :
+            _fn_.__doc__ = cls.__dict__[orig_name].__doc__ + '\nmonkeypatched'
+        else :
+            _fn_.__doc__ = f'monkeypatched into {cls.__name__}'
+            pass
+        if orig_name in cls.__dict__ :
+            # No longer the same as fn, so fix names
+            if is_property:
+                cls.__dict__[orig_name].__set_name__(cls,orig_name)
+                pass
+            else:
+                cls.__dict__[orig_name].__qualname__ = f"{cls_qualname}.{orig_name}"
+                cls.__dict__[orig_name].__name__ = orig_name
+                pass
+            pass
+        if is_property :
+            # for property, add property w/ expected name to locals
+            local[fn_name] = _fn_
+            pass
+        return _fn_
+
+    return decorator
+
+# @overload
+# def mv_cls(cls:type, *, saving:bool=False, saving_new:bool=False, restoring:bool=False, restoring_new:bool=False, new_class:Literal[True | False]) -> Callable: ...
+# @overload
+# def mv_cls(cls:type, *, saving:bool=False, saving_new:bool=False, restoring:bool=False, restoring_new:bool=False, new_class:None) -> None: ...
+# @overload
+# def mv_cls(cls:type, *, saving:bool=False, saving_new:bool=False, restoring:bool=False, restoring_new:bool=False, new_class:type) -> type: ...
+def mv_cls(cls:type, *, saving:bool=False, saving_new:bool=False, restoring:bool=False, restoring_new:bool=False, new_class:type|None|bool = None) -> Any:
+    """
+    Function which does the work of class monkey patching
+    We have (at most) two versions of classes: new and orig
+    The base function will be one of these, but we adjust the cls.__name__
+    as appropriate
+   """
+    if (int(saving) + int(saving_new) + int(restoring) + int(restoring_new) + bool(new_class)) != 1 :
+        raise ValueError("You must set exactly 1 of saving, saving_new, restoring, "
+                         "restoring_new, new_class to True (or a class in the last case)")
+    if (not isinstance(new_class, NoneType)
+        and not isinstance(new_class, bool)
+        and not isclass(new_class)) :
+        raise ValueError("new_class needs to be a class")
+    
+    assert(isclass(cls))
+    cls_name = cls.__name__
+    if cls_name[0:4] == 'new_' :
+        base_name = cls_name[4:]
+        new_name = cls_name
+        orig_name = 'orig_' + base_name
+    elif cls_name[0:5] == 'orig_' :
+        base_name = cls_name[5:]
+        new_name = 'new_' + base_name
+        orig_name = cls_name
+    else:
+        base_name = cls_name
+        new_name = 'new_' + base_name
+        orig_name = 'orig_' + base_name
+        pass
+    module = getmodule(cls)
+    qualpart = '.'.join(cls.__qualname__.split('.')[:-1])
+    d = module.__dict__
+    if saving and orig_name not in d :
+        d[orig_name] = cls
+        if new_name in d :
+            d[new_name].__name__ = new_name
+            d[new_name].__qualname__ = qualpart + '.' + new_name
+            pass
+        return None
+    elif saving_new and new_name not in d :
+        d[new_name] = cls
+        if orig_name in d :
+            d[orig_name].__name__ = orig_name
+            d[orig_name].__qualname__ = qualpart + '.' + orig_name
+            pass
+        return None
+    elif restoring and orig_name in d :
+        d[base_name] = d[orig_name]
+        d[base_name].__name__ = base_name
+        d[base_name].__qualname__ = qualpart + '.' + base_name
+        if new_name in d :
+            d[new_name].__name__ = new_name
+            d[new_name].__qualname__ = qualpart + '.' + new_name
+            pass
+        return None
+    elif restoring and new_name in d :
+        d[base_name] = d[new_name]
+        d[base_name].__name__ = base_name
+        d[base_name].__qualname__ = qualpart + '.' + base_name
+        if orig_name in d :
+            d[orig_name].__name__ = orig_name
+            d[orig_name].__qualname__ = qualpart + '.' + orig_name
+            pass
+        return None
+    elif new_class :
+        def decorator(new_cls:type) -> type :
+            if new_cls.__doc__ :
+                new_cls.__doc__ += f'\nmonkeypatched into {module}'
+            elif base_name in d and d[base_name].__doc__:
+                new_cls.__doc__ = d[base_name].__doc__ + f'\nmonkeypatched into {module}'
+            elif orig_name in d and d[orig_name].__doc__:
+                new_cls.__doc__ = d[orig_name].__doc__ + f'\nmonkeypatched into {module}'
+            else:
+                new_cls.__doc__ = f'monkeypatched into {module}'
+                pass
+            if base_name in d :
+                mv_cls(d[base_name], saving=True)
+                pass
+            #b_name = name
+            d[orig_name] = d[base_name]
+            d[orig_name].__name__ = orig_name
+            d[orig_name].__qualname__ = qualpart + '.' + orig_name
+            d[new_name] = new_cls
+            d[new_name].__name__ = base_name
+            d[new_name].__qualname__ = qualpart + '.' + base_name
+            d[base_name] = d[new_name]
+            return new_cls
+        if isinstance(new_class, bool) and new_class :
+            return decorator
+        else :
+            return decorator(new_class)
+    else :
+        pass # exactly 1 previous case known to be true
+    pass # This branch has returned by now
+
+def backup_class(cls:type) -> None :
+    """
+    cls should be class
+    this will make orig_class = class
+    (checks first if orig_class already exists)
+    """
+    mv_cls(cls, saving=True)
+    return
+
+def backup_new_class(cls:type) -> None :
+    """
+    cls should be class
+    this will make new_class = class
+    (checks first if new_class already exists)
+    """
+    mv_cls(cls, saving_new=True)
+    return
+
+def restore_class(cls:type) -> None :
+    """
+    cls should be class
+    Checks first if orig_class exists, and if so
+    this will make class = orig_class
+    """
+    mv_cls(cls, restoring=True)
+    return
+
+def restore_new_class(cls:type) -> None :
+    """
+    cls should be class
+    Checks first if new_class exists, and if so
+    this will make class = new_class
+    """
+    mv_cls(cls, restoring_new=True)
+    return
+
+def add_new_class(cls:type, new_cls:type|None=None) -> type|Callable :
+    """
+    as a function:
+    cls should be class, as should new_cls
+    this will make new_class = new_cls (backing up class
+    first as orig_class if it already exists), and then
+    copy new_class to class.
+
+    With only one argument, it can be a decorator for
+    a class delcaration
+    """
+    if not new_cls :
+        return mv_cls(cls, new_class=True)
+    else :
+        return mv_cls(cls, new_class=new_cls)
+
+def fix_names_mv_fn(fn:Callable|property, *, saving:bool=False, saving_new:bool=False, restoring:bool=False, restoring_new:bool=False) -> None:
+    """
+    Function which does the work of the member function monkeypatching
+    We have (at most) two versions of functions: new and orig
+    The base function will be one of these, but we adjust the fn.__name__
+    to be correct. E.g.
+    if we have original
+    C.__init__ == C.orig___init__
+    and C.__init__.__name__ == '__init__'
+    and C.new___init__.__name__ == 'new___init__'
+    OR
+    C.__init__ == C.new___init__
+    and C.__init__.__name__ == '__init__'
+    and C.orig___init__.__name__ == 'orig___init__'
+    """
+    if (int(saving) + int(saving_new) + int(restoring) + int(restoring_new)) != 1 :
+        raise ValueError("You must set exactly 1 of saving, saving_new, restoring, "
+                         "restoring_new to True")
+    if isinstance(fn, property) :
+        for f in [fn.fget, fn.fset, fn.fdel]:
+            if f :
+                base_name = f.__name__
+                fn_qname = f.__qualname__
+                break
+            pass
+        pass
+    else :
+        base_name = fn.__name__
+        fn_qname = fn.__qualname__
+        pass
+    orig_name = 'orig_' + base_name
+    new_name = 'new_' + base_name
+    split_name = fn_qname.split('.')
+    cls_qname = '.'.join(split_name[:-1])
+    # find out where cls may be defined
+    _, [g, l], [lg, ll], d1, d2, frm = qualname_context(fn_qname)
+    # prefer local, just up stack frame, and lastly global
+    cls = find_in_dicts(split_name[-2], [ll, l, d2, d1, lg, g])
+    # cls.__qualname__ differs from cls_qname in that the first
+    # may have blah.blah.<locals>. prepended
+    if saving : # base -> orig
+        if not orig_name in cls.__dict__ :
+            setattr(cls, orig_name, fn)
+            # don't change names in fn, as it is still base fn
+        else:
+            pass # nothing to do
+    elif saving_new : # base -> orig
+        if not new_name in cls.__dict__ :
+            setattr(cls, new_name, fn)
+            # don't change names in fn, as it is still base fn
+        else:
+            pass # nothing to do
+    elif restoring and orig_name in cls.__dict__ : # orig -> base
+        if (new_name in cls.__dict__
+            and cls.__dict__[base_name] == cls.__dict__[new_name]) :
+            # Do change names of new, since we replace
+            new_fn = cls.__dict__[new_name]
+            new_fn.__name__ = new_name
+            new_fn.__qualname__ = f"{cls_qname}.{new_name}"
+            pass
+        setattr(cls, base_name, cls.__dict__[orig_name])
+        base_fn = cls.__dict__[base_name]
+        base_fn.__name__ = base_name
+        base_fn.__qualname__ = f"{cls_qname}.{base_name}"
+    elif restoring_new and new_name in cls.__dict__ : # new -> base
+        if (orig_name in cls.__dict__
+            and cls.__dict__[base_name] == cls.__dict__[orig_name]) :
+            # Do change names of orig, since we replace
+            orig_fn = cls.__dict__[orig_name]
+            orig_fn.__name__ = orig_name
+            orig_fn.__qualname__ = f"{cls_qname}.{orig_name}"
+            pass
+        setattr(cls, base_name, cls.__dict__[new_name])
+        base_fn = cls.__dict__[base_name]
+        base_fn.__name__ = base_name
+        base_fn.__qualname__ = f"{cls_qname}.{base_name}"
+    else:
+        pass # all cases enumerated above or we raised ValueError
+    return
+
+def backup_member(member:Any) -> None :
+    """
+    member should be Class.Function
+    this will make Class.orig_Function = Class.Function
+    (checks first if orig_Function already exists)
+    """
+    return fix_names_mv_fn(member, saving=True)
+
+def backup_new_member(member:Any) -> None :
+    """
+    member should be Class.Function
+    this will make Class.new_Function = Class.Function
+    (checks first if new_Function already exists)
+    """
+    return fix_names_mv_fn(member, saving_new=True)
+
+def restore_member(member:Any) -> None :
+    """
+    member should be Class.Function
+    Checks first if orig_Function exists, and if so
+    this will make Class.Function = Class.orig_Function
+    """
+    return fix_names_mv_fn(member, restoring=True)
+
+def restore_new_member(member:Any) -> None :
+    """
+    member should be Class.Function
+    Checks first if new_Function exists, and if so
+    this will make Class.Function = Class.new_Function
+    """
+    return fix_names_mv_fn(member, restoring_new=True)

pusher_debug/tracing/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+author = "Douglas Sojourner <doug@sojournings.org>"
+
+copyright = f"""
+debug-tools, a few tools to make debugging easier
+Copyright (C) 2026  {author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+from objwatch import ObjWatch
+from .tracing import DetailWrapper, labelest, fn_name, fn_entry, fn_exit
+
+__all__ = [
+    # ObjWatch functions and classes:
+    'ObjWatch', 'DetailWrapper', 'labelest',
+    # Debug logging
+    'fn_name', 'fn_entry', 'fn_exit',
+]