Drop `ApiAbstract`

[mesozoic]

This closes #257 by removing ApiAbstract. Instead, we have Api, Base, and Table classes that each have separate functions and responsibilities. They do still refer to each other, and their constructors have at least some backwards compatibility. See below (or read the changes to migrations.rst) for more details.

This will be a breaking API change, so definitely want to get eyes on this before I merge it. Tagging recent contributors for ideas or feedback. @BAPCon @goksan @larsakerson @NicoHood @marks

A note on circular dependencies

Api needs to know how to create Base and Table instances, but the Base and Table instances need to have references back to the Api and Base (respectively). To avoid a circular reference, these modules import each other using fully qualified names, and only refer to the classes within methods that need them. Type annotations are enclosed in quotes.

This results in internal code that might be a bit aesthetically displeasing, like:

class Base:
    def table(self, table_name):
        return pyairtable.api.table.Table(table_name)

class Table:
    api: "pyairtable.api.api.Api"
    base: "pyairtable.api.base.Base"

This was, however, the simplest form I could find that allows for both type annotations and bidirectional runtime dependencies. Api needs to be able to create a Base, but for backwards compatibility, we also need Base to be able to create an Api.

A note on backwards compatibility

The most common use case for this library (based on a cursory search) seems to be:

table = Table(api_key, base_id, table_name)

This branch preserves backwards compatibility with that constructor syntax, but will emit deprecation warnings implying that this style could be removed in the future:

>>> from pyairtable import Base, Table
>>> base = Base("api_key", "base_id")
<stdin>:1: DeprecationWarning: Passing API keys to pyairtable.Base is deprecated; use Api.base() instead. See https://pyairtable.rtfd.org/en/latest/migrations.html for details.
>>> table = Table("api_key", "base_id", "table_name")
<stdin>:1: DeprecationWarning: Passing API keys or base IDs to pyairtable.Table is deprecated; use Api.table() or Base.table() instead. See https://pyairtable.rtfd.org/en/latest/migrations.html for details.

The rationale for deprecating this code path is that, in the future, we might want to perform additional steps when referencing a table (such as validating its existence). This will be easier to do in Base.table() before constructing the Table instance.

Summary of each commit

• 1a90f8b removes ApiAbstract and moves its methods into either Api, Base, or (mostly) Table. I tried not to change behavior or introduce any new methods, but did add two:
  • Api.chunked() breaks an iterable into chunks based on Airtable's maximum record count per request
  • Api.wait() sleeps for 1/N seconds, where N is Airtable's QPS limit. (I hope to remove the need for this soon.)
• 46232cd started a section of migrations.rst that discusses how to upgrade.
• ac5e654 is a substantial reorganization of docs/ to reflect the new Api structure.
• c144f68 removes anything from substitutions.rst that was unused, or only used in one place.
• f210d4a removes the middle column from the Parameters section (which isn't strictly necessary) so that the rest of the table is easier to read.
• 6285dff removes the "Added in 1.0.0" label; now that we are on 2.0.0, it doesn't feel necessary to reference everything that was added when this library was renamed.
• 5313443 folds the "utils" docs into the API Reference section.
• 0f8548e adds sections to the changelog.rst and migrations.rst for the 2.0 release
• e523a5c changes the constructors for the refactored Base and Table classes so that they can receive either str or instances in their constructors. (See backwards compatibility, above.)
• 3e146ee improves backwards-compatibility of the Table() constructor so that it can accept Api kwargs when receiving all str arguments.
• c1c536b is another pass over the docs to improve legibility and fix typos.
• 98a336a standardizes references within our docs to the top-level name (e.g. pyairtable.Table) instead of the canonical name (e.g. pyairtable.api.table.Table)

[codecov[bot]]

Codecov Report

Merging #267 (98a336a) into main (6e95f05) will increase coverage by 1.26%. The diff coverage is 95.60%.

:exclamation: Current head 98a336a differs from pull request most recent head e5485bc. Consider uploading reports for the commit e5485bc to get more accurate results

@@            Coverage Diff             @@
##             main     #267      +/-   ##
==========================================
+ Coverage   93.30%   94.56%   +1.26%     
==========================================
  Files          16       15       -1     
  Lines         836      755      -81     
==========================================
- Hits          780      714      -66     
+ Misses         56       41      -15     

Impacted Files	Coverage Δ
pyairtable/api/retrying.py	100.00% <ø> (ø)
pyairtable/api/types.py	100.00% <ø> (ø)
pyairtable/formulas.py	86.00% <ø> (ø)
pyairtable/metadata.py	26.31% <0.00%> (-3.10%)	:arrow_down:
pyairtable/utils.py	100.00% <ø> (ø)
pyairtable/api/base.py	95.45% <95.45%> (+17.95%)	:arrow_up:
pyairtable/api/table.py	98.09% <97.87%> (-1.91%)	:arrow_down:
pyairtable/api/api.py	100.00% <100.00%> (+22.50%)	:arrow_up:
pyairtable/orm/model.py	96.00% <100.00%> (+0.34%)	:arrow_up:

[mesozoic]

I'm working on some other branches to finish up the rest of the 2.0 release scope, but they depend on this one so I'm not posting them yet. I'll plan to merge this branch next week if there are no objections or questions raised here.