Operation Functions¶
Operations functions are regular Python function that perform actions on the book. Examples of operations are: sheets.import_data
, columns.add_column
, columns.update_column
, and more.
They have a function
name that identifies them, an optional description and a number of parameters that they accept. Different operation functions accept different parameters.
- All operations accepts the following arguments:
name
: The name idnetifying the operation functiondescription
: Optional. A description to print on screen when the operation gets executedparams
: Parameter for the operation. This varies by operation. See below for a detailed list.context
: Optional. An additional set of properties that can be made available to the operation. This can be used in expression or interpolated in strings (by using the{{ my var }}
sysntax).enabled
: Optional. Set this toFalse
to skip execution of the operation. Useful for debug. Defaults toTrue
.
Available Operation Functions¶
sheets.import_data
¶
Creates a new sheet importing data from an external source.
- params:
filename
: Required.sheet
: Optional. Defaults tofilename
‘s basename.format
: Values currently supported are'csv'
and'json'
.headers
: Optional. Defaults to null, meaning that the importer tries to autodetects the header names.encoding
: Optional. Defaults to'utf-8'
.skip_first_lines
: Optional. Defaults to0
. Supported only by the CSV importer.skip_Last_lines
: Optional. Defaults to0
. Supported only by the CSV importer.guess_types
: Optional. If set totrue
, the CSV importer will try to guess the data type. Defaults totrue
.replace
: Optional. if set totrue
and the sheet already exists, its content will be replaced. if set tofalse
, the new data will be appended. Defaults tofalse
.
sheets.add
¶
- params:
name
headers
(optional)
Adds a new empty sheet named name
. Optionally sets its headers as specified in headers
.
sheets.copy
¶
- params:
source
destination
headers
(optional)
Create a copy of the source
sheet named destination
. Optionally copies only the headers specified in headers
.
sheets.export_data
¶
- params:
sheet
format
filename
headers
(optional)
Exports the datasheet named sheet
to the file named filename
in the specified format
. Optionally exports only the headers specified in headers
.
sheets.print_data
¶
- params:
sheet
columns.update_column
¶
- params:
sheet
column
facets
(optional)values
expression
Either values
or expression
are required.
columns.remove_column
¶
- params:
sheet
name
columns.rename_column
¶
- params:
sheet
old_name
new_name
columns.to_float
¶
- params:
sheet
column
facets
(optional)
columns.to_integer
¶
- params:
sheet
column
facets
(optional)
columns.to_decimal
¶
- params:
sheet
column
facets
(optional)
columns.to_text
¶
- params:
sheet
column
facets
(optional)
columns.to_datetime
¶
- params:
sheet
column
facets
(optional)
system.call_command
¶
Calls an external command with the provided arguments.
- params:
command
arguments
system.remove_dir
¶
Deletes a directory and all of its content.
- params:
path
: The path of the directory. Either absolute or relative to the build file.
system.make_dir
¶
Creates a directory recursively.
- params:
path
: The path of the directory. Either absolute or relative to the build file.
operations.define_operation
¶
Define an alias to an operation with default params that can be reused.
- params:
name
: how you want to name your operation. This is name that you will use to call the operation later.operation
: the original path of the operationdefaults
: values that will be used as defaults for the operation. You can override them by using theparams
property when you call your operation
operations.define_task
¶
Define an a task, a list of operations with default params that can be reused.
- params:
name
: How you want to name your task. This is name that you will use to call the task later.operations
: The operations to be applieddescription
: Optional. A description to be printed when calling the task.defaults
: Optional. values that will be used as defaults for the operations. You can override them by using theoverrides
param when you call your task
operations.call_task
¶
Call a previously defined task
- params:
name
: the name your task. This is name that you will use to call the operation later.operations
: the operations to be applieddescription
: Optional. A description to be printed when calling the task.overrides
: values that will override the defaults for the operations.
Custom Operation¶
You can add your custom operation and use them in your buildfile.
An Operation is just a regular python function. The first arguments has to be the context
, but the remaining arguments will be pulled in from the params
property of the operation in the buildfile.
By default, context
is a dict
with following keys:
workbook
: a reference the workbook objectbuildfile
: a reference to the build file the operation has been read from.
def myoperation(context, foo, bar, baz):
pass
Operations are defined in modules, which are just regulare Python files.
As long as your operation modules are in your PYTHONPATH
, you can add them to your OPERATION_MODULES
setting (see operation-modules-setting) and then call the operation in your buildfile by referencing its import path:
[
...,
{
"operation": "mymodule.myoperation",
"description": "",
"params": {
"foo": "foos",
"bar": "bars",
"baz": "bazes"
}
}
]