API Reference

Arrow

Arrow(self, name:str='app')

The arrow object is the main interface between application code and the Gridarrow infrastructure. Once it is created it will act as a central registry of periodic functions and a factory for creating Grids.

Example

from gridarrow import Arrow

arrow = Arrow()

Arguments

  • name (string): [Optional] name of this app, used in logging. Defaults to “app”.

initialize

Arrow.initialize(self, func)

Calls the decorated function to allow initialization of the app. The return value of this function will be passed to the @arrow.on_xxx and @arrow.webhook functions as the first argument.

Example

@arrow.initialize
def initialize():
    grid = arrow.grid(...)
    return dict(grid=grid)

@arrow.on_start
def start(context):
    # pass

Raises

  • ArrowException: If the decorated function does not accept zero arguments.

on_start

Arrow.on_start(self, func)

Calls the decorated function once, on start of the app. The decorated function must accept one argument, which is the return value from the initialize function.

Example

@arrow.on_start
def start(context):
    pass

on_stop

Arrow.on_stop(self, func)

Calls the decorated function once, as the app is shutting down. It can be used for unsubscribing from datafeeds cleanly etc. The decorated function must accept one argument, which is the return value from the initialize function.

Nb. This function will NOT be called if the process ends with an exception.

Example

@arrow.on_stop
def stop(context):
    pass

on_timer

Arrow.on_timer(self, duetime=0, period=None, repeat=None)

Calls the decorated function after duetime has elapsed, and optionally repeatedly on a timer. The decorated function must accept one argument, which is the return value from the initialize function.

Arguments

  • duetime (int): Relative time (specified as an integer denoting seconds) at which to first call the function. Default is 0, meaning the timer will fire immediately.
  • period (int): [Optional] Period (specified as an integer denoting seconds) for calling the function. If not specified the resulting timer is not recurring.
  • repeat (int): [Optional] Number of times the function should be called in total. If not specified the timer will repeat indefinitely.

Example

In this example the timer function will be called immediately, and then every 5 seconds for a total of 10 executions.

@arrow.on_timer(duetime=0, period=5, repeat=10)
def timer(context):
    pass

on_schedule

Arrow.on_schedule(self, crontab, *, timezone='UTC', initialize=False, repeat=None)

Calls the decorated function according to a cron expression. The decorated function must accept one argument, which is the return value from the initialize function.

A cron expression is a string comprising five fields that represents a set of times, separated by white space.

Field Required Allowed values Allowed special characters
Minutes Yes 0-59 * , -
Hours Yes 0-23 * , -
Day of month Yes 1-31 * , - L
Month Yes 1-12 or JAN-DEC * , -
Day of week Yes 0-6 or SUN-SAT * , - L

crontab.guru can be useful for generating a cron expression, and has a good list of example crontabs.

Arguments

  • crontab: (str): A cron expression.
  • timezone: (str): [Optional] The timezone in which the crontab should be evaluated. Default UTC. Valid timezones can be listed with pytz.all_timezones
  • initialize: (bool): [Optional] if True the decorated function will be called immediately, irregardless of the cron expression. Default is False.
  • repeat: (int): [Optional] Number of times the function should be called in total. If not specified the timer will repeat indefinitely.

Example

In this example the schedule function will be called immediately (initialize=True), and then at 5 minutes past 9am on MON-FRI, in the US/Pacific timezone.

@arrow.on_schedule(crontab="5 9 * * MON-FRI", timezone='US/Pacific', initialize=True)
def schedule(*args):
    pass

Raises

  • UnknownTimeZoneError: If passed an unknown timezone.

webhook

Arrow.webhook(self, rule, **options)

Calls the decorated function when a webhook is received matching the URL rule. The decorated function must accept at least two arguments, which are the return value from the initialize function, and the werkzeug request object.

Rule path variables (eg. /user/<int:user_id>) will be passed as additional positional parameters to the decorated function.

For more information refer to http://werkzeug.pocoo.org/docs/0.14/routing/`rule`-format.

Arguments

  • rule: (str): the URL rule as string
  • options: (**kwargs): the options to be forwarded to the underlying werkzeug.routing.Rule object. A change to Werkzeug is handling of method options. methods is a list of methods this rule should be limited to (GET, POST etc.). By default a rule just listens for GET (and implicitly HEAD).

Examples

@arrow.webhook('/', methods=['POST'])
def endpoint(context, request):
    data = json.loads(request.data)

@arrow.webhook('/user/<int:user_id>', methods=['POST'])
def endpoint2(context, request, user_id):
    data = json.loads(request.data)

grid

Arrow.grid(self, topic:str, *, description:str=None, rows:Union[int, List[str]], columns:Union[int, List[str]], default_value:gridarrow.api_v1.gapic.enums.DefaultValue=<DefaultValue.NA: 0>)

Create a new Grid

Arguments

  • topic (str): Name of this grid as it will appear in the Gridarrow Excel Add-in. Must be unique within this application. Must consist only of ascii letters, digits or punctuation !"#$%&'()*+,-./\:;<=>[email protected][]^_{}~. Note, ‘|’ symbol is disallowed.
  • description (str): [Optional] A description of the contents and behaviour of this grid.
  • rows (Union[int, List[str]]): If int, the number of rows the grid will have. If List, the names of the rows, which must all be strings.
  • columns (Union[int, List[str]]): If int, the number of columns the grid will have. If List, the names of the columns, which must all be strings.
  • default_value (DefaultValue): the value of a cell when it is unset.

Example

The example below will create a new grid with 10 rows and 3 named columns.

grid = arrow.grid("cooldata", description="Useful data",
                  rows=10,
                  columns=["foo", "bar", "baz"])

Raises

  • ArrowException: If the grid already exists, or the topic contains disallowed characters.

log

Returns a python logger configured at INFO level.

To change the log level, set an environment variable LOG_LEVEL=CRITICAL|ERROR|WARNING|INFO|DEBUG using the App Secrets.

Example

arrow.log.critical("msg")
arrow.log.error("msg")
arrow.log.warning("msg")
arrow.log.info("msg")
arrow.log.debug("msg")

Grid

Grid(self, name:str, app, *, description:str=None, data=None, rows=None, columns=None, default_value:gridarrow.api_v1.gapic.enums.DefaultValue=None)

rows

returns the row labels as a list


columns

returns the column labels as a list


setitem

Grid.__setitem__(self, key, value)

Update the grid values at key with value. Key may be either int, str, list, slice or tuple, where the the type of the key should be int or str depending on if the grid is labeled.

Arguments

N.b. Only one key argument from the following argument types is required.

  • key (int): Selects the row of the non row-labelled grid at the index passed
  • key (str): Selects the row of the row-labelled grid with the label passed
  • key (list): Selects multiple rows of the grid. For example, [0, 2, 4] or [‘a’, ‘c’, ‘e’]
  • key (slice): Selects multiple rows of the grid using a slice. For example, [0:4]
  • key (tuple): Selects rows and columns using a combination or row and column indexing - (row, column) order.
  • value: The new value(s) for the grid. Must be “broadcastable” to the shape inferred by the key.

Examples

grid = arrow.grid('foo', rows=3, columns=3)

grid[0, 1] = 0
grid[0, [1, 2]] = [0, 0]
grid[[0, 1], 0] = [[0], [0]]
grid[[0, 1], [0, 1]] = [[0, 0], [0, 0]]

grid2 = arrow.grid('bar', rows=['a','b','c'], columns=['x','y','z'])

grid2['a', 'x'] = 0
grid2['a', ['x', 'y']] = [0, 0]
grid2[['a', 'b'], 'x'] = [[0], [0]]
grid2[['a', 'b'], ['x', 'y']] = [[0, 0], [0, 0]]

Raises

  • IndexError: If the grid key was not valid