DBT Python Extensions

When running in DBT, a python script may access functions and objects defined by DBT for integration with the application or document.

DBT defines these functions:

DBT defines these object classes (with methods/properties for each):

Functions

set_progress(progress: int) -> None

This function may be called within a script invoked from an importer and only after a call to set_progress_total. The integer parameter passed sets the position of the progress bar and should be in the range 0 ≤ progress < total, where total is the value previously passed to set_progress_total.

set_progress_total(total: int) -> None

This function is may be called within a script invoked from an importer; it is typically called at the start of the script or after some relatively quick code to analyze the task of the script and estimate how long it will take. The value total should be greater than zero. It reflects an estimate of the time to complete the script, but not the whole import task, which may involve other steps. There is no particular correlation between the value of total and a specific number of seconds estimated step time. Most SCRUB steps (.sbt files) in an importer sequence have a total time of 1. The best way to determine what total should be for custom importer steps is to observe the progress bar while running imports involving your Python script and adjust the value of total until the behavior seems optimal.

After calling set_progress_total, a script must make at least one call to set_progress (and typically will make several) to update the progress bar displayed.

wx_log(level: int, message: str) -> None

This function is useful for implementing a custom logging handler in your Python script. In this case, the simplest path to understanding is likely to be via an example. The code below can be placed at the start 

try:
	from dbt import register_macro, get_topmost_doc, wx_log
	class DBTLoggingHandler(logging.Handler):
		def emit(self, record) -> None:
			assert wx_log(record.levelno, record.getMessage())
	if __name__ == "__main__":
		logger = logging.getLogger(__name__)
		logger.addHandler(DBTLoggingHandler())

except ModuleNotFoundError:
	pass

Having this code at the start of your Python scripts makes it possible for you to use the Logging facility for Python in its most customary form. Logging messages will be displayed by DBT at the completion of the execution of your script. The code as presented above will not interfere with your ability to test your code by running the script on a command line outside of DBT.

get_topmost_toc() -> Document

Returns a Document object that can be used to manipulate the topmost document in DBT, or None if there is no document opened.

register_macro(name: str, func) -> None

Adds a macro to the macro menu, given a name for display in the menu and the entry point for the macro code.

Macros are displayed in the macro menu in the order in which register_macro is called.

This function is normally called from

Document Properties

Your macros may obtain a reference to a Document object may be obtained by calling the get_topmost_doc function, then get or change properties of the document by reading or assigning values to the properties of the Document object.

is_print (readonly bool)

The is_print property is true for print documents and false for braille documents.

is_braille (readonly bool)

The is_braille property is true for braille documents and false for print documents.

title (str)

The title property represents the text shown in the title bar of the document window.

content (str)

The content property represents the text, codes, and style references in the document. It is rather like a string with all the text of the document when View Codes is checked. Unicode Braille Patters (U+28xx) characters are used to represent the text of a braille document. There are some important additional differences between the way coded view appears on screen and the form of the content string property:

styles (dict)

The styles property represents the full set of defined styles as a Python dictionary. Each key in the dictionary is a string, representing the name of a style. Each value is a Python list with exactly two items: a string representing the starting codes of the style and a string representing the ending codes of the style.

The strings representing the starting and ending codes are encoded as for the content string, but U+28xx characters are neither found nor permitted. Nor are spaces permitted in the style names.

There two other important things to note.

DBT uses "hidden" styles to represent certain properties of a document. Some care should therefore be taken not generally to erase all style definitions. Instead, update style definitions or remove style definitions only when you know that these are not "hidden" styles needed for some structural purpose.

The styles properties can be read and written, but it must be written as a whole, because it is really a copy of the internal style definition storage structure of a DBT document. Thus, it is not possible to update individual entries in the dictionary. Instead, you must take a copy of the styles property, modify it, then assign the value to the styles property, even if the intent is to modify only one style.

For example, to change the start codes for the [para.] style, you cannot do this:

doc.styles["para."][0] = '\u001C' + 'p' + '\u001F'

You must instead do this:

styles = doc.styles
styles["para."][0] = '\u001C' + 'p' + '\u001F'
doc.styles = styles