Welcome to Clappform’s API Wrapper

Clappform allows one to easily connect and interact with a Clappform B.V. API. There is no need to manually program HTTP requests to authenticate and consume the API. Many resources of the API are able to be created, read, updated and deleted. To start using Clappform with logging:

>>> import logging
>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> logging.basicConfig()
>>> logging.getLogger().setLevel(logging.DEBUG)
>>> requests_log = logging.getLogger("urllib3")
>>> requests_log.setLevel(logging.DEBUG)
>>> requests_log.propagate = True
>>> c = Clappform("https://app.clappform.com", "j.doe@clappform.com", "S3cr3tP4ssw0rd!")
DEBUG:urllib3.util.retry:Converted retries value: 3 -> Retry(total=3, connect=None, read=None, redirect=None, status=None)
>>> apps = c.get_apps(r.App())
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): app.clappform.com:443
DEBUG:urllib3.connectionpool:https://app.clappform.com:443 "POST /api/auth HTTP/1.1" 200 1912
DEBUG:urllib3.connectionpool:https://app.clappform.com:443 "GET /api/apps?extended=false HTTP/1.1" 200 37106
>>> for app in apps:
...     print(app.name)

Indices and tables

Developer interface

Clappform Python API wrapper

class clappform.Clappform(base_url: str, username: str, password: str, workers: int = 6, tries: int = 4, backoff_factor: int = 1)

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.

  • workers (int) – Number of workers to use in ThreadPoolExecutor and Connectionpool. Defaults to min(32, os.cpu_count() + 4).

  • tries (int) – Number of times to try (not retry) before giving up.

  • backoff_factor (int) – Backoff factor to multiply delay with.

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(r.App()) uses a route which requires authentication. Clappform does the authentication for you.

Usage:

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

The get(), create(), update() and delete() methods can act on any object that implements the clappform.dataclasses.ResourceType interface.

The currently supported resources are:
tries: int

Number of times to try (not retry) before giving up.

backoff_factor: int

Backoff factor to multiply delay with.

status_forcelist: list[int]

List of HTTP status codes to force a try on.

session: Session

Session for all HTTP requests.

username: str

Username to use in the auth

password: str

Password to use in the auth

workers: int

Number of workers to use in ThreadPoolExecutor and Connectionpool. defaults to: min(32, os.cpu_count() + 4).

request_kwargs: dict

Default request keyword arguments.

executor

ThreadPoolExecut obj to submit large amount of requests to.

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

get(resource, item=None)

Get a one or list of resources.

Parameters:

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> collection = c.get(r.Collection(id="clappform", slug="us_presidents"))
>>> c.get(collection, item={"_id", "6475c76276ffd5e8da000b2c"})
{'_id': '6475c76276ffd5e8da000b2c', 'name': "George Washington"}
Returns:

One or a list of resources

create(resource, item=None)

Crete a resource.

Parameters:

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> new_app = r.App(
...     id="uspresidents",
...     name="US Presidents",
...     description="US Presidents Dashboard",
...     settings={}
... )
>>> c.create(new_app)
App(collections=0, default_page='', description='US Presidents Dashboard...
Returns:

Newly created resource

update(resource, item=None)

Update a resource.

Parameters:

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> app = c.get(r.App(id="uspresidents"))
>>> app.description = "Dashboard of US Presidents"
>>> c.update(app)
App(collections=0, default_page='', description='Dashboard of US Preside...
Returns:

Updated resource

delete(resource, item=None)

Delete a resource.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get(r.App(id="uspresidents"))
>>> c.delete(app)
ApiResponse(code=200, message='Successfully deleted app with ID: uspresi...
Returns:

Confirmation of deletion.

Return type:

clappform.dataclasses.ApiResponse

aggregate_dataframe(options: dict, max_workers=None) → Generator[list[dict], None, None]

Aggregate a dataframe

Parameters:

  • options (dict) – Options for dataframe aggregation.

  • max_workers (int) – Optional number of workers to use in thread pool.

Returns:

Generator to read dataframe

Return type:

Generator

read_dataframe(query, limit: int = 100, max_workers=None) → Generator[list[dict], None, None]

Read a dataframe.

Parameters:

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> import pandas as pd
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!"
... )
>>> query = c.get(r.Query(slug="foo")
>>> list_df = []
>>> for chunck in c.read_dataframe(query):
...     list_df.extend(chunck)
Returns:

Generator to read dataframe

Return type:

Generator

write_dataframe(df: DataFrame, collection: Collection, size: int = 100, max_workers=None)

Write Pandas DataFrame to collection.

Parameters:

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

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

  • size (int) – Size of each chunk. Defaults to: 100

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

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

export_app(app) → dict

Export an app.

Parameters:

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

Returns:

Exported App

Return type:

dict

start_actionflow(actionflow: Actionflow, settings: dict[str, Any] | None = None) → dict

Start an actionflow.

Parameters:

  • actionflow – Actionflow with id or slug property.

  • settings (Optional[dict[str, Any]]) – Optional extra settings for starting an actionflow.

Returns:

API response object

Return type:

clappform.dataclasses.ApiResponse

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

transfer_collections(src: dict, dest, max_workers=None) → Generator[ApiResponse, None, None]

Transfer data from collection(s) from an app to a destination.

Destination is an instance of the clappform.Clappform. This method recreates all the data from all collections of an app to the same app and collections on another clappform.Clappform.

Parameters:
Returns:

Generator of clappform.dataclasses.ApiResponse

Return type:

Generator

current_user(extended: bool = False) → User

Get clappform.dataclasses.User object of the current user.

Parameters:

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

Returns:

User object.

Return type:

clappform.dataclasses.User

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 | None = None, web_application: str | None = None, web_server: str | None = None)

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 = None

Version of the API.

web_application: str = None

Version of the Web Application.

web_server: str = None

Version of the Web Server

one_or_all_path() → str

Return the path to retreive the version.

Returns:

Version HTTP path

Return type:

str

class clappform.dataclasses.ResourceType

Bases: object

ResourceType is used as an interface for clappform.Clappform. Any class that uses this class as a base can be used with clappform.Clappform’s methods.

static bool_to_lower(boolean: bool) → str

Return a boolean string in lowercase.

Parameters:

boolean (bool) – True or False value to convert to lowercase string.

Returns:

Lowercase boolean string

Return type:

str

abstract one_or_all_path() → str

Return the path to retreive one or all resources.

Returns:

Resource HTTP path

Return type:

str

abstract one_path() → str

Return the path to retreive this Resource

Returns:

Resource HTTP path

Return type:

str

abstract all_path() → str

Return the path to retreive all Resources.

Returns:

Resource HTTP path

Return type:

str

abstract create_path() → str

Return the path to create a Resource.

Returns:

Resource HTTP path

Return type:

str

class clappform.dataclasses.App(collections: int | None = None, default_page: str | None = None, description: str | None = None, groups: int | None = None, id: str = <property object>, name: str | None = None, settings: dict | None = None, extended: bool = False)

Bases: ResourceType

App resource type.

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.

  • extended (bool) – Whether fully expanded app object with get.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> new_app = r.App(
...     id="uspresidents",
...     name="US Presidents",
...     description="US Presidents Dashboard",
...     settings={}
... )
>>> c.create(new_app)
App(collections=0, default_page='', description='US Presidents Dashboard', g...
>>> app = c.get(r.App(id="uspresidents"))
>>> c.delete(app)
ApiResponse(code=200, message='Successfully deleted app with ID: uspresident...
>>> for app in c.get(r.App()):
...     print(app.name)
collections: int = None

Number of collections this app has. If extended=True this will be a list of collections.

default_page: str = None

Slug of the page to display when opening the app.

description: str = None

Text under app name on the app overview page.

groups: int = None

Groups of pages this app has. If extended=True this will be a list of dicts.

name: str = None

Name of the app displayed on the page.

settings: dict = None

Extra settings that further configure the app.

extended: bool = False

Used by get to gauge whether to fetch fully expanded app object.

property id: str

String id of the app. This is also used in the URL as a slug.

one_or_all_path() → str

Return the path to retreive one or all Apps.

Returns:

App HTTP path

Return type:

str

one_path() → str

Return the path to retreive this App

Returns:

App HTTP path

Return type:

str

all_path() → str

Return the path to retreive all Apps.

Returns:

App HTTP path

Return type:

str

create_path() → str

Return the path to create an App.

Returns:

App HTTP path

Return type:

str

class clappform.dataclasses.Collection(app: str = <property object>, slug: str = <property object>, database: str | None = None, name: str | 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, extended: int = 0)

Bases: ResourceType

Collection resource type.

Parameters:

  • app (str) – Id of the app collection belongs to.

  • slug (str) – Unique id of the collection.

  • database (str) – Database location to store documents, e.g. MONGO or DATALAKE.

  • name (str) – Display name of the collection.

  • description (str) – Description below collection name. extended=1

  • id (int) – Numeric ID of the collection used for internal identification. extended=1

  • is_encrypted (bool) – Use of encryption on this collection. extended=1

  • is_locked (bool) – Read only permissions on collection. extended=1

  • is_logged (bool) – HTTP Access logging on this collection. extended=1

  • sources (bool) – List of locations the data originates from. extended=1

  • queries (list) – Queries that query this collection’s data. extended=2

  • extended (bool) – At what level to expand collection object with get.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> app = c.get(r.App(id="uspresidets"))
>>> new_collection = r.Collection(
...     app=app,
...     database="MONGO",
...     name="United States Presidents",
...     slug="presidents",
...     description="All presidents of the United Stated of America"
... )
>>> c.create(new_collection)
Collection(app='uspresidents', slug='presidents', database='MONGO', name='Un...
>>> collection = c.get(r.Collection(app="uspresidents", slug="presidents"))
>>> c.delete(collection)
ApiResponse(code=200, message='Successfully deleted collection with slug: pr...
>>> for collection in c.get(r.Collection()):
...     print(f"{collection.app}: {collection.slug}")
database: str = None

Database location where this collection is stored, e.g. "MONGO" or "DATALAKE".

name: str = None

Name of the collection to display on the web page.

description: str = None

Description below the name to display on the web page.

is_encrypted: bool = None

Whether to use encryption for this collection. Default is False.

is_locked: bool = None

Whether this collection is write protected. Collection is read only. Default is False.

is_logged: bool = None

Whether HTTP access loggin is enabled. Default is False.

queries: list = None

Queries that have been created for this collection’s data.

sources: list = None

List of location where the data in this collection came from.

id: int = None

Numeric id of this collection, used for internal identifacation.

extended: int = 0

Used by get to gauge whether to fetch fully expanded app object. Allowed values: 0 - 3. Defaults to 0.

property app: str

App id this collection belong to. This can be of type clappform.dataclasses.App or str.

property slug: str

Unique string id for this collection.

static check_extended(extended: int)

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

one_or_all_path()

Return the path to retreive one or all collections.

Returns:

Collection HTTP path

Return type:

str

one_path() → str

Return the path to retreive this Collection

Returns:

Collection HTTP path

Return type:

str

all_path() → str

Return the path to retreive all Collections.

Returns:

Collection HTTP path

Return type:

str

create_path() → str

Return the path to create a Collection.

Returns:

Collection HTTP path

Return type:

str

one_item_path(item: str) → str

Return the route used for creating and deleting items.

Returns:

Item HTTP path

Return type:

str

create_item_path() → str

Return the route used to create an item.

Returns:

Item HTTP path

Return type:

str

dataframe_path() → str

Return the route used to retreive the Dataframe.

Returns:

Collection’s Dataframe HTTP path

Return type:

str

class clappform.dataclasses.Query(app: str = <property object>, collection: str = <property object>, data_source: str | None = None, export: bool | None = None, id: int | None = None, name: str | None = None, query: list | None = None, slug: str | None = None, source_query: str | None = None, modules: list | None = None, primary: bool | None = None, settings: dict | None = None)

Bases: ResourceType

Collection resource type.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> collection = c.get(r.Collection(app="uspresidets", slug="presidents"))
>>> new_query = r.Query(
...     collection=collection,
...     data_source="app",
...     query=[],
...     name="all presidents",
...     slug="f1cb2ba5-64a7-4056-99d5-7d639557970f",
... )
>>> c.create(new_collection)
Query(app='uspresidets', collection='presidents', data_source='app', export=...
>>> query = c.get(r.Query(slug="f1cb2ba5-64a7-4056-99d5-7d639557970f"))
>>> c.delete(query)
ApiResponse(code=200, message='Successfully deleted query with slug: f1cb2ba...
>>> for query in c.get(r.Query()):
...     print(f"{query.app}/{query.collection}: {query.slug}")
data_source: str = None
export: bool = None
id: int = None

Numeric id used for internal identication

name: str = None
query: list = None
slug: str = None
source_query: str = None
modules: list = None
primary: bool = None
settings: dict = None
property app: str

App id this query belong to. This can be of type clappform.dataclasses.App or str.

property collection: str

Collection slug this query refers to. This can be of type clappform.dataclasses.Collection or str.

one_or_all_path() → str

Return the path to retreive one or all resources.

Returns:

Resource HTTP path

Return type:

str

one_path() → str

Return the route used to retreive the Query.

Returns:

Query HTTP resource path

Return type:

str

all_path() → str

Return the route used to retreive the Query.

Returns:

Query HTTP resource path

Return type:

str

create_path() → str

Return the path to create a Resource.

Returns:

Resource HTTP 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 | None = None, name: str | None = None, slug: str | None = None, category: str | None = None, fast: bool | None = None, multiple: bool | None = None, settings: dict | None = None, start_keys: list | None = None, extra_information: list | None = None, cronjobs: list | None = None, tasks: list | None = None)

Bases: ResourceType

Actionflow resource type.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> new_actionflow = r.Actionflow(
...     name="Periodic housekeeping",
...     settings={},
... )
>>> c.create(new_collection)
Actionflow(id=48, name='Periodic housekeeping', settings={}, cronjobs=None, ...
>>> actionflow = c.get(r.Actionflow(id=48))
>>> c.delete(actionflow)
ApiResponse(code=200, message='Deleted action flow.', response_id='648083113...v
>>> for af in c.get(r.Actionflow()):
...     print(f"{af.id}: {af.name}")
id: int = None
name: str = None
slug: str = None
category: str = None
fast: bool = None
multiple: bool = None
settings: dict = None
start_keys: list = None
extra_information: list = None
cronjobs: list = None
tasks: list = None
one_or_all_path() → str

Return the path to retreive one or all resources.

Returns:

Resource HTTP path

Return type:

str

all_path() → str

Return the path to retreive all Resources.

Returns:

Resource HTTP path

Return type:

str

one_path() → str

Return the path to retreive this Resource

Returns:

Resource HTTP path

Return type:

str

create_path() → str

Return the path to create a Resource.

Returns:

Resource HTTP path

Return type:

str

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

Bases: ResourceType

Questionnaire dataclass.

name: str = None
id: int = None
created_at: int = None
active: bool = None
created_by: dict = None
latest_version: dict = None
versions: list = None
settings: dict = None
extended: bool = False
one_or_all_path() → str

Return the path to retreive one or all resources.

Returns:

Resource HTTP path

Return type:

str

all_path() → str

Return the path to retreive all Resources.

Returns:

Resource HTTP path

Return type:

str

one_path() → str

Return the path to retreive this Resource

Returns:

Resource HTTP path

Return type:

str

create_path() → str

Return the path to create a Resource.

Returns:

Resource HTTP path

Return type:

str

class clappform.dataclasses.User(email: str | None = None, extra_information: dict | None = None, first_name: str | None = None, last_name: str | None = None, is_active: bool | None = None, id: int | None = None, phone: str | None = None, messages: dict | None = None, last_online: int | None = None, permissions: list[str] | None = None, roles: list[dict] | None = None, password: str | None = None, extended: bool = False)

Bases: ResourceType

User resource type.

Usage:

>>> from clappform import Clappform
>>> import clappform.dataclasses as r
>>> c = Clappform(
...     "https://app.clappform.com",
...     "j.doe@clappform.com",
...     "S3cr3tP4ssw0rd!",
... )
>>> user = c.get(r.User(email="j.doe@clappform.com")
>>> new_user = r.User(
...     email="g.washington@clappform.com",
...     first_name="George",
...     last_name="Washington",
...     password="HavntGotWoodenTeeth",
... )
>>> c.create(new_user)
User(email='g.washington@clappform.com', extra_information={}, first_name='G...
>>> query = c.get(r.Query(slug="f1cb2ba5-64a7-4056-99d5-7d639557970f"))
>>> c.delete(query)
ApiResponse(code=200, message='Successfully deactivated user, with email: g....
>>> for user in c.get(r.User()):
...     print(f"{user.email}: {user.first_name} {user.last_name}")
email: str = None

Email address of the user.

extra_information: dict = None

Dictionary object describing extra related information about the user.

first_name: str = None

User’s first name.

last_name: str = None

User’s last name.

is_active: bool = None

Whether user can authenticate or not.

id: int = None

Numeric id used for internal identifaction.

phone: str = None

User’s phone number.

messages: dict = None

Dictionary object containing notifications, emails, sms or whatsapp messages. extended=True

last_online: int = None

Unix timestamp of when the user was last online. extended=True

permissions: list[str] = None

List of permissions this user has. extended=True

roles: list[dict] = None

extended=True

password: str = None

Password of the user. Only used when creating a user.

extended: bool = False

Used by get to gauge whether to fetch fully expanded user object.

one_or_all_path() → str

Return the path to retreive this User.

Returns:

User HTTP path

Return type:

str

all_path() → str

Return the path to retreive all Users.

Returns:

User HTTP path

Return type:

str

one_path() → str

Return the path to retreive this User.

Returns:

User HTTP path

Return type:

str

create_path() → str

Return the path to create a Collection.

Returns:

Collection HTTP path

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.

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

Bases: HTTPError

A pagination error in paginated response occurred.

data: dict

Response JSON document.

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

Bases: PaginationError

A total error in paginated response occurred.

total: int

Total number of elements in collection.

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

Bases: PaginationError

A key error in paginated response occurred.

missing_key: str

Key missing from the Response JSON document.