Skip to content
This repository has been archived by the owner on Apr 2, 2023. It is now read-only.
/ geckopush Public archive

Easy to use python 3 library for pushing data your custom Geckoboard push widgets

License

Notifications You must be signed in to change notification settings

patleeman/geckopush

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

44 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

THIS LIBRARY IS NOT ACTIVELY MAINTAINED.

If you fork it, let me know and I can direct users to your fork.

#Geckopush v 0.4 ###Easy to use python library for pushing data your custom Geckoboard widgets. Geckopush makes pushing data to your Geckoboard.com custom widgets painless. It handles structuring your widgets' JSON, request, and subsequent push to Geckoboard's servers. It takes the difficult work out of getting your custom data to your dashboard.

For Geckoboard specific custom widget information, please refer to the developer docs. ###Geckoboard API Docs

##Installation:

Use PyPI:

pip install geckopush

##Quickstart:

from Geckopush import geckopush

# Initialize your dashboard by creating a dashboard object and assigning it to a variable.  You must provide the api_key parameter.
>>> api_key = '<api key from geckoboard>'
>>> d = geckopush.Dashboard(api_key)

# Wrangle up your data from your custom source.  Please see below for specifics of the data types that each widget accepts.
>>> data = [1, 2, 3, 4, 5]

# Grab the widget key for your custom widget from geckoboard.
>>> widget_key = '<widget key from geckoboard bar chart custom widget>'

# Create your bar chart widget and specify which dashboard object it is in and the widget key.
>>> bar_chart = geckopush.BarChart(dashboard=d, widget_key=widget_key)

# Add data.  Must be called once for each set of data and all data must be complete.  This means you can't add one parameter then call .add_data again to add a separate parameter on the next line.
>>> bar_chart.add_data(data)

# Add widget parameters (usually optional).  Additional fields correspond to optional fields in the Geckoboard documentation.
>>> bar.x_axis_labels = ["one", "two", "three"]
>>> bar.x_axis_type = "standard"
>>> bar.y_axis_format = "decimal"

# Push the data to the dashboard
>>> bar.push()

That's it, you've push some data to your geckoboard widget!

Note: you can declare your first set of data while initializing your widget or afterwards using the .add_data method.

>>> bar_chart = geckopush.BarChart(dashboard=d, widget_key=widget_key, data=[1,2,3,4,5]

or

>>> bar_chart = geckopush.BarChart(dashboard=d, widget_key=widget_key)
>>> bar_chart.add_data([1,2,3,4,5])

Geckopush also has a convient push_all function within the Dashboard class (Dashboard.push_all()) allows you to first initialize all your widgets, add data, then with a single command push data to your widgets.:

>>> from Geckopush import geckopush

>>> api_key = '<api key from geckoboard>'
>>> d = geckopush.Dashboard(api_key)

# Initialize your widgets but do not call the push() method yet.
# Widget 1
>>> data = [1, 2, 3, 4, 5]
>>> widget_key = '<widget key from geckoboard bar chart custom widget>'
>>> bar_chart = geckopush.BarChart(dashboard=d, widget_key=widget_key, data=data)
>>> bar.x_axis_labels = ["one", "two", "three"]
>>> bar.x_axis_type = "standard"
>>> bar.y_axis_format = "decimal"

# Widget 2
>>> bullet_widget_key = "<widget key from geckoboard bullet graph custom widget>"
>>> bullet = geckopush.BulletGraph(dashboard=d,
                               widget_key=bullet_widget_key)

>>> bullet.add_data(
            orientation='vertical',
            label='Test Bullet Graph',
            axis=["0", "200", "400", "600", "800", "1000"],
            comparative="200",
            measure_start="0",
            measure_end="500",
            red_start=0,
            red_end=100,
            amber_start=101,
            amber_end=600,
            green_start=601,
            green_end=1000,
            sublabel="A test Bullet graph",
            projected_start='100',
            projected_end='900'
            )

# Then push to all your widgets at once as a method of the dashboard.
>>> d.push_all()

It's that easy!

Notes:

  • You must supply an API key for each dashboard. This is your account API key located in your Geckoboard settings.

  • Each widget requires you to specify the dashboard and widget_key.

    >>> dash = geckopush.Dashboard('API-KEY')
    >>> custom_widget = geckopush.<widget>(dashboard=dash, ...)

#Geckopush Structure

Geckopush is structured in three layers:

  • Dashboard layer: You interface with Geckopush by creating a Dashboard object first with the required parameters. This object contains your account's API key, which can be found under your account details -> API Key.

    >>> from Geckopush import geckopush
    >>> d = geckopush.Dashboard(api_key="API-Key-Goes-Here")
  • Widget layer: This layer contains your custom widgets' data including which dashboard it belongs to and its widget key. This object holds the relevant data points and methods to construct and POST your JSON payload.

    >>> widget = geckopush.LineChart(dashboard=d, widget_key="Widget-Key-Goes-Here")
  • Data layer: This is the data payload that you push to Geckoboard's servers. This contains the JSON payload in a specific structure as laid out in the Geckoboard API Docs. Each widget has a slightly different payload scheme and must be configured very specifically in order to successfully complete your POST request.

    # Adding a parameter to your widget (note: the text widget does not contain any parameters, calling .add will raise an exception on this widget.)
    >>> lc.add(x_axis_type="datetime")
    >>> lc.add(y_axis_format="currency")
    >>> lc.add(y_axis_unit="USD")
    
    # Adding a data point to your widget
    >>> lc.add_data(name="One", data=[400, 500, 900, 900, 1000])
    >>> lc.add_data(name="Two", data=[1000, 900, 800, 200, 100])

The data layer is split into two types of data:

  • widget attributes (added to your widget with the .add() method)
  • data points (added to your widget with the .add_data() method)

This distinction affects how one accesses Geckopush's interface. For widget attributes, you can usually call an attribute after setting it with .add.
To retrieve the values, call

>>> widget.attribute_name
ex: 
>>> lc.x_axis_type
"datetime"

To call data points, if a widget contains more than a single data point, you can call widget.data which will return a list with the formatted data points already initialized.

Widget Types and Parameters

Universal Instance Variables and Methods

All widgets inherit from a base Widget class which have methods and instance variables that are accessable from all widget subclasses.

Widget Class Variable/Methods Notes
self.dashboard Stores the reference to the dashboard object
self.api_key Stores the dashboard api_key
self.widget Stores the widget key associated with the widget
self.get_payload() Method which assembles the payload and returns it. The payload is not assembled until either this method or push() is called.
self.push() Method which assembles the payload, forms the POST request, and pushs the data to Geckoboard's servers.

If you wanted to see the structure of the final JSON after executing the .push() method, call self.payload.

Bar Chart

Parameter Name Optional Data Type Instance Variable Name Notes
data no list self.data list must contain integers
x_axis_labels yes list self.x_axis_labels list must contain strings
x_axis_type yes string self.x_axis_type
y_axis_format yes string self.y_axis_format
y_axis_unit yes string self.y_axis_unit
Instance Methods Accepts Parameters Notes
self.add_data() data variables stored in self.data
self.add() x_axis_labels, x_axis_type, y_axis_format, y_axis_unit

######Example:

bar = geckopush.BarChart(dashboard=d, widget_key=bar_widget_key, data=[1,2,3,4,5,6,7,8,9,10])
bar.x_axis_labels = ["one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"]
bar.x_axis_type = "standard"
bar.y_axis_format = "decimal"
bar.y_axis_unit = "USD"
bar.push()

Bullet Graph

Parameter Name Optional Data Type Instance Variable Name Notes
orientation yes string self.orientation
label no string stored in self.data
axis no list list must contain strings
red_start no integer stored in self.data
red_end no integer stored in self.data
amber_start no integer stored in self.data
amber_end no integer stored in self.data
green_start no integer stored in self.data
green_end no integer stored in self.data
measure_start no string stored in self.data
measure_end no string stored in self.data
projected_start no string stored in self.data
projected_end no string stored in self.data
comparative no string stored in self.data
sublabel yes string stored in self.data
Instance Methods Accepts Parameters Notes
self.add_data() label, axis, red_start, red_end, amber_start, amber_end, green_start, green_end, measure_start, measure_end, projected_start, projected_end, comparative, sublabel
self.add() orientation

######Example:

bullet = geckopush.BulletGraph(dashboard=d,
                               widget_key=bullet_widget_key,
                               label='Test Bullet Graph',
                               axis=["0", "200", "400", "600", "800", "1000"],
                               comparative="200",
                               measure_start="0",
                               measure_end="500",
                               red_start=0,
                               red_end=100,
                               amber_start=101,
                               amber_end=600,
                               green_start=601,
                               green_end=1000,
                               sublabel="A test Bullet graph",
                               projected_start='100',
                               projected_end='900',
                               )
bullet.add_data(
   label='Second Bullet Graph',
   axis=["0", "200", "400", "600", "800", "1000"],
   comparative="100",
   measure_start="0",
   measure_end="800",
   red_start=0,
   red_end=200,
   amber_start=201,
   amber_end=300,
   green_start=301,
   green_end=1000,
   sublabel="womp womp womp",
   projected_start='600',
   projected_end='900'
)
bullet.push()

Funnel

Parameter Name Optional Data Type Instance Variable Name Notes
value no string stored in self.data
label no string stored in self.data
funnel_type yes string self.funnel_type
percentage yes string self.percentage
Instance Methods Accepts Parameters Notes
self.add_data() value, label

######Example:

fun = geckopush.Funnel(dashboard=d, widget_key=funnel_widget_key)
fun.add_data(100, "one hundred")
fun.add_data(200, "two hundred")
fun.add_data(300, "three hundred")
fun.add_data(400, "four hundred")
fun.add_data(500, "five hundred")
fun.add_data(600, "six hundred")
fun.add_data(700, "seven hundred")
fun.add_data(800, "eight hundred")

fun.push()

Geck-o-meter

Parameter Name Optional Data Type Instance Variable Name Notes
item no integer self.item
min_value no integer self.min_value
max_value no integer self.max_value
Instance Methods Accepts Parameters Notes
self.add_data() item, min_value, max_value

######Example:

gm = geckopush.GeckoMeter(dashboard=d, widget_key=geckometer_widget_key,
                          item=26, min_value=0, max_value=50)
gm.push()

Highcharts

Parameter Name Optional Data Type Instance Variable Name Notes
highchart no string self.highchart highchart code must be within a string
Instance Methods Accepts Parameters Notes
self.add_data() highchart

######Example:

    highchart_str = "<HighCharts String>"
    hc = geckopush.HighCharts(dashboard=d,
                         widget_key=highchart_widget_key,
                         highchart=highchart_str)
    hc.push()

Leaderboard

Parameter Name Optional Data Type Instance Variable Name Notes
label no string stored in self.data
value yes integer stored in self.data
previous_rank yes string stored in self.data
number_format yes string self.number_format
unit yes string self.unit
Instance Methods Accepts Parameters Notes
self.add_data() label, value, previous_rank Widget accepts a max of 22 labels.

######Example:

lb = geckopush.Leaderboard(dashboard=d, widget_key=leaderboard_widget_key)
lb.add_data("Jack", 100, 200)
lb.add_data("Bob", 50, 50)
lb.add_data("Renaldo", 100, 20)
lb.add_data("Barney", 0, 0)
lb.add_data("Farnsworth", 96, 4)
lb.push()

Line Chart

Parameter Name Optional Data Type Instance Variable Name Notes
data no list stored in self.data
name yes string stored in self.data
incomplete_from yes string stored in self.data
series_type yes string stored in self.data
x_axis_labels yes list self.x_axis_labels list must contain strings
x_axis_type yes string self.x_axis_type
y_axis_format yes string self.y_axis_format
y_axis_unit yes string self.y_axis_unit
Instance Methods Accepts Parameters Notes
self.add_data() data, name, incomplete_from, series_type
self.add() x_axis_labels, x_axis_type, y_axis_format, y_axis_unit

######Example:

lc = geckopush.LineChart(dashboard=d, widget_key=linechart_widget_key)
lc.add_data(name="One", data=[400, 500, 900, 900, 1000])
lc.add_data(name="Two", data=[1000, 900, 800, 200, 100])
lc.add(x_axis_labels=["2015-10-01", "2015-10-02", "2015-10-03", "2015-10-04", "2015-10-06"])
lc.add(x_axis_type="datetime")
lc.add(y_axis_format="currency")
lc.add(y_axis_unit="USD")
lc.push()

List

Parameter Name Optional Data Type Instance Variable Name Notes
text no string stored in self.data
name yes string stored in self.data
color yes string stored in self.data
description yes string stored in self.data
Instance Methods Accepts Parameters Notes
self.add_data() text, name, color, description

######Example:

lt = geckopush.List(dashboard=d,
                    widget_key=lst_widget_key)
lt.add_data(text="12345", name="numbers",
            color="#ff2015", description="These are numbers")
lt.add_data(text="abcde", name="letters", color= "#ffffff", description="These are letters")
lt.push()

Map

Parameter Name Optional Data Type Instance Variable Name Notes
city_name string stored in self.data
country_code string stored in self.data
region_code string stored in self.data
latitude float stored in self.data
longitude float stored in self.data
ip string stored in self.data
host string stored in self.data
Instance Methods Accepts Parameters Notes
self.add_data() city_name, country_code, region_code, latitude, longitude, ip, host

When adding a map point, the method checks whether the correct set of variables are input. For example, you can only call city_name, country_code, and region_code in the same add_data() call. If you try to mix city_name and longitude, the method will raise an error. The method also checks if both a text and secondary value are supplied and raises an error if so.

######Example:

mp = geckopush.Map(dashboard=d, widget_key=map_widget_key)
mp.add_data(city_name="New York", country_code="US", size="10")
mp.add_data(host="google.com")
mp.add_data(ip="46.228.47.115")
mp.add_data(latitude=22.434355, longitude=11.12345, size=5, color="#ffffff")
mp.push()

Monitoring

Parameter Name Optional Data Type Instance Variable Name Notes
status no string self.status accepts "up" or "down"
downtime yes string self.downtime
responsetime yes string self.responsetime
Instance Methods Accepts Parameters Notes
self.add_data() status, downtime, responsetime

######Example:

monitoring_widget_key = WIDGET_KEYS["monitoring_widget_key"]
mo = geckopush.Monitoring(dashboard=d, widget_key=monitoring_widget_key)
mo.add_data(status="up", downtime="Never", responsetime= "123 ms")
mo.push()

Number and Secondary Stat

When adding values to the Number and Secondary Stat widget, you must add all data either during instantiation or at once with the .add_data() method. You can not .add_data(primary_value=123) and then .add_data(secondary_value=456). It must be specified in the same call i.e. .add_data(primary_value=123, secondary_value=456).

Parameter Name Optional Data Type Instance Variable Name Notes
primary_value no int, float stored in self.data
secondary_value yes int, float, list stored in self.data. list must contain integers or floats
text yes string stored in self.data
prefix yes string stored in self.data
metric_type yes string self.metric_type
absolute yes string self.absolute
Instance Methods Accepts Parameters Notes
self.add_data() primary_value, secondary_value, text, prefix
self.add() metric_type, absolute

The add_data() method checks whether the secondary_value is a single number or a list of numbers for use in a line chart to be displayed underneath the primary number.

######Example:

ns = geckopush.NumberAndSecondaryStat(dashboard=d, widget_key=widget_key)
ns.add_data(primary_value=15, secondary_value=25)
ns.push()

or 

ns = geckopush.NumberAndSecondaryStat(dashboard=d, widget_key=widget_key)
ns.add_data(primary_value=15, text="Hola Amigo")
ns.push()

of

ns = geckopush.NumberAndSecondaryStat(dashboard=d, widget_key=widget_key)
ns.add_data(primary_value=15, secondary_value=[5,10,15,20])
ns.push()

Pie Chart

Parameter Name Optional Data Type Instance Variable Name Notes
value no int, float? stored in self.data
label no string stored in self.data
color yes string stored in self.data
Instance Methods Accepts Parameters Notes
self.add_data() value, label, color

######Example:

pi = geckopush.PieChart(dashboard=d, widget_key=piechart_widget_key)
pi.add_data(100, "Slice 1", "13699c")
pi.add_data(200, "Slice 2", "198acd")
pi.push()

RAG (Red, Amber, Green)

Push to both RAG Number and RAG Column widgets.

Parameter Name Optional Data Type Instance Variable Name Notes
text no string stored in self.data
value yes integer stored in self.data
prefix yes string stored in self.data
reverse_type yes self.reverse_type API only accepts "reverse" string
color yes string Accepts "red", "amber" or "green" only
Instance Methods Accepts Parameters Notes
self.add_data() text, value, prefix
self.add() reverse_type

*Color: The Geckoboard API detects color assignment to Red, Amber or Green through the positioning of the text/value/prefix payloads. This optional parameter allows you to specify the exact color you want to assign the data to without having to declare your data points in order. If omitted, the .add_data() method will assign it to the next unassigned color in the order from Red->Amber->Green.

######Example:

rg = geckopush.RAG(dashboard=d, widget_key=widget_key)
rg.add_data(text="One", value=50, prefix="$", color="green")
rg.add_data(text="Two", value=100, prefix="$", color="amber")
rg.add_data(text="Three", value=150, prefix="$")  # Will be assigned to red automatically.
rg.push()

Text

Parameter Name Optional Data Type Instance Variable Name Notes
text no string stored in self.data
text_type yes integer stored in self.data
Instance Methods Accepts Parameters Notes
self.add_data() text, text_type

This widget accepts a max of 10 text items.

######Example:

rg = geckopush.Text(dashboard=d, widget_key=widget_key)
rg.add_data(text="Hello There My Friend", type=0)
rg.add_data(text="How are you doing?", type=1)
rg.push()

For questions, issues, bugs please contact the author through github or email.

About

Easy to use python 3 library for pushing data your custom Geckoboard push widgets

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages