Package: cs.debug
Assorted debugging facilities.Latest release 20230613.1:
Bugfix builtins monkey patch.If the environment variable $CS_DEBUG_BUILTINS is set to a comma
separated list of names then thebuiltinsmodule will be monkey
patched with those names, enabling trite debug use of those names
anywhere in the code provided this module has been imported somewhere.
The allowed names are the following:X:cs.x.Xpformat:pprint.pformatpprint:pprint.pprintr:cs.lex.rs:cs.lex.strace:cs.debug.trace(the@tracedecorator)FunctionDEBUG(f, force=False)Decorator to wrap functions in timing and value debuggers.Functiondebug_object_shell(o, prompt=None)Interactive prompt for inspecting variables.ClassDebuggingLock(DebugWrapper, types.SimpleNamespace)Wrapper class forthreading.Lockto trace creation and use.cs.threads.Lock()returns one of these in debug mode or a rawthreading.Lockotherwise.ClassDebuggingRLock(DebugWrapper, types.SimpleNamespace)Wrapper class for threading.RLock to trace creation and use.cs.threads.RLock()returns on of these in debug mode or a rawthreading.RLockotherwise.ClassDebugShell(cmd.Cmd)An interactive prompt for python statements, attached to/dev/ttyby default.ClassDebugWrapper(types.SimpleNamespace)Base class for classes presenting debugging wrappers.FunctionDF(func, *a, **kw)Wrapper for a function call to debug its use.This requires rewriting the call fromf(*a,*kw)toDF(f,*a,**kw).
Alternatively one could rewrite asDEBUG(f)(*a,**kw).ClassLock(DebugWrapper, types.SimpleNamespace)Wrapper class forthreading.Lockto trace creation and use.cs.threads.Lock()returns one of these in debug mode or a rawthreading.Lockotherwise.Functionopenfiles(substr=None, pid=None)Run lsof(8) against processpidreturning paths of open files whose paths containsubstr.Parameters:substr: default substring to select by; default returns all paths.pid: process to examine; default fromos.getpid().ClassRLock(DebugWrapper, types.SimpleNamespace)Wrapper class for threading.RLock to trace creation and use.cs.threads.RLock()returns on of these in debug mode or a rawthreading.RLockotherwise.Functionselftest(module_name, defaultTest=None, argv=None)Called by my unit tests.Functionstack_dump(stack=None, limit=None, logger=None, log_level=None)Dump a stack trace to a logger.Parameters:stack: a stack list as returned bytraceback.extract_stack.
If missing orNone, use the result oftraceback.extract_stack().limit: a limit to the number of stack entries to dump.
If missing orNone, dump all entries.logger: alogger.Loggerducktype or the name of a logger.
If missing orNone, obtain a logger fromlogging.getLogger().log_level: the logging level for the dump.
If missing orNone, usecs.logutils.loginfo.level.Functionthread_dump(Ts=None, fp=None)Write thread identifiers and stack traces to the filefp.Parameters:Ts: theThreads to dump; if unspecified usethreading.enumerate().fp: the file to which to write; if unspecified usesys.stderr.ClassTimingOutLockALockreplacement which times out, used for locating deadlock points.Functiontrace(*da, **dkw)Decorator to report the call and return of a function.Functiontrace_caller(func)Decorator to report the caller of a function when called.ClassTraceSuiteContext manager to trace start and end of a code suite.Release LogRelease 20230613.1:
Bugfix builtins monkey patch.Release 20230613:
Honour $CS_DEBUG_BUILTINS envvar to monkey patch the builtins module, constraints via a white list.Release 20230610:DebuggingRLock fixes.Move @trace from cs.py.func to cs.debug.Drop Lock and RLock alias factories - importers should just use the debugging lock classes directly.Rename threading.Thread to threading_Thread.Simplify the debugging lock classes.Release 20221118:
stack_dump: cope when cs.logutils.setup_logging not run yet.Release 20211208:
@trace moved to cs.pyfunc, other minor changes.Release 20200318:
Remove use of cs.obj.O, universally supplanted by types.SimpleNamespace.Release 20181231:New TimingOutLock for locating deadlock points, grew from debugging cs.vt.index.Other minor changes.Release 20171231:Update imports for recentchanges.New context manager TraceSuite to trace start and end of a code suite.Release 20160918:
selftest(): fix parameter ordering to match unittest.Release 20160828:
Update metadata with "install_requires" instead of "requires".Release 20160827:New openfiles() to return selected pathnames of open files via lsof(8).New selftest() to invoke unittests with benefits.DebugShell, a cmd.Cmd subclass for debugging - current use case calls this with self.dictin a test case tearDwon.debug_object_shell: convenience wrapper for DebugShell to call it on an object's attributes.Release 20150116:
PyPI prep.