Welcome to Clappform’s API Wrapper

Indices and tables

• Index

• Module Index

• Search Page

Developer interface

Clappform Python API wrapper

class clappform.Clappform(base_url: str, username: str, password: str, timeout: int = 2)

Bases: object

Clappform class is used to more easily interact with an Clappform environement through the API.

Parameters:

• base_url (str) – Base URL of a Clappform environment e.g. https://app.clappform.com.

• username (str) – Username used in the authentication auth.

• password (str) – Password used in the authentication auth.

• timeout (int) – Optional HTTP request timeout in seconds, defaults to: 2.

Most routes of the Clappform API require authentication. For the routes in the Clappform API that require authentication Clappform will do the authentication for you.

In the example below c.get_apps() uses a route which requires authentication. Clappform does the authentication for you.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> apps = c.get_apps()
>>> for app in apps:
...     print(app.name)

username: str

Username to use in the auth

password: str

Password to use in the auth

timeout: int

HTTP request timeout in seconds.

auth() → None

Sends an authentication request. Gets called whenever authentication is required.

The _auth attribute is set to a newly constructed clappform.dataclasses.Auth object.

verify_auth() → ApiResponse

Verify against the API if the authentication is valid.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

version() → Version

Get the current version of the API.

Returns:

Version Object

Return type:

clappform.dataclasses.Version

get_apps() → list[clappform.dataclasses.App]

Gets all apps.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> apps = c.get_apps()

Returns:

List of clappform.dataclasses.App or empty list if there are no apps.

Return type:

list[clappform.dataclasses.App]

get_app(app, extended: bool = False) → App

Get a single app.

Parameters:

• app (str | clappform.dataclasses.App) – App to get from the API

• extended (bool) – Optional retreive fully expanded app, defaults to false.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> app = c.get_app("clappform")
>>> app = c.get_app(app)

Returns:

App Object

Return type:

clappform.dataclasses.App

create_app(app_id: str, name: str, desc: str, settings: dict) → App

Create a new app.

Parameters:

• app_id (str) – String for internal identification.

• name (str) – Display name for the new app.

• desc (str) – Description for the new app.

• settings (dict) – Configuration options for an app.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> new_app = c.create_app("foo", "Foo", "Foo Bar", {})

Returns:

Newly created app

Return type:

clappform.dataclasses.App

update_app(app) → App

Update an existing app.

Parameters:

app (clappform.dataclasses.App) – Modified app object.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get_app("foo")
>>> app.name = "Bar"
>>> app = c.update_app(app)

Returns:

Updated app object

Return type:

clappform.dataclasses.App

delete_app(app) → ApiResponse

Delete an app.

Parameters:

app (str | clappform.dataclasses.App) – App to delete from the API

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> c.delete_app("foo")

Returns:

Response from the API

Return type:

clappform.dataclasses.ApiResponse

get_collections(app=None, extended: int = 0) → list[clappform.dataclasses.Collection]

Get all the collections.

The extended parameter allows an integer value from 0 - 3.

Parameters:

• app (clappform.dataclasses.Collection) – Optional return only collections from specified app, default: None.

• extended (int) – Optional level of detail for each collection, default: 0.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get_app("foo")
>>> collections = c.get_collections(extended=3)
>>> collections = c.get_collections(app=app)

Raises:

ValueError – extended value not in [0, 1, 2 ,3]

Returns:

List of Collections or empty list if there are no collections

Return type:

list[clappform.dataclasses.Collection]

get_collection(collection, app=None, extended: int = 0, offset: int = 0) → Collection

Get a single collection.

The extended parameter allows an integer value from 0 - 3.

Parameters:

• collection (str | clappform.dataclasses.Collection) – Identifier for collection to retreive.

• app (str | clappform.dataclasses.App) – Required when collection is of type str, default: None.

• extended (int) – Optional level of detail for each collection, default: 0.

• offset (int) – Offset from which to retreive items, only useful when extended is 3.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get_app("foo")
>>> collection = c.get_collection("bar", app=app)
>>> collection = c.get_collection("bar", app="foo")
>>> collection = c.get_collection(collection)

The TypeError is only raised when collection parameter is of type

str

and app parameter is None.

Raises:

• ValueError – extended value not in [0, 1, 2 ,3]

• TypeError – app kwargs must be of type clappform.dataclasses.App or str.

Returns:

Collection Object

Return type:

clappform.dataclasses.Collection

create_collection(app, slug: str, name: str, desc: str, db: str = 'MONGO') → Collection

Create a new Collection.

Parameters:

• app (str | clappform.dataclasses.App.) – App identifier to create collection for.

• slug (str) – Name used for internal identification.

• name (str) – Name of the collection.

• desc (str) – Description of what data the collection holds.

• db (str) – Database where collection is stored. Valid values for db are MONGO and DATALAKE, defaults to: MONGO

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get_app("foo")
>>> new_collection = c.create_collection(
...     app,
...     "bar",
...     "Bar",
...     "Bar Collection"
... )

Returns:

New Collection Object

Return type:

clappform.dataclasses.Collection

update_collection(collection: Collection) → Collection

Update an existing collection.

Parameters:

collection (clappform.dataclasses.Collection) – Collection object to update

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> collection = c.get_collection("bar", app="foo")
>>> collection.name = "Spam & Eggs Collection"
>>> collection = c.update_collection(collection)

Raises:

TypeError – collection arg is not of type clappform.dataclasses.Collection

Returns:

Updated Collection object

Return type:

clappform.dataclasses.Collection

delete_collection(collection: Collection) → ApiResponse

Delete a collection.

Parameters:

collection (clappform.dataclasses.Collection) – Collection to remove

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> collection = c.get_collection("bar", app="foo")
>>> c.delete_collection(collection)

Returns:

API reponse object

Return type:

clappform.dataclasses.Collection

get_queries() → list[clappform.dataclasses.Query]

Get all queries.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> queries = c.get_queries()

Returns:

List of Query objects

Return type:

list[clappform.dataclasses.Query]

get_query(query) → Query

Get single query.

Parameters:

query (str | clappform.dataclasses.Query) – Query identifier

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> query = c.get_query("foo")

Returns:

Query object

Return type:

clappfrom.dataclasses.Query

source_query(query: Query) → ApiResponse

Source a query

Parameters:

query (clappform.dataclasses.Query) – Query to source.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

create_query(data_source: str, query: list, name: str, slug: str, collection=None) → Query

Create a new query.

Parameters:

• data_source (str) – Source of the data either app or filterbar.

• query (list) –

  Query that follows the specification described in

  Query Editor.

• name (str) – Name for the query

• slug (str) – Internal identification string

• collection (clappform.dataclasses.Collection) – Only required when the data_source argument holds the "app" value.

Returns:

New Query object

Return type:

clappform.dataclasses.Query

update_query(query: Query) → Query

Update an existing Query.

Parameters:

query (clappform.dataclasses.Query) – Query object to update.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> query = c.get_query("foo")
>>> query.name = "Bar Query"
>>> query = c.update_query(query)

Returns:

Updated Query object

Return type:

clappform.dataclasses.Query

delete_query(query) → ApiResponse

Delete a Query.

Parameters:

query (str | clappform.dataclasses.Query) – Query identifier

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

aggregate_dataframe(options: dict, interval_timeout: int = 0.1)

Aggregate a dataframe

Parameters:

options (dict) – Options for dataframe aggregation.

Returns:

Generator to read dataframe

Return type:

generator

read_dataframe(query, limit: int = 100, interval_timeout: int = 0.1)

Read a dataframe.

Parameters:

• query (clappform.dataclasses.Query | clappform.dataclasses.Collection) – Query to for retreiving data. When Query is of type clappform.dataclasses.Collection everything inside the collection is retreived.

• limit (int) – Amount of records to retreive per request.

• interval_timeout (int) – Optional time to sleep per request, defaults to: 0.1.

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> query = c.get_query("foo")
>>> it = c.read_dataframe(query)
>>> for i in it:
...     print(i)

Returns:

Generator to read dataframe

Return type:

generator

write_dataframe(df: DataFrame, collection: Collection, chunk_size: int = 100, interval_timeout: int = 0.1)

Write Pandas DataFrame to collection.

Parameters:

• df (pandas.DataFrame) – Pandas DataFrame to write to collection

• collection (clappform.dataclasses.Collection) – Collection to hold DataFrame records

• chunk_size (int) – defaults to: 100

• interval_timeout (int) – Optional time to sleep per request, defaults to: 0.1.

append_dataframe(collection, array: list[dict]) → ApiResponse

Append data to a collection.

Parameters:

• collection (clappform.dataclasses.Collection) – Collection to append data to.

• array (list[dict]) – List of dictionary objects to append.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

sync_dataframe(collection, array: list[dict]) → ApiResponse

Synchronize a dataframe.

Synchronize replaces the existing data with data found in array.

Parameters:

• collection (clappform.dataclasses.Collection) – Collection to append data to.

• array (list[dict]) – Is a list of dictionary objects.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

empty_dataframe(collection) → ApiResponse

Empty a dataframe.

Parameters:

collection (clappform.dataclasses.Collection) – Collection to append data to.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

get_actionflows() → list[clappform.dataclasses.Actionflow]

Get all actionflows.

Returns:

List of clappform.dataclasses.Actionflow or empty list if there are no actionflows.

Return type:

list[clappform.dataclasses.Actionflow]

get_actionflow(actionflow) → Actionflow

Get single actionflow.

Parameters:

actionflow (int | clappform.dataclasses.App) – Actionflow to get from the API

Usage:

>>> from clappform import Clappform
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> af = c.get_actionflow(1)
>>> af = c.get_actionflow(af)

Returns:

Actionflow Object

Return type:

clappform.dataclasses.Actionflow

create_actionflow(name: str, settings: dict) → Actionflow

Create a new actionflow.

Parameters:

• name (str) – Display name for the new actionflow.

• settings (dict) – Settings object

Returns:

New Actionflow object

Return type:

clappform.dataclasses.Actionflow

update_actionflow(actionflow: Actionflow) → Actionflow

Update an existing Actionflow.

Parameters:

actionflow (clappform.dataclasses.Actionflow) – Actionflow object to update.

Returns:

Updated Actionflow object

Return type:

clappform.dataclasses.Actionflow

delete_actionflow(actionflow) → ApiResponse

Delete a Actionflow.

Parameters:

actionflow (int | clappform.dataclasses.Actionflow) – Actionflow identifier

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

get_questionnaires(extended: bool = False) → list[clappform.dataclasses.Questionnaire]

Get all questionnaires

Parameters:

extended (bool) – Optional retreive fully expanded questionnaires, defaults to false.

Returns:

List of clappform.dataclasses.Questionnaire or empty list if there are no questionnaires.

Return type:

list[clappform.dataclasses.Questionnaire]

get_questionnaire(questionnaire, extended: bool = False) → Questionnaire

Get a questionnaire

Parameters:

extended (bool) – Optional retreive fully expanded questionnaire, defaults to false.

Returns:

Qustionnaire Object

Return type:

clappform.dataclasses.Questionnaire

create_questionnaire(name: str, settings: dict) → ApiResponse

Create a new questionnaire.

Parameters:

• name (str) – Display name for the new questionnaire.

• settings (dict) – Settings object

Returns:

ApiResponse object

Return type:

clappform.dataclasses.ApiResponse

update_questionnaire(questionnaire: Questionnaire, settings: dict) → Questionnaire

Update an existing Questionnaire.

Parameters:

• questionnaire (clappform.dataclasses.Questionnaire) – Questionnaire object to update.

• settings (dict) – Settings object

Returns:

Updated Questionnaire object

Return type:

clappform.dataclasses.Questionnaire

delete_questionnaire(questionnaire)

Delete a Questionnaire.

Parameters:

questionnaire (int | clappform.dataclasses.Questionnaire) – Questionnaire identifier

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

export_app(app) → dict

Export an app.

Parameters:

app (str | clappform.dataclasses.App) – App to export

Returns:

Exported App

Return type:

dict

import_app(app: dict, data_export: bool = False) → ApiResponse

Import an app.

Parameters:

app (dict) – Exported app object.

Returns:

Api Response Object

Return type:

clappform.dataclasses.ApiResponse

clappform.dataclasses

This module contains the set of Clappform’s return objects.

class clappform.dataclasses.ApiResponse(code: int, message: str, response_id: str, **kwargs)

Bases: object

Data class to represent generic API response.

Parameters:

• code (int) – HTTP status code.

• message (str) – Message about the request and response.

• response_id (str) – Response Id can be used to open support ticket.

code: int

HTTP status code.

message: str

Message about the request and response.

response_id: str

Response Id can be used to open support ticket.

class clappform.dataclasses.Auth(access_token: str, refresh_expiration: int, refresh_token: str)

Bases: object

Authentication dataclass.

Parameters:

• access_token (str) – Bearer token to be used in a HTTP authorization header.

• refresh_expiration (int) – Integer representing the when the refresh_token is invalid.

• refresh_token (str) – Bearer token to be used get new access_token.

access_token: str

Bearer token to be used in a HTTP authorization header.

refresh_expiration: int

Integer representing the when the refresh_token is invalid.

refresh_token: str

Bearer token to be used get new access_token.

is_token_valid() → bool

Returns boolean answer to: is the access_token still valid?

Returns:

Validity of access_token

Return type:

bool

class clappform.dataclasses.Version(api: str, web_application: str, web_server: str)

Bases: object

Version dataclass.

Parameters:

• api (str) – Version of the API.

• web_application (str) – Version of the Web Application.

• web_server (str) – Version of the Web Server

api: str

Version of the API.

web_application: str

Version of the Web Application.

web_server: str

Version of the Web Server

class clappform.dataclasses.AbstractBase

Bases: object

AbstractBase is used as a base class for dataclasses. AbstractBase contains only one abstract method. Any class that inherits from AbstractBase is required to implement path.

abstract path() → str

Return the route used to by the resource.

Returns:

HTTP path of the resource

Return type:

str

class clappform.dataclasses.App(collections: int, default_page: str, description: str, groups: int, id: str, name: str, settings: dict)

Bases: AbstractBase

App dataclass.

Parameters:

• collections (int) – Number of collections this app has.

• default_page (str) – Page to view when opening app.

• description (str) – Description below app name.

• groups (int) – Nuber of groups in an app.

• id (str) – Used internally to identify app.

• name (str) – Name of the app.

• settings (dict) – Settings to configure app.

collections: int

default_page: str

description: str

groups: int

id: str

name: str

settings: dict

static format_path(app: str, extended: bool = False) → str

Return the route used to retreive the App.

Returns:

App’s HTTP resource path.

Return type:

str

static format_collection_path(app: str) → str

Return the base route used to get and create the App’s collections’.

Returns:

App’s collection HTTP get and create path.

Return type:

str

path(extended: bool = False) → str

Return the route used to retreive the App.

Returns:

App’s HTTP resource path.

Return type:

str

collection_path() → str

Return the base route used to get and create the App’s collections’.

Returns:

App’s collection HTTP get and create path.

Return type:

str

class clappform.dataclasses.Collection(app: str, database: str, name: str, slug: str, items: int | None = None, description: str | None = None, is_encrypted: bool | None = None, is_locked: bool | None = None, is_logged: bool | None = None, queries: list | None = None, sources: list | None = None, id: int | None = None)

Bases: AbstractBase

Collection dataclass.

app: str

database: str

name: str

slug: str

items: int = None

description: str = None

is_encrypted: bool = None

is_locked: bool = None

is_logged: bool = None

queries: list = None

sources: list = None

id: int = None

static check_extended(extended: int)

Check if extended is of type int and 0 to 3.

static format_base_path(app: str, extended: int = 0) → str

Return the route used for getting all and creating collections.

Returns:

Collection getting and creating HTTP path

Return type:

str

base_path(extended: int = 0) → str

Return the route used for getting all and creating collections.

Returns:

Collection getting and creating HTTP path

Return type:

str

static format_path(app: str, collection: str, extended: int = 0) → str

Return the route used to retreive the collection.

Parameters:

• app (str) – App to which collection belongs to.

• collection (str) – Collection to get from app.

• extended (int) – Optional level to which the fields get expanded, defaults to: 0

Returns:

Collection’s HTTP resouce path

Return type:

str

path(extended: int = 0) → str

Return the route used to retreive the Collection.

Parameters:

extended (int) – Level to which the fields get expanded.

Returns:

Collection API route

Return type:

str

dataframe_path() → str

Return the route used to retreive the Dataframe.

Returns:

Collection’s Dataframe HTTP resource path

Return type:

str

class clappform.dataclasses.Query(app: str, collection: str, data_source: str, export: bool, id: int, name: str, query: list, slug: str, source_query: str, modules: list | None = None)

Bases: AbstractBase

Query dataclass.

app: str

collection: str

data_source: str

export: bool

id: int

name: str

query: list

slug: str

source_query: str

modules: list = None

static format_path(query: str) → str

Return the route used to retreive the Query.

Returns:

Query HTTP resource path

Return type:

str

path() → str

Return the route used to retreive the Query.

Returns:

Query HTTP resource path

Return type:

str

source_path() → str

Return the route used to source the Query.

Returns:

Source Query API route

Return type:

str

class clappform.dataclasses.Actionflow(id: int, name: str, settings: dict, cronjobs: list | None = None, tasks: list | None = None)

Bases: AbstractBase

Actionflow dataclass.

id: int

name: str

settings: dict

cronjobs: list = None

tasks: list = None

static format_path(actionflow: int) → str

Return the route used to retreive the Actionflow.

Parameters:

actionflow (int) – Actionflow id.

Returns:

Actionflow HTTP resource path

Return type:

str

path() → str

Return the route used to retreive the Actionflow.

Returns:

Actionflow HTTP resource path

Return type:

str

class clappform.dataclasses.Questionnaire(name: str, id: int, created_at: int, active: bool, created_by: dict, latest_version: dict, versions: list | None = None)

Bases: AbstractBase

Questionnaire dataclass.

name: str

id: int

created_at: int

active: bool

created_by: dict

latest_version: dict

versions: list = None

static format_path(questionnaire: int, extended: bool = False) → str

Return the route used to retreive the Questionnaire.

Parameters:

• questionnaire (int) – Questionnaire id.

• extended (bool) – Include versions when retreiving questionnaire.

Returns:

Questionnaire HTTP resource path

Return type:

str

path(extended: bool = False) → str

Return the route used to retreive the Questionnaire.

Parameters:

extended (bool) – Include versions when retreiving questionnaire.

Returns:

Questionnaire API route

Return type:

str

clappform.exceptions

This module contains the set of Clappform’s exceptions.

exception clappform.exceptions.HTTPError(*args, **kwargs)

Bases: HTTPError

An HTTP error occurred.

code: int

HTTP status code from JSON body.

response_id: str

Response Id useful for support ticket.