| Name | cs-debug JSON |
| Version |
20250728
JSON |
| download |
| home_page | None |
| Summary | Assorted debugging facilities. |
| upload_time | 2025-07-27 23:31:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
python2
python3
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Assorted debugging facilities.
*Latest release 20250728*:
@trace: several updates/improvements to the trace output.
If the environment variable `$CS_DEBUG_BUILTINS` is set to a comma
separated list of names then the `builtins` module 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 list `cs.debug.__all__` and include:
* `X`: `cs.x.X`
* `abrk`: a decorator to call `breakpoint()` on an `AssertionError`
* `pformat`: `pprint.pformat`
* `pprint`: `pprint.pprint`
* `print`: `cs.upd.print`
* `r`: `cs.lex.r`
* `redirect_stdout`: `contextlib.redirect_stdout`
* `s`: `cs.lex.s`
* `stack_dump`: dump current `Thread`'s call stack
* `thread_dump` dump the active `Thread`s with their call stacks
* `trace`: the `@trace` decorator
`$CS_DEBUG_BUILTINS` can also be set to `"1"` to install all of
`__all__` in the builtins.
Short summary:
* `abrk`: A decorator to intercept certain exceptions (by default `AssertionError`, `NameError`, `RuntimeError`) and call `breakpoint()`. The breakpoint frame contains: - `func`: the wrapper function - `func_a`, `func_kw`: the function positional and keyword arguments.
* `stack_dump`: Dump a stack trace to a logger.
* `thread_dump`: Write thread identifiers and stack traces to the file `fp`.
* `TimingOutLock`: A `Lock` replacement which times out, used for locating deadlock points.
* `trace`: Decorator to report the call and return of a function.
Module contents:
- <a name="abrk"></a>`abrk(*da, **dkw)`: A decorator to intercept certain exceptions
(by default `AssertionError`, `NameError`, `RuntimeError`)
and call `breakpoint()`.
The breakpoint frame contains:
- `func`: the wrapper function
- `func_a`, `func_kw`: the function positional and keyword arguments
- <a name="stack_dump"></a>`stack_dump(stack=None, limit=None, logger=None, log_level=None)`: Dump a stack trace to a logger.
Parameters:
* `stack`: a stack list as returned by `traceback.extract_stack`.
If missing or `None`, use the result of `traceback.extract_stack()`.
If `stack` has a `.tb_frame` or `.__traceback__` attribute,
extract the stack from that (this covers traceback objects and exceptions).
* `limit`: a limit to the number of stack entries to dump.
If missing or `None`, dump all entries.
* `logger`: a `logger.Logger` ducktype or the name of a logger.
If missing or `None`, obtain a logger from `logging.getLogger()`.
* `log_level`: the logging level for the dump.
If missing or `None`, use `cs.logutils.loginfo.level`.
- <a name="thread_dump"></a>`thread_dump(Ts=None, fp=None)`: Write thread identifiers and stack traces to the file `fp`.
Parameters:
* `Ts`: the `Thread`s to dump; if unspecified use `threading.enumerate()`.
* `fp`: the file to which to write; if unspecified use `sys.stderr`.
- <a name="TimingOutLock"></a>`class TimingOutLock`: A `Lock` replacement which times out, used for locating deadlock points.
- <a name="trace"></a>`trace(*da, **dkw)`: Decorator to report the call and return of a function.
Decorator parameters:
* `call`: trace the call, default `True`
* `retval`: trace the return, default `False`
* `exception`: trace raised exceptions, default `True`
* `use_pformat`: present the return value using
`pformat` instead of `repr`, default `False`
* `with_caller`: include the caller if this function, default `True`
* `with_pfx`: include the current `Pfx` prefix, default `False`
# Release Log
*Release 20250728*:
@trace: several updates/improvements to the trace output.
*Release 20250325*:
* stack_dump: stack may also be a traceback object or an exception.
* stack_dump: move the logic to obtain the stack into cs.py.stack.frames().
*Release 20241005*:
* New log_via_print(msg, *args[, file=stdout]) function to use cs.upd.print as a logging call.
* @trace: new $CS_DEBUG_TRACE envvar which may be "print" or "warning" or "X".
* New @abrk decorator to intercept AssertionError, NameError and RuntimeError and call breakpoint.
*Release 20240630*:
Assorted updates.
*Release 20240519*:
trace_caller: access frame.name instead of frame.funcname.
*Release 20240423*:
* Support "import *" by populating __all__ with X, r, s, TimingOutLock, thread_dump, stack_dump, trace.
* @trace: include the elapsed time on the return/exception log message.
*Release 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.__dict__ in a test case tearDwon.
* debug_object_shell: convenience wrapper for DebugShell to call it on an object's attributes.
*Release 20150116*:
PyPI prep.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs-debug",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/4d/85/aeeacb9becd63156b31c08ef2fb01cf0e2c53bdbeb3a0c9103b5801b1c0f/cs_debug-20250728.tar.gz",
"platform": null,
"description": "Assorted debugging facilities.\n\n*Latest release 20250728*:\n@trace: several updates/improvements to the trace output.\n\nIf the environment variable `$CS_DEBUG_BUILTINS` is set to a comma\nseparated list of names then the `builtins` module will be monkey\npatched with those names, enabling trite debug use of those names\nanywhere in the code provided this module has been imported somewhere.\n\nThe allowed names are the list `cs.debug.__all__` and include:\n* `X`: `cs.x.X`\n* `abrk`: a decorator to call `breakpoint()` on an `AssertionError`\n* `pformat`: `pprint.pformat`\n* `pprint`: `pprint.pprint`\n* `print`: `cs.upd.print`\n* `r`: `cs.lex.r`\n* `redirect_stdout`: `contextlib.redirect_stdout`\n* `s`: `cs.lex.s`\n* `stack_dump`: dump current `Thread`'s call stack\n* `thread_dump` dump the active `Thread`s with their call stacks\n* `trace`: the `@trace` decorator\n`$CS_DEBUG_BUILTINS` can also be set to `\"1\"` to install all of\n`__all__` in the builtins.\n\nShort summary:\n* `abrk`: A decorator to intercept certain exceptions (by default `AssertionError`, `NameError`, `RuntimeError`) and call `breakpoint()`. The breakpoint frame contains: - `func`: the wrapper function - `func_a`, `func_kw`: the function positional and keyword arguments.\n* `stack_dump`: Dump a stack trace to a logger.\n* `thread_dump`: Write thread identifiers and stack traces to the file `fp`.\n* `TimingOutLock`: A `Lock` replacement which times out, used for locating deadlock points.\n* `trace`: Decorator to report the call and return of a function.\n\nModule contents:\n- <a name=\"abrk\"></a>`abrk(*da, **dkw)`: A decorator to intercept certain exceptions\n (by default `AssertionError`, `NameError`, `RuntimeError`)\n and call `breakpoint()`.\n The breakpoint frame contains:\n - `func`: the wrapper function\n - `func_a`, `func_kw`: the function positional and keyword arguments\n- <a name=\"stack_dump\"></a>`stack_dump(stack=None, limit=None, logger=None, log_level=None)`: Dump a stack trace to a logger.\n\n Parameters:\n * `stack`: a stack list as returned by `traceback.extract_stack`.\n If missing or `None`, use the result of `traceback.extract_stack()`.\n If `stack` has a `.tb_frame` or `.__traceback__` attribute,\n extract the stack from that (this covers traceback objects and exceptions).\n * `limit`: a limit to the number of stack entries to dump.\n If missing or `None`, dump all entries.\n * `logger`: a `logger.Logger` ducktype or the name of a logger.\n If missing or `None`, obtain a logger from `logging.getLogger()`.\n * `log_level`: the logging level for the dump.\n If missing or `None`, use `cs.logutils.loginfo.level`.\n- <a name=\"thread_dump\"></a>`thread_dump(Ts=None, fp=None)`: Write thread identifiers and stack traces to the file `fp`.\n\n Parameters:\n * `Ts`: the `Thread`s to dump; if unspecified use `threading.enumerate()`.\n * `fp`: the file to which to write; if unspecified use `sys.stderr`.\n- <a name=\"TimingOutLock\"></a>`class TimingOutLock`: A `Lock` replacement which times out, used for locating deadlock points.\n- <a name=\"trace\"></a>`trace(*da, **dkw)`: Decorator to report the call and return of a function.\n\n Decorator parameters:\n * `call`: trace the call, default `True`\n * `retval`: trace the return, default `False`\n * `exception`: trace raised exceptions, default `True`\n * `use_pformat`: present the return value using\n `pformat` instead of `repr`, default `False`\n * `with_caller`: include the caller if this function, default `True`\n * `with_pfx`: include the current `Pfx` prefix, default `False`\n\n# Release Log\n\n\n\n*Release 20250728*:\n@trace: several updates/improvements to the trace output.\n\n*Release 20250325*:\n* stack_dump: stack may also be a traceback object or an exception.\n* stack_dump: move the logic to obtain the stack into cs.py.stack.frames().\n\n*Release 20241005*:\n* New log_via_print(msg, *args[, file=stdout]) function to use cs.upd.print as a logging call.\n* @trace: new $CS_DEBUG_TRACE envvar which may be \"print\" or \"warning\" or \"X\".\n* New @abrk decorator to intercept AssertionError, NameError and RuntimeError and call breakpoint.\n\n*Release 20240630*:\nAssorted updates.\n\n*Release 20240519*:\ntrace_caller: access frame.name instead of frame.funcname.\n\n*Release 20240423*:\n* Support \"import *\" by populating __all__ with X, r, s, TimingOutLock, thread_dump, stack_dump, trace.\n* @trace: include the elapsed time on the return/exception log message.\n\n*Release 20230613.1*:\nBugfix builtins monkey patch.\n\n*Release 20230613*:\nHonour $CS_DEBUG_BUILTINS envvar to monkey patch the builtins module, constraints via a white list.\n\n*Release 20230610*:\n* DebuggingRLock fixes.\n* Move @trace from cs.py.func to cs.debug.\n* Drop Lock and RLock alias factories - importers should just use the debugging lock classes directly.\n* Rename threading.Thread to threading_Thread.\n* Simplify the debugging lock classes.\n\n*Release 20221118*:\nstack_dump: cope when cs.logutils.setup_logging not run yet.\n\n*Release 20211208*:\n@trace moved to cs.pyfunc, other minor changes.\n\n*Release 20200318*:\nRemove use of cs.obj.O, universally supplanted by types.SimpleNamespace.\n\n*Release 20181231*:\n* New TimingOutLock for locating deadlock points, grew from debugging cs.vt.index.\n* Other minor changes.\n\n*Release 20171231*:\n* Update imports for recentchanges.\n* New context manager TraceSuite to trace start and end of a code suite.\n\n*Release 20160918*:\nselftest(): fix parameter ordering to match unittest.\n\n*Release 20160828*:\nUpdate metadata with \"install_requires\" instead of \"requires\".\n\n*Release 20160827*:\n* New openfiles() to return selected pathnames of open files via lsof(8).\n* New selftest() to invoke unittests with benefits.\n* DebugShell, a cmd.Cmd subclass for debugging - current use case calls this with self.__dict__ in a test case tearDwon.\n* debug_object_shell: convenience wrapper for DebugShell to call it on an object's attributes.\n\n*Release 20150116*:\nPyPI prep.\n",
"bugtrack_url": null,
"license": null,
"summary": "Assorted debugging facilities.",
"version": "20250728",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/branch/main",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/debug.py"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dfffd2df71f44a3355786e4d1ace8453a8b1233ef4b4c947bd6afc2f4f9e8d4d",
"md5": "0674e2326f43a662f9fe2e51898f2ac0",
"sha256": "78350072598546f519f17bec73d36a21912df2a6be8b0e323d7fd9b96539a0a1"
},
"downloads": -1,
"filename": "cs_debug-20250728-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0674e2326f43a662f9fe2e51898f2ac0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11301,
"upload_time": "2025-07-27T23:31:22",
"upload_time_iso_8601": "2025-07-27T23:31:22.097545Z",
"url": "https://files.pythonhosted.org/packages/df/ff/d2df71f44a3355786e4d1ace8453a8b1233ef4b4c947bd6afc2f4f9e8d4d/cs_debug-20250728-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d85aeeacb9becd63156b31c08ef2fb01cf0e2c53bdbeb3a0c9103b5801b1c0f",
"md5": "e67349b5357baff3d85c2c1ea7ba1b70",
"sha256": "729e4fbff4adcc6ee0ab8a621c1b824005991d8573221a60109cdb38db7c1b72"
},
"downloads": -1,
"filename": "cs_debug-20250728.tar.gz",
"has_sig": false,
"md5_digest": "e67349b5357baff3d85c2c1ea7ba1b70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11305,
"upload_time": "2025-07-27T23:31:23",
"upload_time_iso_8601": "2025-07-27T23:31:23.782563Z",
"url": "https://files.pythonhosted.org/packages/4d/85/aeeacb9becd63156b31c08ef2fb01cf0e2c53bdbeb3a0c9103b5801b1c0f/cs_debug-20250728.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 23:31:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs-debug"
}
