Merge pull request #1435 from jorwoods/jorwoods/filter_docstrings

docs: add docstrings detailing the filter options

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -9,6 +9,7 @@
 from typing import List, Mapping, Optional, Sequence, Tuple, TYPE_CHECKING, Union
 
 from tableauserverclient.helpers.headers import fix_filename
+from tableauserverclient.server.query import QuerySet
 
 if TYPE_CHECKING:
     from tableauserverclient.server import Server
@@ -459,3 +460,87 @@ def schedule_extract_refresh(
         self, schedule_id: str, item: DatasourceItem
     ) -> List["AddResponse"]:  # actually should return a task
         return self.parent_srv.schedules.add_to_schedule(schedule_id, datasource=item)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[DatasourceItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        authentication_type=...
+        authentication_type__in=...
+        connected_workbook_type=...
+        connected_workbook_type__gt=...
+        connected_workbook_type__gte=...
+        connected_workbook_type__lt=...
+        connected_workbook_type__lte=...
+        connection_to=...
+        connection_to__in=...
+        connection_type=...
+        connection_type__in=...
+        content_url=...
+        content_url__in=...
+        created_at=...
+        created_at__gt=...
+        created_at__gte=...
+        created_at__lt=...
+        created_at__lte=...
+        database_name=...
+        database_name__in=...
+        database_user_name=...
+        database_user_name__in=...
+        description=...
+        description__in=...
+        favorites_total=...
+        favorites_total__gt=...
+        favorites_total__gte=...
+        favorites_total__lt=...
+        favorites_total__lte=...
+        has_alert=...
+        has_embedded_password=...
+        has_extracts=...
+        is_certified=...
+        is_connectable=...
+        is_default_port=...
+        is_hierarchical=...
+        is_published=...
+        name=...
+        name__in=...
+        owner_domain=...
+        owner_domain__in=...
+        owner_email=...
+        owner_name=...
+        owner_name__in=...
+        project_name=...
+        project_name__in=...
+        server_name=...
+        server_name__in=...
+        server_port=...
+        size=...
+        size__gt=...
+        size__gte=...
+        size__lt=...
+        size__lte=...
+        table_name=...
+        table_name__in=...
+        tags=...
+        tags__in=...
+        type=...
+        updated_at=...
+        updated_at__gt=...
+        updated_at__gte=...
+        updated_at__lt=...
+        updated_at__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/flow_runs_endpoint.py

@@ -7,6 +7,7 @@
 from tableauserverclient.exponential_backoff import ExponentialBackoffTimer
 
 from tableauserverclient.helpers.logging import logger
+from tableauserverclient.server.query import QuerySet
 
 if TYPE_CHECKING:
     from tableauserverclient.server.server import Server
@@ -78,3 +79,42 @@ def wait_for_job(self, flow_run_id: str, *, timeout: Optional[int] = None) -> Fl
             raise FlowRunCancelledException(flow_run)
         else:
             raise AssertionError("Unexpected status in flow_run", flow_run)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[FlowRunItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        complete_at=...
+        complete_at__gt=...
+        complete_at__gte=...
+        complete_at__lt=...
+        complete_at__lte=...
+        flow_id=...
+        flow_id__in=...
+        progress=...
+        progress__gt=...
+        progress__gte=...
+        progress__lt=...
+        progress__lte=...
+        started_at=...
+        started_at__gt=...
+        started_at__gte=...
+        started_at__lt=...
+        started_at__lte=...
+        user_id=...
+        user_id__in=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/flows_endpoint.py

@@ -22,6 +22,7 @@
     get_file_type,
     get_file_object_size,
 )
+from tableauserverclient.server.query import QuerySet
 
 io_types_r = (io.BytesIO, io.BufferedReader)
 io_types_w = (io.BytesIO, io.BufferedWriter)
@@ -295,3 +296,39 @@ def schedule_flow_run(
         self, schedule_id: str, item: FlowItem
     ) -> List["AddResponse"]:  # actually should return a task
         return self.parent_srv.schedules.add_to_schedule(schedule_id, flow=item)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[FlowItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        created_at=...
+        created_at__gt=...
+        created_at__gte=...
+        created_at__lt=...
+        created_at__lte=...
+        name=...
+        name__in=...
+        owner_name=...
+        project_id=...
+        project_name=...
+        project_name__in=...
+        updated=...
+        updated__gt=...
+        updated__gte=...
+        updated__lt=...
+        updated__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/groups_endpoint.py

@@ -10,6 +10,8 @@
 
 from typing import Iterable, List, Optional, TYPE_CHECKING, Tuple, Union
 
+from tableauserverclient.server.query import QuerySet
+
 if TYPE_CHECKING:
     from tableauserverclient.server.request_options import RequestOptions
 
@@ -162,3 +164,42 @@ def add_users(self, group_item: GroupItem, users: Iterable[Union[str, UserItem]]
         users = UserItem.from_response(server_response.content, self.parent_srv.namespace)
         logger.info("Added users to group (ID: {0})".format(group_item.id))
         return users
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[GroupItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        domain_name=...
+        domain_name__in=...
+        domain_nickname=...
+        domain_nickname__in=...
+        is_external_user_enabled=...
+        is_local=...
+        luid=...
+        luid__in=...
+        minimum_site_role=...
+        minimum_site_role__in=...
+        name__cieq=...
+        name=...
+        name__in=...
+        name__like=...
+        user_count=...
+        user_count__gt=...
+        user_count__gte=...
+        user_count__lt=...
+        user_count__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/groupsets_endpoint.py

@@ -5,6 +5,7 @@
 from tableauserverclient.models.groupset_item import GroupSetItem
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint
+from tableauserverclient.server.query import QuerySet
 from tableauserverclient.server.request_options import RequestOptions
 from tableauserverclient.server.request_factory import RequestFactory
 from tableauserverclient.server.endpoint.endpoint import api
@@ -85,3 +86,42 @@ def update(self, groupset: GroupSetItem) -> GroupSetItem:
         server_response = self.put_request(url, request)
         updated_groupset = GroupSetItem.from_response(server_response.content, self.parent_srv.namespace)
         return updated_groupset[0]
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[GroupSetItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        domain_name=...
+        domain_name__in=...
+        domain_nickname=...
+        domain_nickname__in=...
+        is_external_user_enabled=...
+        is_local=...
+        luid=...
+        luid__in=...
+        minimum_site_role=...
+        minimum_site_role__in=...
+        name__cieq=...
+        name=...
+        name__in=...
+        name__like=...
+        user_count=...
+        user_count__gt=...
+        user_count__gte=...
+        user_count__lt=...
+        user_count__lte=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/jobs_endpoint.py

@@ -1,5 +1,7 @@
 import logging
 
+from tableauserverclient.server.query import QuerySet
+
 from .endpoint import QuerysetEndpoint, api
 from .exceptions import JobCancelledException, JobFailedException
 from tableauserverclient.models import JobItem, BackgroundJobItem, PaginationItem
@@ -74,3 +76,57 @@ def wait_for_job(self, job_id: Union[str, JobItem], *, timeout: Optional[float]
             raise JobCancelledException(job)
         else:
             raise AssertionError("Unexpected finish_code in job", job)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[JobItem]:
+        """
+        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
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+
+        args__has=...
+        completed_at=...
+        completed_at__gt=...
+        completed_at__gte=...
+        completed_at__lt=...
+        completed_at__lte=...
+        created_at=...
+        created_at__gt=...
+        created_at__gte=...
+        created_at__lt=...
+        created_at__lte=...
+        job_type=...
+        job_type__in=...
+        notes__has=...
+        priority=...
+        priority__gt=...
+        priority__gte=...
+        priority__lt=...
+        priority__lte=...
+        progress=...
+        progress__gt=...
+        progress__gte=...
+        progress__lt=...
+        progress__lte=...
+        started_at=...
+        started_at__gt=...
+        started_at__gte=...
+        started_at__lt=...
+        started_at__lte=...
+        status=...
+        subtitle=...
+        subtitle__has=...
+        title=...
+        title__has=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)