Python Client Library for Airtable

0.4.8 verified Mon Apr 13 auth: no python maintenance

The `airtable` library, maintained by josephbestjames on PyPI (version 0.4.8), is a Python client for interacting with the Airtable REST API. It provides a straightforward interface for performing CRUD (Create, Read, Update, Delete) operations on Airtable bases and tables, abstracting the underlying HTTP requests. This library has a relatively slow release cadence, with its latest update in early 2021. Developers seeking a more actively maintained and feature-rich client should consider `pyairtable`.

pip install airtable

Common errors

error AttributeError: module 'airtable' has no attribute 'Airtable' ↓

cause This error occurs when the 'airtable' module is imported incorrectly or if there's a naming conflict with a local file named 'airtable.py'.

fix

Ensure the module is imported correctly using 'from airtable import Airtable' and verify that no local files are named 'airtable.py'.

error ModuleNotFoundError: No module named 'airtable' ↓

cause This error indicates that the 'airtable' module is not installed in the current Python environment.

fix

Install the module using 'pip install airtable' and ensure the correct Python environment is active.

error ImportError: cannot import name 'Airtable' from 'airtable' ↓

cause This error occurs when the 'Airtable' class is not found in the 'airtable' module, possibly due to an outdated or incorrect installation.

fix

Verify the installation of the 'airtable' module and ensure it is up to date by running 'pip install --upgrade airtable'.

error KeyError: 'AIRTABLE_API_KEY' or {'error': {'type': 'AUTHENTICATION_REQUIRED', 'message': 'Authentication required'}} or HTTP 401 Unauthorized / 403 Forbidden ↓

cause These errors indicate issues with your Airtable API key, Personal Access Token (PAT), Base ID, or table permissions. The `airtable` library (or underlying API calls) might be expecting the API key to be set as an environment variable (`AIRTABLE_API_KEY`) or passed incorrectly, or the provided credentials lack the necessary permissions for the requested action or resource.

fix

Verify your Airtable API key or Personal Access Token (PAT) is correct and has the appropriate read/write permissions for the base and table you are accessing. Ensure the Base ID and table name are accurate. For airtable-python-wrapper, try setting your API key as an environment variable: os.environ['AIRTABLE_API_KEY'] = 'your_api_key_here' before initializing the Airtable object, or pass it as a parameter: Airtable(base_id, table_name, api_key='your_api_key'). Also, confirm that you are using a Personal Access Token (PAT) if your API key starts with 'pat', as older 'key' prefixed API keys have been deprecated by Airtable.

error {'error': {'type': 'INVALID_REQUEST_UNKNOWN', 'message': 'Invalid request: parameter validation failed. Check your request data.'}} or HTTP 422 Invalid Request ↓

cause This error occurs when the data sent to Airtable during record creation or update does not match the expected format or schema, or you are attempting to write to a read-only field (e.g., a formula field) or a linked record field with an invalid value.

fix

Review the Airtable API documentation for the specific table and field types to ensure your request payload is correctly structured. Data for record creation/update should typically be wrapped in a 'fields' dictionary, like {'fields': {'FieldName': 'Value'}}. Check that field names match exactly (case-sensitive) and that data types are compatible with the Airtable field types. Ensure you are not trying to update computed fields or fields where the provided value is invalid for a linked record.

Warnings

breaking This `airtable` library (josephbestjames/airtable.py) is distinct from `pyairtable` (gtalarico/pyairtable). The `pyairtable` library is the actively maintained successor, offering more features, better documentation, and more frequent updates. Many online resources and migration guides refer to `pyairtable`. Mixing up these libraries will lead to `ModuleNotFoundError` or unexpected API behavior. ↓

fix Determine which library you intend to use. If you need current features and active development, install `pyairtable` (`pip install pyairtable`). If you specifically need this `airtable` library, ensure your code adheres to its API, which may differ significantly from `pyairtable`.

breaking Airtable deprecated legacy API keys on February 1, 2024. While this `airtable` library might still accept API keys, it is strongly recommended to switch to Personal Access Tokens (PATs) for authentication. Using deprecated API keys may lead to authentication failures in the future. ↓

fix Generate a Personal Access Token from your Airtable Developer Hub. Configure it with the necessary scopes for your base and tables, and use this token in place of your old API key.

gotcha Naming your Python script `airtable.py` will cause a `ModuleNotFoundError` when you try to import `airtable`. This happens because Python's import system will prioritize your local file over the installed package. ↓

fix Rename your script to something other than `airtable.py` (e.g., `my_airtable_script.py`).

gotcha Airtable's API enforces a rate limit of 5 requests per second per base. Exceeding this limit will result in 429 'Too Many Requests' errors. ↓

fix Implement exponential backoff and retry logic in your application to handle 429 responses gracefully. If using `pyairtable`, it includes built-in retry mechanisms.

deprecated Some older tutorials or documentation for this library (or its predecessors/forks) might refer to methods like `get_all()` or `insert()`. The current version of this `airtable` library (0.4.8) primarily uses `get()` for fetching records (optionally with an ID for a single record) and `create()` for inserting new records. ↓

fix Refer to the method signatures in the `airtable` library's GitHub README or source code. Use `at.get(table_name, record_id=None, ...)` for fetching and `at.create(table_name, fields)` for creating records.

Imports

Airtable
wrong
```
from airtable import airtable
```
correct
```
from airtable import Airtable
```
The class name `Airtable` is capitalized, while the module name is lowercase. Importing `airtable` (lowercase) will not provide the intended class. Some older tutorials or forks might also suggest `from airtablib import Airtable` which is incorrect for this library.

Quickstart

This quickstart demonstrates how to initialize the Airtable client and fetch all records from a specified table. It also includes an example of creating a new record. Authentication should use an Airtable Personal Access Token (PAT) loaded from an environment variable for security, as legacy API keys are deprecated.

import os
from airtable import Airtable

# It's recommended to use Personal Access Tokens (PATs) and store them as environment variables.
# Legacy API keys are deprecated by Airtable as of Feb 2024.
AIRTABLE_BASE_ID = os.environ.get('AIRTABLE_BASE_ID', 'YOUR_BASE_ID')
AIRTABLE_API_KEY = os.environ.get('AIRTABLE_API_KEY', 'YOUR_PERSONAL_ACCESS_TOKEN') # Or legacy API key if absolutely necessary
AIRTABLE_TABLE_NAME = 'MyTable'

try:
    at = Airtable(AIRTABLE_BASE_ID, AIRTABLE_TABLE_NAME, AIRTABLE_API_KEY)
    
    # Fetch all records from the table
    records = at.get(AIRTABLE_TABLE_NAME)
    
    print(f"Successfully fetched {len(records['records'])} records from '{AIRTABLE_TABLE_NAME}':")
    for record in records['records']:
        print(f"- ID: {record.get('id')}, Fields: {record.get('fields')}")

    # Example: Create a new record
    new_record_data = {'Name': 'New Task', 'Status': 'To Do'}
    created_record = at.create(AIRTABLE_TABLE_NAME, new_record_data)
    print(f"\nCreated new record: {created_record['id']} with fields {created_record['fields']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure AIRTABLE_BASE_ID, AIRTABLE_API_KEY, and AIRTABLE_TABLE_NAME are correctly set.")
    print("Also, verify that the table and fields exist and the token has appropriate permissions.")