pusher-debug 1.0.0__py3-none-any.whl

pusher_debug/tracing/tracing.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python
+from pprint import pformat as pretty
+from inspect import currentframe, signature, formatargvalues, getargvalues, Signature
+from objwatch.wrappers.base_wrapper import BaseWrapper
+from io import TextIOBase
+from typing import Any
+from types import NoneType, FrameType
+
+from ..util import fix_locals_qualname
+from ..monkeypatching import add_to_class
+
+# Prevent fn_name from infinite recursion (for example if
+# put in __init__, which wants to say what self is (which
+# triggers an __init__ ...). That particular route is blocked
+# in the actual code, but I'm betting I missed another way
+# this problem arises
+_fn_name_recursion_block_:int = 0
+_fn_name_recursion_fn_:str = ""
+def fn_name(frame: FrameType | None = None, caller:bool|str = False) -> str :
+    """
+    Returns a string listing the function signature and arguements
+    for the calling function (or if frame is provided, for the function
+    that frame represents). caller, if provided, should be True (to
+    provide info on the caller of the calling function) or 'both'
+    (to provide info on calling function AND the function that called it)
+    """
+    global _fn_name_recursion_block_
+    global _fn_name_recursion_fn_
+    if not frame :
+        frame = currentframe()
+        assert(isinstance(frame, FrameType))
+        frame = frame.f_back # frame of caller of fn_name
+        pass
+    if not isinstance(frame, FrameType) :
+        return ''
+    caller_frame = frame.f_back
+    assert(isinstance(caller_frame, FrameType))
+    if _fn_name_recursion_block_ :
+        from_name = caller_frame.f_code.co_qualname
+        return f'recursion {_fn_name_recursion_block_} called from {from_name} originally {_fn_name_recursion_fn_}'
+    else :
+        _fn_name_recursion_block_ += 1
+        _fn_name_recursion_fn_ = caller_frame.f_code.co_qualname
+        pass
+    if caller :
+        if type(caller) == str and caller == "both" :
+            do_caller = True
+            call = "Fn: "
+        else:
+            do_caller = False
+            frame = frame.f_back
+            assert(isinstance(frame, FrameType))
+            call = "Caller: "
+            pass
+    else:
+        do_caller = False
+        call = "Fn: "
+        pass
+    args, varargs, keywords, locals = getargvalues(frame)
+    arg_str = formatargvalues(args, varargs,keywords, locals)
+    fn_qname = fix_locals_qualname(frame.f_code.co_qualname)
+    result = f"{call}{fn_qname}{arg_str}"
+    _fn_name_recursion_block_ -= 1
+    _fn_name_recursion_fn_ = ''
+    if do_caller :
+        result += f"\nCaller: {fn_name(caller_frame)[4:]}" #trim "Fn: "
+    return result
+
+def labelest(label:str) -> None :
+    """
+    Function to watch with ObjWatch, which just notes
+    what is going on in the log
+    """
+    return
+
+class DetailWrapper(BaseWrapper) :
+    """
+    ObjWatch 'wrapper' which logs all inputs and output.
+
+    Can be subclassed as
+    class CustWrapper(DetailWrapper, special_classes = [C1, C2, C3])
+        pass
+
+    in which case C1, C2, and C3 have an _id_ property added which is
+    read only and unique for each instance of the same class. This _id_
+    is used in the wrap_return to note which instance is returning the value
+    in question.
+    """
+    special_classes:list[type] = []
+
+    def __init_subclass__(cls2, *, special_classes:list[type], **kwargs) :
+        cls2.special_classes = special_classes
+        for c in special_classes :
+            c._i_count_ = 0 # type: ignore[attr-defined]
+            @add_to_class(c) # type: ignore[misc]
+            @classmethod
+            def _inst_count_(cls) -> int : 
+                cls._i_count_ += 1
+                return cls._i_count_
+            @add_to_class(c) # type: ignore[misc]
+            @property
+            def _id_(self) -> str :
+                if '_inst_id_' not in self.__dict__ :
+                    self._inst_id_ = self.__class__._inst_count_()
+                    pass
+                return f'{self._inst_id_:05d}'
+            pass
+        super().__init_subclass__(**kwargs)
+        return
+
+    def inst_id(self, slf:Any) -> str :
+        """
+        Find unique instance identifier for class we are monitoring
+        """
+        DW = self.__class__ # class of wrapper
+        if slf == None :
+            return ""
+        cls = slf.__class__ # class if instance we are logging
+        if cls in DW.special_classes :
+            return slf._id_ # we've made certain this property exists
+        return ""
+
+    def wrap_call(self, func_name:str, frame: FrameType) -> str:
+        if 'saved_frame' not in self.__dict__ :
+            self.saved_frame:list[FrameType] = []
+            pass
+        self.saved_frame.append(frame)
+        g = frame.f_globals
+        l = frame.f_locals
+        code = frame.f_code
+        qname = code.co_qualname # equals func_name I think ...
+        simple_report = False
+        if frame.f_back :
+            caller = f" called from {frame.f_back.f_code.co_qualname}"
+        else :
+            caller = ""
+            pass
+        if 'self' in l:
+            slf = l['self']
+            fn = getattr(slf, code.co_name)
+        elif code.co_qualname in g:
+            slf = None
+            fn = g[code.co_qualname]
+        else:
+            slf = None
+            simple_report = True
+            pass
+        if simple_report :
+            return f"Function {func_name}{caller}: Locals: {str(l)}"
+        sig = signature(fn)
+        args_str = ""
+        return_str = sig.return_annotation
+        if return_str == Signature.empty :
+            return_str = ":"
+        else:
+            return_str = f"-> {str(return_str)} :"
+            pass
+        for p,v in sig.parameters.items() :
+            if '=' in str(v) :
+                sv = str(v)[0:str(v).index('=')]
+            else :
+                sv = str(v)
+                pass
+            try :
+                s = f"{sv}={l[p].__repr__()}"
+            except :
+                s = f"{sv}={l[p]}"
+                pass
+            if not args_str :
+                args_str = s
+            else :
+                args_str += ", " + s
+                pass
+            pass
+        result = f"{func_name} ({args_str}) {return_str} ({caller})"
+        return result
+
+    def wrap_return(self, func_name:str, result: Any) -> str:
+        frame = self.saved_frame.pop()
+        l = frame.f_locals
+        if 'self' in l:
+            slf = l['self']
+            cls = slf.__class__.__qualname__ + ':'
+            inst_id = self.inst_id(slf)
+            if inst_id :
+                return_str = f"{cls}{func_name} -> {result.__repr__()}  <{inst_id}>"
+            else :
+                return_str = f"{cls}{func_name} -> {result.__repr__()}"
+                pass
+        else :
+            return_str = f"{func_name} -> {result.__repr__()}"
+            pass
+        return return_str
+        
+
+    def wrap_upd(self, old_value: Any, new_value: Any) -> tuple[str,str]:
+        return_strs = (f"{old_value.__repr__()}", f"{new_value.__repr__()}",)
+        return return_strs
+    
+
+def fn_entry(frame: FrameType | None = None, callers:int=0, file:TextIOBase|None = None) -> None:
+    '''
+    Prints entry info, including caller info if key word callers is set to the
+    number of callers to report. If key word file is not set, prints to stdout,
+    otherwise to the specified file.
+    '''
+    if not isinstance(frame, FrameType) :
+        frame = currentframe()
+        if isinstance(frame, FrameType) :
+            frame = frame.f_back
+            pass
+        pass
+    print(fn_name(frame), file=file)
+    for _ in range(callers) :
+        if isinstance(frame, FrameType) :
+            frame = frame.f_back
+            print(f'Called by{fn_name(frame)[2:]}', file=file)
+            pass
+        pass
+    return
+        
+def fn_exit(frame: FrameType | None = None, **kwargs) -> None :
+    '''
+    Prints exit info, including return value if key word result is defined. If key
+    word file is not set, prints to stdout, otherwise to the specified file.
+    '''
+    if not isinstance(frame, FrameType) :
+        frame = currentframe()
+        if isinstance(frame, FrameType) :
+            frame = frame.f_back
+            pass
+        pass
+    if 'file' in kwargs :
+        file = kwargs['file']
+    else:
+        file = None
+        pass
+    if 'result' in kwargs :
+        result = str(kwargs['result'])
+        print(f'{fn_name(frame)} -> {result}')
+    else:
+        print(f'{fn_name(frame)}')
+        pass
+    return

pusher_debug/util/__init__.py

@@ -0,0 +1,23 @@
+#!/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 .util import grab_all_namespaces, qualname_context, fix_locals_qualname, find_in_dicts
+
+__all__ = ['grab_all_namespaces', 'qualname_context', 'fix_locals_qualname']

pusher_debug/util/util.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python
+
+from inspect import currentframe, isclass
+from typing import Any, Callable, overload, Literal
+from types import FrameType, FunctionType, NoneType
+
+_local_mark = "<locals>"
+_local_mark2 = f".{_local_mark}."
+
+def find_in_dicts(name:str, dicts:list|dict|None) -> Any :
+    """
+    searches a list of dictionaries for name, or returns None
+    (Note that a successfull lookup can also return None)
+    """
+    if isinstance(dicts, dict) :
+        ds = [dicts,]
+    elif isinstance(dicts, list):
+        ds = []
+        for item in dicts :
+            if isinstance(item, list):
+                for i2 in item :
+                    assert(type(i2) == dict)
+                    ds.append(i2)
+                    pass
+                pass
+            elif isinstance(item, NoneType) :
+                pass
+            else :
+                if type(item) != dict :
+                    print(f"Expecting dict, got {type(item)} = {str(item)}")
+                    continue
+                assert(type(item) == dict)
+                ds.append(item)
+                pass
+            pass # end each item
+        pass # end flattening dicts if needed
+    for d in ds :
+        if d and name in d : # skip None's
+            return d[name]
+        pass
+    return None
+
+def return_empty_list() -> list :
+    """
+    function to replace __dir__ when it isn't found
+    """
+    return []
+
+@overload
+def grab_all_namespaces(o: object, split:Literal[True]) -> list[dict[str,Any]]: ...
+@overload
+def grab_all_namespaces(o: object, split:Literal[False]) -> dict[str,Any]: ...
+@overload
+def grab_all_namespaces(o: object) -> dict[str,Any]: ...
+
+def grab_all_namespaces(o: object, split=False) -> dict[str,Any] | list[dict[str,Any]]:
+    '''
+    find Any namespaces associated with o, and collect them
+    together. Should even survive cases where __dir__() and/or
+    __dict__ don't exist
+    '''
+    d = getattr(o, '__dict__', None)
+    if not d :
+        d = dict()
+    else:
+        d = dict(d) # incase it was something standing in for a dictionary
+        pass
+    l = d
+    g = dict()
+    try :
+        dirs = getattr(o,'__dir__', return_empty_list)()
+    except TypeError:
+        if isclass(o) :
+            try :
+                o = o() # only works if __init__ has no arguments, or defauts for all
+                dirs = getattr(o,'__dir__', return_empty_list)()
+            except TypeError:
+                dirs = []
+                pass
+            pass
+        else:
+            dirs = []
+            pass
+        pass
+    if not dirs :
+        pass
+    if 'globals' in d :
+        g.update(d['globals'])
+        pass
+    if '__globals__' in d :
+        g.update(d['__globals__'])
+        pass
+    if 'globals' in dirs :
+        g.update(getattr(o,'globals'))
+        pass
+    if '__globals__' in dirs :
+        g.update(getattr(o,'__globals__'))
+        pass
+    if 'locals' in dirs :
+        l.update(getattr(o,'locals'))
+        pass
+    if '__locals__' in dirs :
+        l.update(getattr(o,'__locals__'))
+        pass
+    if 'locals' in d :
+        l.update(d['locals'])
+        pass
+    if '__locals__' in d :
+        l.update(d['__locals__'])
+        pass
+    if split :
+        return [dict(g), dict(l)]
+    else :
+        d2 = dict(g)
+        d2.update(l)
+        return d2
+    pass # type: ignore[unreachable]
+
+# We want to get global/local address spaces for function
+# Handling these variations on qualname
+#
+# A) N2.N3.fn   vs
+# B) N0.N1.<locals>.N2.N3.fn <Figure out N2, then it is reduced to (A)
+#
+# 
+# 1) fn : Go back in stack until fn is in global or local
+# 2) N1.fn : Go Back until N1 is in global or local
+# 3) N1.N2.fn           same
+# To get actual function go forward using Ni.__dict__, until
+# you finally find a dictionary you can look fn up in.
+
+def qualname_context(item:str|Callable) -> tuple[str,list[dict[str,Any]],list[dict[str,Any]],dict[str,Any],dict[str,Any],FrameType|None] :
+    """
+    Given a string with the qualname, or a function (from which we get the
+    qualname) find:
+    1) "qualname after <locals>"
+    2) pair of global and local dictionaries where fn or containing package/class
+       are defined
+    3) __dict__ of package/class where fn is defined
+    4) frame where (non "<locals>") part of qualname was first found
+    """
+    if isinstance(item, str) :
+        name = item
+    else:
+        name = item.__qualname__
+        pass
+    split_name = name.split('.')
+    if _local_mark in split_name :
+        local_index = split_name.index(_local_mark)
+    else:
+        local_index = len(split_name) + 1
+        pass
+    top_name = split_name[0]
+    bottom_name = split_name[-1]
+    frame = currentframe()
+    found_index = -1
+    while (isinstance(frame, FrameType)
+           and frame.f_back
+           and found_index < 0) : # to continue if we find wrong one first
+        while (isinstance(frame, FrameType)
+               and frame.f_back # No earlier frames
+               and (not frame.f_code.co_name in split_name # code not in qualname
+                    or (local_index # or is, but before local_index
+                        and split_name.index(frame.f_code.co_name) > local_index)
+                    )
+               and not split_name[0] in frame.f_locals # root of qualname in globals
+               and not split_name[0] in frame.f_globals # or locals
+               ):
+            frame = frame.f_back # Then go back a level
+            pass # end moving back
+        top_dicts = [dict(frame.f_locals), dict(frame.f_globals)]
+        obj = None
+        found_index = -1
+        local_dicts = top_dicts # default value for extra dictionaries returned
+        d2:dict[str,Any] = {}
+        d1:dict[str,Any] = {}
+        for i in range(len(split_name)) :
+            if split_name[i] == _local_mark :
+                local_dicts = grab_all_namespaces(obj, split=True) # return g and l separately
+                local_index = i
+                continue
+            obj = find_in_dicts(split_name[i], top_dicts)
+            if obj :
+                found_index = i
+                if i == len(split_name) - 3 :
+                    d1 = grab_all_namespaces(obj, split=False)
+                elif i == len(split_name) - 2 :
+                    d2 = grab_all_namespaces(obj, split=False)
+                    pass
+                for j in range(i+1, len(split_name)) :
+                    if split_name[j] == _local_mark :
+                        local_dicts = grab_all_namespaces(obj, split=True)
+                        local_index = j
+                        continue
+                    obj = find_in_dicts(split_name[j], grab_all_namespaces(obj, split=True))
+                    if not obj :
+                        found_index = -1
+                        break
+                    if j == len(split_name) - 3 :
+                        d1 = grab_all_namespaces(obj, split=False)
+                    elif j == len(split_name) - 2 :
+                        d2 = grab_all_namespaces(obj)
+                    pass
+                if found_index >= 0 :
+                    break
+                pass #end if lookup worked
+            pass # end of searching in dicts for parts of name
+        if found_index < 0 :
+            frame = frame.f_back
+            pass
+        pass # end searching for frame
+    if found_index == len(split_name) - 1:
+        lname = split_name[-1]
+    elif (local_index < len(split_name)
+          and local_index == len(split_name) - 2) :
+        lname = split_name[-1]
+    elif local_index < len(split_name):
+        lname = '.'.join(split_name[max(found_index, local_index+1):])
+    else:
+        lname = '.'.join(split_name[found_index:])
+        pass
+    if found_index > len(split_name) :
+        raise ValueError("What The Hell?")
+    elif found_index == len(split_name)-1 :
+        if isinstance(frame, FrameType) and frame.f_back :
+            f = frame.f_back 
+            d2 = dict(f.f_globals)
+            d2.update(f.f_locals)
+            if f.f_back :
+                f = f.f_back
+                d1 = dict(f.f_globals)
+                d1.update(f.f_locals)
+            else :
+                d1 = {}
+                pass
+        else:
+            d2 = {}
+            d1 = {}
+            pass
+        # Take care of case where we lack "context" right away
+        return (lname, top_dicts, [{}, {}], d2, d1, frame)
+    else:
+        return (lname, top_dicts, local_dicts,  d2, d1, frame)
+    pass # type: ignore[unreachable]
+
+def fix_locals_qualname(name:str) -> str :
+    """
+    returns the portion of qualname after '<locals>', or all
+    of the qualname if '<locals>' does not occur
+    """
+    if _local_mark in name :
+        name = name[name.index(_local_mark2)+len(_local_mark2):]
+        pass
+    return name
+

pusher_debug-1.0.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: pusher_debug
+Version: 1.0.0
+Summary: tools to assist with debug
+Project-URL: repository, https://codeberg.org/Pusher2531/debug_tools.git
+Project-URL: issues, https://codeberg.org/Pusher2531/debug_tools/issues
+Author-email: Doug Sojourner <doug@sojournings.org>
+License: GNU General Public License v3 (GPLv3)
+License-File: LICENSE.md
+Keywords: class modification,debug,debuging,decorator,monkeypatching,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.14
+Requires-Dist: objwatch
+Requires-Dist: packaging
+Requires-Dist: project-version-finder
+Requires-Dist: regex
+Description-Content-Type: text/markdown
+
+### `pusher_debug`
+## `pusher_debug.tracing`
+Tools to aid in adding print statements to trace program flow:
+* `ObjWatch` from the objwatch library
+* `DetailWrapper`, a "wrapper" to use with Objwatch that provides more details on function calls and returns, and can be subclassed easily to provide distinct id strings for different instances of selected classes.
+* `fn_name`, `fn_entry`, and `fn_exit`, to provide manual logging of details of function you enter (caller, parameters, return value, annotations)
+
+## `pusher_debug.monkeypatching`
+Tools to aid in monkeypatching. Two decorators:
+```python
+@add_new_class(ExistingClass)
+class MyClass: ...
+```
+
+will (in the module where `ExistingClass` is defined)
+1. Create `orig_ExistingClass`, as a backup of `ExistingClass`  
+2. Create `new_ExistingClass`, as a backup of `MyClass`  
+3. Make `ExistingClass` be `new_ExistingClass` (fixing `__name__` and `__qualname__` between `new_ExistingClass` and `orig_ExistingClass` as well)  
+
+Then `restore_class(ExistingClass)` will restore the original, and `restore_new_class(ExistingClass)` will put back the new version again.  
+
+```python
+@add_to_class(ExistingClass)
+def fn():...
+```
+
+will (in `ExistingClass`) add a method `fn`. If `fn` already exists, the the original is backed up as `orig_fn`. `new_fn` is created and names are fixed as for `@add_new_class`.  
+
+`@add_to_class` can be combined with one of `@classmethod`, `@staticmethod`, or `@property` (and if property, then `fn` in the local namespace will be the property, so you can then do  
+```python
+@add_to_class(ExistingClass)
+@fn@setter
+def fn():...
+```
+
+You should know that monkeypatching will wreack havoc with mypy, since it does stuff you shouldn't do. (It's for __debugging__ !)  
+
+For examples, use help(...), and/or download the source package and look at the tests. Seeing all the # test: ignore[] stuff in the test program gives you an idea of how much mypy hates this.  
+
+The library can be built with `hatchling build`, tested with `tests/test_tools.py -v`, and should pass `mypy` (including having annotations for objwatch).  

pusher_debug-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pusher_debug/__init__.py,sha256=1GCNPeim3YNLiAhQEGp9IeiWUrm-4IUmMTTuwZGa47A,2052
+pusher_debug/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pusher_debug/monkeypatching/__init__.py,sha256=79YSIMcQEg5OZLvmHhjnA46DgaiFmJPZzP6qCytKFgw,1225
+pusher_debug/monkeypatching/monkeypatching.py,sha256=r7j71ITB8wOqbr7S1lGhxcaO3KMCATyHnEjMzrk7RwI,15754
+pusher_debug/tracing/__init__.py,sha256=Ie5HwdQVrdqi6pmOYxttU5pOoAB0LLpMLb_AQ5ip2Yo,1049
+pusher_debug/tracing/tracing.py,sha256=FhjQi0U70d72sQfsm09YyQbQq66j7Vh4U5MPpXpjlhI,8452
+pusher_debug/util/__init__.py,sha256=mGyRpNPxneDM7b94UaoYMBBIPzZwzuOxWpHogSFi71U,959
+pusher_debug/util/util.py,sha256=cwm6peTxaA2DHwtBVplOr-QPQAcAeWtup8Dx-pHe-Wk,8746
+pusher_debug-1.0.0.dist-info/METADATA,sha256=p-zeagKl0RrXD8n3w3cYCcguGYn-yXfF0EoiNpXof9M,3319
+pusher_debug-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pusher_debug-1.0.0.dist-info/licenses/LICENSE.md,sha256=zFRw_u1mGSOH8GrpOu0L1P765aX9fB5UpKz06mTxAos,34893
+pusher_debug-1.0.0.dist-info/RECORD,,

pusher_debug-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any