Embedding Guide

Using embed()

pw console is invoked by calling PwConsoleEmbed().embed() in your own Python script.

pw_console embed class.

class pw_console.embed.PwConsoleEmbed(global_vars=None, local_vars=None, loggers: Optional[Union[Dict[str, Iterable[logging.Logger]], Iterable]] = None, test_mode=False, repl_startup_message: Optional[str] = None, help_text: Optional[str] = None, app_title: Optional[str] = None)

Bases: object

Embed class for customizing the console before startup.

__init__(global_vars=None, local_vars=None, loggers: Optional[Union[Dict[str, Iterable[logging.Logger]], Iterable]] = None, test_mode=False, repl_startup_message: Optional[str] = None, help_text: Optional[str] = None, app_title: Optional[str] = None) None

Call this to embed pw console at the call point within your program.

Example usage:

import logging

from pw_console import PwConsoleEmbed

# Create the pw_console embed instance
console = PwConsoleEmbed(
    global_vars=globals(),
    local_vars=locals(),
    loggers={
        'Host Logs': [
            logging.getLogger(__package__),
            logging.getLogger(__file__)
        ],
        'Device Logs': [
            logging.getLogger('usb_gadget')
        ],
    },
    app_title='My Awesome Console',
)
# Optional: Add custom completions
console.add_sentence_completer(
    {
        'some_function', 'Function',
        'some_variable', 'Variable',
    }
)
# Then run the console with:
console.embed()
Parameters
  • global_vars – Dictionary representing the desired global symbol table. Similar to what is returned by globals().

  • local_vars – Dictionary representing the desired local symbol table. Similar to what is returned by locals().

  • loggers – Dict with keys of log window titles and values of logging.getLogger() instances in lists. Each key that should be shown in the pw console user interface.

  • app_title – Custom title text displayed in the user interface.

  • repl_startup_message – Custom text shown by default in the repl output pane.

  • help_text – Custom text shown at the top of the help window before keyboard shortcuts.

add_sentence_completer(word_meta_dict: Dict[str, str], ignore_case=True)

Include a custom completer that matches on the entire repl input.

Parameters

word_meta_dict – Dictionary representing the sentence completions and descriptions. Keys are completion text, values are descriptions.

embed()

Start the console.

Adding Log Metadata

pw_console can display log messages in a table with justified columns for metadata fields provided by pw_log_tokenized.

It is also possible to manually add values that should be displayed in columns using the extra keyword argument when logging from Python. See the Python’s logging documentation for how extra works. A dict of name, value pairs can be passed in as the extra_metadata_fields variable. For example, the following code will create a log message with two custom columns titled module and timestamp.

import logging

LOG = logging.getLogger('log_source_1')

LOG.info(
    'Hello there!',
    extra={
        'extra_metadata_fields': {
            'module': 'cool',
            'timestamp': 1.2345,
        }
    }
)