Control Python source symbol tables

When you debug a native Python program, TotalView builds symbol tables for the top-level script and Python files reached by its import statements. Symbol tables make Python source files, functions, and classes available in the Source and Call Stack views and as breakpoint targets.

For programs that import large packages, building symbol tables for every imported file can increase debugging-session startup time. To reduce debugging-session startup time for these programs, you can configure TotalView to exclude selected Python source files.

Configure Python source symbol tables using CLI state variables

By default, TotalView builds a symbol table only for Python source files that are part of your application. It skips building a symbol table for imports of Python site packages, which are packages that are installed under a directory name matching /site-packages/, /dist-packages/, or /lib/pythonX.Y/. For example, site package directories include /usr/lib/python3/site-packages, /usr/lib/python3/dist-packages, and /usr/lib/python3.13.

To configure the default behavior, use one of the following options:

  • Set TV::python_skim_all_files to true to force building a symbol table for all Python files.

    dset TV::python_skim_all_files true

  • Leave TV::python_skim_all_files set to its default value of false, then set TV::python_skim_handling to a Tcl list of regexp and action pairs to specify which Python source files TotalView builds a symbol table for or skips.

    dset TV::python_skim_handling {{/vendor/mypkg/ skim} {/vendor/ skip}}

    In this example, TotalView builds a symbol table for files under /vendor/mypkg/ and excludes other files under /vendor/. Put more-specific rules before broader rules.

To use these settings whenever you start TotalView, add the dset commands to your .tvdrc file. To learn more, see dset.

Configure Python source symbol tables using command-line options

By default, TotalView applies filtering rules when it starts a Python debugging session. You can override the default or configured CLI state variable settings for your debugging session as follows:

  • To build a symbol table for every Python source file, use -python_skim_all_files.

  • To customize the filtering rules, use -python_skim_handling to specify a Tcl list of regexp and action pairs. This option has no effect when you also use -python_skim_all_files.

    totalview -python_skim_handling '{/vendor/mypkg/ skim} {/vendor/ skip}' -args %tv_python_wrapper% python <script.py>

Filtering rules

Refer to these rules when you configure Python source filtering with TV::python_skim_handling or -python_skim_handling list.

  • Each regular expression is matched against the full path of a Python source file. Use ^ and $ to match the beginning or end of a path.

  • Use skim to build a symbol table for a file. Use skip to exclude the file.

  • When you exclude a file, TotalView does not build a symbol table for that file and does not follow that file's import statements.

  • TotalView always builds a symbol table for the top-level script that you specify for debugging.

  • If a Python thread stops execution inside a source file for which TotalView has not yet built a symbol table, a symbol table is built for that source file without following its import statements.

  • If you specify a Python source file by name, for example by using dlist, dbreak, or the Folder view, TotalView builds a symbol table for that source file without following its import statements. By default, files with the extensions .py, .py3, .pyi, or .pyw are considered Python source files. The CLI state variable TV::suffixes can be changed to include other file extensions.