Airtable.py: Python API wrapper for Airtable

Python interface to the Airtable's REST API - https://airtable.com - |Build Status|

For javascript enthusiasts: https://github.com/Airtable/airtable.js

Installation

Airtable Python uses Requests.py <http://docs.python-requests.org/>__: make sure you have it installed by running

::

$ pip install requests

Getting started

Once you have created a new base <https://support.airtable.com/hc/en-us/articles/202576419-Introduction-to-Airtable-bases>__ and a new table through the Web interface, you're ready to start using Airtable Python.

.. code:: python

import airtable
at = airtable.Airtable('BASE_ID', 'ACCESS_TOKEN')
at.get('TABLE_NAME')

Here's an example of response from the Restaurant's example base

.. code:: python

{u'records': [
  {u'fields': {u'Diet': u'Kosher or Halal',
    u'Friendly Restaurants': [u'recr0ITqq9C1I92FL', u'recGeAJLw0ZkbwdXZ'],
    u'Icon': [{u'filename': u'no-pig.jpg',
      u'id': u'attzKGOBbjndOx0FU',
      u'size': 34006,
      u'thumbnails': {u'large': {u'height': 202,
        u'url': u'https://dl.airtable.com/trmtq3BaRoa0sWnyffWZ_large_no-pig.jpg',
        u'width': 256},
       u'small': {u'height': 36,
        u'url': u'https://dl.airtable.com/yzuRv5CyRs2PVH4fDvCe_small_no-pig.jpg',
        u'width': 46}},
      u'type': u'image/jpeg',
      u'url': u'https://dl.airtable.com/DyGOjAASze6AIkQxFpDv_no-pig.jpg'}],
    u'People': [u'Annie', u'Maryam']},
   u'id': u'rec5sD6mBBd0SaXof'},
   ...

API Reference

The available methods closely mimic the REST API <https://airtable.com/api>__:

Get

Given a table name, fetched one or multiple records.

.. code:: python

    at.get(table_name, record_id=None, limit=0, offset=None,
           filter_by_formula=None, view=None, max_records=0, fields=[])

where

::

    table_name (required) is a string representing the table name
    record_id (optional) is a string, which fetches a specific item by id. If not specified, all items are fetched
    limit (optional) is an integer, and it can only be specified if record_id is not present, and limits the number of items fetched (see pageSize in the AirTable documentation)
    offset is a string representing the record id from which we start the offset
    filter_by_formula (optional) is a string to filter the retrieving records (see filterByFormula in the AirTable documentation)
    max_records (optional) is the total number of records that will be returned (see maxRecords in the AirTable documentation)
    fields (optional) is a list of strings with the field names to be returned

Iterate

Given a table name, fetched all records.

.. code:: python

at.iterate(table_name, batch_size=0, filter_by_formula=None,
       view=None, max_records=0, fields=[])

where

::

table_name (required) is a string representing the table name
batch_size (optional) is an integer specifying the number of records to fetch per request. The default (0) uses the API default, which is (as of 2016-09) 100.
limit (optional) is an integer, and it can only be specified if record_id is not present, and limits the number of items fetched (see pageSize in the AirTable documentation)
filter_by_formula (optional) is a string to filter the retrieving records (see filterByFormula in the AirTable documentation)
view  (optional) is a string representing the name or ID of a view in the table. If set, only the records in that view will be returned. The records will be sorted according to the order of the view.
max_records (optional) is the total number of records that will be returned (see maxRecords in the AirTable documentation)
fields (optional) is a list of strings with the field names to be returned

Note: this returns a generator instead, which you can use to loop each record:

.. code:: python

# example with similar results of at.get
result = { "records": [] }
for r in self.at.iterate(self.table, fields=fields):
    result["records"].append(r)

Create

Creates a new entry in a table, and returns the newly created entry with
its new ID.

.. code:: python

    at.create(table_name, data)

where

::

    table_name (required) is a string representing the table name
    data (required) is a dictionary containing the fields and the respective values

Update

Updates some fields in a specific entry in the table. Fields which are not explicitly included will not get updated

.. code:: python

at.update(table_name, record_id, data)

where

::

table_name (required) is a string representing the table name
record_id (required) is a string representing the item to update
data (required) is a dictionary containing the fields (and the respective values) to be updated

Update All

Like the previous method, but updates all fields, clearing the ones that
are not included in the request.

.. code:: python

    at.update_all(table_name, record_id, data)

Delete
~~~~~~

Delete a specific record from the table

.. code:: python

    at.delete(table_name, record_id)

where

::

    table_name (required) is a string representing the table name
    record_id (required) is a string representing the item to update

.. |Build Status| image:: https://travis-ci.org/josephbestjames/airtable.py.svg?branch=master
   :target: https://travis-ci.org/josephbestjames/airtable.py

Release
-------

To release, tag the Git repo with a new version number, push that tag to GitHub then Travis CI will do the rest.