### CLI Quickstart

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

A quick guide to install pyAirtable with CLI support, set up authentication, and run basic commands.

```APIDOC
## CLI Quickstart

Install pyAirtable with CLI support:
```bash
% pip install 'pyairtable[cli]'
```

Set up your Airtable API Key:
```bash
% read -s AIRTABLE_API_KEY
% export AIRTABLE_API_KEY
```

Run basic commands:
```bash
% pyairtable whoami
% pyairtable base YOUR_BASE_ID table YOUR_TABLE_NAME records
```
```

--------------------------------

### Setup Development Environment

Source: https://pyairtable.readthedocs.io/en/stable/about.html

Commands to clone the repository, create a virtual environment, and install dependencies.

```bash
git clone git@github.com:gtalarico/pyairtable.git
cd pyairtable
# Create Virtual Environment
python3 -m venv .venv
source .venv/bin/activate
make setup # Sets up githooks and install package and depedencies
make test # run test complete suite
# Optional, use as needed
make lint # lints locally - also done in pre-merge CI
make docs # builds docs locally - see `docs/build/index.html`
```

--------------------------------

### Install pyAirtable CLI

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

Install pyAirtable with the CLI extra. Ensure your API key is set in the environment before proceeding.

```bash
% pip install 'pyairtable[cli]'
% read -s AIRTABLE_API_KEY
...
% export AIRTABLE_API_KEY
```

--------------------------------

### Initializing a Base

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Examples of both deprecated and current constructor patterns for initializing a Base object.

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

```python
>>> Base(api, "table_name")
```

--------------------------------

### Install pyAirtable

Source: https://pyairtable.readthedocs.io/en/stable/getting-started.html

Use pip to add the pyAirtable library to your project.

```bash
$ pip install pyairtable

```

--------------------------------

### Initialize Model Instances

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Examples of creating model instances, including setting field values and specifying a record ID.

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

```python
>>> Contact(id="recWPqD9izdsNvlE", name="Bob")
<Contact id='recWPqD9izdsNvlE'>
```

--------------------------------

### Construct a Table instance

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/table.html

Examples of deprecated and recommended constructor patterns for the Table class.

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

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

--------------------------------

### LinkField Populate Method Example

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/orm/fields.html

Demonstrates how to populate a LinkField for a given instance, controlling lazy loading and memoization.

```python
from pyairtable.orm import Model, fields as F

class Book(Model):
    class Meta: ...

class Author(Model):
    class Meta: ...
    books = F.LinkField("Books", Book)

author = Author.from_id("reculZ6qSLw0OCA61")
Author.books.populate(author, lazy=True, memoize=False)
```

--------------------------------

### Get a Table Instance

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Use the `table()` method to get a Table instance associated with this base. You can provide the table ID or name. Metadata validation is optional.

```python
>>> table = base.table('Apartments')
>>> print(table)
<Table base='appLkNDICXNqxSDhG' name='Apartments'>
```

--------------------------------

### Example RecordDict return format

Source: https://pyairtable.readthedocs.io/en/stable/tables.html

Shows the structure of records returned by pyAirtable methods.

```python
>>> table.all()
[
    {
        'id': 'recwPQIfs4wKPyc9D',
        'createdTime': '2017-03-14T22:04:31.000Z'
        'fields': {
            'Name': 'Alice',
        },
    },
    {
        'id': 'rechOLltN9SpPHq5o',
        'createdTime': '2017-03-20T15:21:50.000Z'
        'fields': {
            'Name': 'Bob',
        },
    },
    {
        'id': 'rec5eR7IzKSAOBHCz',
        'createdTime': '2017-08-05T21:47:52.000Z'
        'fields': {
            'Name': 'Carol',
        },
    }
]
```

--------------------------------

### CreateRecordDict Example

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Demonstrates the dictionary structure required to create a new record in Airtable. Field values must conform to `WritableFieldValue`.

```python
{
    "fields": {
        "Field Name": "Field Value",
        "Other Field": ["Value 1", "Value 2"]
    }
}
```

--------------------------------

### Upload Attachment Example

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Demonstrates uploading an attachment to an Airtable record. This is the expected output format for a successful attachment upload.

```python
>>> table.upload_attachment("recAdw9EjV90xbZ", "Attachments", "/tmp/example.jpg")
{
    'id': 'recAdw9EjV90xbZ',
    'createdTime': '2023-05-22T21:24:15.333134Z',
    'fields': {
        'Attachments': [
            {
                'id': 'attW8eG2x0ew1Af',
                'url': 'https://content.airtable.com/ப்புகளை',
                'filename': 'example.jpg'
            }
        ]
    }
}
```

--------------------------------

### RecordDict Example: First Record

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Illustrates the structure of a record returned by the `first()` method when no specific options are used.

```python
{
    'id': 'recAdw9EjV90xbW',
    'createdTime': '2023-05-22T21:24:15.333134Z',
    'fields': {'Name': 'Alice', 'Department': 'Engineering'}
}
```

--------------------------------

### Configure API Retry Strategy

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Examples for customizing or disabling retry behavior when initializing the API client.

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

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

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

--------------------------------

### GET /tables

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Retrieve the base's schema and return a list of Table instances.

```APIDOC
## GET /tables

### Description
Retrieve the base's schema and return a list of Table instances.

### Method
GET

### Endpoint
/tables

### Parameters
#### Query Parameters
- **force** (bool) - Optional - Force metadata refresh.
```

--------------------------------

### GET /table

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/api.html

Build a new :class:`Table` instance that uses this instance of :class:`Api`.

```APIDOC
## GET /table

### Description
Build a new :class:`Table` instance that uses this instance of :class:`Api`.

### Method
GET

### Endpoint
/table

#### Parameters
##### Query Parameters
- **base_id** (str) - Required - The ID of the base.
- **table_name** (str) - Required - The Airtable table's ID or name.
- **validate** (bool) - Optional - If true, validates the table schema.
- **force** (bool) - Optional - If true, bypasses cache and forces metadata refresh.

### Request Example
```python
table = api.table(base_id='appSW9...', table_name='Tasks')
```

### Response
#### Success Response (200)
- **Table** (:class:`Table`) - The requested Table instance.

#### Response Example
```json
{
  "id": "tblTasks",
  "name": "Tasks",
  "fields": [
    {"id": "fldName", "name": "Name", "type": "singleLineText"},
    {"id": "fldStatus", "name": "Status", "type": "singleSelect"}
  ]
}
```
```

--------------------------------

### UpdateRecordDict Example: Batch Update

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Shows the structure for updating multiple records using `batch_update`. Each item requires an 'id' and the 'fields' to update.

```python
[
    {
        "id": "recAdw9EjV90xbW",
        "fields": {
            "Email": "alice@example.com"
        }
    },
    {
        "id": "recAdw9EjV90xbX",
        "fields": {
            "Email": "bob@example.com"
        }
    }
]
```

--------------------------------

### Define and Use ORM Fields

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Example of defining a model with specific field types and interacting with its data.

```python
>>> 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,
    }
}
```

--------------------------------

### Defining ORM Models with Fields

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Example of how to define a model using various field types and interact with the data.

```APIDOC
## Defining ORM Models

### Description
Use field classes to define the schema of your ORM models. These fields handle the conversion between Python types and Airtable API formats.

### Request Example
```python
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)
```
```

--------------------------------

### Initialize Development Environment

Source: https://pyairtable.readthedocs.io/en/stable/contributing.html

Commands to prepare the local environment, execute tests, and build documentation.

```bash
% make setup
% make test
% make docs
```

--------------------------------

### Make a GET Request to Airtable API

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/api.html

Convenience method for making GET requests. See Api.request for available keyword arguments.

```python
def get(self, url: str, **kwargs: Any) -> Any:
        """
        Make a GET request to the Airtable API.
        See :meth:`~Api.request` for keyword arguments.
        """
        return self.request("GET", url, **kwargs)
```

--------------------------------

### Initialize and use the Api class

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/api.html

Demonstrates basic instantiation of the Api class and how to access a table to retrieve records.

```python
>>> api = Api('auth_token')
>>> table = api.table('base_id', 'table_name')
>>> records = table.all()
```

--------------------------------

### Define a Contact Model with Fields

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/orm/fields.html

Example of defining a `Contact` model using `pyairtable.orm.Model` and `fields.TextField`, `fields.CheckboxField`. Shows instantiation and conversion to an Airtable record.

```python
>>> 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,
    }
}
```

--------------------------------

### SEARCH Function

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/formulas.html

Finds the starting position of a substring within a larger string. Returns an empty result if the substring is not found. An optional starting position can be provided.

```python
def SEARCH(string_to_find: FunctionArg, where_to_search: FunctionArg, start_from_position: Optional[FunctionArg] = None, /) -> FunctionCall:
    """
    Searches for an occurrence of stringToFind in whereToSearch string starting from an optional startFromPosition. (startFromPosition is 0 by default.) If no occurrence of stringToFind is found, the result will be empty.
    """
    return FunctionCall('SEARCH', string_to_find, where_to_search, *(v for v in [start_from_position] if v is not None))
```

--------------------------------

### Get All Records

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Retrieve all records from a table at once.

```APIDOC
## GET /records (All)

### Description
Retrieve all records from a table at once. This is a convenience method that calls `iterate()` and collects all results.

### Method
GET

### Endpoint
`/v0/<base_id>/<table_id_or_name>`

### Parameters
#### Query Parameters
- **view** (str) - Optional - 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** (int) - Optional - 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** (int) - Optional - 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** (list[str]) - Optional - 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[str]) - Optional - 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** (str) - Optional - 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. Read more at Building Formulas.
- **cell_format** (str) - Optional - 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** (str) - Optional - The user locale that should be used to format dates when using `string` as the `cell_format`. See Supported SET_LOCALE modifiers for valid values.
- **time_zone** (str) - Optional - The time zone that should be used to format dates when using `string` as the `cell_format`. See Supported SET_TIMEZONE timezones for valid values.
- **use_field_ids** (bool) - Optional - 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. This behavior can be overridden by passing `use_field_ids=True` to `Api`.
- **count_comments** (bool) - Optional - If `True`, the API will include a `commentCount` field for each record. This allows you to see which records have comments without fetching each record individually. Defaults to `False`.

### Request Example
```python
>>> table.all()
```

### Response
#### Success Response (200)
- **List**[`RecordDict`] - A list containing all records in the table.

#### Response Example
```json
[
  {
    "id": "recXXXXXXXXXXXXXX",
    "fields": {
      "Name": "Example Record 1"
    }
  },
  {
    "id": "recYYYYYYYYYYYYYY",
    "fields": {
      "Name": "Example Record 2"
    }
  }
]
```
```

--------------------------------

### Accessing a Table from a Base

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Demonstrates the standard workflow for initializing a base and retrieving records from a table.

```python
>>> base = api.base("appNxslc6jG0XedVM")
>>> table = base.table("Table Name")
>>> records = table.all()
```

--------------------------------

### GET /table/schema

Source: https://pyairtable.readthedocs.io/en/stable/metadata.html

Retrieve the schema of a specific table.

```APIDOC
## GET /table/schema

### Description
Retrieve the schema of the current table.

### Method
GET

### Parameters
#### Query Parameters
- **force** (bool) - Optional - If True, forces an API call and overwrites cached values. Defaults to False.

### Response
#### Success Response (200)
- **TableSchema** - The schema object for the table.
```

--------------------------------

### Initialize Url object

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Demonstrates the initialization of the Url class and its string representation.

```python
url = Url('http://example.com')
url
```

--------------------------------

### GET /webhooks

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Retrieve all webhooks associated with the base.

```APIDOC
## GET /webhooks

### Description
Retrieve all the base's webhooks.

### Method
GET

### Endpoint
/webhooks
```

--------------------------------

### Initialize Base with Api Instance

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

The recommended way to initialize a Base instance is by passing an existing Api instance and the base ID.

```python
from pyairtable import Api

api = Api("access_token")
base = Base(api, "base_id")
```

--------------------------------

### GET /schema

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Retrieve the schema of all tables in the base.

```APIDOC
## GET /schema

### Description
Retrieve the schema of all tables in the base and cache it.

### Method
GET

### Endpoint
/tables

### Parameters
#### Query Parameters
- **include** (List[str]) - Optional - List of fields to include, e.g., ["visibleFieldIds"].
```

--------------------------------

### GET /enterprise/info

Source: https://pyairtable.readthedocs.io/en/stable/enterprise.html

Retrieves basic information about the enterprise account.

```APIDOC
## GET /enterprise/info

### Description
Retrieve basic information about the enterprise, caching the result.

### Method
GET

### Endpoint
Enterprise.info()

### Parameters
#### Query Parameters
- **aggregated** (bool) - Optional - If True, include aggregated values across the enterprise.
- **descendants** (bool) - Optional - If True, include information about the enterprise’s descendant orgs.
- **force** (bool) - Optional - If True, bypasses cache and forces an API call.
```

--------------------------------

### Webhook.payloads

Source: https://pyairtable.readthedocs.io/en/stable/webhooks.html

Iterates through webhook payloads starting from a given cursor.

```APIDOC
## GET /webhooks/{webhook_id}/payloads

### Description
Iterates through all payloads on or after the given cursor. 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.

### Method
GET

### Endpoint
/webhooks/{webhook_id}/payloads

### Parameters
#### Path Parameters
- **webhook_id** (str) - Required - The ID of the webhook.

#### Query Parameters
- **cursor** (int) - Optional - The cursor of the first webhook payload to retrieve. Defaults to 1.
- **limit** (Optional[int]) - Optional - The number of payloads to yield before stopping. If not provided, will retrieve all remaining payloads.

### Response
#### Success Response (200)
- **Iterator[WebhookPayload]** - An iterator yielding WebhookPayload objects.

#### Response Example
```json
{
  "timestamp": "2023-10-27T10:00:00",
  "base_transaction_number": 4,
  "payload_format": "v0",
  "action_metadata": {},
  "changed_tables_by_id": {},
  "created_tables_by_id": {},
  "destroyed_table_ids": [],
  "error": null,
  "error_code": null,
  "cursor": 1
}
```
```

--------------------------------

### Model Initialization and Attribute Handling

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/orm/model.html

Explains how Model instances are initialized and how attributes are managed, including checks for clashes with existing methods and mapping of attributes to field descriptors.

```APIDOC
## Model Initialization and Attribute Handling

### Description
This section covers the initialization of a Model instance and the internal mechanisms for managing attributes and field mappings. It includes methods for checking attribute clashes and creating descriptor maps.

### Methods

#### `_attribute_descriptor_map()`

##### Description
Builds a mapping of the model's attribute names to their corresponding field descriptor instances.

##### Example
```python
class Test(Model):
    first_name = TextField("First Name")
    age = NumberField("Age")

Test._attribute_descriptor_map()
# Expected output: {
#     "field_name": <TextField field_name="First Name">
#     "another_Field": <NumberField field_name="Age">
# }
```

#### `_field_name_descriptor_map()`

##### Description
Builds a mapping of the model's field names to their corresponding field descriptor instances.

##### Example
```python
class Test(Model):
    first_name = TextField("First Name")
    age = NumberField("Age")

Test._field_name_descriptor_map()
# Expected output: {
#     "First Name": <TextField field_name="First Name">
#     "Age": <NumberField field_name="Age">
# }
```

#### `__init__(**fields: Any)`

##### Description
Constructs a model instance with field values provided as keyword arguments. The `id` keyword argument is special-cased to set the record ID.

##### Parameters
- **fields** (Any) - Keyword arguments representing field names and their values.

##### Request Example
```python
Contact(name="Alice", birthday=date(1980, 1, 1))
# Returns: <unsaved Contact>

Contact(id="recWPqD9izdsNvlE", name="Bob")
# Returns: <Contact id='recWPqD9izdsNvlE'>
```
```

--------------------------------

### GET /base/tables

Source: https://pyairtable.readthedocs.io/en/stable/metadata.html

Retrieve a list of all tables within a specific base.

```APIDOC
## GET /base/tables

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

### Method
GET

### Parameters
#### Query Parameters
- **force** (bool) - Optional - If True, forces an API call and overwrites cached values. Defaults to False.

### Response
#### Success Response (200)
- **List[Table]** - A list of Table instances.
```

--------------------------------

### Table Initialization

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/table.html

Demonstrates the different ways to initialize a Table object, including deprecated methods and the recommended approach using an existing Base object.

```APIDOC
## Table Initialization

### Description
Initializes a Table object, representing an Airtable table. It can be initialized using an API key and base ID (deprecated) or by providing an existing Base object.

### Method
`__init__`

### Parameters
- **api_key** (str | None) - The Airtable API key. Deprecated.
- **base_id** (Base | str) - The Base object or base ID. If `api_key` is a string, this should be a string base ID. If `api_key` is None, this should be a Base object.
- **table_name** (str | TableSchema) - The name or schema of the table.
- **timeout** (Optional[TimeoutTuple]) - Optional timeout settings for API requests.
- **retry_strategy** (Optional[Retry]) - Optional retry strategy for API requests.
- **endpoint_url** (str) - The base URL for the Airtable API.

### Request Example (Deprecated)
```python
from pyairtable.api.table import Table

table = Table("api_key", "base_id", "table_name", timeout=(1, 1))
```

### Request Example (Recommended)
```python
from pyairtable.api.base import Base
from pyairtable.api.table import Table

# Assuming 'base' is an existing Base object
table = Table(None, base, "table_name")
```
```

--------------------------------

### GET /base/schema

Source: https://pyairtable.readthedocs.io/en/stable/metadata.html

Retrieve the schema of all tables within a specific base.

```APIDOC
## GET /base/schema

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

### Method
GET

### Parameters
#### Query Parameters
- **force** (bool) - Required - If True, forces an API call and overwrites cached values.

### Response
#### Success Response (200)
- **BaseSchema** - The schema object containing table definitions.
```

--------------------------------

### PyAirtable API Initialization

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/api.html

Demonstrates how to initialize the Api class with an API key and optional configurations like timeout and retry strategy.

```APIDOC
## PyAirtable API Initialization

### Description
Initializes the main Api client for interacting with Airtable.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pyairtable import Api

api = Api('YOUR_AIRTABLE_API_KEY')
```

### Response
None

#### Success Response (200)
None

#### Response Example
None

### Additional Configuration Options

- **timeout** (tuple[int, int]): Connect and read timeout for requests. Example: `timeout=(2, 5)`.
- **retry_strategy** (bool or urllib3.util.Retry): Configures request retries. `True` uses default, `False` disables retries.
- **endpoint_url** (str): Custom API endpoint URL. Defaults to `https://api.airtable.com`.
- **use_field_ids** (bool): If `True`, responses will use field IDs instead of names.
```

--------------------------------

### GET /bases

Source: https://pyairtable.readthedocs.io/en/stable/metadata.html

Retrieve a list of all bases associated with the API instance.

```APIDOC
## GET /bases

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

### Method
GET

### Parameters
#### Query Parameters
- **force** (bool) - Optional - If True, forces an API call and overwrites cached values. Defaults to False.

### Response
#### Success Response (200)
- **List[Base]** - A list of Base instances.
```

--------------------------------

### MockAirtable Initialization and Passthrough

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/testing.html

Explains how to initialize MockAirtable and control its behavior regarding unmocked requests using the `passthrough` argument and context managers.

```APIDOC
## MockAirtable Initialization and Passthrough

### Description
This section details the initialization of the `MockAirtable` class and how to manage network request handling. You can control whether unmocked API calls raise an error or are allowed to proceed to the network using the `passthrough` argument or context managers like `set_passthrough`, `enable_passthrough`, and `disable_passthrough`.

### Method
N/A (Class and Context Manager)

### Endpoint
N/A

### Parameters
#### Constructor Parameters
- **passthrough** (bool) - Optional - If `True`, unmocked methods will perform real network requests. If `False` (default), they will raise a `RuntimeError`.

### Request Example
```python
from pyairtable import Api
from pyairtable.testing import MockAirtable

# Initialize with passthrough enabled
with MockAirtable(passthrough=True) as m:
    # ... test code ...

# Initialize with default passthrough (disabled)
with MockAirtable() as m:
    # ... test code ...

# Temporarily enable passthrough within a context
with MockAirtable() as m:
    with m.enable_passthrough():
        # Network requests are allowed here
        ... 
```

### Response
N/A
```

--------------------------------

### User Identity

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Structure for the 'Get user ID & scopes' endpoint.

```APIDOC
## GET /meta/whoami

### Description
Retrieves the current user's ID and authorized scopes.

### Response
- **id** (str) - The user's unique identifier.
- **scopes** (List[str]) - List of authorized API scopes.
```

--------------------------------

### Initialize Base with API Key (Deprecated)

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

This constructor is deprecated and will likely be removed in the future. It takes an API key string and a base ID to create a Base instance.

```python
from pyairtable import Api

base = Base("access_token", "base_id")
```

--------------------------------

### GET /table/all

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Retrieves all matching records from a specified table in a single list.

```APIDOC
## GET /table/all

### Description
Retrieve all matching records in a single list from an Airtable table.

### Method
GET

### Parameters
#### Query Parameters
- **view** (string) - Optional - The name or ID of a view.
- **page_size** (integer) - Optional - The number of records returned in each request (max 100).
- **max_records** (integer) - Optional - The maximum total number of records to return.
- **fields** (list) - Optional - List of field names to be retrieved.
- **sort** (list) - Optional - List of fields to sort by.
- **formula** (string) - Optional - An Airtable formula to filter records.
- **cell_format** (string) - Optional - Format of cells (json or string).
- **user_locale** (string) - Optional - Locale for date formatting.
- **time_zone** (string) - Optional - Time zone for date formatting.
- **use_field_ids** (boolean) - Optional - Return field objects with field IDs as keys.
- **count_comments** (boolean) - Optional - Include a commentCount field for each record.

### Response
#### Success Response (200)
- **records** (List[RecordDict]) - A list of record objects.
```

--------------------------------

### GET /meta/bases/{base.id}/tables

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/models/schema.html

Retrieve the schema of all tables within a base.

```APIDOC
## GET meta/bases/{base.id}/tables

### Description
Retrieve the schema of all tables within the base, including fields and views.

### Method
GET

### Endpoint
meta/bases/{base.id}/tables

### Parameters
#### Path Parameters
- **base.id** (str) - Required - The unique identifier of the base.
```

--------------------------------

### GET /records (All Records)

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/table.html

Retrieves all matching records from a table into a single list.

```APIDOC
## GET /records (All)

### Description
Retrieve all matching records in a single list. This method internally uses the `iterate()` method and collects all results.

### Method
GET

### Endpoint
/records

### Parameters
#### Query Parameters
- **view** (str) - Optional - The name of the view to use.
- **max_records** (int) - Optional - The maximum number of records to retrieve.
- **fields** (list[str]) - Optional - A list of field names to include in the response.
- **sort** (list[dict]) - Optional - A list of dictionaries specifying sort order.
- **formula** (str | Formula) - Optional - A formula to filter records.
- **cell_format** (str) - Optional - Specifies the format for cell values.
- **user_locale** (str) - Optional - The user's locale for formatting.
- **time_zone** (str) - Optional - The time zone to use for date/time values.
- **use_field_ids** (bool) - Optional - If True, use field IDs instead of names.
- **count_comments** (bool) - Optional - If True, include comment counts.

### Request Example
```python
# Example usage within the pyairtable library
all_records = table.all()
```

### Response
#### Success Response (200)
- **records** (list[RecordDict]) - A list containing all records that match the query criteria.

#### Response Example
```json
[
  {
    "id": "recwPQIfs4wKPyc9D",
    "fields": {
      "First Name": "John",
      "Age": 21
    }
  },
  {
    "id": "recwPQIfs4wKPyc9E",
    "fields": {
      "First Name": "Jane",
      "Age": 22
    }
  }
]
```
```

--------------------------------

### GET /records/{record_id}

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/table.html

Retrieves a single record from a table by its unique ID.

```APIDOC
## GET /records/{record_id}

### Description
Retrieve a record by its ID.

### Method
GET

### Endpoint
/records/{record_id}

### Parameters
#### Path Parameters
- **record_id** (str) - Required - The unique identifier for the record.

#### Query Parameters
- **cell_format** (str) - Optional - Specifies the format for cell values (e.g., 'json', 'string').
- **time_zone** (str) - Optional - The time zone to use for date/time values.
- **user_locale** (str) - Optional - The user's locale for formatting.
- **use_field_ids** (bool) - Optional - If True, use field IDs instead of names.

### Request Example
```python
# Example usage within the pyairtable library
table.get('recwPQIfs4wKPyc9D')
```

### Response
#### Success Response (200)
- **id** (str) - The unique identifier of the record.
- **fields** (dict) - A dictionary containing the record's fields and their values.

#### Response Example
```json
{
  "id": "recwPQIfs4wKPyc9D",
  "fields": {
    "First Name": "John",
    "Age": 21
  }
}
```
```

--------------------------------

### Initialize and use a Table

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/table.html

Basic usage pattern for creating a table instance from an API object and retrieving all records.

```python
>>> api = Api(access_token)
>>> table = api.table("base_id", "table_name")
>>> records = table.all()
```

--------------------------------

### Get Base Collaborators

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Retrieves collaborators, invite links, and interfaces for the base.

```APIDOC
## GET /meta

### Description
Retrieves collaborators, invite links, and interfaces for the base.

### Method
GET

### Endpoint
/meta

### Query Parameters
- **include** (string) - Optional - Comma-separated list of items to include. Possible values: "collaborators", "inviteLinks", "interfaces".

### Response
#### Success Response (200)
- **BaseCollaborators** (object) - An object containing collaborators, invite links, and interfaces.

#### Response Example
```json
{
  "collaborators": [
    {
      "id": "usrXXXXXXXXXXXXXX",
      "email": "user@example.com",
      "name": "User Name",
      "permissionLevel": "editor"
    }
  ],
  "inviteLinks": [
    {
      "id": "invXXXXXXXXXXXXXX",
      "url": "https://airtable.com/invite/XXXXXXXXXXXXXX",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ],
  "interfaces": [
    {
      "id": "intXXXXXXXXXXXXXX",
      "name": "My Interface",
      "type": "grid"
    }
  ]
}
```
```

--------------------------------

### Release Project

Source: https://pyairtable.readthedocs.io/en/stable/about.html

Command to trigger the release process.

```bash
make bump
```

--------------------------------

### GET /meta/bases/{id}

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/base.html

Retrieves metadata and collaborators for a specific Airtable base.

```APIDOC
## GET /meta/bases/{id}

### Description
Retrieves metadata and collaborators for a specific Airtable base.

### Method
GET

### Endpoint
/meta/bases/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The base ID (e.g., appXXXXXXXXXXXXXX)
```

--------------------------------

### Build a Table instance

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Creates a new Table instance from a base using a table name or ID.

```python
>>> base.table('Apartments')
<Table base='appLkNDICXNqxSDhG' name='Apartments'>
```

--------------------------------

### POST /create_base

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/api.html

Create a base in the given workspace.

```APIDOC
## POST /create_base

### Description
Create a base in the given workspace.

### Method
POST

### Endpoint
/create_base

#### Parameters
##### Request Body
- **workspace_id** (str) - Required - The ID of the workspace where the new base will live.
- **name** (str) - Required - The name to give to the new base. Does not need to be unique.
- **tables** (Sequence[Dict[str, Any]]) - Required - A list of ``dict`` objects that conform to Airtable's `Table model <https://airtable.com/developers/web/api/model/table-model>`__.

### Request Example
```python
api.create_base(
    workspace_id='ws123',
    name='New Project Base',
    tables=[
        {'name': 'Tasks', 'primary_field_name': 'Name'},
        {'name': 'Projects', 'primary_field_name': 'Project Name'}
    ]
)
```

### Response
#### Success Response (200)
- **Base** (:class:`Base`) - The newly created Base instance.

#### Response Example
```json
{
  "id": "appNewBaseId",
  "name": "New Project Base",
  "tables": [
    {
      "id": "tblNewTable1",
      "name": "Tasks",
      "primaryFieldId": "fldTaskName"
    },
    {
      "id": "tblNewTable2",
      "name": "Projects",
      "primaryFieldId": "fldProjectName"
    }
  ]
}
```
```

--------------------------------

### MID function

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/formulas.html

Extracts a substring of a specific length starting at a given index.

```python
def MID(string: FunctionArg, where_to_start: FunctionArg, count: FunctionArg, /) -> FunctionCall:
    """
    Extract a substring of count characters starting at whereToStart.
    """
    return FunctionCall('MID', string, where_to_start, count)
```

--------------------------------

### GET /meta/bases/{base.id}

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/models/schema.html

Retrieve detailed information about who can access a specific Airtable base.

```APIDOC
## GET meta/bases/{base.id}

### Description
Retrieve detailed information about who can access a base.

### Method
GET

### Endpoint
meta/bases/{base.id}

### Parameters
#### Path Parameters
- **base.id** (str) - Required - The unique identifier of the base.
```

--------------------------------

### Instantiating Api, Base, and Table in pyAirtable 2.x

Source: https://pyairtable.readthedocs.io/en/stable/migrations.html

Demonstrates supported and unsupported ways to instantiate Api, Base, and Table objects in pyAirtable 2.x. The supported patterns use instances for API and Base objects, while unsupported patterns mix string and instance types, leading to TypeErrors.

```python
>>> api = Api(api_key, timeout=..., retry_strategy=..., endpoint_url=...)
>>> base = api.base(base_id)  # [str]
>>> base = Base(api, base_id)  # [Api, str]
>>> table = base.table(table_name)  # [str]
>>> table = api.table(base_id, table_name)  # [str, str]
>>> table = Table(None, base, table_name)  # [None, Base, str]
```

```python
# The following are still supported but will issue a DeprecationWarning:
>>> base = Base(api_key, base_id)  # [str, str]
>>> table = Table(api_key, base_id, table_name)  # [str, str, str]
```

```python
# The following will raise a TypeError for mixing str & instances:
>>> table = Table(api_key, base, table_name)  # [str, Base, str]
>>> table = Table(api, base_id, table_name)  # [Api, str, str]
```

```python
# The following will raise a TypeError. We do this proactively
# to avoid situations where self.api and self.base don't align.
>>> table = Table(api, base, table_name)  # [Api, Base, str]
```

--------------------------------

### GET /enterprise/audit-log

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/enterprise.html

Retrieves a paginated list of audit log events for an enterprise account.

```APIDOC
## GET /enterprise/audit-log

### Description
Retrieves audit log events for an enterprise account with support for filtering by time, user, event type, and model. Supports pagination.

### Method
GET

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - How many events per page to return (maximum 100).
- **sortOrder** (string) - Optional - Sort order: 'ascending' or 'descending'.
- **previous** (string) - Optional - Requests the previous page of results.
- **next** (string) - Optional - Requests the next page of results.
- **startTime** (string) - Optional - Earliest timestamp to retrieve (inclusive).
- **endTime** (string) - Optional - Latest timestamp to retrieve (inclusive).
- **originatingUserId** (string/list) - Optional - Retrieve events originating from specific user ID(s).
- **eventType** (string/list) - Optional - Retrieve events by event type(s).
- **modelId** (string/list) - Optional - Retrieve events involving specific model ID(s).
- **category** (string/list) - Optional - Retrieve events by category.

### Response
#### Success Response (200)
- **events** (array) - List of audit log events.
- **pagination** (object) - Pagination metadata containing next/previous tokens.
```

--------------------------------

### Command List

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

Lists all available commands and their general usage.

```APIDOC
## Command list

```
Usage: pyairtable [OPTIONS] COMMAND [ARGS]...

Options:
  -k, --key TEXT        Your API key.
  -kf, --key-file PATH  File containing your API key.
  -ke, --key-env VAR    Env var containing your API key.
  -v, --verbose         Print verbose output.
  --help                Show this message and exit.

Commands:
  whoami                              Print the current user's information.
  bases                               List all available bases.
  base ID schema                      Print the base schema.
  base ID table ID_OR_NAME records    Retrieve records from the table.
  base ID table ID_OR_NAME schema     Print the table's schema as JSON.
  base ID collaborators               Print base collaborators.
  base ID shares                      Print base shares.
  base ID orm                         Generate a Python ORM module.
  enterprise ID info                  Print information about an enterprise.
  enterprise ID user ID_OR_EMAIL      Print one user's information.
  enterprise ID users ID_OR_EMAIL...  Print many users, keyed by user ID.
  enterprise ID group ID              Print a user group's information.
  enterprise ID groups ID...          Print many groups, keyed by group ID.
```
```

--------------------------------

### Add records to MockAirtable

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/testing.html

Demonstrates how to populate the mock instance with records using either base/table identifiers or a Table object.

```python
m = MockAirtable()
m.add_records("baseId", "tableName", [{"Name": "Alice"}])
m.add_records(table, records=[{"id": "recFake", {"Name": "Alice"}}])
```

--------------------------------

### pyAirtable CLI: whoami Command Help

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

Displays help information for the 'whoami' command, which prints the current user's information.

```bash
Usage: pyairtable whoami [OPTIONS]

  Print the current user's information.

Options:
  --help  Show this message and exit.
```

--------------------------------

### pyAirtable CLI: base schema Command Help

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

Displays help information for the 'base schema' command, used to print the schema of a specific Airtable base.

```bash
Usage: pyairtable base BASE_ID schema [OPTIONS]

  Print the base schema.

Options:
  --help  Show this message and exit.
```

--------------------------------

### UpsertResultDict Example

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

The structure of the response from `batch_upsert`, detailing created, updated, and all affected records.

```python
{
    'createdRecords': [...],
    'updatedRecords': [...],
    'records': [...] 
}
```

--------------------------------

### Create Workspace Method

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/enterprise.html

Creates a new workspace within an enterprise account. Requires the requesting user to be an active effective admin.

```python
    def create_workspace(self, name: str) -> "Workspace":
        """
        Creates a new workspace with the provided name within the enterprise account
        and returns the workspace ID. The requesting user must be an active effective
        admin of the enterprise account; the created workspace's owner will be the user
        who makes the request.

        See `Create workspace <https://airtable.com/developers/web/api/create-workspace>`__.

        Args:
            name: The name of the workspace to be created.

        Returns:
            The ID of the newly created workspace.
        """
        response = self.api.post(
            self.urls.create_workspace,
            json={
                "enterpriseAccountId": self.id,
                "name": name,
            },
        )
        return self.api.workspace(str(response["id"]))
```

--------------------------------

### RecordDeletedDict Example

Source: https://pyairtable.readthedocs.io/en/stable/_modules/pyairtable/api/types.html

Represents the confirmation payload returned by the API after a record is successfully deleted.

```python
{'id': 'recAdw9EjV90xbZ', 'deleted': True}
```

--------------------------------

### pyAirtable CLI: base shares Command Help

Source: https://pyairtable.readthedocs.io/en/stable/cli.html

Displays help information for the 'base shares' command, used to list shares for a specific Airtable base.

```bash
Usage: pyairtable base BASE_ID shares [OPTIONS]

  Print base shares.

Options:
  --help  Show this message and exit.
```

--------------------------------

### GET /table/first

Source: https://pyairtable.readthedocs.io/en/stable/api.html

Retrieves the first matching record from a table, returning None if no records are found.

```APIDOC
## GET /table/first

### Description
Retrieve the first matching record. This is similar to all(), but limits the result to one record.

### Method
GET

### Parameters
#### Query Parameters
- **view** (string) - Optional - The name or ID of a view.
- **fields** (list) - Optional - List of field names to be retrieved.
- **sort** (list) - Optional - List of fields to sort by.
- **formula** (string) - Optional - An Airtable formula to filter records.
- **cell_format** (string) - Optional - Format of cells (json or string).
- **user_locale** (string) - Optional - Locale for date formatting.
- **time_zone** (string) - Optional - Time zone for date formatting.

### Response
#### Success Response (200)
- **record** (RecordDict) - The first matching record or None.
```