big-jobs · codefoxut · Mar 15, 2024 · Mar 18, 2024 · Mar 18, 2024 · Mar 18, 2024
diff --git a/.github/workflows/test_lint_deploy.yml b/.github/workflows/test_lint_deploy.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.8", "3.9", "3.10", "3.11"]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v3
@@ -42,6 +42,12 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     needs: test
+
+    # See https://docs.pypi.org/trusted-publishers/using-a-publisher/
+    environment: release
+    permissions:
+      id-token: write
+
     # Only Publish if it's a tagged commit
     if: >-
       startsWith(github.ref, 'refs/tags/')
@@ -50,10 +56,10 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up Python 3.8
+      - name: Set up Python 3.14
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.14
 
       - name: Install pypa/build
         run: >-
@@ -70,9 +76,6 @@ jobs:
           --wheel
           --outdir dist/
           .
+
       - name: Publish distribution 📦 to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
-          repository_url: https://upload.pypi.org/legacy/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,8 +1,16 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
+-   repo: local
+    hooks:
+    -   id: cog
+        name: cog
+        language: python
+        additional_dependencies: [cogapp]
+        entry: 'python -m cogapp -cr --verbosity=1 --markers="[[[cog]]] [[[out]]] [[[end]]]"'
+        files: \.py$
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     -   id: check-added-large-files
     -   id: check-json
@@ -11,15 +19,15 @@ repos:
     -   id: fix-byte-order-marker
     -   id: trailing-whitespace
 -   repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         args: [--profile, black]
 -   repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 24.2.0
     hooks:
     -   id: black
 -   repo: https://github.com/pycqa/flake8
-    rev: 6.0.0
+    rev: 7.0.0
     hooks:
     -   id: flake8
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -2,9 +2,9 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.8"
+    python: "3.10"
 
 sphinx:
   configuration: docs/source/conf.py

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md
+
+Read all developer instructions and contribution guidelines in @README.md.
+
+## Testing your changes
+
+When changing code in `pyairtable/`, follow these steps one at a time:
+
+1. `tox -e mypy`
+2. `tox -e py314 -- $CHANGED_FILE $CORRESPONDING_TEST_FILE`
+3. `tox -e coverage`
+4. `make lint`
+5. `make docs`
+6. `make test`
+
+When changing code in `docs/`, follow these steps instead:
+
+1. `make docs`
+2. `make lint`
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -3,3 +3,4 @@ include *.rst
 include tox.ini
 include LICENSE
 include README.md
+exclude pyairtable/formulas.txt
diff --git a/Makefile b/Makefile
@@ -10,25 +10,12 @@ hooks:
 	.tox/pre-commit/bin/pre-commit install
 	.tox/pre-commit/bin/pre-commit install-hooks
 
-.PHONY: release release-test bump
+.PHONY: release
 release:
-	make clean
-	python -m build --sdist --wheel --outdir ./dist
-	twine upload ./dist/*
+	@zsh -c "./scripts/release.sh"
 
-release-test:
-	make clean
-	python -m build --sdist --wheel --outdir ./dist
-	twine upload --repository testpypi ./dist/*
-
-bump:
-	@bash -c "./scripts/bump.sh"
-
-.PHONY: test test-e2e coverage lint format docs clean
+.PHONY: test coverage lint format docs clean
 test:
-	tox -- -m 'not integration'
-
-test-e2e:
 	tox
 
 coverage:

diff --git a/README.md b/README.md
@@ -16,9 +16,9 @@ pip install pyairtable
 
 ## Documentation
 
-Read the full documentation on [pyairtable.readthedocs.io](https://pyairtable.readthedocs.io/en/latest/getting-started.html).
+Read the full documentation on [pyairtable.readthedocs.io](https://pyairtable.readthedocs.io/en/stable/getting-started.html).
 
-If you're still using airtable-python-wrapper and want to upgrade, read the [migration guide](https://pyairtable.readthedocs.io/en/latest/migrations.html).
+If you're still using airtable-python-wrapper and want to upgrade, read the [migration guide](https://pyairtable.readthedocs.io/en/stable/migrations.html).
 
 ## Contributing
 
@@ -29,8 +29,14 @@ Everyone who has an idea or suggestion is welcome to contribute! As maintainers,
 If it's your first time working on this library, clone the repo, set up pre-commit hooks, and make sure you can run tests (and they pass). If that doesn't work out of the box, please check your local development environment before filing an issue.
 
 ```sh
-% make setup
-% make test
+make setup
+make test
+```
+
+For a quick test run (~15s after the environments are created) use:
+
+```sh
+tox -e mypy && tox -e coverage
 ```
 
 ### Reporting a bug
@@ -50,8 +56,10 @@ Anyone who uses this library is welcome to [submit a pull request](https://githu
 
 1. Public functions/methods have docstrings and type annotations.
 2. New functionality is accompanied by clear, descriptive unit tests.
-3. You can run `make test && make docs` successfully.
-4. You have [signed your commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
+3. The library maintains 100% test coverage.
+4. You can run `make test && make docs` successfully.
+5. No backwards-incompatible changes (unless discussed in an existing issue).
+6. You have [signed your commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
 
 If you want to discuss an idea you're working on but haven't yet finished all of the above, please [open a draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). That will be a clear signal that you're not asking to merge your code (yet) and are just looking for discussion or feedback.
 

diff --git a/docs/source/_substitutions.rst b/docs/source/_substitutions.rst
@@ -1,6 +1,9 @@
-.. |arg_base_id| replace:: An Airtable base id.
+.. |arg_base_id| replace:: An Airtable base ID.
 
-.. |arg_record_id| replace:: An Airtable record id.
+.. |arg_record_id| replace:: An Airtable record ID.
+
+.. |arg_table_id_or_name| replace:: An Airtable table ID or name.
+        Table name should be unencoded, as shown on browser.
 
 .. |kwarg_view| replace:: The name or ID of a view.
     If set, only the records in that view will be returned.
@@ -32,8 +35,7 @@
 .. |kwarg_formula| replace:: 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}"``.
+    formula will be returned. Read more at :doc:`formulas`.
 
 .. |kwarg_typecast| replace:: The Airtable API will perform best-effort
     automatic data conversion from string values.
@@ -46,17 +48,52 @@
 
 .. |kwarg_user_locale| replace:: 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
+    `Supported SET_LOCALE modifiers <https://support.airtable.com/docs/supported-locale-modifiers-for-set-locale>`__
     for valid values.
 
 .. |kwarg_time_zone| replace:: 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
+    `Supported SET_TIMEZONE timezones <https://support.airtable.com/docs/supported-timezones-for-set-timezone>`__
     for valid values.
 
 .. |kwarg_replace| replace:: 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.
+    bet set to null. If ``False``, only provided fields are updated.
+
+.. |kwarg_use_field_ids| replace:: 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 :class:`~pyairtable.Api`.
+
+.. |kwarg_count_comments| replace:: 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``.
+
+.. |kwarg_force_metadata| replace::
+    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.
+
+.. |kwarg_validate_metadata| replace::
+    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.
+
+.. |kwarg_orm_fetch| replace::
+    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.
+
+.. |kwarg_orm_memoize| replace::
+    If ``True``, any objects created will be memoized for future reuse.
+    If ``False``, objects created will *not* be memoized.
+    The default behavior is defined on the :class:`~pyairtable.orm.Model` subclass.
+
+.. |kwarg_orm_lazy| replace::
+    If ``True``, this field will return empty objects with only IDs;
+    call :meth:`~pyairtable.orm.Model.fetch` to retrieve values.
+
+.. |kwarg_permission_level| replace::
+    See `application permission levels <https://airtable.com/developers/web/api/model/application-permission-levels>`__.
+
+.. |warn| unicode:: U+26A0 .. WARNING SIGN
 
-.. |kwarg_return_fields_by_field_id| replace:: 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.
+.. |enterprise_only| replace:: |warn| This feature is only available on Enterprise billing plans.
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -6,7 +6,7 @@ API Reference
 =============
 
 
-Module: pyairtable
+API: pyairtable
 *******************************
 
 .. autoclass:: pyairtable.Api
@@ -18,48 +18,106 @@ Module: pyairtable
 .. autoclass:: pyairtable.Table
     :members:
 
+.. autoclass:: pyairtable.Workspace
+    :members:
+
+.. autoclass:: pyairtable.Enterprise
+    :members:
+
 .. autofunction:: pyairtable.retry_strategy
 
 
-Module: pyairtable.api.types
+API: pyairtable.api.enterprise
+*******************************
+
+.. automodule:: pyairtable.api.enterprise
+    :members:
+    :exclude-members: Enterprise
+    :inherited-members: BaseModel, AirtableModel
+
+
+API: pyairtable.api.types
 *******************************
 
 .. automodule:: pyairtable.api.types
     :members:
 
 
-Module: pyairtable.formulas
+API: pyairtable.exceptions
+*******************************
+
+.. automodule:: pyairtable.exceptions
+    :members:
+
+
+API: pyairtable.formulas
 *******************************
 
 .. automodule:: pyairtable.formulas
     :members:
 
 
-Module: pyairtable.models
+API: pyairtable.models
 *******************************
 
 .. automodule:: pyairtable.models
     :members:
+    :inherited-members: BaseModel, AirtableModel
+
 
+API: pyairtable.models.comment
+-------------------------------
+
+.. automodule:: pyairtable.models.comment
+    :members:
+    :exclude-members: Comment
+    :inherited-members: BaseModel, AirtableModel
 
-Module: pyairtable.orm
+
+API: pyairtable.models.schema
+-------------------------------
+
+.. automodule:: pyairtable.models.schema
+    :members:
+    :inherited-members: BaseModel, AirtableModel
+
+
+API: pyairtable.models.webhook
+-------------------------------
+
+.. automodule:: pyairtable.models.webhook
+    :members:
+    :exclude-members: Webhook, WebhookNotification, WebhookPayload
+    :inherited-members: BaseModel, AirtableModel
+
+
+API: pyairtable.orm
 *******************************
 
 .. autoclass:: pyairtable.orm.Model
     :members:
 
+.. autoclass:: pyairtable.orm.SaveResult
+    :members:
+
 
-Module: pyairtable.orm.fields
+API: pyairtable.orm.fields
 *******************************
 
 .. automodule:: pyairtable.orm.fields
     :members:
-    :member-order: bysource
     :exclude-members: valid_types, contains_type
     :no-inherited-members:
 
 
-Module: pyairtable.utils
+API: pyairtable.testing
+*******************************
+
+.. automodule:: pyairtable.testing
+    :members:
+
+
+API: pyairtable.utils
 *******************************
 
 .. automodule:: pyairtable.utils