diff --git a/CHANGELOG.md b/CHANGELOG.md index d169657c12..b78961c6d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -79,6 +79,7 @@ - Start structuring the `CHANGELOG` to list features in more detail. - Inflection and grouping of multiple objects in default room (an box, three boxes) +- `evennia.set_trace()` is now a shortcut for launching pdb/pudb on a line in the Evennia event loop. ### Contribs diff --git a/evennia/__init__.py b/evennia/__init__.py index fc916351ad..bb9c29a594 100644 --- a/evennia/__init__.py +++ b/evennia/__init__.py @@ -319,3 +319,53 @@ def _init(): del object del absolute_import del print_function + + +def set_trace(debugger="auto", term_size=(140, 40)): + """ + Helper function for running a debugger inside the Evennia event loop. + + Args: + debugger (str, optional): One of 'auto', 'pdb' or 'pudb'. Pdb is the standard debugger. Pudb + is an external package with a different, more 'graphical', ncurses-based UI. With + 'auto', will use pudb if possible, otherwise fall back to pdb. Pudb is available through + `pip install pudb`. + term_size (tuple, optional): Only used for Pudb and defines the size of the terminal + (width, height) in number of characters. + + Notes: + To use: + + 1) add this to a line to act as a breakpoint for entering the debugger: + + from evennia import set_trace; set_trace() + + 2) restart evennia in interactive mode + + evennia istart + + 3) debugger will appear in the interactive terminal when breakpoint is reached. Exit + with 'q', remove the break line and restart server when finished. + + """ + import sys + dbg = None + + if debugger in ('auto', 'pudb'): + try: + from pudb import debugger + dbg = debugger.Debugger(stdout=sys.__stdout__, + term_size=term_size) + except ImportError: + if debugger == 'pudb': + raise + pass + + if not dbg: + import pdb + dbg = pdb.Pdb(stdout=sys.__stdout__) + + # + # stopped at breakpoint. Use 'n' (next) to continue into the code. + # + dbg.set_trace()