Welcome to Clappform’s API Wrapper¶

Indices and tables¶

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.

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) → App¶

Get a single app.

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

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=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) – Time to sleep per request.

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

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

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.App(collections: int, default_page: str, description: str, groups: int, id: str, name: str, settings: dict)¶

Bases: object

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¶

path() → str¶

Return the route used to retreive the App.

Returns: App API route
Return type: str

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

Bases: object

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¶

path() → str¶

Return the route used to retreive the Collection.

Returns: Collection API route
Return type: str

dataframe_path() → str¶

Return the route used to retreive the Dataframe.

Returns: Dataframe API route
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: Optional[list] = None)¶

Bases: object

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¶

path() → str¶

Return the route used to retreive the Query.

Returns: Query API route
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: Optional[list] = None, tasks: Optional[list] = None)¶

Bases: object

Actionflow dataclass.

id: int¶

name: str¶

settings: dict¶

cronjobs: list = None¶

tasks: list = None¶

path() → str¶

Return the route used to retreive the Actionflow.

Returns: Actionflow 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.

Welcome to Clappform’s API Wrapper¶

Indices and tables¶

Developer interface¶

clappform.dataclasses¶

clappform.exceptions¶

Clappform

Navigation

Related Topics