Custom DSI Writer

DSI Writers are the primary way to translate data from DSI to an external format. All Writers must be structured as a Class with 2 mandatory methods: __init__, and get_rows.

Loading Custom Writer into DSI

Before understanding the structure of Writers, it is important to know how they can be loaded via the User API and the Contributor API:

  • User API: Users loading a custom external Writer can use the write() method from the DSI class. Unlike a normal write(), the second argument should be the path to the Python script containing the user’s custom Writer.

    While there currently isn’t an example of loading an external Writer, Example 9: Load an external Reader has a similar process to load an external Reader.

  • Contributor API: Users loading a custom external Writer must first call Terminal.add_external_python_module() to temporarily register the Writer with DSI before loading the Writer and its data normally. For detailed instructions, follow Example 9: External Readers/Writers.

    Users intending to add the custom Writer to DSI’s codebase must include the file in the dsi/plugins directory and include the Writer name in the Terminal.VALID_WRITERS class variable of dsi/core.py. If done correctly, the Writer will be accessible by Terminal.load_module().

Initializer: __init__(self) -> None:

__init__ is where you can include all of your initialization logic, and specify the parameters needed for a given application.

Example __init__:

def __init__(self, filename, table_name) -> None:
  # see "plugins" to determine which superclass your Writer should extend
  super().__init__()

  self.output_filename = filename

  # a Writer might be table-specific and require a table_name input. Ex: Plotting a table's data.
  self.table_name = table_name

Get Rows: get_rows(self, collection) -> None

get_rows is responsible for converting data from DSI’s internal abstraction, an OrderedDict, to whichever format this Writer’s goal is.

It is important to note that collection will be a nested OrderedDict with at least one table of data. Essentially, each entry in the larger OrderedDict has a table’s name as a key and its data as a value. That table’s data will be an inner OrderedDict.

Unlike DSI Readers, there is no standard structure for get_rows as each Writer can have a vastly different output. If a Writer requires units of data, or primary key/foreign key relations, they are stored in tables named ‘dsi_units’ and ‘dsi_relations’ respectively.

Various examples of get_rows can be found in dsi/plugins/file_writer.py.

Contributing Your Writer

If your Writer is helpful and acceptable for public use, you should consider making a pull request (PR) into DSI.

Please note that any accepted PRs into DSI should satisfy the following:

  • Passes all tests in dsi/plugins/tests

  • Has no pylama errors/warnings (see dsi/.githooks)