Import plugins
Veusz supports user defined plugins for loading data from arbitrary files. If you have a special data format for loading then a plugin is a perfect way to get the data quickly into Veusz. Users can add plugins into Veusz using the Plugins tab in the Preferences dialog box, giving the filename for the plugin.
A plugin consists of a class which inherits from veusz.plugins.ImportPlugin. An instance of this class should be appended to veusz.plugins.importpluginregistry.
The new class should redefine the members name (name of the plugin, shown in the import dialog), author and description. The most important member is doImport(self, params) which does the import and returns a list of datasets (ImportDataset1D, ImportDataset2D and ImportDatasetText objects):
1 class ImportDataset1D(object):
2 """Return 1D dataset."""
3 def __init__(self, name, data=None, serr=None, perr=None, nerr=None):
4 """1D dataset
5 name: name of dataset
6 data: data in dataset: list of floats or numpy 1D array
7 serr: (optional) symmetric errors on data: list or numpy array
8 perr: (optional) positive errors on data: list or numpy array
9 nerr: (optional) negative errors on data: list or numpy array
10
11 If errors are returned for data implement serr or nerr and perr.
12 nerr should be negative values if used.
13 perr should be positive values if used.
14 """
15
16 class ImportDataset2D(object):
17 """Return 2D dataset."""
18 def __init__(self, name, data, rangex=None, rangey=None):
19 """2D dataset.
20 name: name of dataset
21 data: 2D numpy array of values or list of lists of floats
22 rangex: optional tuple with X range of data (min, max)
23 rangey: optional tuple with Y range of data (min, max)
24 """
25
26 class ImportDatasetText(object):
27 """Return a text dataset (only available in Veusz 1.9 or greater)."""
28 def __init__(self, name, data):
29 """A text dataset
30 name: name of dataset
31 data: data in dataset: list of strings
32 """
In fact these are aliases to Dataset1D, Dataset2D and DatasetText classes (PluginDatasetTypes), which should be used with Veusz 1.9 or greater.
The parameters passed to doImport in params are the object:
1 class ImportPluginParams(object):
2 """Parameters to plugin are passed in this object."""
3 def __init__(self, filename, encoding, field_results):
4 self.filename = filename
5 self.encoding = encoding
6 self.field_results = field_results
7
8 def openFileWithEncoding(self):
9 """Helper to open filename but respecting encoding."""
The attributes are filename (filename to import), encoding (character encoding to use for reading if appropriate) and field_results (dict of values from the fields of the plugin). params also includes a useful openFileWithEncoding method which returns a file object with reads text from the filename with the encoding requested by the user.
The class can also include a getPreview(self, params) member for returning a preview view of the file (by default the first 4kb of text). This should read the file in the parameters and return a tuple (text, ok), where text is the text to display and ok is a boolean saying whether the import should be allowed.
If the plugin wants to receive input from the user it can define a fields member which is a list of ImportField objects. There are various possible field types possible:
1 class ImportField(object):
2 """A class to represent an input field on the dialog or command line."""
3 def __init__(self, name, descr=None, default=None):
4 """name: name of field
5 descr: description to show to user
6 default: default value."""
7
8 class ImportFieldCheck(ImportField):
9 """A check box on the dialog."""
10
11 class ImportFieldText(ImportField):
12 """Text entry on the dialog."""
13
14 class ImportFieldFloat(ImportField):
15 """Enter a floating point number."""
16
17 class ImportFieldCombo(ImportField):
18 """Drop-down combobox on dialog."""
19 def __init__(self, name, descr=None, default=None, items=(),
20 editable=True):
21 """name: name of field
22 descr: description to show to user
23 default: default value
24 items: items in drop-down box
25 editable: whether user can enter their own value."""
In versions of Veusz 1.9 or greater, this list is a lot longer. See PluginFields.
Example plugin
This is a plugin which reads unformatted numbers from a file. The user can give the name for the dataset (name field). There are also options to invert the input data (invert checkbox), multiply the values by a figure (mult float field) or subtract a value (subtract combo drop down list).
1 from veusz.plugins import *
2
3 class ImportPluginExample(ImportPlugin):
4 """An example plugin for reading a set of unformatted numbers
5 from a file."""
6
7 name = "Example plugin"
8 author = "Jeremy Sanders"
9 description = "Reads a list of numbers in a text file"
10
11 def __init__(self):
12 ImportPlugin.__init__(self)
13 self.fields = [
14 ImportFieldText("name", descr="Dataset name", default="name"),
15 ImportFieldCheck("invert", descr="invert values"),
16 ImportFieldFloat("mult", descr="Multiplication factor", default=1),
17 ImportFieldCombo("subtract", items=("0", "1", "2"),
18 editable=False, default="0")
19 ]
20
21 def doImport(self, params):
22 """Actually import data
23 params is a ImportPluginParams object.
24 Return a list of ImportDataset1D, ImportDataset2D objects
25 """
26 f = params.openFileWithEncoding()
27 data = []
28 mult = params.field_results["mult"]
29 sub = float(params.field_results["subtract"])
30 if params.field_results["invert"]:
31 mult *= -1
32 for line in f:
33 data += [float(x)*mult-sub for x in line.split()]
34
35 return [ImportDataset1D(params.field_results["name"], data)]
36
37 importpluginregistry.append(ImportPluginExample())