feat: Support requests.auth authenticators (#1109)

meltano · Feb 3, 2023 · 9e2ae5c · 9e2ae5c
1 parent 7ec2a71
commit 9e2ae5c
Show file tree

Hide file tree

Showing 47 changed files with 157 additions and 52 deletions.
diff --git a/docs/_templates/class.rst b/docs/_templates/class.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: {{ name }}
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.BatchSink.rst b/docs/classes/singer_sdk.BatchSink.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BatchSink
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.GraphQLStream.rst b/docs/classes/singer_sdk.GraphQLStream.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: GraphQLStream
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.InlineMapper.rst b/docs/classes/singer_sdk.InlineMapper.rst
@@ -7,4 +7,4 @@
     :members:
     :show-inheritance:
     :inherited-members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.RESTStream.rst b/docs/classes/singer_sdk.RESTStream.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: RESTStream
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.RecordSink.rst b/docs/classes/singer_sdk.RecordSink.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: RecordSink
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.SQLConnector.rst b/docs/classes/singer_sdk.SQLConnector.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SQLConnector
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.SQLSink.rst b/docs/classes/singer_sdk.SQLSink.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SQLSink
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.SQLStream.rst b/docs/classes/singer_sdk.SQLStream.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SQLStream
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.SQLTap.rst b/docs/classes/singer_sdk.SQLTap.rst
@@ -7,4 +7,4 @@
     :members:
     :show-inheritance:
     :inherited-members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.SQLTarget.rst b/docs/classes/singer_sdk.SQLTarget.rst
@@ -7,4 +7,4 @@
     :members:
     :show-inheritance:
     :inherited-members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.Sink.rst b/docs/classes/singer_sdk.Sink.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: Sink
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.Stream.rst b/docs/classes/singer_sdk.Stream.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: Stream
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.Tap.rst b/docs/classes/singer_sdk.Tap.rst
@@ -7,4 +7,4 @@
     :members:
     :show-inheritance:
     :inherited-members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.Target.rst b/docs/classes/singer_sdk.Target.rst
@@ -7,4 +7,4 @@
     :members:
     :show-inheritance:
     :inherited-members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.APIAuthenticatorBase.rst b/docs/classes/singer_sdk.authenticators.APIAuthenticatorBase.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: APIAuthenticatorBase
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.APIKeyAuthenticator.rst b/docs/classes/singer_sdk.authenticators.APIKeyAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: APIKeyAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.BasicAuthenticator.rst b/docs/classes/singer_sdk.authenticators.BasicAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BasicAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.BearerTokenAuthenticator.rst b/docs/classes/singer_sdk.authenticators.BearerTokenAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BearerTokenAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.OAuthAuthenticator.rst b/docs/classes/singer_sdk.authenticators.OAuthAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: OAuthAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.OAuthJWTAuthenticator.rst b/docs/classes/singer_sdk.authenticators.OAuthJWTAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: OAuthJWTAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.authenticators.SimpleAuthenticator.rst b/docs/classes/singer_sdk.authenticators.SimpleAuthenticator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SimpleAuthenticator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.ConfigValidationError.rst b/docs/classes/singer_sdk.exceptions.ConfigValidationError.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: ConfigValidationError
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.FatalAPIError.rst b/docs/classes/singer_sdk.exceptions.FatalAPIError.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: FatalAPIError
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.InvalidStreamSortException.rst b/docs/classes/singer_sdk.exceptions.InvalidStreamSortException.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: InvalidStreamSortException
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.MapExpressionError.rst b/docs/classes/singer_sdk.exceptions.MapExpressionError.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: MapExpressionError
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.MaxRecordsLimitException.rst b/docs/classes/singer_sdk.exceptions.MaxRecordsLimitException.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: MaxRecordsLimitException
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.RecordsWithoutSchemaException.rst b/docs/classes/singer_sdk.exceptions.RecordsWithoutSchemaException.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: RecordsWithoutSchemaException
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.RetriableAPIError.rst b/docs/classes/singer_sdk.exceptions.RetriableAPIError.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: RetriableAPIError
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.StreamMapConfigError.rst b/docs/classes/singer_sdk.exceptions.StreamMapConfigError.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: StreamMapConfigError
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.TapStreamConnectionFailure.rst b/docs/classes/singer_sdk.exceptions.TapStreamConnectionFailure.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: TapStreamConnectionFailure
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.exceptions.TooManyRecordsException.rst b/docs/classes/singer_sdk.exceptions.TooManyRecordsException.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: TooManyRecordsException
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.BaseAPIPaginator.rst b/docs/classes/singer_sdk.pagination.BaseAPIPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BaseAPIPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.BaseHATEOASPaginator.rst b/docs/classes/singer_sdk.pagination.BaseHATEOASPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BaseHATEOASPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.BaseOffsetPaginator.rst b/docs/classes/singer_sdk.pagination.BaseOffsetPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BaseOffsetPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.BasePageNumberPaginator.rst b/docs/classes/singer_sdk.pagination.BasePageNumberPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: BasePageNumberPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.HeaderLinkPaginator.rst b/docs/classes/singer_sdk.pagination.HeaderLinkPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: HeaderLinkPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.JSONPathPaginator.rst b/docs/classes/singer_sdk.pagination.JSONPathPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: JSONPathPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.LegacyPaginatedStreamProtocol.rst b/docs/classes/singer_sdk.pagination.LegacyPaginatedStreamProtocol.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: LegacyPaginatedStreamProtocol
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.LegacyStreamPaginator.rst b/docs/classes/singer_sdk.pagination.LegacyStreamPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: LegacyStreamPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.SimpleHeaderPaginator.rst b/docs/classes/singer_sdk.pagination.SimpleHeaderPaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SimpleHeaderPaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/classes/singer_sdk.pagination.SinglePagePaginator.rst b/docs/classes/singer_sdk.pagination.SinglePagePaginator.rst
@@ -5,4 +5,4 @@
 
 .. autoclass:: SinglePagePaginator
     :members:
-    :special-members: __init__
+    :special-members: __init__, __call__
diff --git a/docs/code_samples.md b/docs/code_samples.md
@@ -255,6 +255,34 @@ class CachedAuthStream(RESTStream):
         return APIAuthenticatorBase(stream=self)
 ```
 
+### Use one of `requests`'s built-in authenticators
+
+```python
+from requests.auth import HTTPDigestAuth
+from singer_sdk.streams import RESTStream
+
+class DigestAuthStream(RESTStream):
+    """A stream with digest authentication."""
+
+    @property
+    def authenticator(self) -> HTTPDigestAuth:
+        """Stream authenticator."""
+        return HTTPDigestAuth(
+            username=self.config["username"],
+            password=self.config["password"],
+        )
+```
+
+[`HTTPBasicAuth`](https://requests.readthedocs.io/en/latest/api/#requests.auth.HTTPBasicAuth) and
+[`HTTPProxyAuth`](https://requests.readthedocs.io/en/latest/api/#requests.auth.HTTPProxyAuth)
+are also available in `requests.auth`. In addition to `requests.auth` classes, the community
+has published a few packages with custom authenticator classes, which are compatible with the SDK.
+For example:
+
+- [`requests-aws4auth`](https://github.com/tedder/requests-aws4auth): AWS v4 authentication
+- [`requests_auth`](https://github.com/Colin-b/requests_auth): A collection of authenticators
+  for various services and protocols including Azure, Okta and NTLM.
+
 ### Custom response validation
 
 Some APIs deviate from HTTP status codes to report failures. For those cases,