Add audit log to documentation

docs/source/api.rst

@@ -49,6 +49,14 @@ API: pyairtable.models
     :inherited-members: AirtableModel
 
 
+API: pyairtable.models.audit
+********************************
+
+.. automodule:: pyairtable.models.audit
+    :members:
+    :inherited-members: AirtableModel
+
+
 API: pyairtable.models.schema
 ********************************
 

docs/source/enterprise.rst

@@ -0,0 +1,29 @@
+.. include:: _substitutions.rst
+.. include:: _warn_latest.rst
+
+Enterprise Features
+==============================
+
+
+pyAirtable exposes a number of classes and methods for interacting with enterprise organizations.
+The following methods are only available on an `Enterprise plan <https://airtable.com/pricing>`__.
+If you call one of them against a base that is not part of an enterprise workspace, Airtable will
+return a 404 error, and pyAirtable will add a reminder to the exception to check your billing plan.
+
+.. automethod:: pyairtable.Api.enterprise
+    :noindex:
+
+.. automethod:: pyairtable.Base.collaborators
+    :noindex:
+
+.. automethod:: pyairtable.Base.shares
+    :noindex:
+
+.. automethod:: pyairtable.Workspace.collaborators
+    :noindex:
+
+.. automethod:: pyairtable.Enterprise.info
+    :noindex:
+
+.. automethod:: pyairtable.Enterprise.iterate_audit_log
+    :noindex:

docs/source/index.rst

@@ -27,16 +27,17 @@ pyAirtable
    getting-started
    tables
    orm
-   webhooks
    metadata
-   migrations
+   webhooks
+   enterprise
    api
 
 
 .. toctree::
    :caption: More
    :hidden:
 
+   migrations
    about
    changelog
    contributing

docs/source/metadata.rst

@@ -33,30 +33,6 @@ You'll find more detail in the API reference for :mod:`pyairtable.models.schema`
     :noindex:
 
 
-Enterprise information
------------------------------
-
-pyAirtable exposes a number of classes and methods for interacting with enterprise organizations.
-The following methods are only available on an `Enterprise plan <https://airtable.com/pricing>`__.
-If you call one of them against a base that is not part of an enterprise workspace, Airtable will
-return a 404 error, and pyAirtable will add a reminder to the exception to check your billing plan.
-
-.. automethod:: pyairtable.Api.enterprise
-    :noindex:
-
-.. automethod:: pyairtable.Base.collaborators
-    :noindex:
-
-.. automethod:: pyairtable.Base.shares
-    :noindex:
-
-.. automethod:: pyairtable.Workspace.collaborators
-    :noindex:
-
-.. automethod:: pyairtable.Enterprise.info
-    :noindex:
-
-
 Modifying existing schema
 -----------------------------
 

docs/source/webhooks.rst

@@ -1,3 +1,6 @@
+.. include:: _substitutions.rst
+.. include:: _warn_latest.rst
+
 Webhooks
 ==============================
 

pyairtable/models/audit.py

@@ -6,6 +6,13 @@
 
 
 class AuditLogResponse(AirtableModel):
+    """
+    Represents a page of audit log events.
+
+    See `Audit log events <https://airtable.com/developers/web/api/audit-log-events>`__
+    for more information on how to interpret this data structure.
+    """
+
     events: List["AuditLogEvent"]
     pagination: Optional["AuditLogResponse.Pagination"] = None
 
@@ -15,6 +22,13 @@ class Pagination(AirtableModel):
 
 
 class AuditLogEvent(AirtableModel):
+    """
+    Represents a single audit log event.
+
+    See `Audit log events <https://airtable.com/developers/web/api/audit-log-events>`__
+    for more information on how to interpret this data structure.
+    """
+
     id: str
     timestamp: str
     action: str

tests/test_api_enterprise.py

@@ -136,6 +136,9 @@ def test_group(enterprise, enterprise_mocks):
     ],
 )
 def test_audit_log(enterprise, fncall, expected_size):
+    """
+    Test that we iterate through multiple pages of the audit log. correctly
+    """
     events = [
         event
         for page in enterprise.iterate_audit_log(*fncall.args, **fncall.kwargs)
@@ -144,6 +147,23 @@ def test_audit_log(enterprise, fncall, expected_size):
     assert len(events) == expected_size
 
 
+def test_audit_log__no_loop(enterprise, requests_mock):
+    """
+    Test that an empty page of events does not cause an infinite loop.
+    """
+    requests_mock.get(
+        enterprise.api.build_url(
+            f"meta/enterpriseAccounts/{enterprise.id}/auditLogEvents"
+        ),
+        json={
+            "events": [],
+            "pagination": {"previous": "dummy"},
+        },
+    )
+    events = [event for page in enterprise.iterate_audit_log() for event in page.events]
+    assert len(events) == 0
+
+
 @pytest.mark.parametrize(
     "fncall,sortorder,offset_field",
     [
@@ -159,6 +179,10 @@ def test_audit_log__sortorder(
     sortorder,
     offset_field,
 ):
+    """
+    Test that we calculate sortorder and offset_field correctly
+    dpeending on whether we're ascending or descending.
+    """
     with patch.object(api, "iterate_requests", wraps=api.iterate_requests) as m:
         list(enterprise.iterate_audit_log(*fncall.args, **fncall.kwargs))