API Reference

API: pyairtable

class pyairtable.Api[source]

Represents an Airtable API. Implements basic URL construction, session and request management, and retrying logic.

Usage:
>>> api = Api('auth_token')
>>> table = api.table('base_id', 'table_name')
>>> records = table.all()
MAX_RECORDS_PER_REQUEST = 10

Airtable-imposed limit on number of records per batch create/update operation.

MAX_URL_LENGTH = 16000

Airtable-imposed limit on the length of a URL (including query parameters).

__init__(api_key, *, timeout=None, retry_strategy=True, endpoint_url='https://api.airtable.com')[source]
Parameters
  • api_key (str) – An Airtable API key or personal access token.

  • timeout (Optional[Tuple[int, int]], default: None) – A tuple indicating a connect and read timeout. e.g. timeout=(2,5) would configure a 2 second timeout for the connection to be established and 5 seconds for a server read timeout. Default is None (no timeout).

  • retry_strategy (Union[bool, Retry, None], default: True) – An instance of urllib3.util.Retry. If None or False, requests will not be retried. If True, the default strategy will be applied (see retry_strategy() for details).

  • endpoint_url (str, default: 'https://api.airtable.com') – The API endpoint to use. Override this if you are using a debugging or caching proxy.

property api_key: str

Airtable API key or access token to use on all connections.

Return type

str

whoami()[source]

Return the current user ID and (if connected via OAuth) the list of scopes. See Get user ID & scopes for more information.

Return type

UserAndScopesDict

base(base_id, *, validate=False, force=False)[source]

Return a new Base instance that uses this instance of Api.

Parameters
  • base_id (str) – An Airtable base ID.

  • validate (bool, default: False) – If False, will create an object without validating the ID/name provided. If True, will fetch information from the metadata API and validate the ID/name exists, raising KeyError if it does not.

  • force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Raises

KeyError – if validate=True and the given base ID does not exist.

Return type

Base

bases(*, force=False)[source]

Retrieve the base’s schema and return a list of Base instances.

Parameters

force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:
>>> api.bases()
[
    <pyairtable.Base base_id='appSW9...'>,
    <pyairtable.Base base_id='appLkN...'>
]
Return type

List[Base]

create_base(workspace_id, name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters
  • workspace_id (str) – The ID of the workspace where the new base will live.

  • name (str) – The name to give to the new base. Does not need to be unique.

  • tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

table(base_id, table_name, *, validate=False, force=False)[source]

Build a new Table instance that uses this instance of Api.

Parameters
  • base_id (str) – An Airtable base ID.

  • table_name (str) – The Airtable table’s ID or name.

  • validate (bool, default: False) – If False, will create an object without validating the ID/name provided. If True, will fetch information from the metadata API and validate the ID/name exists, raising KeyError if it does not.

  • force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

Table

build_url(*components)[source]

Build a URL to the Airtable API endpoint with the given URL components, including the API version number.

Return type

str

request(method, url, fallback=None, options=None, params=None, json=None)[source]

Make a request to the Airtable API, optionally converting a GET to a POST if the URL exceeds the maximum URL length.

Parameters
  • method (str) – HTTP method to use.

  • url (str) – The URL we’re attempting to call.

  • fallback (Optional[Tuple[str, str]], default: None) – The method and URL to use if we have to convert a GET to a POST.

  • options (Optional[Dict[str, Any]], default: None) – Airtable-specific query params to use while fetching records. See Parameters for valid options.

  • params (Optional[Dict[str, Any]], default: None) – Additional query params to append to the URL as-is.

  • json (Optional[Dict[str, Any]], default: None) – The JSON payload for a POST/PUT/PATCH/DELETE request.

Return type

Any

iterate_requests(method, url, fallback=None, options=None, params=None, offset_field='offset')[source]

Make one or more requests and iterates through each result.

If the response payload contains an ‘offset’ value, this method will perform another request with that offset value as a parameter (query params for GET, body payload for POST/PATCH/etc).

If the response payload is not a ‘dict’, it will be yielded as normal and the method will return.

Parameters
  • method (str) – HTTP method to use.

  • url (str) – The URL we’re attempting to call.

  • fallback (Optional[Tuple[str, str]], default: None) – The method and URL to use if we have to convert a GET to a POST.

  • options (Optional[Dict[str, Any]], default: None) – Airtable-specific query params to use while fetching records. See Parameters for valid options.

  • params (Optional[Dict[str, Any]], default: None) – Additional query params to append to the URL as-is.

  • offset_field (str, default: 'offset') – The key to use in the API response to determine whether there are additional pages to retrieve.

Return type

Iterator[Any]

chunked(iterable)[source]

Iterate through chunks of the given sequence that are equal in size to the maximum number of records per request allowed by the API.

Return type

Iterator[Sequence[TypeVar(T)]]

enterprise(enterprise_account_id)[source]

⚠ This feature is only available on Enterprise billing plans.

Build an object representing an enterprise account.

Return type

Enterprise

class pyairtable.Base[source]

Represents an Airtable base.

Usage:
>>> base = api.base("appNxslc6jG0XedVM")
>>> table = base.table("Table Name")
>>> records = table.all()
__init__(api, base_id, *, name=None, permission_level=None)[source]

Old style constructor takes str arguments, and will create its own instance of Api.

This approach is deprecated, and will likely be removed in the future.

>>> Base("access_token", "base_id")

New style constructor takes an instance of Api:

>>> Base(api, "table_name")
Parameters
  • api (Union[Api, str]) – An instance of Api or an Airtable access token.

  • base_id (str) – An Airtable base ID.

  • name (Optional[str], default: None) – The name of the Airtable base, if known.

  • permission_level (Optional[str], default: None) – The permission level the current authenticated user has upon the Airtable base, if known.

api: pyairtable.api.api.Api

The connection to the Airtable API.

id: str

The base ID, in the format appXXXXXXXXXXXXXX

permission_level: Optional[str]

The permission level the current user has on the base

property name: Optional[str]

The name of the base, if provided to the constructor or available in cached base information.

Return type

Optional[str]

table(id_or_name, *, validate=False, force=False)[source]

Build a new Table instance using this instance of Base.

Parameters
  • id_or_name (str) – An Airtable table ID or name. Table name should be unencoded, as shown on browser.

  • validate (bool, default: False) – If False, will create an object without validating the ID/name provided. If True, will fetch information from the metadata API and validate the ID/name exists, raising KeyError if it does not.

  • force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:
>>> base.table('Apartments')
<Table base='appLkNDICXNqxSDhG' name='Apartments'>
Return type

Table

tables(*, force=False)[source]

Retrieve the base’s schema and returns a list of Table instances.

Parameters

force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:
>>> base.tables()
[
    <Table base='appLkN...' id='tbltp8DGLhqbUmjK1' name='Apartments'>,
    <Table base='appLkN...' id='tblK6MZHez0ZvBChZ' name='Districts'>
]
Return type

List[Table]

create_table(name, fields, description=None)[source]

Create a table in the given base.

Parameters
  • name (str) – The unique table name.

  • fields (Sequence[Dict[str, Any]]) – A list of dict objects that conform to the Airtable field model.

  • description (Optional[str], default: None) – The table description. Must be no longer than 20k characters.

Return type

Table

meta_url(*components)[source]

Build a URL to a metadata endpoint for this base.

Return type

str

schema()[source]

Retrieve the schema of all tables in the base and caches it.

Usage:
>>> base.schema().tables
[TableSchema(...), TableSchema(...), ...]
>>> base.schema().table("tblXXXXXXXXXXXXXX")
TableSchema(id="tblXXXXXXXXXXXXXX", ...)
>>> base.schema().table("My Table")
TableSchema(id="...", name="My Table", ...)
Parameters

force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

BaseSchema

webhooks()[source]

Retrieve all the base’s webhooks (see: List webhooks).

Usage:
>>> base.webhooks()
[
    Webhook(
        id='ach00000000000001',
        are_notifications_enabled=True,
        cursor_for_next_payload=1,
        is_hook_enabled=True,
        last_successful_notification_time=None,
        notification_url="https://example.com",
        last_notification_result=None,
        expiration_time="2023-07-01T00:00:00.000Z",
        specification: WebhookSpecification(...)
    )
]
Return type

List[Webhook]

webhook(webhook_id)[source]

Build a single webhook or raises KeyError if the given ID is invalid.

Airtable’s API does not permit retrieving a single webhook, so this function will call webhooks() and simply return one item from the list.

Return type

Webhook

add_webhook(notify_url, spec)[source]

Create a webhook on the base with the given webhooks specification.

The return value will contain a unique secret that must be saved in order to validate payloads as they are sent to your notification endpoint. If you do not save this, you will have no way of confirming that payloads you receive did, in fact, come from Airtable.

For more on how to validate notifications to your webhook, see WebhookNotification.from_request().

Usage:
>>> base.add_webhook(
...     "https://example.com",
...     {
...         "options": {
...             "filters": {
...                 "dataTypes": ["tableData"],
...             }
...         }
...     }
... )
CreateWebhookResponse(
    id='ach00000000000001',
    mac_secret_base64='c3VwZXIgZHVwZXIgc2VjcmV0',
    expiration_time='2023-07-01T00:00:00.000Z'
)
Raises

pydantic.ValidationError – If the dict provided is invalid.

Parameters
  • notify_url (str) – The URL where Airtable will POST all event notifications.

  • spec (Union[WebhookSpecification, Dict[Any, Any]]) – The configuration for the webhook. It is easiest to pass a dict that conforms to the webhooks specification but you can also provide WebhookSpecification.

Return type

CreateWebhookResponse

collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base collaborators.

Parameters

force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

BaseCollaborators

shares()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base shares.

Parameters

force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

List[Info]

delete()[source]

⚠ This feature is only available on Enterprise billing plans.

Delete the base.

Usage:
>>> base = api.base("appMxESAta6clCCwF")
>>> base.delete()
Return type

None

class pyairtable.Table[source]

Represents an Airtable table.

Usage:
>>> api = Api(access_token)
>>> table = api.table("base_id", "table_name")
>>> records = table.all()
__init__(api_key: str, base_id: str, table_name: str, *, timeout: Optional[pyairtable.api.api.TimeoutTuple] = 'None', retry_strategy: Optional[urllib3.util.retry.Retry] = 'None', endpoint_url: str = "'https://api.airtable.com'")[source]
__init__(api_key: None, base_id: pyairtable.api.base.Base, table_name: str)
__init__(api_key: None, base_id: pyairtable.api.base.Base, table_name: pyairtable.models.schema.TableSchema)

Old style constructor takes str arguments, and will create its own instance of Api. This constructor can also be provided with keyword arguments to the Api class.

This approach is deprecated, and will likely be removed in the future.

>>> Table("api_key", "base_id", "table_name", timeout=(1, 1))

New style constructor has an odd signature to preserve backwards-compatibility with the old style (above), requiring None as the first argument, followed by an instance of Base, followed by the table name.

>>> Table(None, base, "table_name")

These signatures may change in the future. Developers using this library are encouraged to not construct Table instances directly, and instead fetch tables via Api.table().

base: pyairtable.api.base.Base

The base that this table belongs to.

name: str

Can be either the table name or the table ID (tblXXXXXXXXXXXXXX).

property id: str

Get the table’s Airtable ID.

If the instance was created with a name rather than an ID, this property will perform an API request to retrieve the base’s schema. For example:

# This will not create any network traffic
>>> table = base.table('tbl00000000000123')
>>> table.id
'tbl00000000000123'

# This will fetch schema for the base when `table.id` is called
>>> table = base.table('Table Name')
>>> table.id
'tbl00000000000123'
Return type

str

property url: str

Build the URL for this table.

Return type

str

meta_url(*components)[source]

Build a URL to a metadata endpoint for this table.

Return type

str

record_url(record_id, *components)[source]

Build the URL for the given record ID, with optional trailing components.

Return type

str

property api: pyairtable.api.api.Api

The API connection used by the table’s Base.

Return type

Api

get(record_id, **options)[source]

Retrieve a record by its ID.

>>> table.get('recwPQIfs4wKPyc9D')
{'id': 'recwPQIfs4wKPyc9D', 'fields': {'First Name': 'John', 'Age': 21}}
Parameters

record_id (str) – An Airtable record ID.

Keyword Arguments
Return type

RecordDict

iterate(**options)[source]

Iterate through each page of results from List records. To get all records at once, use all().

>>> it = table.iterate()
>>> next(it)
[{"id": ...}, {"id": ...}, {"id": ...}, ...]
>>> next(it)
[{"id": ...}, {"id": ...}, {"id": ...}, ...]
>>> next(it)
[{"id": ...}]
>>> next(it)
Traceback (most recent call last):
StopIteration
Keyword Arguments
  • view – The name or ID of a view. If set, only the records in that view will be returned. The records will be sorted according to the order of the view.

  • page_size – The number of records returned in each request. Must be less than or equal to 100. If no value given, Airtable’s default is 100.

  • max_records – The maximum total number of records that will be returned. If this value is larger than page_size, multiple requests will be needed to fetch all records.

  • fields – Name of field or fields to be retrieved. Default is all fields. Only data for fields whose names are in this list will be included in the records. If you don’t need every field, you can use this parameter to reduce the amount of data transferred.

  • sort – List of fields to sort by. Default order is ascending. This parameter specifies how the records will be ordered. If you set the view parameter, the returned records in that view will be sorted by these fields. If sorting by multiple columns, column names can be passed as a list. Sorting Direction is ascending by default, but can be reversed by prefixing the column name with a minus sign -.

  • formula – An Airtable formula. The formula will be evaluated for each record, and if the result is none of 0, false, "", NaN, [], or #Error! the record will be included in the response. If combined with view, only records in that view which satisfy the formula will be returned. For example, to only include records where COLUMN_A isn’t empty, pass in formula="{COLUMN_A}".

  • cell_format – The cell format to request from the Airtable API. Supported options are json (the default) and string. json will return cells as a JSON object. string will return the cell as a string. user_locale and time_zone must be set when using string.

  • user_locale – The user locale that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/220340268-Supported-locale-modifiers-for-SET-LOCALE for valid values.

  • time_zone – The time zone that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/216141558-Supported-timezones-for-SET-TIMEZONE for valid values.

  • return_fields_by_field_id – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

Iterator[List[RecordDict]]

all(**options)[source]

Retrieve all matching records in a single list.

>>> table = api.table('base_id', 'table_name')
>>> table.all(view='MyView', fields=['ColA', '-ColB'])
[{'fields': ...}, ...]
>>> table.all(max_records=50)
[{'fields': ...}, ...]
Keyword Arguments
  • view – The name or ID of a view. If set, only the records in that view will be returned. The records will be sorted according to the order of the view.

  • page_size – The number of records returned in each request. Must be less than or equal to 100. If no value given, Airtable’s default is 100.

  • max_records – The maximum total number of records that will be returned. If this value is larger than page_size, multiple requests will be needed to fetch all records.

  • fields – Name of field or fields to be retrieved. Default is all fields. Only data for fields whose names are in this list will be included in the records. If you don’t need every field, you can use this parameter to reduce the amount of data transferred.

  • sort – List of fields to sort by. Default order is ascending. This parameter specifies how the records will be ordered. If you set the view parameter, the returned records in that view will be sorted by these fields. If sorting by multiple columns, column names can be passed as a list. Sorting Direction is ascending by default, but can be reversed by prefixing the column name with a minus sign -.

  • formula – An Airtable formula. The formula will be evaluated for each record, and if the result is none of 0, false, "", NaN, [], or #Error! the record will be included in the response. If combined with view, only records in that view which satisfy the formula will be returned. For example, to only include records where COLUMN_A isn’t empty, pass in formula="{COLUMN_A}".

  • cell_format – The cell format to request from the Airtable API. Supported options are json (the default) and string. json will return cells as a JSON object. string will return the cell as a string. user_locale and time_zone must be set when using string.

  • user_locale – The user locale that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/220340268-Supported-locale-modifiers-for-SET-LOCALE for valid values.

  • time_zone – The time zone that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/216141558-Supported-timezones-for-SET-TIMEZONE for valid values.

  • return_fields_by_field_id – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

List[RecordDict]

first(**options)[source]

Retrieve the first matching record. Returns None if no records are returned.

This is similar to all(), except it sets page_size and max_records to 1.

Keyword Arguments
  • view – The name or ID of a view. If set, only the records in that view will be returned. The records will be sorted according to the order of the view.

  • fields – Name of field or fields to be retrieved. Default is all fields. Only data for fields whose names are in this list will be included in the records. If you don’t need every field, you can use this parameter to reduce the amount of data transferred.

  • sort – List of fields to sort by. Default order is ascending. This parameter specifies how the records will be ordered. If you set the view parameter, the returned records in that view will be sorted by these fields. If sorting by multiple columns, column names can be passed as a list. Sorting Direction is ascending by default, but can be reversed by prefixing the column name with a minus sign -.

  • formula – An Airtable formula. The formula will be evaluated for each record, and if the result is none of 0, false, "", NaN, [], or #Error! the record will be included in the response. If combined with view, only records in that view which satisfy the formula will be returned. For example, to only include records where COLUMN_A isn’t empty, pass in formula="{COLUMN_A}".

  • cell_format – The cell format to request from the Airtable API. Supported options are json (the default) and string. json will return cells as a JSON object. string will return the cell as a string. user_locale and time_zone must be set when using string.

  • user_locale – The user locale that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/220340268-Supported-locale-modifiers-for-SET-LOCALE for valid values.

  • time_zone – The time zone that should be used to format dates when using string as the cell_format. See https://support.airtable.com/hc/en-us/articles/216141558-Supported-timezones-for-SET-TIMEZONE for valid values.

  • return_fields_by_field_id – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

Optional[RecordDict]

create(fields, typecast=False, return_fields_by_field_id=False)[source]

Create a new record

>>> record = {'Name': 'John'}
>>> table = api.table('base_id', 'table_name')
>>> table.create(record)
Parameters
  • fields (Dict[str, WritableFieldValue]) – Fields to insert. Must be a dict with field names or IDs as keys.

  • typecast (bool, default: False) – The Airtable API will perform best-effort automatic data conversion from string values.

  • return_fields_by_field_id (bool, default: False) – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

RecordDict

batch_create(records, typecast=False, return_fields_by_field_id=False)[source]

Create a number of new records in batches.

>>> table.batch_create([{'Name': 'John'}, {'Name': 'Marc'}])
[
    {
        'id': 'recW9e0c9w0er9gug',
        'createdTime': '2017-03-14T22:04:31.000Z',
        'fields': {'Name': 'John'}
    },
    {
        'id': 'recW9e0c9w0er9guh',
        'createdTime': '2017-03-14T22:04:31.000Z',
        'fields': {'Name': 'Marc'}
    }
]
Parameters
  • records (Iterable[Dict[str, WritableFieldValue]]) – Iterable of dicts representing records to be created.

  • typecast (bool, default: False) – The Airtable API will perform best-effort automatic data conversion from string values.

  • return_fields_by_field_id (bool, default: False) – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

List[RecordDict]

update(record_id, fields, replace=False, typecast=False, return_fields_by_field_id=False)[source]

Update a particular record ID with the given fields.

>>> table.update('recwPQIfs4wKPyc9D', {"Age": 21})
{'id': 'recwPQIfs4wKPyc9D', 'fields': {'First Name': 'John', 'Age': 21}}
>>> table.update('recwPQIfs4wKPyc9D', {"Age": 22}, replace=True)
{'id': 'recwPQIfs4wKPyc9D', 'fields': {'Age': 22}}
Parameters
  • record_id (str) – An Airtable record ID.

  • fields (Dict[str, WritableFieldValue]) – Fields to update. Must be a dict with column names or IDs as keys.

  • replace (bool, default: False) – If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null. If False, only provided fields are updated.

  • typecast (bool, default: False) – The Airtable API will perform best-effort automatic data conversion from string values.

  • return_fields_by_field_id (bool, default: False) – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

RecordDict

batch_update(records, replace=False, typecast=False, return_fields_by_field_id=False)[source]

Update several records in batches.

Parameters
  • records (Iterable[UpdateRecordDict]) – Records to update.

  • replace (bool, default: False) – If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null. If False, only provided fields are updated.

  • typecast (bool, default: False) – The Airtable API will perform best-effort automatic data conversion from string values.

  • return_fields_by_field_id (bool, default: False) – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

List[RecordDict]

Returns

The list of updated records.

batch_upsert(records, key_fields, replace=False, typecast=False, return_fields_by_field_id=False)[source]

Update or create records in batches, either using id (if given) or using a set of fields (key_fields) to look for matches. For more information on how this operation behaves, see Airtable’s API documentation for Update multiple records.

New in version 1.5.0.

Parameters
  • records (Iterable[Dict[str, Any]]) – Records to update.

  • key_fields (List[str]) – List of field names that Airtable should use to match records in the input with existing records on the server.

  • replace (bool, default: False) – If True, record is replaced in its entirety by provided fields; if a field is not included its value will bet set to null. If False, only provided fields are updated.

  • typecast (bool, default: False) – The Airtable API will perform best-effort automatic data conversion from string values.

  • return_fields_by_field_id (bool, default: False) – An optional boolean value that lets you return field objects where the key is the field id. This defaults to false, which returns field objects where the key is the field name.

Return type

UpsertResultDict

Returns

Lists of created/updated record IDs, along with the list of all records affected.

delete(record_id)[source]

Delete the given record.

>>> table.delete('recwPQIfs4wKPyc9D')
{'id': 'recwPQIfs4wKPyc9D', 'deleted': True}
Parameters

record_id (str) – An Airtable record ID.

Return type

RecordDeletedDict

Returns

Confirmation that the record was deleted.

batch_delete(record_ids)[source]

Delete the given records, operating in batches.

>>> table.batch_delete(['recwPQIfs4wKPyc9D', 'recwDxIfs3wDPyc3F'])
[
    {'id': 'recwPQIfs4wKPyc9D', 'deleted': True},
    {'id': 'recwDxIfs3wDPyc3F', 'deleted': True}
]
Parameters

record_ids (Iterable[str]) – Record IDs to delete

Return type

List[RecordDeletedDict]

Returns

Confirmation that the records were deleted.

comments(record_id)[source]

Retrieve all comments on the given record.

Usage:
>>> table = Api.table("appNxslc6jG0XedVM", "tblslc6jG0XedVMNx")
>>> table.comments("recMNxslc6jG0XedV")
[
    Comment(
        id='comdVMNxslc6jG0Xe',
        text='Hello, @[usrVMNxslc6jG0Xed]!',
        created_time='2023-06-07T17:46:24.435891',
        last_updated_time=None,
        mentioned={
            'usrVMNxslc6jG0Xed': Mentioned(
                display_name='Alice',
                email='alice@example.com',
                id='usrVMNxslc6jG0Xed',
                type='user'
            )
        },
        author=Collaborator(
            id='usr0000pyairtable',
            email='pyairtable@example.com',
            name='Your pyairtable access token'
        )
    )
]
Parameters

record_id (str) – An Airtable record ID.

Return type

List[Comment]

add_comment(record_id, text)[source]

Create a comment on a record. See Create comment for details.

Usage:
>>> table = Api.table("appNxslc6jG0XedVM", "tblslc6jG0XedVMNx")
>>> comment = table.add_comment("recMNxslc6jG0XedV", "Hello, @[usrVMNxslc6jG0Xed]!")
>>> comment.text = "Never mind!"
>>> comment.save()
>>> comment.delete()
Parameters
  • record_id (str) – An Airtable record ID.

  • text (str) – The text of the comment. Use @[usrIdentifier] to mention users.

Return type

Comment

schema(*, force=False)[source]

Retrieve the schema of the current table.

Usage:
>>> table.schema()
TableSchema(
    id='tblslc6jG0XedVMNx',
    name='My Table',
    primary_field_id='fld6jG0XedVMNxFQW',
    fields=[...],
    views=[...]
)
Parameters

force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

TableSchema

create_field(name, type, description=None, options=None)[source]

Create a field on the table.

Parameters
  • name (str) – The unique name of the field.

  • field_type – One of the Airtable field types.

  • description (Optional[str], default: None) – A long form description of the table.

  • options (Optional[Dict[str, Any]], default: None) – Only available for some field types. For more information, read about the Airtable field model.

Return type

Union[AITextFieldSchema, AutoNumberFieldSchema, BarcodeFieldSchema, ButtonFieldSchema, CheckboxFieldSchema, CountFieldSchema, CreatedByFieldSchema, CreatedTimeFieldSchema, CurrencyFieldSchema, DateFieldSchema, DateTimeFieldSchema, DurationFieldSchema, EmailFieldSchema, ExternalSyncSourceFieldSchema, FormulaFieldSchema, LastModifiedByFieldSchema, LastModifiedTimeFieldSchema, MultilineTextFieldSchema, MultipleAttachmentsFieldSchema, MultipleCollaboratorsFieldSchema, MultipleLookupValuesFieldSchema, MultipleRecordLinksFieldSchema, MultipleSelectsFieldSchema, NumberFieldSchema, PercentFieldSchema, PhoneNumberFieldSchema, RatingFieldSchema, RichTextFieldSchema, RollupFieldSchema, SingleCollaboratorFieldSchema, SingleLineTextFieldSchema, SingleSelectFieldSchema, UrlFieldSchema, UnknownFieldSchema]

class pyairtable.Workspace[source]

Represents an Airtable workspace, which contains a number of bases and its own set of collaborators.

>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> ws.collaborators().name
'my first workspace'
>>> ws.create_base("Base Name", tables=[...])
<pyairtable.Base base_id="appMhESAta6clCCwF">

Most workspace functionality is limited to users on Enterprise billing plans.

__init__(api, workspace_id)[source]
create_base(name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters
  • name (str) – The name to give to the new base. Does not need to be unique.

  • tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information, collaborators, and invite links for the given workspace, caching the result.

See https://airtable.com/developers/web/api/get-workspace-collaborators

Parameters

force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

WorkspaceCollaborators

bases()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve all bases within the workspace.

Return type

List[Base]

property name: str

⚠ This feature is only available on Enterprise billing plans.

The name of the workspace.

Return type

str

delete()[source]

⚠ This feature is only available on Enterprise billing plans.

Delete the workspace.

See https://airtable.com/developers/web/api/delete-workspace

Usage:
>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> ws.delete()
Return type

None

move_base(base, target, index=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Move the given base to a new workspace.

See https://airtable.com/developers/web/api/move-base

Usage:
>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> base = api.workspace("appCwFmhESAta6clC")
>>> workspace.move_base(base, "wspSomeOtherPlace", index=0)
Return type

None

class pyairtable.Enterprise[source]

⚠ This feature is only available on Enterprise billing plans.

Represents an Airtable enterprise account.

>>> enterprise = api.enterprise("entUBq2RGdihxl3vU")
>>> enterprise.info().workspace_ids
['wspmhESAta6clCCwF', ...]
__init__(api, workspace_id)[source]
info()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information about the enterprise, caching the result.

Parameters

force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Return type

EnterpriseInfo

group(group_id, collaborations=True)[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve information on a single user group with the given ID.

Parameters
  • group_id (str) – A user group ID (grpQBq2RGdihxl3vU).

  • collaborations (bool, default: True) – If False, no collaboration data will be requested from Airtable. This may result in faster responses.

Return type

UserGroup

user(id_or_email, collaborations=True)[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve information on a single user with the given ID or email.

Parameters
  • id_or_email (str) – A user ID (usrQBq2RGdihxl3vU) or email address.

  • collaborations (bool, default: True) – If False, no collaboration data will be requested from Airtable. This may result in faster responses.

Return type

UserInfo

users(ids_or_emails, collaborations=True)[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve information on the users with the given IDs or emails.

Read more at Get users by ID or email.

Parameters
  • ids_or_emails (Iterable[str]) – A sequence of user IDs (usrQBq2RGdihxl3vU) or email addresses (or both).

  • collaborations (bool, default: True) – If False, no collaboration data will be requested from Airtable. This may result in faster responses.

Return type

List[UserInfo]

audit_log(*, page_size=None, page_limit=None, sort_asc=False, previous=None, next=None, start_time=None, end_time=None, user_id=None, event_type=None, model_id=None, category=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve and yield results from the Audit Log, one page of results at a time. Each result is an instance of AuditLogResponse and contains the pagination IDs returned from the API, as described in the linked documentation.

By default, the Airtable API will return up to 180 days of audit log events, going backwards from most recent. Retrieving all records may take some time, but is as straightforward as:

>>> enterprise = Enterprise("entYourEnterpriseId")
>>> events = [
...     event
...     for page in enterprise.audit_log()
...     for event in page.events
... ]

If you are creating a record of all audit log events, you probably want to start with the earliest events in the retention window and iterate chronologically. You’ll likely have a job running periodically in the background, so you’ll need some way to persist the pagination IDs retrieved from the API in case that job is interrupted and needs to be restarted.

The sample code below will use a local file to remember the next page’s ID, so that if the job is interrupted, it will resume where it left off (potentially processing some entries twice).

import os
import shelve
import pyairtable

def handle_event(event):
    print(event)

api = pyairtable.Api(os.environ["AIRTABLE_API_KEY"])
enterprise = api.enterprise(os.environ["AIRTABLE_ENTERPRISE_ID"])
persistence = shelve.open("audit_log.db")
first_page = persistence.get("next", None)

for page in enterprise.audit_log(sort_asc=True, next=first_page):
    for event in page.events:
        handle_event(event)
    persistence["next"] = page.pagination.next

For more information on any of the keyword parameters below, refer to the audit log events API documentation.

Parameters
  • page_size (Optional[int], default: None) – How many events per page to return (maximum 100).

  • page_limit (Optional[int], default: None) – How many pages to return before stopping.

  • sort_asc (Optional[bool], default: False) – Whether to sort in ascending order (earliest to latest) rather than descending order (latest to earliest).

  • previous (Optional[str], default: None) – Requests the previous page of results from the given ID. See the audit log integration guide for more information on pagination parameters.

  • next (Optional[str], default: None) – Requests the next page of results according to the given ID. See the audit log integration guide for more information on pagination parameters.

  • start_time (Union[str, date, datetime, None], default: None) – Earliest timestamp to retrieve (inclusive).

  • end_time (Union[str, date, datetime, None], default: None) – Latest timestamp to retrieve (inclusive).

  • originating_user_id – Retrieve audit log events originating from the provided user ID or IDs (maximum 100).

  • event_type (Union[str, Iterable[str], None], default: None) – Retrieve audit log events falling under the provided audit log event type or types (maximum 100).

  • model_id (Union[str, Iterable[str], None], default: None) – Retrieve audit log events taking action on, or involving, the provided model ID or IDs (maximum 100).

  • category (Union[str, Iterable[str], None], default: None) – Retrieve audit log events belonging to the provided audit log event category or categories.

Return type

Iterator[AuditLogResponse]

Returns

An object representing a single page of audit log results.

remove_user(user_id, replacement=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Unshare a user from all enterprise workspaces, bases, and interfaces. If applicable, the user will also be removed from as an enterprise admin.

See Remove user from enterprise for more information.

Parameters
  • user_id (str) – The user ID.

  • replacement (Optional[str], default: None) – If the user is the sole owner of any workspaces, you must specify a replacement user ID to be added as the new owner of such workspaces. If the user is not the sole owner of any workspaces, this is optional and will be ignored if provided.

Return type

UserRemoved

claim_users(users)[source]

⚠ This feature is only available on Enterprise billing plans.

Batch manage organizations enterprise account users. This endpoint allows you to change a user’s membership status from being unmanaged to being an organization member, and vice versa.

See Manage user membership for more information.

Parameters

users (Dict[str, Literal[‘managed’, ‘unmanaged’]]) – A dict mapping user IDs or emails to the desired state, either "managed" or "unmanaged".

Return type

ClaimUsersResponse

delete_users(emails)[source]

⚠ This feature is only available on Enterprise billing plans.

Delete multiple users by email.

Parameters

emails (Iterable[str]) – A list or other iterable of email addresses.

Return type

DeleteUsersResponse

pyairtable.retry_strategy(*, status_forcelist=(429,), backoff_factor=0.1, total=5, allowed_methods=None, **kwargs)[source]

Create a Retry instance with adjustable default values. Api accepts this via the retry_strategy= parameter.

For example, to increase the total number of retries:

>>> from pyairtable import Api, retry_strategy
>>> api = Api('auth_token', retry_strategy=retry_strategy(total=10))

Or to retry certain types of server errors in addition to rate limiting errors:

>>> from pyairtable import Api, retry_strategy
>>> retry = retry_strategy(status_forcelist=(429, 500, 502, 503, 504))
>>> api = Api('auth_token', retry_strategy=retry)

You can also disable retries entirely:

>>> from pyairtable import Api
>>> api = Api('auth_token', retry_strategy=None)

New in version 1.4.0.

Parameters
  • status_forcelist (Tuple[int, ...], default: (429,)) – Status codes which should be retried.

  • allowed_methods (Optional[Collection[str]], default: None) – HTTP methods which can be retried. If None, then all HTTP methods will be retried.

  • backoff_factor (Union[int, float], default: 0.1) – A backoff factor to apply between attempts after the second try. Sleep time between each request will be calculated as backoff_factor * (2 ** (retry_count - 1))

  • total (int, default: 5) – Maximum number of retries. Note that 0 means no retries, whereas 1 will execute a total of two requests (original + 1 retry).

  • **kwargs – Accepts any valid parameter to Retry.

Return type

Retry

API: pyairtable.api.types

pyAirtable provides a number of type aliases and TypedDicts which are used as inputs and return values to various pyAirtable methods.

pyairtable.api.types.RecordId

An alias for str used internally for disambiguation. Record IDs for Airtable look like "recAdw9EjV90xbZ".

pyairtable.api.types.Timestamp

An alias for str used internally for disambiguation. Airtable returns timestamps as ISO 8601 UTC strings, e.g. "2023-05-22T21:24:15.333134Z"

pyairtable.api.types.FieldName

An alias for str used internally for disambiguation. Field names can be any valid string.

class pyairtable.api.types.NestedIdDict[source]
class pyairtable.api.types.AITextDict[source]

A dict representing text generated by AI.

>>> record = table.get('recW8eG2x0ew1Af')
>>> record['fields']['Generated Text']
{
    'state': 'generated',
    'isStale': False,
    'value': '...'
}
class pyairtable.api.types.AttachmentDict[source]

A dict representing an attachment stored in an Attachments field.

>>> record = table.get('recW8eG2x0ew1Af')
>>> record['fields']['Attachments']
[
    {
        'id': 'attW8eG2x0ew1Af',
        'url': 'https://example.com/hello.jpg',
        'filename': 'hello.jpg'
    }
]

See https://airtable.com/developers/web/api/field-model#multipleattachment

class pyairtable.api.types.CreateAttachmentDict[source]

A dict representing a new attachment to be written to the Airtable API.

>>> new_attachment = {
...     "url": "https://example.com/image.jpg",
...     "filename": "something_else.jpg",
... }
>>> existing = record["fields"].setdefault("Attachments", [])
>>> existing.append(new_attachment)
>>> table.update(existing["id"], existing["fields"])
class pyairtable.api.types.BarcodeDict[source]

A dict representing the value stored in a Barcode field.

>>> record = table.get('recW8eG2x0ew1Af')
>>> record['fields']['Barcode']
{'type': 'upce', 'text': '01234567'}

See https://airtable.com/developers/web/api/field-model#barcode

class pyairtable.api.types.ButtonDict[source]

A dict representing the value stored in a Button field.

>>> record = table.get('recW8eG2x0ew1Af')
>>> record['fields']['Click Me']
{'label': 'Click Me', 'url': 'http://example.com'}

See https://airtable.com/developers/web/api/field-model#button

class pyairtable.api.types.CollaboratorDict[source]

A dict representing the value stored in a User field returned from the API.

>>> record = table.get('recW8eG2x0ew1Af')
>>> record['fields']['Created By']
{
    'id': 'usrAdw9EjV90xbW',
    'email': 'alice@example.com',
    'name': 'Alice Arnold'
}
>>> record['fields']['Collaborators']
[
    {
        'id': 'usrAdw9EjV90xbW',
        'email': 'alice@example.com',
        'name': 'Alice Arnold'
    },
    {
        'id': 'usrAdw9EjV90xbX',
        'email': 'bob@example.com',
        'name': 'Bob Barker'
    }
]

See https://airtable.com/developers/web/api/field-model#collaborator

class pyairtable.api.types.CollaboratorEmailDict[source]

A dict representing a collaborator identified by email, not by ID. Often used when writing to the API, because the email of a collaborator may be more easily accessible than their Airtable user ID.

>>> table = Table("access_token", "base_id", "api_key")
>>> record = table.update("recW8eG2x0ew1Af", {
...     "Collaborator": {"email": "alice@example.com"}
... })
>>> record
{
    'id': 'recW8eG2x0ew1Af',
    'createdTime': 2023-06-07T17:35:17Z',
    'fields': {
        'Collaborator': {
            'id': 'usrAdw9EjV90xbW',
            'email': 'alice@example.com',
            'name': 'Alice Arnold'
        }
    }
}
class pyairtable.api.types.AddUserCollaboratorDict[source]

Used to add a user as a collaborator to a base, workspace, or interface.

class pyairtable.api.types.AddGroupCollaboratorDict[source]

Used to add a group as a collaborator to a base, workspace, or interface.

pyairtable.api.types.FieldValue: typing_extensions.TypeAlias = typing.Any

Represents the types of values that we might receive from the API. At present, is an alias for Any because we don’t want to lose forward compatibility with any changes Airtable makes in the future.

pyairtable.api.types.Fields

A mapping of field names to values that we might receive from the API.

alias of Dict[str, Any]

pyairtable.api.types.WritableFieldValue

Represents the types of values that can be written to the Airtable API.

alias of Union[None, str, int, float, bool, pyairtable.api.types.CollaboratorDict, pyairtable.api.types.CollaboratorEmailDict, pyairtable.api.types.BarcodeDict, List[str], List[pyairtable.api.types.AttachmentDict], List[pyairtable.api.types.CreateAttachmentDict], List[pyairtable.api.types.CollaboratorDict], List[pyairtable.api.types.CollaboratorEmailDict]]

pyairtable.api.types.WritableFields

A mapping of field names to values which can be sent to the API.

alias of Dict[str, Union[None, str, int, float, bool, pyairtable.api.types.CollaboratorDict, pyairtable.api.types.CollaboratorEmailDict, pyairtable.api.types.BarcodeDict, List[str], List[pyairtable.api.types.AttachmentDict], List[pyairtable.api.types.CreateAttachmentDict], List[pyairtable.api.types.CollaboratorDict], List[pyairtable.api.types.CollaboratorEmailDict]]]

class pyairtable.api.types.RecordDict[source]

A dict representing a record returned from the Airtable API. See List records.

Usage:
>>> table.first(formula="Name = 'Alice'")
{
    'id': 'recAdw9EjV90xbW',
    'createdTime': '2023-05-22T21:24:15.333134Z',
    'fields': {'Name': 'Alice', 'Department': 'Engineering'}
}
class pyairtable.api.types.CreateRecordDict[source]

A dict representing the payload passed to the Airtable API to create a record.

Field values must each be a WritableFieldValue.

Usage:
>>> table.create({
...     "fields": {
...         "Field Name": "Field Value",
...         "Other Field": ["Value 1", "Value 2"]
...     }
... })
class pyairtable.api.types.UpdateRecordDict[source]

A dict representing the payload passed to the Airtable API to update a record.

Field values must each be a WritableFieldValue.

Usage:
>>> table.batch_update([
...     {
...         "id": "recAdw9EjV90xbW",
...         "fields": {
...             "Email": "alice@example.com"
...         }
...     },
...     {
...         "id": "recAdw9EjV90xbX",
...         "fields": {
...             "Email": "bob@example.com"
...         }
...     }
... ])
class pyairtable.api.types.RecordDeletedDict[source]

A dict representing the payload returned by the Airtable API to confirm a deletion.

Usage:
>>> table.delete("recAdw9EjV90xbZ")
{'id': 'recAdw9EjV90xbZ', 'deleted': True}
class pyairtable.api.types.UpsertResultDict[source]

A dict representing the payload returned by the Airtable API after an upsert. For more details on this data structure, see the Update multiple records API documentation.

Usage:
>>> table.batch_upsert(records, key_fields=["Name"])
{
    'createdRecords': [...],
    'updatedRecords': [...],
    'records': [...]
}
class pyairtable.api.types.UserAndScopesDict[source]

A dict representing the Get user ID & scopes endpoint.

Usage:
>>> api.whoami()
{'id': 'usrX9e810wHn3mMLz'}
pyairtable.api.types.assert_typed_dict(cls, obj)[source]

Raises a TypeError if the given object is not a dict, or raises pydantic.ValidationError if the given object does not conform to the interface declared by the given TypedDict.

Parameters
  • cls (Type[TypeVar(T)]) – The TypedDict class.

  • obj (Any) – The object that should be a TypedDict.

Usage:
>>> assert_typed_dict(
...     RecordDict,
...     {
...         "id": "recAdw9EjV90xbZ",
...         "createdTime": "2023-05-22T21:24:15.333134Z",
...         "fields": {},
...     }
... )
{
    'id': 'recAdw9EjV90xbZ',
    'createdTime': '2023-05-22T21:24:15.333134Z',
    'fields': {}
}
>>> assert_typed_dict(RecordDict, {"foo": "bar"})
Traceback (most recent call last):
pydantic.error_wrappers.ValidationError: 3 validation errors for RecordDict
id
  field required (type=value_error.missing)
createdTime
  field required (type=value_error.missing)
fields
  field required (type=value_error.missing)
Return type

TypeVar(T)

pyairtable.api.types.assert_typed_dicts(cls, objects)[source]

Like assert_typed_dict() but for a list of dicts.

Parameters
  • cls (Type[TypeVar(T)]) – The TypedDict class.

  • objects (Any) – The object that should be a list of TypedDicts.

Return type

List[TypeVar(T)]

pyairtable.api.types.is_airtable_error(obj)[source]

Determine whether the given object represents an Airtable error.

Return type

bool

API: pyairtable.formulas

pyairtable.formulas.match(dict_values, *, match_any=False)[source]

Create one or more EQUAL() expressions for each provided dict value. If more than one assetions is included, the expressions are groupped together into using AND() (all values must match).

If match_any=True, expressions are grouped with OR(), record is return if any of the values match.

This function also handles escaping field names and casting python values to the appropriate airtable types using to_airtable_value() on all provided values to help generate the expected formula syntax.

If you need more advanced matching you can build similar expressions using lower level forumula primitives.

Parameters

dict_values (Dict[str, Any]) – dictionary containing column names and values

Keyword Arguments

default (match_any (bool,) – False): If True, matches if any of the provided values match. Otherwise, all values must match.

Usage:
>>> match({"First Name": "John", "Age": 21})
"AND({First Name}='John',{Age}=21)"
>>> match({"First Name": "John", "Age": 21}, match_any=True)
"OR({First Name}='John',{Age}=21)"
>>> match({"First Name": "John"})
"{First Name}='John'"
>>> match({"Registered": True})
"{Registered}=1"
>>> match({"Owner's Name": "Mike"})
"{Owner\'s Name}='Mike'"
Return type

str

pyairtable.formulas.escape_quotes(value)[source]

Ensures any quotes are escaped. Already escaped quotes are ignored.

Parameters

value (str) – text to be escaped

Usage:
>>> escape_quotes("Player's Name")
Player\'s Name
>>> escape_quotes("Player\'s Name")
Player\'s Name
Return type

str

pyairtable.formulas.to_airtable_value(value)[source]

Cast value to appropriate airtable types and format. For example, to check bool values in formulas, you actually to compare to 0 and 1.

Input

Output

bool

int

str

str; text is wrapped in ‘single quotes’; existing quotes are escaped.

all others

unchanged

Parameters

value (Any) – value to be cast.

Return type

Any

pyairtable.formulas.EQUAL(left, right)[source]

Create an equality assertion

>>> EQUAL(2,2)
'2=2'
Return type

str

pyairtable.formulas.FIELD(name)[source]

Create a reference to a field. Quotes are escaped.

Parameters

name (str) – field name

Usage:
>>> FIELD("First Name")
'{First Name}'
>>> FIELD("Guest's Name")
"{Guest\'s Name}"
Return type

str

pyairtable.formulas.STR_VALUE(value)[source]

Wrap string in quotes. This is needed when referencing a string inside a formula. Quotes are escaped.

>>> STR_VALUE("John")
"'John'"
>>> STR_VALUE("Guest's Name")
"'Guest\'s Name'"
>>> EQUAL(STR_VALUE("John"), FIELD("First Name"))
"'John'={First Name}"
Return type

str

pyairtable.formulas.IF(logical, value1, value2)[source]

Create an IF statement

>>> IF(1=1, 0, 1)
'IF(1=1, 0, 1)'
Return type

str

pyairtable.formulas.FIND(what, where, start_position=0)[source]

Create a FIND statement

>>> FIND(STR_VALUE(2021), FIELD('DatetimeCol'))
"FIND('2021', {DatetimeCol})"
Parameters
  • what (str) – String to search for

  • where (str) – Where to search. Could be a string, or a field reference.

  • start_position (int, default: 0) – Index of where to start search. Default is 0.

Return type

str

pyairtable.formulas.AND(*args)[source]

Create an AND Statement

>>> AND(1, 2, 3)
'AND(1, 2, 3)'
Return type

str

pyairtable.formulas.OR(*args)[source]

New in version 1.2.0.

Creates an OR Statement

>>> OR(1, 2, 3)
'OR(1, 2, 3)'
Return type

str

pyairtable.formulas.LOWER(value)[source]

New in version 1.3.0.

Creates the LOWER function, making a string lowercase. Can be used on a string or a field name and will lower all the strings in the field.

>>> LOWER("TestValue")
"LOWER(TestValue)"
Return type

str

pyairtable.formulas.NOT_EQUAL(left, right)[source]

Create an inequality assertion

>>> NOT_EQUAL(2,2)
'2!=2'
Return type

str

pyairtable.formulas.LESS_EQUAL(left, right)[source]

Create a less than assertion

>>> LESS_EQUAL(2,2)
'2<=2'
Return type

str

pyairtable.formulas.GREATER_EQUAL(left, right)[source]

Create a greater than assertion

>>> GREATER_EQUAL(2,2)
'2>=2'
Return type

str

pyairtable.formulas.LESS(left, right)[source]

Create a less assertion

>>> LESS(2,2)
'2<2'
Return type

str

pyairtable.formulas.GREATER(left, right)[source]

Create a greater assertion

>>> GREATER(2,2)
'2>2'
Return type

str

API: pyairtable.models

pyAirtable will wrap certain API responses in type-annotated models, some of which will be deeply nested within each other. Models which implementers can interact with directly are documented below.

pydantic model pyairtable.models.Collaborator[source]

Represents an Airtable user being passed from the API.

This is only used in contexts involving other models (e.g. Comment). In contexts where API values are returned as dict, we will return collaborator information as a dict as well.

field id: str

Airtable’s unique ID for the user, in the format usrXXXXXXXXXXXXXX.

field email: Optional[str]

The email address of the user.

field name: Optional[str]

The display name of the user.

pydantic model pyairtable.models.Comment[source]

A record comment that has been retrieved from the Airtable API.

>>> comment = table.add_comment("recMNxslc6jG0XedV", "Hello, @[usrVMNxslc6jG0Xed]!")
>>> table.comments("recMNxslc6jG0XedV")
[
    Comment(
        id='comdVMNxslc6jG0Xe',
        text='Hello, @[usrVMNxslc6jG0Xed]!',
        created_time='2023-06-07T17:46:24.435891',
        last_updated_time=None,
        mentioned={
            'usrVMNxslc6jG0Xed': Mentioned(
                display_name='Alice',
                email='alice@example.com',
                id='usrVMNxslc6jG0Xed',
                type='user'
            )
        },
        author=Collaborator(
            id='usr0000pyairtable',
            email='pyairtable@example.com',
            name='Your pyairtable access token'
        )
    )
]
>>> comment.text = "Never mind!"
>>> comment.save()
>>> comment.delete()

The following fields can be modified and saved: text

field id: str

The unique ID of the comment.

field text: str

The text of the comment.

field created_time: str

The ISO 8601 timestamp of when the comment was created.

field last_updated_time: Optional[str]

The ISO 8601 timestamp of when the comment was last edited.

field author: pyairtable.models.collaborator.Collaborator

The account which created the comment.

field mentioned: Optional[Dict[str, Mentioned]]

Users or groups that were mentioned in the text.

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

pydantic model pyairtable.models.Webhook[source]

A webhook that has been retrieved from the Airtable API.

>>> spec = {
...     "options": {
...         "filters": {
...             "dataTypes": ["tableData"],
...         }
...     }
... }
>>> base.add_webhook("https://example.com", spec)
CreateWebhookResponse(
    id='ach00000000000001',
    mac_secret_base64='c3VwZXIgZHVwZXIgc2VjcmV0',
    expiration_time='2023-07-01T00:00:00.000Z'
)
>>> webhooks = base.webhooks()
>>> webhooks[0]
Webhook(
    id='ach00000000000001',
    are_notifications_enabled=True,
    cursor_for_next_payload=1,
    is_hook_enabled=True,
    last_successful_notification_time=None,
    notification_url="https://example.com",
    last_notification_result=None,
    expiration_time="2023-07-01T00:00:00.000Z",
    specification: WebhookSpecification(...)
)
>>> webhooks[0].disable_notifications()
>>> webhooks[0].enable_notifications()
>>> webhooks[0].extend_expiration()
>>> webhooks[0].delete()
field id: str
field are_notifications_enabled: bool
field cursor_for_next_payload: int
field is_hook_enabled: bool
field last_successful_notification_time: Optional[str]
field notification_url: Optional[str]
field last_notification_result: Optional[WebhookNotificationResult]
field expiration_time: Optional[str]
field specification: WebhookSpecification
enable_notifications()[source]

Turn on notifications for this webhook. See Enable/disable webhook notifications.

Return type

None

disable_notifications()[source]

Turn off notifications for this webhook. See Enable/disable webhook notifications.

Return type

None

extend_expiration()[source]

Extend the life of a webhook by seven days. See Refresh a webhook.

Return type

None

payloads(cursor=1, *, limit=None)[source]

Iterate through all payloads on or after the given cursor. See WebhookPayload. Each payload will contain an extra attribute, cursor, which you will need to store if you want to later resume retrieving payloads after that point.

For more details on the mechanisms of retrieving webhook payloads, or to find more information about the data structures you’ll get back, see List webhook payloads.

Parameters
  • cursor (int, default: 1) – The cursor of the first webhook payload to retrieve.

  • limit (Optional[int], default: None) – The number of payloads to yield before stopping. If not provided, will retrieve all remaining payloads.

Usage:
>>> webhook = Base.webhook("ach00000000000001")
>>> iter_payloads = webhook.payloads()
>>> next(iter_payloads)
WebhookPayload(
    timestamp="2022-02-01T21:25:05.663Z",
    base_transaction_number=4,
    payload_format="v0",
    action_metadata=ActionMetadata(
        source="client",
        source_metadata={
            "user": {
                "id": "usr00000000000000",
                "email": "foo@bar.com",
                "permissionLevel": "create"
            }
        }
    ),
    changed_tables_by_id={},
    created_tables_by_id={},
    destroyed_table_ids=["tbl20000000000000", "tbl20000000000001"],
    error=None,
    error_code=None,
    cursor=1
)
Return type

Iterator[WebhookPayload]

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

pydantic model pyairtable.models.WebhookNotification[source]

Represents the value that Airtable will POST to the webhook’s notification URL.

This will not contain the full webhook payload; it will only contain the IDs of the base and the webhook which triggered the notification. You will need to use Webhook.payloads to retrieve the actual payloads describing the change(s) which triggered the webhook.

You will also need some way to persist the cursor of the webhook payload, so that on subsequent calls you do not retrieve the same payloads again.

Usage:
from flask import Flask, request
from pyairtable import Api
from pyairtable.models import WebhookNotification

app = Flask(__name__)

@app.route("/airtable-webhook", methods=["POST"])
def airtable_webhook():
    body = request.data
    header = request.headers["X-Airtable-Content-MAC"]
    secret = app.config["AIRTABLE_WEBHOOK_SECRET"]
    event = WebhookNotification.from_request(body, header, secret)
    airtable = Api(app.config["AIRTABLE_API_KEY"])
    webhook = airtable.base(event.base.id).webhook(event.webhook.id)
    cursor = int(your_db.get(f"cursor_{event.webhook}", 0)) + 1
    for payload in webhook.payloads(cursor=cursor):
        # ...do stuff...
        your_db.set(f"cursor_{event.webhook}", payload.cursor)
    return ("", 204)  # intentionally empty response

See Webhook notification delivery for more information on how these payloads are structured.

field base: pyairtable.models.webhook._NestedId
field webhook: pyairtable.models.webhook._NestedId
field timestamp: str
classmethod from_request(body, header, secret)[source]

Validate a request body and X-Airtable-Content-MAC header using the secret returned when the webhook was created.

Parameters
  • body (str) – The full request body sent over the wire.

  • header (str) – The request’s X-Airtable-Content-MAC header.

  • secret (Union[bytes, str]) – The MAC secret provided when the webhook was created. If str, it’s assumed this is still base64-encoded; if bytes, it’s assumed that this has been decoded.

Returns

An instance parsed from the provided request body.

Return type

WebhookNotification

Raises

ValueError – if the header and body do not match the secret.

pydantic model pyairtable.models.WebhookPayload[source]

Payload returned by Webhook.payloads(). See API docs: Webhooks payload.

field timestamp: str
field base_transaction_number: int
field payload_format: str
field action_metadata: Optional[pyairtable.models.webhook.WebhookPayload.ActionMetadata]
field changed_tables_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.TableChanged] [Optional]
field created_tables_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.TableCreated] [Optional]
field destroyed_table_ids: List[str] [Optional]
field error: Optional[bool]
field error_code: Optional[str]
field cursor: Optional[int]

This is not a part of Airtable’s webhook payload specification. This indicates the cursor field in the response which provided this payload.

pydantic model ActionMetadata[source]
field source: str
field source_metadata: Dict[Any, Any] [Optional]
pydantic model TableInfo[source]
field name: str
field description: Optional[str]
pydantic model FieldInfo[source]
field name: Optional[str]
field type: Optional[str]
pydantic model FieldChanged[source]
field current: pyairtable.models.webhook.WebhookPayload.FieldInfo
field previous: Optional[pyairtable.models.webhook.WebhookPayload.FieldInfo]
pydantic model TableChanged[source]
field changed_views_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.ViewChanged] [Optional]
field changed_fields_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.FieldChanged] [Optional]
field changed_records_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.RecordChanged] [Optional]
field created_fields_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.FieldInfo] [Optional]
field created_records_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.RecordCreated] [Optional]
field changed_metadata: Optional[pyairtable.models.webhook.WebhookPayload.TableChanged.ChangedMetadata]
field destroyed_field_ids: List[str] [Optional]
field destroyed_record_ids: List[str] [Optional]
pydantic model ChangedMetadata[source]
field current: pyairtable.models.webhook.WebhookPayload.TableInfo
field previous: pyairtable.models.webhook.WebhookPayload.TableInfo
pydantic model ViewChanged[source]
field changed_records_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.RecordChanged] [Optional]
field created_records_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.RecordCreated] [Optional]
field destroyed_record_ids: List[str] [Optional]
pydantic model TableCreated[source]
field metadata: Optional[pyairtable.models.webhook.WebhookPayload.TableInfo]
field fields_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.FieldInfo] [Optional]
field records_by_id: Dict[str, pyairtable.models.webhook.WebhookPayload.RecordCreated] [Optional]
pydantic model RecordChanged[source]
field current: pyairtable.models.webhook.WebhookPayload.CellValuesByFieldId
field previous: Optional[pyairtable.models.webhook.WebhookPayload.CellValuesByFieldId]
field unchanged: Optional[pyairtable.models.webhook.WebhookPayload.CellValuesByFieldId]
pydantic model CellValuesByFieldId[source]
field cell_values_by_field_id: Dict[str, Any]
pydantic model RecordCreated[source]
field created_time: str
field cell_values_by_field_id: Dict[str, Any]

API: pyairtable.models.audit

pydantic model pyairtable.models.audit.AuditLogResponse[source]

Represents a page of audit log events.

See Audit log events for more information on how to interpret this data structure.

field events: List[pyairtable.models.audit.AuditLogEvent]
field pagination: Optional[pyairtable.models.audit.AuditLogResponse.Pagination]
pydantic model Pagination[source]
field next: Optional[str]
field previous: Optional[str]
pydantic model pyairtable.models.audit.AuditLogEvent[source]

Represents a single audit log event.

See Audit log events for more information on how to interpret this data structure.

field id: str
field timestamp: str
field action: str
field actor: pyairtable.models.audit.AuditLogActor
field model_id: str
field model_type: str
field payload: Dict[str, Any]
field payload_version: str
field context: pyairtable.models.audit.AuditLogEvent.Context
field origin: pyairtable.models.audit.AuditLogEvent.Origin
pydantic model Context[source]
field base_id: Optional[str]
field action_id: str
field enterprise_account_id: str
field descendant_enterprise_account_id: Optional[str]
field interface_id: Optional[str]
field workspace_id: Optional[str]
pydantic model Origin[source]
field ip_address: str
field user_agent: str
field oauth_access_token_id: Optional[str]
field personal_access_token_id: Optional[str]
field session_id: Optional[str]
pydantic model pyairtable.models.audit.AuditLogActor[source]
field type: str
field user: Optional[pyairtable.models.audit.AuditLogActor.UserInfo]
field view_id: Optional[str]
field automation_id: Optional[str]
pydantic model UserInfo[source]
field id: str
field email: str
field name: Optional[str]

API: pyairtable.models.schema

pydantic model pyairtable.models.schema.Bases[source]

The list of bases visible to the API token.

See https://airtable.com/developers/web/api/list-bases

field bases: List[pyairtable.models.schema.Bases.Info] [Optional]
base(base_id)[source]

Get basic information about the base with the given ID.

Return type

Info

pydantic model Info[source]
field id: str
field name: str
field permission_level: str
pydantic model pyairtable.models.schema.BaseCollaborators[source]

Detailed information about who can access a base.

See https://airtable.com/developers/web/api/get-base-collaborators

field id: str
field name: str
field permission_level: str
field workspace_id: str
field interfaces: Dict[str, BaseCollaborators.InterfaceCollaborators] [Optional]
field group_collaborators: BaseCollaborators.GroupCollaborators [Optional]
field individual_collaborators: BaseCollaborators.IndividualCollaborators [Optional]
pydantic model InterfaceCollaborators[source]
field created_time: str
field group_collaborators: List[GroupCollaborator] [Optional]
field individual_collaborators: List[IndividualCollaborator] [Optional]
add(collaborator_type, collaborator_id, permission_level)

Add a user or group as a collaborator to this Airtable object.

Parameters
  • collaborator_type (str) – Either 'user' or 'group'.

  • collaborator_id (str) – The user or group ID.

  • permission_level (str) – See application permission levels.

Return type

None

add_collaborators(collaborators)

Add multiple collaborators to this Airtable object.

Parameters

collaborators (Iterable[Union[AddUserCollaboratorDict, AddGroupCollaboratorDict]]) – A list of dict that conform to the specification laid out in the Add base collaborator API documentation.

Return type

None

add_group(group_id, permission_level)

Add a group as a collaborator to this Airtable object.

Parameters
Return type

None

add_user(user_id, permission_level)

Add a user as a collaborator to this Airtable object.

Parameters
Return type

None

remove(collaborator_id)

Remove a user or group as a collaborator.

Parameters

collaborator_id (str) – The user or group ID.

Return type

None

update(collaborator_id, permission_level)

Change the permission level granted to a user or group.

Parameters
Return type

None

pydantic model GroupCollaborators[source]
field via_base: List[pyairtable.models.schema.GroupCollaborator] [Optional]
field via_workspace: List[pyairtable.models.schema.GroupCollaborator] [Optional]
pydantic model IndividualCollaborators[source]
field via_base: List[pyairtable.models.schema.IndividualCollaborator] [Optional]
field via_workspace: List[pyairtable.models.schema.IndividualCollaborator] [Optional]
field via_base: List[InviteLink] [Optional]
field via_workspace: List[WorkspaceInviteLink] [Optional]
add(collaborator_type, collaborator_id, permission_level)

Add a user or group as a collaborator to this Airtable object.

Parameters
  • collaborator_type (str) – Either 'user' or 'group'.

  • collaborator_id (str) – The user or group ID.

  • permission_level (str) – See application permission levels.

Return type

None

add_collaborators(collaborators)

Add multiple collaborators to this Airtable object.

Parameters

collaborators (Iterable[Union[AddUserCollaboratorDict, AddGroupCollaboratorDict]]) – A list of dict that conform to the specification laid out in the Add base collaborator API documentation.

Return type

None

add_group(group_id, permission_level)

Add a group as a collaborator to this Airtable object.

Parameters
Return type

None

add_user(user_id, permission_level)

Add a user as a collaborator to this Airtable object.

Parameters
Return type

None

remove(collaborator_id)

Remove a user or group as a collaborator.

Parameters

collaborator_id (str) – The user or group ID.

Return type

None

update(collaborator_id, permission_level)

Change the permission level granted to a user or group.

Parameters
Return type

None

pydantic model pyairtable.models.schema.BaseShares[source]

Collection of shared views in a base.

See https://airtable.com/developers/web/api/list-shares

field shares: List[pyairtable.models.schema.BaseShares.Info]
pydantic model Info[source]
field state: str
field created_by_user_id: str
field created_time: str
field share_id: str
field type: str
field is_password_protected: bool
field block_installation_id: Optional[str]
field restricted_to_email_domains: List[str] [Optional]
field view_id: Optional[str]
field effective_email_domain_allow_list: List[str] [Optional]
enable()[source]

Enable the base share.

Return type

None

disable()[source]

Disable the base share.

Return type

None

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

pydantic model pyairtable.models.schema.BaseSchema[source]

Schema of all tables within the base.

See https://airtable.com/developers/web/api/get-base-schema

Usage:
>>> schema = api.base(base_id).schema()
>>> schema.tables
[TableSchema(...), ...]
>>> schema.table("Table Name")
TableSchema(
    id='tbl6jG0XedVMNxFQW',
    name='Table Name',
    primary_field_id='fld0XedVMNxFQW6jG',
    description=None,
    fields=[...],
    views=[...]
)
field tables: List[pyairtable.models.schema.TableSchema]
table(id_or_name)[source]

Get the schema for the table with the given ID or name.

Return type

TableSchema

pydantic model pyairtable.models.schema.TableSchema[source]

Metadata for a table.

See https://airtable.com/developers/web/api/get-base-schema

Usage:
>>> schema = base.table("Table Name").schema()
>>> schema.id
'tbl6clmhESAtaCCwF'
>>> schema.name
'Table Name'
>>> schema.fields
[FieldSchema(...), ...]
>>> schema().field("fld6jG0XedVMNxFQW")
SingleLineTextFieldSchema(
    id='fld6jG0XedVMNxFQW',
    name='Name',
    type='singleLineText'
)
>>> schema.views
[ViewSchema(...), ...]
>>> schema().view("View Name")
ViewSchema(
    id='viw6jG0XedVMNxFQW',
    name='My Grid View',
    type='grid'
)

The following fields can be modified and saved: name, description

field id: str
field name: str
field primary_field_id: str
field description: Optional[str]
field fields: List[FieldSchema]
field views: List[ViewSchema]
field(id_or_name)[source]

Get the schema for the field with the given ID or name.

Return type

Union[AITextFieldSchema, AutoNumberFieldSchema, BarcodeFieldSchema, ButtonFieldSchema, CheckboxFieldSchema, CountFieldSchema, CreatedByFieldSchema, CreatedTimeFieldSchema, CurrencyFieldSchema, DateFieldSchema, DateTimeFieldSchema, DurationFieldSchema, EmailFieldSchema, ExternalSyncSourceFieldSchema, FormulaFieldSchema, LastModifiedByFieldSchema, LastModifiedTimeFieldSchema, MultilineTextFieldSchema, MultipleAttachmentsFieldSchema, MultipleCollaboratorsFieldSchema, MultipleLookupValuesFieldSchema, MultipleRecordLinksFieldSchema, MultipleSelectsFieldSchema, NumberFieldSchema, PercentFieldSchema, PhoneNumberFieldSchema, RatingFieldSchema, RichTextFieldSchema, RollupFieldSchema, SingleCollaboratorFieldSchema, SingleLineTextFieldSchema, SingleSelectFieldSchema, UrlFieldSchema, UnknownFieldSchema]

view(id_or_name)[source]

Get the schema for the view with the given ID or name.

Return type

ViewSchema

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

pydantic model pyairtable.models.schema.ViewSchema[source]

Metadata for a view.

See https://airtable.com/developers/web/api/get-view-metadata

Usage:
>>> vw = table.schema().view("View name")
>>> vw.name
'View name'
>>> vw.type
'grid'
>>> vw.delete()
field id: str
field type: str
field name: str
field personal_for_user_id: Optional[str]
field visible_field_ids: Optional[List[str]]
delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

pydantic model pyairtable.models.schema.GroupCollaborator[source]
field created_time: str
field granted_by_user_id: str
field group_id: str
field name: str
field permission_level: str
pydantic model pyairtable.models.schema.IndividualCollaborator[source]
field created_time: str
field granted_by_user_id: str
field user_id: str
field email: str
field permission_level: str
pydantic model pyairtable.models.schema.BaseIndividualCollaborator[source]
field base_id: str
field created_time: str
field granted_by_user_id: str
field user_id: str
field email: str
field permission_level: str
pydantic model pyairtable.models.schema.BaseGroupCollaborator[source]
field base_id: str
field created_time: str
field granted_by_user_id: str
field group_id: str
field name: str
field permission_level: str

Represents an invite link.

field id: str
field type: str
field created_time: str
field invited_email: Optional[str]
field referred_by_user_id: str
field permission_level: str
field restricted_to_email_domains: List[str] [Optional]
delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

Represents a base invite link.

field base_id: str
delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

field id: str
field type: str
field created_time: str
field invited_email: Optional[str]
field referred_by_user_id: str
field permission_level: str
field restricted_to_email_domains: List[str] [Optional]

Represents an invite link to a workspace that was returned within a base schema.

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

field id: str
field type: str
field created_time: str
field invited_email: Optional[str]
field referred_by_user_id: str
field permission_level: str
field restricted_to_email_domains: List[str] [Optional]

Represents an invite link to an interface that was returned within a base schema.

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

field id: str
field type: str
field created_time: str
field invited_email: Optional[str]
field referred_by_user_id: str
field permission_level: str
field restricted_to_email_domains: List[str] [Optional]
pydantic model pyairtable.models.schema.EnterpriseInfo[source]

Information about groups, users, workspaces, and email domains associated with an enterprise account.

See https://airtable.com/developers/web/api/get-enterprise

field id: str
field created_time: str
field group_ids: List[str]
field user_ids: List[str]
field workspace_ids: List[str]
field email_domains: List[pyairtable.models.schema.EnterpriseInfo.EmailDomain]
pydantic model EmailDomain[source]
field email_domain: str
field is_sso_required: bool
pydantic model pyairtable.models.schema.WorkspaceCollaborators[source]

Detailed information about who can access a workspace.

See https://airtable.com/developers/web/api/get-workspace-collaborators

field id: str
field name: str
field created_time: str
field base_ids: List[str]
field restrictions: WorkspaceCollaborators.Restrictions
field group_collaborators: WorkspaceCollaborators.GroupCollaborators [Optional]
field individual_collaborators: WorkspaceCollaborators.IndividualCollaborators [Optional]
pydantic model Restrictions[source]
field invite_creation: str
field share_creation: str
save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

pydantic model GroupCollaborators[source]
field via_base: List[pyairtable.models.schema.BaseGroupCollaborator] [Optional]
field via_workspace: List[pyairtable.models.schema.GroupCollaborator] [Optional]
pydantic model IndividualCollaborators[source]
field via_base: List[pyairtable.models.schema.BaseIndividualCollaborator] [Optional]
field via_workspace: List[pyairtable.models.schema.IndividualCollaborator] [Optional]
field via_base: List[BaseInviteLink] [Optional]
field via_workspace: List[InviteLink] [Optional]
add(collaborator_type, collaborator_id, permission_level)

Add a user or group as a collaborator to this Airtable object.

Parameters
  • collaborator_type (str) – Either 'user' or 'group'.

  • collaborator_id (str) – The user or group ID.

  • permission_level (str) – See application permission levels.

Return type

None

add_collaborators(collaborators)

Add multiple collaborators to this Airtable object.

Parameters

collaborators (Iterable[Union[AddUserCollaboratorDict, AddGroupCollaboratorDict]]) – A list of dict that conform to the specification laid out in the Add base collaborator API documentation.

Return type

None

add_group(group_id, permission_level)

Add a group as a collaborator to this Airtable object.

Parameters
Return type

None

add_user(user_id, permission_level)

Add a user as a collaborator to this Airtable object.

Parameters
Return type

None

remove(collaborator_id)

Remove a user or group as a collaborator.

Parameters

collaborator_id (str) – The user or group ID.

Return type

None

update(collaborator_id, permission_level)

Change the permission level granted to a user or group.

Parameters
Return type

None

pydantic model pyairtable.models.schema.NestedId[source]
field id: str
pydantic model pyairtable.models.schema.NestedFieldId[source]
field field_id: str
pydantic model pyairtable.models.schema.Collaborations[source]

The full set of collaborations granted to a user or user group.

See https://airtable.com/developers/web/api/model/collaborations

field base_collaborations: List[pyairtable.models.schema.Collaborations.BaseCollaboration] [Optional]
field interface_collaborations: List[pyairtable.models.schema.Collaborations.InterfaceCollaboration] [Optional]
field workspace_collaborations: List[pyairtable.models.schema.Collaborations.WorkspaceCollaboration] [Optional]
property bases: Dict[str, pyairtable.models.schema.Collaborations.BaseCollaboration]

Mapping of base IDs to collaborations, to make lookups easier.

Return type

Dict[str, BaseCollaboration]

property interfaces: Dict[str, pyairtable.models.schema.Collaborations.InterfaceCollaboration]

Mapping of interface IDs to collaborations, to make lookups easier.

Return type

Dict[str, InterfaceCollaboration]

property workspaces: Dict[str, pyairtable.models.schema.Collaborations.WorkspaceCollaboration]

Mapping of workspace IDs to collaborations, to make lookups easier.

Return type

Dict[str, WorkspaceCollaboration]

pydantic model BaseCollaboration[source]
field base_id: str
field created_time: str
field granted_by_user_id: str
field permission_level: str
pydantic model InterfaceCollaboration[source]
field interface_id: str
field base_id: str
field created_time: str
field granted_by_user_id: str
field permission_level: str
pydantic model WorkspaceCollaboration[source]
field workspace_id: str
field created_time: str
field granted_by_user_id: str
field permission_level: str
pydantic model pyairtable.models.schema.UserInfo[source]

Detailed information about a user.

See https://airtable.com/developers/web/api/get-user-by-id

The following fields can be modified and saved: state, email, first_name, last_name

field id: str
field name: str
field email: str
field state: str
field is_sso_required: bool
field is_two_factor_auth_enabled: bool
field last_activity_time: Optional[str]
field created_time: Optional[str]
field enterprise_user_type: Optional[str]
field invited_to_airtable_by_user_id: Optional[str]
field is_managed: bool
field groups: List[pyairtable.models.schema.NestedId] [Optional]
field collaborations: Collaborations [Optional]
logout()[source]
Return type

None

delete()

Delete the record on the server and mark this instance as deleted.

Return type

None

property deleted: bool

Indicates whether the record has been deleted since being returned from the API.

Return type

bool

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

pydantic model pyairtable.models.schema.UserGroup[source]

Detailed information about a user group and its members.

See https://airtable.com/developers/web/api/get-user-group

field id: str
field name: str
field enterprise_account_id: str
field created_time: str
field updated_time: str
field members: List[pyairtable.models.schema.UserGroup.Member]
field collaborations: pyairtable.models.schema.Collaborations [Optional]
pydantic model Member[source]
field user_id: str
field email: str
field first_name: str
field last_name: str
field role: str
field created_time: str
pydantic model pyairtable.models.schema.AITextFieldConfig[source]

Field configuration for AI text.

field type: Literal['aiText']
field options: pyairtable.models.schema.AITextFieldOptions
pydantic model pyairtable.models.schema.AITextFieldOptions[source]
field prompt: Optional[List[Union[str, pyairtable.models.schema.AITextFieldOptions.PromptField]]]
field referenced_field_ids: Optional[List[str]]
pydantic model PromptField[source]
field field: pyairtable.models.schema.NestedFieldId
pydantic model pyairtable.models.schema.AutoNumberFieldConfig[source]

Field configuration for Auto number.

field type: Literal['autoNumber']
pydantic model pyairtable.models.schema.BarcodeFieldConfig[source]

Field configuration for Barcode.

field type: Literal['barcode']
pydantic model pyairtable.models.schema.ButtonFieldConfig[source]

Field configuration for Button.

field type: Literal['button']
pydantic model pyairtable.models.schema.CheckboxFieldConfig[source]

Field configuration for Checkbox.

field type: Literal['checkbox']
field options: Optional[pyairtable.models.schema.CheckboxFieldOptions]
pydantic model pyairtable.models.schema.CheckboxFieldOptions[source]
field color: str
field icon: str
pydantic model pyairtable.models.schema.CountFieldConfig[source]

Field configuration for Count.

field type: Literal['count']
field options: Optional[pyairtable.models.schema.CountFieldOptions]
pydantic model pyairtable.models.schema.CountFieldOptions[source]
field is_valid: bool
pydantic model pyairtable.models.schema.CreatedByFieldConfig[source]

Field configuration for Created by.

field type: Literal['createdBy']
pydantic model pyairtable.models.schema.CreatedTimeFieldConfig[source]

Field configuration for Created time.

field type: Literal['createdTime']
pydantic model pyairtable.models.schema.CurrencyFieldConfig[source]

Field configuration for Currency.

field type: Literal['currency']
field options: pyairtable.models.schema.CurrencyFieldOptions
pydantic model pyairtable.models.schema.CurrencyFieldOptions[source]
field precision: int
field symbol: str
pydantic model pyairtable.models.schema.DateFieldConfig[source]

Field configuration for Date.

field type: Literal['date']
field options: pyairtable.models.schema.DateFieldOptions
pydantic model pyairtable.models.schema.DateFieldOptions[source]
field date_format: pyairtable.models.schema.DateTimeFieldOptions.DateFormat
pydantic model pyairtable.models.schema.DateTimeFieldConfig[source]

Field configuration for Date and time.

field type: Literal['dateTime']
field options: pyairtable.models.schema.DateTimeFieldOptions
pydantic model pyairtable.models.schema.DateTimeFieldOptions[source]
field time_zone: str
field date_format: pyairtable.models.schema.DateTimeFieldOptions.DateFormat
field time_format: pyairtable.models.schema.DateTimeFieldOptions.TimeFormat
pydantic model DateFormat[source]
field format: str
field name: str
pydantic model TimeFormat[source]
field format: str
field name: str
pydantic model pyairtable.models.schema.DurationFieldConfig[source]

Field configuration for Duration.

field type: Literal['duration']
field options: Optional[pyairtable.models.schema.DurationFieldOptions]
pydantic model pyairtable.models.schema.DurationFieldOptions[source]
field duration_format: str
pydantic model pyairtable.models.schema.EmailFieldConfig[source]

Field configuration for Email.

field type: Literal['email']
pydantic model pyairtable.models.schema.ExternalSyncSourceFieldConfig[source]

Field configuration for Sync source.

field type: Literal['externalSyncSource']
field options: Optional[pyairtable.models.schema.SingleSelectFieldOptions]
pydantic model pyairtable.models.schema.FormulaFieldConfig[source]

Field configuration for Formula.

field type: Literal['formula']
field options: Optional[pyairtable.models.schema.FormulaFieldOptions]
pydantic model pyairtable.models.schema.FormulaFieldOptions[source]
field formula: str
field is_valid: bool
field referenced_field_ids: Optional[List[str]]
field result: Optional[Union[pyairtable.models.schema.AITextFieldConfig, pyairtable.models.schema.AutoNumberFieldConfig, pyairtable.models.schema.BarcodeFieldConfig, pyairtable.models.schema.ButtonFieldConfig, pyairtable.models.schema.CheckboxFieldConfig, pyairtable.models.schema.CountFieldConfig, pyairtable.models.schema.CreatedByFieldConfig, pyairtable.models.schema.CreatedTimeFieldConfig, pyairtable.models.schema.CurrencyFieldConfig, pyairtable.models.schema.DateFieldConfig, pyairtable.models.schema.DateTimeFieldConfig, pyairtable.models.schema.DurationFieldConfig, pyairtable.models.schema.EmailFieldConfig, pyairtable.models.schema.ExternalSyncSourceFieldConfig, pyairtable.models.schema.FormulaFieldConfig, pyairtable.models.schema.LastModifiedByFieldConfig, pyairtable.models.schema.LastModifiedTimeFieldConfig, pyairtable.models.schema.MultilineTextFieldConfig, pyairtable.models.schema.MultipleAttachmentsFieldConfig, pyairtable.models.schema.MultipleCollaboratorsFieldConfig, pyairtable.models.schema.MultipleLookupValuesFieldConfig, pyairtable.models.schema.MultipleRecordLinksFieldConfig, pyairtable.models.schema.MultipleSelectsFieldConfig, pyairtable.models.schema.NumberFieldConfig, pyairtable.models.schema.PercentFieldConfig, pyairtable.models.schema.PhoneNumberFieldConfig, pyairtable.models.schema.RatingFieldConfig, pyairtable.models.schema.RichTextFieldConfig, pyairtable.models.schema.RollupFieldConfig, pyairtable.models.schema.SingleCollaboratorFieldConfig, pyairtable.models.schema.SingleLineTextFieldConfig, pyairtable.models.schema.SingleSelectFieldConfig, pyairtable.models.schema.UrlFieldConfig, pyairtable.models.schema.UnknownFieldConfig]]
pydantic model pyairtable.models.schema.LastModifiedByFieldConfig[source]

Field configuration for Last modified by.

field type: Literal['lastModifiedBy']
pydantic model pyairtable.models.schema.LastModifiedTimeFieldConfig[source]

Field configuration for Last modified time.

field type: Literal['lastModifiedTime']
field options: Optional[pyairtable.models.schema.LastModifiedTimeFieldOptions]
pydantic model pyairtable.models.schema.LastModifiedTimeFieldOptions[source]
field is_valid: bool
field referenced_field_ids: Optional[List[str]]
field result: Optional[Union[pyairtable.models.schema.DateFieldConfig, pyairtable.models.schema.DateTimeFieldConfig]]
pydantic model pyairtable.models.schema.MultilineTextFieldConfig[source]

Field configuration for Long text.

field type: Literal['multilineText']
pydantic model pyairtable.models.schema.MultipleAttachmentsFieldConfig[source]

Field configuration for Attachments.

field type: Literal['multipleAttachments']
field options: Optional[pyairtable.models.schema.MultipleAttachmentsFieldOptions]
pydantic model pyairtable.models.schema.MultipleAttachmentsFieldOptions[source]

Field configuration for Attachments.

field is_reversed: bool
pydantic model pyairtable.models.schema.MultipleCollaboratorsFieldConfig[source]

Field configuration for Multiple Collaborators.

field type: Literal['multipleCollaborators']
pydantic model pyairtable.models.schema.MultipleLookupValuesFieldConfig[source]

Field configuration for Lookup <https://airtable.com/developers/web/api/field-model#lookup>__.

field type: Literal['multipleLookupValues']
field options: Optional[pyairtable.models.schema.MultipleLookupValuesFieldOptions]
pydantic model pyairtable.models.schema.MultipleLookupValuesFieldOptions[source]
field field_id_in_linked_table: Optional[str]
field is_valid: bool
field result: Optional[Union[pyairtable.models.schema.AITextFieldConfig, pyairtable.models.schema.AutoNumberFieldConfig, pyairtable.models.schema.BarcodeFieldConfig, pyairtable.models.schema.ButtonFieldConfig, pyairtable.models.schema.CheckboxFieldConfig, pyairtable.models.schema.CountFieldConfig, pyairtable.models.schema.CreatedByFieldConfig, pyairtable.models.schema.CreatedTimeFieldConfig, pyairtable.models.schema.CurrencyFieldConfig, pyairtable.models.schema.DateFieldConfig, pyairtable.models.schema.DateTimeFieldConfig, pyairtable.models.schema.DurationFieldConfig, pyairtable.models.schema.EmailFieldConfig, pyairtable.models.schema.ExternalSyncSourceFieldConfig, pyairtable.models.schema.FormulaFieldConfig, pyairtable.models.schema.LastModifiedByFieldConfig, pyairtable.models.schema.LastModifiedTimeFieldConfig, pyairtable.models.schema.MultilineTextFieldConfig, pyairtable.models.schema.MultipleAttachmentsFieldConfig, pyairtable.models.schema.MultipleCollaboratorsFieldConfig, pyairtable.models.schema.MultipleLookupValuesFieldConfig, pyairtable.models.schema.MultipleRecordLinksFieldConfig, pyairtable.models.schema.MultipleSelectsFieldConfig, pyairtable.models.schema.NumberFieldConfig, pyairtable.models.schema.PercentFieldConfig, pyairtable.models.schema.PhoneNumberFieldConfig, pyairtable.models.schema.RatingFieldConfig, pyairtable.models.schema.RichTextFieldConfig, pyairtable.models.schema.RollupFieldConfig, pyairtable.models.schema.SingleCollaboratorFieldConfig, pyairtable.models.schema.SingleLineTextFieldConfig, pyairtable.models.schema.SingleSelectFieldConfig, pyairtable.models.schema.UrlFieldConfig, pyairtable.models.schema.UnknownFieldConfig]]
pydantic model pyairtable.models.schema.MultipleRecordLinksFieldConfig[source]

Field configuration for Link to another record <https://airtable.com/developers/web/api/field-model#foreignkey>__.

field type: Literal['multipleRecordLinks']
field options: Optional[pyairtable.models.schema.MultipleRecordLinksFieldOptions]
pydantic model pyairtable.models.schema.MultipleRecordLinksFieldOptions[source]
field is_reversed: bool
field linked_table_id: str
field view_id_for_record_selection: Optional[str]
pydantic model pyairtable.models.schema.MultipleSelectsFieldConfig[source]

Field configuration for Multiple select.

field type: Literal['multipleSelects']
field options: Optional[pyairtable.models.schema.SingleSelectFieldOptions]
pydantic model pyairtable.models.schema.NumberFieldConfig[source]

Field configuration for Number.

field type: Literal['number']
field options: Optional[pyairtable.models.schema.NumberFieldOptions]
pydantic model pyairtable.models.schema.NumberFieldOptions[source]
field precision: int
pydantic model pyairtable.models.schema.PercentFieldConfig[source]

Field configuration for Percent.

field type: Literal['percent']
field options: Optional[pyairtable.models.schema.NumberFieldOptions]
pydantic model pyairtable.models.schema.PhoneNumberFieldConfig[source]

Field configuration for Phone.

field type: Literal['phoneNumber']
pydantic model pyairtable.models.schema.RatingFieldConfig[source]

Field configuration for Rating.

field type: Literal['rating']
field options: Optional[pyairtable.models.schema.RatingFieldOptions]
pydantic model pyairtable.models.schema.RatingFieldOptions[source]
field color: str
field icon: str
field max: int
pydantic model pyairtable.models.schema.RichTextFieldConfig[source]

Field configuration for Rich text.

field type: Literal['richText']
pydantic model pyairtable.models.schema.RollupFieldConfig[source]

Field configuration for Rollup <https://airtable.com/developers/web/api/field-model#rollup>__.

field type: Literal['rollup']
field options: Optional[pyairtable.models.schema.RollupFieldOptions]
pydantic model pyairtable.models.schema.RollupFieldOptions[source]
field field_id_in_linked_table: Optional[str]
field is_valid: bool
field referenced_field_ids: Optional[List[str]]
field result: Optional[Union[pyairtable.models.schema.AITextFieldConfig, pyairtable.models.schema.AutoNumberFieldConfig, pyairtable.models.schema.BarcodeFieldConfig, pyairtable.models.schema.ButtonFieldConfig, pyairtable.models.schema.CheckboxFieldConfig, pyairtable.models.schema.CountFieldConfig, pyairtable.models.schema.CreatedByFieldConfig, pyairtable.models.schema.CreatedTimeFieldConfig, pyairtable.models.schema.CurrencyFieldConfig, pyairtable.models.schema.DateFieldConfig, pyairtable.models.schema.DateTimeFieldConfig, pyairtable.models.schema.DurationFieldConfig, pyairtable.models.schema.EmailFieldConfig, pyairtable.models.schema.ExternalSyncSourceFieldConfig, pyairtable.models.schema.FormulaFieldConfig, pyairtable.models.schema.LastModifiedByFieldConfig, pyairtable.models.schema.LastModifiedTimeFieldConfig, pyairtable.models.schema.MultilineTextFieldConfig, pyairtable.models.schema.MultipleAttachmentsFieldConfig, pyairtable.models.schema.MultipleCollaboratorsFieldConfig, pyairtable.models.schema.MultipleLookupValuesFieldConfig, pyairtable.models.schema.MultipleRecordLinksFieldConfig, pyairtable.models.schema.MultipleSelectsFieldConfig, pyairtable.models.schema.NumberFieldConfig, pyairtable.models.schema.PercentFieldConfig, pyairtable.models.schema.PhoneNumberFieldConfig, pyairtable.models.schema.RatingFieldConfig, pyairtable.models.schema.RichTextFieldConfig, pyairtable.models.schema.RollupFieldConfig, pyairtable.models.schema.SingleCollaboratorFieldConfig, pyairtable.models.schema.SingleLineTextFieldConfig, pyairtable.models.schema.SingleSelectFieldConfig, pyairtable.models.schema.UrlFieldConfig, pyairtable.models.schema.UnknownFieldConfig]]
pydantic model pyairtable.models.schema.SingleCollaboratorFieldConfig[source]

Field configuration for Collaborator.

field type: Literal['singleCollaborator']
pydantic model pyairtable.models.schema.SingleLineTextFieldConfig[source]

Field configuration for Single line text.

field type: Literal['singleLineText']
pydantic model pyairtable.models.schema.SingleSelectFieldConfig[source]

Field configuration for Single select.

field type: Literal['singleSelect']
field options: Optional[pyairtable.models.schema.SingleSelectFieldOptions]
pydantic model pyairtable.models.schema.SingleSelectFieldOptions[source]
field choices: List[pyairtable.models.schema.SingleSelectFieldOptions.Choice]
pydantic model Choice[source]
field id: str
field name: str
field color: Optional[str]
pydantic model pyairtable.models.schema.UrlFieldConfig[source]

Field configuration for Url.

field type: Literal['url']
pydantic model pyairtable.models.schema.UnknownFieldConfig[source]

Field configuration class used as a fallback for unrecognized types. This ensures we don’t raise pydantic.ValidationError if Airtable adds new types.

field type: str
field options: Optional[Dict[str, Any]]
pydantic model pyairtable.models.schema.AITextFieldSchema[source]

Field schema for AI text.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['aiText']
field options: AITextFieldOptions
pydantic model pyairtable.models.schema.AutoNumberFieldSchema[source]

Field schema for Auto number.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['autoNumber']
pydantic model pyairtable.models.schema.BarcodeFieldSchema[source]

Field schema for Barcode.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['barcode']
pydantic model pyairtable.models.schema.ButtonFieldSchema[source]

Field schema for Button.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['button']
pydantic model pyairtable.models.schema.CheckboxFieldSchema[source]

Field schema for Checkbox.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['checkbox']
field options: Optional['CheckboxFieldOptions']
pydantic model pyairtable.models.schema.CountFieldSchema[source]

Field schema for Count.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['count']
field options: Optional['CountFieldOptions']
pydantic model pyairtable.models.schema.CreatedByFieldSchema[source]

Field schema for Created by.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['createdBy']
pydantic model pyairtable.models.schema.CreatedTimeFieldSchema[source]

Field schema for Created time.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['createdTime']
pydantic model pyairtable.models.schema.CurrencyFieldSchema[source]

Field schema for Currency.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['currency']
field options: CurrencyFieldOptions
pydantic model pyairtable.models.schema.DateFieldSchema[source]

Field schema for Date.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['date']
field options: DateFieldOptions
pydantic model pyairtable.models.schema.DateTimeFieldSchema[source]

Field schema for Date and time.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['dateTime']
field options: DateTimeFieldOptions
pydantic model pyairtable.models.schema.DurationFieldSchema[source]

Field schema for Duration.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['duration']
field options: Optional['DurationFieldOptions']
pydantic model pyairtable.models.schema.EmailFieldSchema[source]

Field schema for Email.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['email']
pydantic model pyairtable.models.schema.ExternalSyncSourceFieldSchema[source]

Field schema for Sync source.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['externalSyncSource']
field options: Optional['SingleSelectFieldOptions']
pydantic model pyairtable.models.schema.FormulaFieldSchema[source]

Field schema for Formula.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['formula']
field options: Optional['FormulaFieldOptions']
pydantic model pyairtable.models.schema.LastModifiedByFieldSchema[source]

Field schema for Last modified by.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['lastModifiedBy']
pydantic model pyairtable.models.schema.LastModifiedTimeFieldSchema[source]

Field schema for Last modified time.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['lastModifiedTime']
field options: Optional['LastModifiedTimeFieldOptions']
pydantic model pyairtable.models.schema.MultilineTextFieldSchema[source]

Field schema for Long text.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multilineText']
pydantic model pyairtable.models.schema.MultipleAttachmentsFieldSchema[source]

Field schema for Attachments.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multipleAttachments']
field options: Optional['MultipleAttachmentsFieldOptions']
pydantic model pyairtable.models.schema.MultipleCollaboratorsFieldSchema[source]

Field schema for Multiple Collaborators.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multipleCollaborators']
pydantic model pyairtable.models.schema.MultipleLookupValuesFieldSchema[source]

Field schema for Lookup <https://airtable.com/developers/web/api/field-model#lookup>__.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multipleLookupValues']
field options: Optional['MultipleLookupValuesFieldOptions']
pydantic model pyairtable.models.schema.MultipleRecordLinksFieldSchema[source]

Field schema for Link to another record <https://airtable.com/developers/web/api/field-model#foreignkey>__.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multipleRecordLinks']
field options: Optional['MultipleRecordLinksFieldOptions']
pydantic model pyairtable.models.schema.MultipleSelectsFieldSchema[source]

Field schema for Multiple select.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['multipleSelects']
field options: Optional['SingleSelectFieldOptions']
pydantic model pyairtable.models.schema.NumberFieldSchema[source]

Field schema for Number.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['number']
field options: Optional['NumberFieldOptions']
pydantic model pyairtable.models.schema.PercentFieldSchema[source]

Field schema for Percent.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['percent']
field options: Optional['NumberFieldOptions']
pydantic model pyairtable.models.schema.PhoneNumberFieldSchema[source]

Field schema for Phone.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['phoneNumber']
pydantic model pyairtable.models.schema.RatingFieldSchema[source]

Field schema for Rating.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['rating']
field options: Optional['RatingFieldOptions']
pydantic model pyairtable.models.schema.RichTextFieldSchema[source]

Field schema for Rich text.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['richText']
pydantic model pyairtable.models.schema.RollupFieldSchema[source]

Field schema for Rollup <https://airtable.com/developers/web/api/field-model#rollup>__.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['rollup']
field options: Optional['RollupFieldOptions']
pydantic model pyairtable.models.schema.SingleCollaboratorFieldSchema[source]

Field schema for Collaborator.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['singleCollaborator']
pydantic model pyairtable.models.schema.SingleLineTextFieldSchema[source]

Field schema for Single line text.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['singleLineText']
pydantic model pyairtable.models.schema.SingleSelectFieldSchema[source]

Field schema for Single select.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['singleSelect']
field options: Optional['SingleSelectFieldOptions']
pydantic model pyairtable.models.schema.UrlFieldSchema[source]

Field schema for Url.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: Literal['url']
pydantic model pyairtable.models.schema.UnknownFieldSchema[source]

Field schema class used as a fallback for unrecognized types. This ensures we don’t raise pydantic.ValidationError if Airtable adds new types.

The following fields can be modified and saved: name, description

save()

Save any changes made to the instance’s writable fields and update the instance with any refreshed values returned from the API.

Will raise RuntimeError if the record has been deleted.

Return type

None

field id: str
field name: str
field description: Optional[str]
field type: str
field options: Optional[Dict[str, Any]]

API: pyairtable.orm

class pyairtable.orm.Model[source]

Supports creating ORM-style classes representing Airtable tables. For more details, see ORM.

A nested class called Meta is required and can specify the following attributes:

  • api_key (required) - API key or personal access token.

  • base_id (required) - Base ID (not name).

  • table_name (required) - Table ID or name.

  • timeout - A tuple indicating a connect and read timeout. Defaults to no timeout.

  • typecast - The Airtable API will perform best-effort automatic data conversion from string values. Defaults to True.

from pyairtable.orm import Model, fields

class Contact(Model):
    first_name = fields.TextField("First Name")
    age = fields.IntegerField("Age")

    class Meta:
        base_id = "appaPqizdsNHDvlEm"
        table_name = "Contact"
        api_key = "keyapikey"
        timeout = (5, 5)
        typecast = True

You can implement meta attributes as callables if certain values need to be dynamically provided or are unavailable at import time:

from pyairtable.orm import Model, fields
from your_app.config import get_secret

class Contact(Model):
    first_name = fields.TextField("First Name")
    age = fields.IntegerField("Age")

    class Meta:
        base_id = "appaPqizdsNHDvlEm"
        table_name = "Contact"

        @staticmethod
        def api_key():
            return get_secret("AIRTABLE_API_KEY")
__init__(**fields)[source]

Construct a model instance with field values based on the given keyword args.

>>> Contact(name="Alice", birthday=date(1980, 1, 1))
<unsaved Contact>

The keyword argument id= special-cased and sets the record ID, not a field value.

>>> Contact(id="recWPqD9izdsNvlE", name="Bob")
<Contact id='recWPqD9izdsNvlE'>
exists()[source]

Whether the instance has been saved to Airtable already.

Return type

bool

save()[source]

Save the model to the API.

If the instance does not exist already, it will be created; otherwise, the existing record will be updated.

Return type

bool

Returns

True if a record was created, False if it was updated.

delete()[source]

Delete the record.

Raises

ValueError – if the record does not exist.

Return type

bool

classmethod all(**kwargs)[source]

Retrieve all records for this model. For all supported keyword arguments, see Table.all.

Return type

List[Self]

classmethod first(**kwargs)[source]

Retrieve the first record for this model. For all supported keyword arguments, see Table.first.

Return type

Optional[Self]

to_record(only_writable=False)[source]

Build a RecordDict to represent this instance.

This method converts internal field values into values expected by Airtable. For example, a datetime value from DatetimeField is converted into an ISO 8601 string.

Parameters

only_writable (bool, default: False) – If True, the result will exclude any values which are associated with readonly fields.

Return type

RecordDict

classmethod from_record(record)[source]

Create an instance from a record dict.

Return type

Self

classmethod from_id(record_id, fetch=True)[source]

Create an instance from a record ID.

Parameters
  • record_id (str) – An Airtable record ID.

  • fetch (bool, default: True) – If True, record will be fetched and field values will be updated. If False, a new instance is created with the provided ID, but field values are unset.

Return type

Self

fetch()[source]

Fetch field values from the API and resets instance field values.

Return type

None

classmethod from_ids(record_ids, fetch=True)[source]

Create a list of instances from record IDs. If any record IDs returned are invalid this will raise a KeyError, but only after retrieving all other valid records from the API.

Parameters
  • record_ids (Iterable[str]) – An Airtable record ID.

  • fetch (bool, default: True) – If True, records will be fetched and field values will be updated. If False, new instances are created with the provided IDs, but field values are unset.

Return type

List[Self]

classmethod batch_save(models)[source]

Save a list of model instances to the Airtable API with as few network requests as possible. Can accept a mixture of new records (which have not been saved yet) and existing records that have IDs.

Return type

None

classmethod batch_delete(models)[source]

Delete a list of model instances from Airtable.

Raises

ValueError – if the model has not been saved to Airtable.

Return type

None

comments()[source]

Return a list of comments on this record. See Table.comments.

Return type

List[Comment]

add_comment(text)[source]

Add a comment to this record. See Table.add_comment.

Return type

Comment

API: pyairtable.orm.fields

Field are used to define the Airtable column type for your pyAirtable models.

Internally these are implemented as descriptors, which allows us to define methods and type annotations for getting and setting attribute values.

>>> from pyairtable.orm import Model, fields
>>> class Contact(Model):
...     class Meta:
...         ...
...     name = fields.TextField("Name")
...     is_registered = fields.CheckboxField("Registered")
...
>>> contact = Contact(name="George", is_registered=True)
>>> assert contact.name == "George"
>>> reveal_type(contact.name)  # -> str
>>> contact.to_record()
{
    "id": recS6qSLw0OCA6Xul",
    "createdTime": "2021-07-14T06:42:37.000Z",
    "fields": {
        "Name": "George",
        "Registered": True,
    }
}
class pyairtable.orm.fields.Field[source]

A generic class for an Airtable field descriptor that will be included in an ORM model.

Type-checked subclasses should provide two type parameters, T_API and T_ORM, which indicate the type returned by the API and the type used to store values internally.

Subclasses should also define valid_types as a type or tuple of types, which will be used to validate the type of field values being set via this descriptor.

__init__(field_name, validate_type=True, readonly=None)[source]
Parameters
  • field_name (str) – The name of the field in Airtable.

  • validate_type (bool, default: True) – Whether to raise a TypeError if anything attempts to write an object of an unsupported type as a field value. If False, you may encounter unpredictable behavior from the Airtable API.

  • readonly (Optional[bool], default: None) – If True, any attempt to write a value to this field will raise an AttributeError. Each field implements appropriate default values, but you may find it useful to mark fields as readonly if you know that the access token your code uses does not have permission to modify specific fields.

readonly: bool = False

Whether to allow modification of the value in this field.

to_record_value(value)[source]

Calculate the value which should be persisted to the API.

Return type

Any

to_internal_value(value)[source]

Convert a value from the API into the value’s internal representation.

Return type

Any

valid_or_raise(value)[source]

Validate the type of the given value and raise TypeError if invalid.

Return type

None

class pyairtable.orm.fields.AITextField[source]

Read-only field that returns a dict. For more information, read the AI Text documentation.

class pyairtable.orm.fields.AttachmentsField[source]

Accepts a list of dicts in the format detailed in Attachments.

class pyairtable.orm.fields.AutoNumberField[source]

Equivalent to IntegerField(readonly=True).

See Auto number.

class pyairtable.orm.fields.BarcodeField[source]

Accepts a dict that should conform to the format detailed in the Barcode documentation.

class pyairtable.orm.fields.ButtonField[source]

Read-only field that returns a dict. For more information, read the Button documentation.

class pyairtable.orm.fields.CheckboxField[source]

Returns False instead of None if the field is empty on the Airtable base.

See Checkbox.

class pyairtable.orm.fields.CollaboratorField[source]

Accepts a dict that should conform to the format detailed in the Collaborator documentation.

class pyairtable.orm.fields.CountField[source]

Equivalent to IntegerField(readonly=True).

See Count.

class pyairtable.orm.fields.CreatedByField[source]

Equivalent to CollaboratorField(readonly=True).

See Created by.

class pyairtable.orm.fields.CreatedTimeField[source]

Equivalent to DatetimeField(readonly=True).

See Created time.

class pyairtable.orm.fields.CurrencyField[source]

Equivalent to NumberField.

See Currency.

class pyairtable.orm.fields.DateField[source]

Date field. Accepts only date values.

See Date.

to_record_value(value)[source]

Convert a date into an ISO 8601 string, e.g. “2014-09-05”.

Return type

str

to_internal_value(value)[source]

Convert an ISO 8601 string, e.g. “2014-09-05” into a date.

Return type

date

class pyairtable.orm.fields.DatetimeField[source]

DateTime field. Accepts only datetime values.

See Date and time.

to_record_value(value)[source]

Convert a datetime into an ISO 8601 string, e.g. “2014-09-05T12:34:56.000Z”.

Return type

str

to_internal_value(value)[source]

Convert an ISO 8601 string, e.g. “2014-09-05T07:00:00.000Z” into a datetime.

Return type

datetime

class pyairtable.orm.fields.DurationField[source]

Duration field. Accepts only timedelta values.

See Duration. Airtable’s API returns this as a number of seconds.

to_record_value(value)[source]

Convert a timedelta into a number of seconds.

Return type

float

to_internal_value(value)[source]

Convert a number of seconds into a timedelta.

Return type

timedelta

class pyairtable.orm.fields.EmailField[source]

Equivalent to TextField.

See Email.

class pyairtable.orm.fields.ExternalSyncSourceField[source]

Equivalent to TextField(readonly=True).

See Sync source.

class pyairtable.orm.fields.FloatField[source]

Number field with decimal precision. Accepts only float values.

See Number.

class pyairtable.orm.fields.IntegerField[source]

Number field with integer precision. Accepts only int values.

See Number.

class pyairtable.orm.fields.LastModifiedByField[source]

Equivalent to CollaboratorField(readonly=True).

See Last modified by.

class pyairtable.orm.fields.LastModifiedTimeField[source]

Equivalent to DatetimeField(readonly=True).

See Last modified time.

class pyairtable.orm.fields.LinkField[source]

Represents a MultipleRecordLinks field. Returns and accepts lists of Models.

Can also be used with a lookup field that pulls from a MultipleRecordLinks field, provided the field is created with readonly=True.

See Link to another record.

__init__(field_name, model, validate_type=True, readonly=None, lazy=False)[source]
Parameters
  • field_name (str) – Name of the Airtable field.

  • model (Union[str, LinkSelf, Type[Model]]) –

    Model class representing the linked table. There are a few options:

    1. You can provide a str that is the fully qualified module and class name. For example, "your.module.Model" will import Model from your.module.

    2. You can provide a str that is just the class name, and it will be imported from the same module as the model class.

    3. You can provide the sentinel value LinkSelf, and the link field will point to the same model where the link field is created.

  • validate_type (bool, default: True) – Whether to raise a TypeError if attempting to write an object of an unsupported type as a field value. If False, you may encounter unpredictable behavior from the Airtable API.

  • readonly (Optional[bool], default: None) – If True, any attempt to write a value to this field will raise an AttributeError. This will not, however, prevent any modification of the list object returned by this field.

  • lazy (bool, default: False) – If True, this field will return empty objects with oly IDs; call fetch() to retrieve values.

property linked_model: Type[pyairtable.orm.fields.T_Linked]

Resolve a Model class based on the model= constructor parameter to this field instance.

Return type

Type[Model]

to_record_value(value)[source]

Build the list of record IDs which should be persisted to the API.

Return type

List[str]

valid_or_raise(value)[source]

Validate the type of the given value and raise TypeError if invalid.

Return type

None

class pyairtable.orm.fields.LookupField[source]

Generic field class for a lookup, which returns a list of values.

pyAirtable does not inspect field configuration at runtime or during type checking. If you use mypy, you can declare which type(s) the lookup returns:

>>> from pyairtable.orm import fields as F
>>> class MyTable(Model):
...     Meta = fake_meta()
...     lookup = F.LookupField[str]("My Lookup")
...
>>> rec = MyTable.first()
>>> rec.lookup
["First value", "Second value", ...]

See Lookup.

class pyairtable.orm.fields.MultipleCollaboratorsField[source]

Accepts a list of dicts in the format detailed in Multiple Collaborators.

class pyairtable.orm.fields.MultipleSelectField[source]

Accepts a list of str.

See Multiple select.

class pyairtable.orm.fields.NumberField[source]

Number field with unspecified precision. Accepts either int or float.

See Number.

class pyairtable.orm.fields.PercentField[source]

Equivalent to NumberField.

See Percent.

class pyairtable.orm.fields.PhoneNumberField[source]

Equivalent to TextField.

See Phone.

class pyairtable.orm.fields.RatingField[source]

Accepts int values that are greater than zero.

See Rating.

valid_or_raise(value)[source]

Validate the type of the given value and raise TypeError if invalid.

Return type

None

class pyairtable.orm.fields.RichTextField[source]

Equivalent to TextField.

See Rich text.

class pyairtable.orm.fields.SelectField[source]

Equivalent to TextField.

See Single select.

class pyairtable.orm.fields.TextField[source]

Used for all Airtable text fields. Accepts str.

See Single line text and Long text.

class pyairtable.orm.fields.UrlField[source]

Equivalent to TextField.

See Url.

pyairtable.orm.fields.ALL_FIELDS

Set of all Field subclasses exposed by the library.

pyairtable.orm.fields.READONLY_FIELDS

Set of all read-only Field subclasses exposed by the library.

pyairtable.orm.fields.FIELD_TYPES_TO_CLASSES

Mapping of Airtable field type names to their ORM classes. See https://airtable.com/developers/web/api/field-model and Formula, Rollup, and Lookup Fields.

The data type of “formula” and “rollup” fields will depend on the underlying fields they reference, so it is not practical for the ORM to know or detect those fields’ types. These two field type names are mapped to the constant NotImplemented.

pyairtable.orm.fields.FIELD_CLASSES_TO_TYPES

Mapping of field classes to the set of supported Airtable field types.

pyairtable.orm.fields.LinkSelf = _LinkFieldOptions.LinkSelf

Sentinel option for the model= param to LinkField

API: pyairtable.utils

pyairtable.utils.datetime_to_iso_str(value)[source]

Convert datetime object into Airtable compatible ISO 8601 string e.g. “2014-09-05T12:34:56.000Z”

Parameters

value (datetime) – datetime object

Return type

str

pyairtable.utils.datetime_from_iso_str(value)[source]

Convert an ISO 8601 datetime string into a datetime object.

Parameters

value (str) – datetime string, e.g. “2014-09-05T07:00:00.000Z”

Return type

datetime

pyairtable.utils.date_to_iso_str(value)[source]

Convert a date or datetime into an Airtable-compatible ISO 8601 string

Parameters

value (Union[date, datetime]) – date or datetime object, e.g. “2014-09-05”

Return type

str

pyairtable.utils.date_from_iso_str(value)[source]

Convert ISO 8601 date string into a date object.

Parameters

value (str) – date string, e.g. “2014-09-05”

Return type

date

pyairtable.utils.attachment(url, filename='')[source]

Build a dict in the expected format for creating attachments.

When creating an attachment, url is required, and filename is optional. Airtable will download the file at the given url and keep its own copy of it. All other attachment object properties will be generated server-side soon afterward.

Note

Attachment field values must be an array of AttachmentDict or CreateAttachmentDict; it is not valid to pass a single item to the API.

Usage:
>>> table = Table(...)
>>> profile_url = "https://myprofile.com/id/profile.jpg
>>> rec = table.create({"Profile Photo": [attachment(profile_url)]})
{
    'id': 'recZXOZ5gT9vVGHfL',
    'fields': {
        'attachment': [
            {
                'id': 'attu6kbaST3wUuNTA',
                'url': 'https://aws1.discourse-cdn.com/airtable/original/2X/4/411e4fac00df06a5e316a0585a831549e11d0705.png',
                'filename': '411e4fac00df06a5e316a0585a831549e11d0705.png'
            }
        ]
    },
    'createdTime': '2021-08-21T22:28:36.000Z'
}
Return type

CreateAttachmentDict

pyairtable.utils.chunked(iterable, chunk_size)[source]

Break a sequence into chunks.

Parameters
  • iterable (Sequence[TypeVar(T)]) – Any sequence.

  • chunk_size (int) – Maximum items to yield per chunk.

Return type

Iterator[Sequence[TypeVar(T)]]

pyairtable.utils.is_airtable_id(value, prefix='')[source]

Check whether the given value is an Airtable ID.

Parameters
  • value (Any) – The value to check.

  • prefix (str, default: '') – If provided, the ID must have the given prefix.

Return type

bool

pyairtable.utils.is_record_id(value: Any, *, prefix: str = 'rec') bool

Check whether the given value is an Airtable ID.

Parameters
  • value – The value to check.

  • prefix – If provided, the ID must have the given prefix.

pyairtable.utils.is_base_id(value: Any, *, prefix: str = 'app') bool

Check whether the given value is an Airtable ID.

Parameters
  • value – The value to check.

  • prefix – If provided, the ID must have the given prefix.

pyairtable.utils.is_table_id(value: Any, *, prefix: str = 'tbl') bool

Check whether the given value is an Airtable ID.

Parameters
  • value – The value to check.

  • prefix – If provided, the ID must have the given prefix.

pyairtable.utils.is_field_id(value: Any, *, prefix: str = 'fld') bool

Check whether the given value is an Airtable ID.

Parameters
  • value – The value to check.

  • prefix – If provided, the ID must have the given prefix.

pyairtable.utils.is_user_id(value: Any, *, prefix: str = 'usr') bool

Check whether the given value is an Airtable ID.

Parameters
  • value – The value to check.

  • prefix – If provided, the ID must have the given prefix.

pyairtable.utils.enterprise_only(wrapped, /, modify_docstring=True)[source]

Wrap a function or method so that if Airtable returns a 404, we will annotate the error with a helpful note to the user.

Return type

TypeVar(F, bound= Callable[..., Any])

class pyairtable.utils.FetchMethod[source]
__init__(*args, **kwargs)
pyairtable.utils.cache_unless_forced(func)[source]

Wrap a method (e.g. Base.shares()) in a decorator that will save a memoized version of the return value for future reuse, but will also allow callers to pass force=True to recompute the memoized version.

Return type

FetchMethod[TypeVar(R, covariant=True)]

pyairtable.utils.coerce_iso_str(value)[source]

Given an input that might be a date or datetime, or an ISO 8601 formatted str, convert the value into an ISO 8601 formatted str.

Return type

Optional[str]

pyairtable.utils.coerce_list_str(value)[source]

Given an input that is either a str or an iterable of str, return a list.

Return type

List[str]