App

knackpy.app #

App Objects # 

class App()

Knackpy is designed around the App class. It provides helpers for querying and manipulating Knack application data. You should use the App class because:

  • It allows you to query obejcts and views by key or name
  • It takes care of localization issues # noqa:E501
  • It let’s you download and upload files from your app.
  • It does other things, too.

Arguments:

  • app_id str - Knack application ID # noqa:E501 string.
  • api_key str, optional, default=None - Knack API key.
  • metadata dict, optional - The Knack app’s metadata as a dict. If None it will be fetched on init. You can find your apps metadata here.
  • tzinfo pytz.Timezone, optional - [description]. A pytz.Timezone object. When None, is set automatically based on the app’s metadadata.
  • max_attempts int - The maximum number of attempts to make if a request times out. Default values that are set in knackpy.api.request.
  • timeout int, optional - Number of seconds to wait before a Knack API request times out. Further reading: Requests docs.

info # 

def info()

Returns a dict of basic app information:

  • Number of objects
  • Number of scenes
  • Number of records
  • Number total file size

get # 

def get(identifier: str = None,
        refresh: bool = False,
        record_limit: int = None,
        filters: typing.Union[dict, list] = None,
        generate=False)

Get records from a knack object or view.

Note that we accept the request params record_limit and filters here because the user would presumably want to set these on a per-object/view basis. They are not stored in state. Whereas max_attempts and timeout are set on App construction and persist in App state.

Arguments:

  • identifier str, optional* - an object or view key or name string that exists in the app. If None is provided and only one container has been fetched, will return records from that container.
  • refresh bool, optional - Force the re-querying of data from Knack API. Defaults to False.
  • record_limit int - the maximum number of records to retrieve. If None, will return all records.
  • filters dict or list, optional - A dict or list of Knack API filters.
  • See - https://www.knack.com/developer-documentation/`filters`.
  • generate bool, optional - If True, will return a generator which yields knacky.Record objects instead of return a list of of them.

Returns:

A generator which yields knackpy Record objects.

to_csv # 

def to_csv(identifier: str,
           *,
           out_dir: str = "_csv",
           delimiter=",",
           record_limit: int = None,
           filters: typing.Union[dict, list] = None) -> None

Write formatted Knack records to CSV.

Arguments:

  • identifier str - an object or view key or name string that exists in the app.
  • out_dir str, optional - Relative path to the directory to which files will be written. Defaults to “_csv”.
  • delimiter str, optional - [description]. Defaults to “,”.
  • record_limit int - the maximum number of records to retrieve. If None, will return all records.
  • filters dict or list, optional - A dict or of Knack API filiters.
  • See - https://www.knack.com/developer-documentation/`filters`.

download # 

def download(*,
             container: str,
             field: str,
             out_dir: str = "_downloads",
             label_keys: list = None)

Download files and images from Knack records.

Arguments:

  • container str - The name or key of the object from which files will be downloaded.
  • out_dir str, optional - Relative path to the directory to which files will be written. Defaults to “_downloads”.
  • field str - The Knack field key of the file or image field to be downloaded.
  • label_keys list, optional - A list of field keys whose values will be prepended to the attachment filename, separated by an underscore.

Returns:

  • [int] - Count of files downloaded.

record # 

def record(*, data: dict, method: str, obj: str)

Create, update, or delete a Knack record.

Arguments:

  • data dict - The Knack record data payload.
  • method str - Choose from create, update, or delete.
  • obj str, optional - The Knack object key or name which holds the record data.

Returns:

  • dict - The updated or newly created Knack record data, or, if deleting a
  • record - {"delete": true}

upload # 

def upload(*,
           container: str,
           field: str,
           path: str,
           asset_type: str,
           record_id: str = None)

Upload a file or image to Knack. This is a two-step process:

  1. Upload file asset to Knack storage
  2. Create/update a record that links to the file in storage

Knack docs: https://www.knack.com/developer-documentation/`file`-image-uploads

Arguments:

  • container str - The name or key of the object from which files will be downloaded.
  • field str - The knack field key of the field you’re uploading into.
  • path str - The path to the file to be uploaded.
  • asset_type str - The type of Knack field you’re uploading to. Must be file or image.
  • record_id str, optional - The knack record ID to which the upload will be attached. If None, will create a new record. Otherwise will update an existing record.