chore(typing): endpoint decorators

Author: jorwoods

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -126,7 +126,7 @@ def download(
         datasource_id: str,
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
-    ) -> str:
+    ) -> PathOrFileW:
         return self.download_revision(
             datasource_id,
             None,
@@ -405,7 +405,7 @@ def _get_datasource_revisions(
     def download_revision(
         self,
         datasource_id: str,
-        revision_number: str,
+        revision_number: Optional[str],
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
     ) -> PathOrFileW:

tableauserverclient/server/endpoint/endpoint.py

@@ -1,30 +1,42 @@
+from typing_extensions import Concatenate
 from tableauserverclient import datetime_helpers as datetime
 
 import abc
 from packaging.version import Version
 from functools import wraps
 from xml.etree.ElementTree import ParseError
-from typing import Any, Callable, Dict, Generic, List, Optional, TYPE_CHECKING, Tuple, TypeVar, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    TYPE_CHECKING,
+    ParamSpec,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.request_options import RequestOptions
 
-from .exceptions import (
+from tableauserverclient.server.endpoint.exceptions import (
     ServerResponseError,
     InternalServerError,
     NonXMLResponseError,
     NotSignedInError,
 )
-from ..exceptions import EndpointUnavailableError
+from tableauserverclient.server.exceptions import EndpointUnavailableError
 
 from tableauserverclient.server.query import QuerySet
 from tableauserverclient import helpers, get_versions
 
 from tableauserverclient.helpers.logging import logger
-from tableauserverclient.config import DELAY_SLEEP_SECONDS
 
 if TYPE_CHECKING:
-    from ..server import Server
+    from tableauserverclient.server.server import Server
     from requests import Response
 
 
@@ -38,7 +50,7 @@
 USER_AGENT_HEADER = "User-Agent"
 
 
-class Endpoint(object):
+class Endpoint:
     def __init__(self, parent_srv: "Server"):
         self.parent_srv = parent_srv
 
@@ -232,7 +244,12 @@ def patch_request(self, url, xml_request, content_type=XML_CONTENT_TYPE, paramet
         )
 
 
-def api(version):
+E = TypeVar("E", bound="Endpoint")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def api(version: str) -> Callable[[Callable[Concatenate[E, P], R]], Callable[Concatenate[E, P], R]]:
     """Annotate the minimum supported version for an endpoint.
 
     Checks the version on the server object and compares normalized versions.
@@ -251,9 +268,9 @@ def api(version):
     >>>     ...
     """
 
-    def _decorator(func):
+    def _decorator(func: Callable[Concatenate[E, P], R]) -> Callable[Concatenate[E, P], R]:
         @wraps(func)
-        def wrapper(self, *args, **kwargs):
+        def wrapper(self: E, *args: P.args, **kwargs: P.kwargs) -> R:
             self.parent_srv.assert_at_least_version(version, self.__class__.__name__)
             return func(self, *args, **kwargs)
 
@@ -262,7 +279,7 @@ def wrapper(self, *args, **kwargs):
     return _decorator
 
 
-def parameter_added_in(**params):
+def parameter_added_in(**params: str) -> Callable[[Callable[Concatenate[E, P], R]], Callable[Concatenate[E, P], R]]:
     """Annotate minimum versions for new parameters or request options on an endpoint.
 
     The api decorator documents when an endpoint was added, this decorator annotates
@@ -285,9 +302,9 @@ def parameter_added_in(**params):
     >>>     ...
     """
 
-    def _decorator(func):
+    def _decorator(func: Callable[Concatenate[E, P], R]) -> Callable[Concatenate[E, P], R]:
         @wraps(func)
-        def wrapper(self, *args, **kwargs):
+        def wrapper(self: E, *args: P.args, **kwargs: P.kwargs) -> R:
             import warnings
 
             server_ver = Version(self.parent_srv.version or "0.0")
@@ -335,5 +352,5 @@ def paginate(self, **kwargs) -> QuerySet[T]:
         return queryset
 
     @abc.abstractmethod
-    def get(self, request_options: RequestOptions) -> Tuple[List[T], PaginationItem]:
+    def get(self, request_options: Optional[RequestOptions] = None) -> Tuple[List[T], PaginationItem]:
         raise NotImplementedError(f".get has not been implemented for {self.__class__.__qualname__}")

tableauserverclient/server/endpoint/jobs_endpoint.py

@@ -1,4 +1,5 @@
 import logging
+from typing_extensions import Self, overload
 
 from tableauserverclient.server.query import QuerySet
 
@@ -13,15 +14,25 @@
 from typing import List, Optional, Tuple, Union
 
 
-class Jobs(QuerysetEndpoint[JobItem]):
+class Jobs(QuerysetEndpoint[BackgroundJobItem]):
     @property
     def baseurl(self):
         return "{0}/sites/{1}/jobs".format(self.parent_srv.baseurl, self.parent_srv.site_id)
 
+    @overload  # type: ignore[override]
+    def get(self: Self, job_id: str, req_options: Optional[RequestOptionsBase] = None) -> JobItem:  # type: ignore[override]
+        ...
+
+    @overload  # type: ignore[override]
+    def get(self: Self, job_id: RequestOptionsBase, req_options: None) -> Tuple[List[BackgroundJobItem], PaginationItem]:  # type: ignore[override]
+        ...
+
+    @overload  # type: ignore[override]
+    def get(self: Self, job_id: None, req_options: Optional[RequestOptionsBase]) -> Tuple[List[BackgroundJobItem], PaginationItem]:  # type: ignore[override]
+        ...
+
     @api(version="2.6")
-    def get(
-        self, job_id: Optional[str] = None, req_options: Optional[RequestOptionsBase] = None
-    ) -> Tuple[List[BackgroundJobItem], PaginationItem]:
+    def get(self, job_id=None, req_options=None):
         # Backwards Compatibility fix until we rev the major version
         if job_id is not None and isinstance(job_id, str):
             import warnings
@@ -77,7 +88,7 @@ def wait_for_job(self, job_id: Union[str, JobItem], *, timeout: Optional[float]
         else:
             raise AssertionError("Unexpected finish_code in job", job)
 
-    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[JobItem]:
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[BackgroundJobItem]:
         """
         Queries the Tableau Server for items using the specified filters. Page
         size can be specified to limit the number of items returned in a single

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -184,7 +184,7 @@ def download(
         workbook_id: str,
         filepath: Optional[PathOrFileW] = None,
         include_extract: bool = True,
-    ) -> str:
+    ) -> PathOrFileW:
         return self.download_revision(
             workbook_id,
             None,