tableauserverclient 0.37__py3-none-any.whl → 0.38__py3-none-any.whl

tableauserverclient/server/endpoint/dqw_endpoint.py

@@ -1,4 +1,5 @@
 import logging
+from typing import Callable, Optional, Protocol, TYPE_CHECKING
 
 from .endpoint import Endpoint
 from .exceptions import MissingRequiredFieldError
@@ -7,6 +8,15 @@ from tableauserverclient.models import DQWItem
 
 from tableauserverclient.helpers.logging import logger
 
+if TYPE_CHECKING:
+    from tableauserverclient.server.request_options import RequestOptions
+
+
+class HasId(Protocol):
+    @property
+    def id(self) -> Optional[str]: ...
+    def _set_data_quality_warnings(self, dqw: Callable[[], list[DQWItem]]): ...
+
 
 class _DataQualityWarningEndpoint(Endpoint):
     def __init__(self, parent_srv, resource_type):
@@ -14,12 +24,12 @@ class _DataQualityWarningEndpoint(Endpoint):
         self.resource_type = resource_type
 
     @property
-    def baseurl(self):
+    def baseurl(self) -> str:
         return "{}/sites/{}/dataQualityWarnings/{}".format(
             self.parent_srv.baseurl, self.parent_srv.site_id, self.resource_type
         )
 
-    def add(self, resource, warning):
+    def add(self, resource: HasId, warning: DQWItem) -> list[DQWItem]:
         url = f"{self.baseurl}/{resource.id}"
         add_req = RequestFactory.DQW.add_req(warning)
         response = self.post_request(url, add_req)
@@ -28,7 +38,7 @@ class _DataQualityWarningEndpoint(Endpoint):
 
         return warnings
 
-    def update(self, resource, warning):
+    def update(self, resource: HasId, warning: DQWItem) -> list[DQWItem]:
         url = f"{self.baseurl}/{resource.id}"
         add_req = RequestFactory.DQW.update_req(warning)
         response = self.put_request(url, add_req)
@@ -37,11 +47,11 @@ class _DataQualityWarningEndpoint(Endpoint):
 
         return warnings
 
-    def clear(self, resource):
+    def clear(self, resource: HasId) -> None:
         url = f"{self.baseurl}/{resource.id}"
         return self.delete_request(url)
 
-    def populate(self, item):
+    def populate(self, item: HasId) -> None:
         if not item.id:
             error = "Server item is missing ID. Item must be retrieved from server first."
             raise MissingRequiredFieldError(error)
@@ -52,7 +62,7 @@ class _DataQualityWarningEndpoint(Endpoint):
         item._set_data_quality_warnings(dqw_fetcher)
         logger.info(f"Populated permissions for item (ID: {item.id})")
 
-    def _get_data_quality_warnings(self, item, req_options=None):
+    def _get_data_quality_warnings(self, item: HasId, req_options: Optional["RequestOptions"] = None) -> list[DQWItem]:
         url = f"{self.baseurl}/{item.id}"
         server_response = self.get_request(url, req_options)
         dqws = DQWItem.from_response(server_response.content, self.parent_srv.namespace)

tableauserverclient/server/endpoint/endpoint.py

@@ -14,6 +14,7 @@ from typing import (
     TypeVar,
     Union,
 )
+from typing_extensions import Self
 
 from tableauserverclient.models.pagination_item import PaginationItem
 from tableauserverclient.server.request_options import RequestOptions
@@ -353,3 +354,41 @@ class QuerysetEndpoint(Endpoint, Generic[T]):
     @abc.abstractmethod
     def get(self, request_options: Optional[RequestOptions] = None) -> tuple[list[T], PaginationItem]:
         raise NotImplementedError(f".get has not been implemented for {self.__class__.__qualname__}")
+
+    def fields(self: Self, *fields: str) -> QuerySet:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be used in addition to the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        queryset = QuerySet(self)
+        queryset.request_options.fields |= set(fields) | set(("_default_",))
+        return queryset
+
+    def only_fields(self: Self, *fields: str) -> QuerySet:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be replaced by the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        queryset = QuerySet(self)
+        queryset.request_options.fields |= set(fields)
+        return queryset

tableauserverclient/server/endpoint/schedules_endpoint.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Callable, Optional, Union
 from .endpoint import Endpoint, api, parameter_added_in
 from .exceptions import MissingRequiredFieldError
 from tableauserverclient.server import RequestFactory
-from tableauserverclient.models import PaginationItem, ScheduleItem, TaskItem
+from tableauserverclient.models import PaginationItem, ScheduleItem, TaskItem, ExtractItem
 
 from tableauserverclient.helpers.logging import logger
 
@@ -30,6 +30,23 @@ class Schedules(Endpoint):
 
     @api(version="2.3")
     def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[ScheduleItem], PaginationItem]:
+        """
+        Returns a list of flows, extract, and subscription server schedules on
+        Tableau Server. For each schedule, the API returns name, frequency,
+        priority, and other information.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#query_schedules
+
+        Parameters
+        ----------
+        req_options : Optional[RequestOptions]
+            Filtering and paginating options for request.
+
+        Returns
+        -------
+        Tuple[List[ScheduleItem], PaginationItem]
+            A tuple of list of ScheduleItem and PaginationItem
+        """
         logger.info("Querying all schedules")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -38,7 +55,22 @@ class Schedules(Endpoint):
         return all_schedule_items, pagination_item
 
     @api(version="3.8")
-    def get_by_id(self, schedule_id):
+    def get_by_id(self, schedule_id: str) -> ScheduleItem:
+        """
+        Returns detailed information about the specified server schedule.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get-schedule
+
+        Parameters
+        ----------
+        schedule_id : str
+            The ID of the schedule to get information for.
+
+        Returns
+        -------
+        ScheduleItem
+            The schedule item that corresponds to the given ID.
+        """
         if not schedule_id:
             error = "No Schedule ID provided"
             raise ValueError(error)
@@ -49,6 +81,20 @@ class Schedules(Endpoint):
 
     @api(version="2.3")
     def delete(self, schedule_id: str) -> None:
+        """
+        Deletes the specified schedule from the server.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#delete_schedule
+
+        Parameters
+        ----------
+        schedule_id : str
+            The ID of the schedule to delete.
+
+        Returns
+        -------
+        None
+        """
         if not schedule_id:
             error = "Schedule ID undefined"
             raise ValueError(error)
@@ -58,6 +104,23 @@ class Schedules(Endpoint):
 
     @api(version="2.3")
     def update(self, schedule_item: ScheduleItem) -> ScheduleItem:
+        """
+        Modifies settings for the specified server schedule, including the name,
+        priority, and frequency details on Tableau Server. For Tableau Cloud,
+        see the tasks and subscritpions API.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#update_schedule
+
+        Parameters
+        ----------
+        schedule_item : ScheduleItem
+            The schedule item to update.
+
+        Returns
+        -------
+        ScheduleItem
+            The updated schedule item.
+        """
         if not schedule_item.id:
             error = "Schedule item missing ID."
             raise MissingRequiredFieldError(error)
@@ -71,6 +134,20 @@ class Schedules(Endpoint):
 
     @api(version="2.3")
     def create(self, schedule_item: ScheduleItem) -> ScheduleItem:
+        """
+        Creates a new server schedule on Tableau Server. For Tableau Cloud, use
+        the tasks and subscriptions API.
+
+        Parameters
+        ----------
+        schedule_item : ScheduleItem
+            The schedule item to create.
+
+        Returns
+        -------
+        ScheduleItem
+            The newly created schedule.
+        """
         if schedule_item.interval_item is None:
             error = "Interval item must be defined."
             raise MissingRequiredFieldError(error)
@@ -92,6 +169,41 @@ class Schedules(Endpoint):
         flow: Optional["FlowItem"] = None,
         task_type: Optional[str] = None,
     ) -> list[AddResponse]:
+        """
+        Adds a workbook, datasource, or flow to a schedule on Tableau Server.
+        Only one of workbook, datasource, or flow can be passed in at a time.
+
+        The task type is optional and will default to ExtractRefresh if a
+        workbook or datasource is passed in, and RunFlow if a flow is passed in.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_workbook_to_schedule
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#add_flow_task_to_schedule
+
+        Parameters
+        ----------
+        schedule_id : str
+            The ID of the schedule to add the item to.
+
+        workbook : Optional[WorkbookItem]
+            The workbook to add to the schedule.
+
+        datasource : Optional[DatasourceItem]
+            The datasource to add to the schedule.
+
+        flow : Optional[FlowItem]
+            The flow to add to the schedule.
+
+        task_type : Optional[str]
+            The type of task to add to the schedule. If not provided, it will
+            default to ExtractRefresh if a workbook or datasource is passed in,
+            and RunFlow if a flow is passed in.
+
+        Returns
+        -------
+        list[AddResponse]
+            A list of responses for each item added to the schedule.
+        """
         # There doesn't seem to be a good reason to allow one item of each type?
         if workbook and datasource:
             warnings.warn("Passing in multiple items for add_to_schedule will be deprecated", PendingDeprecationWarning)
@@ -149,3 +261,21 @@ class Schedules(Endpoint):
             )
         else:
             return OK
+
+    @api(version="2.3")
+    def get_extract_refresh_tasks(
+        self, schedule_id: str, req_options: Optional["RequestOptions"] = None
+    ) -> tuple[list["ExtractItem"], "PaginationItem"]:
+        """Get all extract refresh tasks for the specified schedule."""
+        if not schedule_id:
+            error = "Schedule ID undefined"
+            raise ValueError(error)
+
+        logger.info(f"Querying extract refresh tasks for schedule (ID: {schedule_id})")
+        url = f"{self.siteurl}/{schedule_id}/extracts"
+        server_response = self.get_request(url, req_options)
+
+        pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
+        extract_items = ExtractItem.from_response(server_response.content, self.parent_srv.namespace)
+
+        return extract_items, pagination_item

tableauserverclient/server/endpoint/sites_endpoint.py

@@ -4,7 +4,7 @@ import logging
 from .endpoint import Endpoint, api
 from .exceptions import MissingRequiredFieldError
 from tableauserverclient.server import RequestFactory
-from tableauserverclient.models import SiteItem, PaginationItem
+from tableauserverclient.models import SiteAuthConfiguration, SiteItem, PaginationItem
 
 from tableauserverclient.helpers.logging import logger
 
@@ -418,3 +418,20 @@ class Sites(Endpoint):
 
         empty_req = RequestFactory.Empty.empty_req()
         self.post_request(url, empty_req)
+
+    @api(version="3.24")
+    def list_auth_configurations(self) -> list[SiteAuthConfiguration]:
+        """
+        Lists all authentication configurations on the current site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#list_authentication_configurations_site
+
+        Returns
+        -------
+        list[SiteAuthConfiguration]
+            A list of authentication configurations on the current site.
+        """
+        url = f"{self.baseurl}/{self.parent_srv.site_id}/site-auth-configurations"
+        server_response = self.get_request(url)
+        auth_configurations = SiteAuthConfiguration.from_response(server_response.content, self.parent_srv.namespace)
+        return auth_configurations

tableauserverclient/server/endpoint/tables_endpoint.py

@@ -1,7 +1,8 @@
 import logging
-from typing import Union
+from typing import Optional, Union, TYPE_CHECKING
 from collections.abc import Iterable
 
+from tableauserverclient.models.permissions_item import PermissionsRule
 from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
 from tableauserverclient.server.endpoint.endpoint import api, Endpoint
 from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
@@ -12,6 +13,10 @@ from tableauserverclient.models import TableItem, ColumnItem, PaginationItem
 from tableauserverclient.server.pager import Pager
 
 from tableauserverclient.helpers.logging import logger
+from tableauserverclient.server.request_options import RequestOptions
+
+if TYPE_CHECKING:
+    from tableauserverclient.models import DQWItem, PermissionsRule
 
 
 class Tables(Endpoint, TaggingMixin[TableItem]):
@@ -22,11 +27,29 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         self._data_quality_warnings = _DataQualityWarningEndpoint(self.parent_srv, "table")
 
     @property
-    def baseurl(self):
+    def baseurl(self) -> str:
         return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/tables"
 
     @api(version="3.5")
-    def get(self, req_options=None):
+    def get(self, req_options: Optional[RequestOptions] = None) -> tuple[list[TableItem], PaginationItem]:
+        """
+        Get information about all tables on the site. Endpoint is paginated, and
+        will return a default of 100 items per page. Use the `req_options`
+        parameter to customize the request.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_tables
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Options to customize the request. If not provided, defaults to None.
+
+        Returns
+        -------
+        tuple[list[TableItem], PaginationItem]
+            A tuple containing a list of TableItem objects and a PaginationItem
+            object.
+        """
         logger.info("Querying all tables on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -36,7 +59,27 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
 
     # Get 1 table
     @api(version="3.5")
-    def get_by_id(self, table_id):
+    def get_by_id(self, table_id: str) -> TableItem:
+        """
+        Get information about a single table on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_table
+
+        Parameters
+        ----------
+        table_id : str
+            The ID of the table to retrieve.
+
+        Returns
+        -------
+        TableItem
+            A TableItem object representing the table.
+
+        Raises
+        ------
+        ValueError
+            If the table ID is not provided.
+        """
         if not table_id:
             error = "table ID undefined."
             raise ValueError(error)
@@ -46,7 +89,24 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return TableItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     @api(version="3.5")
-    def delete(self, table_id):
+    def delete(self, table_id: str) -> None:
+        """
+        Delete a single table from the server.
+
+        Parameters
+        ----------
+        table_id : str
+            The ID of the table to delete.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the table ID is not provided.
+        """
         if not table_id:
             error = "Database ID undefined."
             raise ValueError(error)
@@ -55,7 +115,27 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         logger.info(f"Deleted single table (ID: {table_id})")
 
     @api(version="3.5")
-    def update(self, table_item):
+    def update(self, table_item: TableItem) -> TableItem:
+        """
+        Update a table on the server.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_table
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object to update.
+
+        Returns
+        -------
+        TableItem
+            The updated TableItem object.
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the table item is missing an ID.
+        """
         if not table_item.id:
             error = "table item missing ID."
             raise MissingRequiredFieldError(error)
@@ -69,21 +149,46 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
 
     # Get all columns of the table
     @api(version="3.5")
-    def populate_columns(self, table_item, req_options=None):
+    def populate_columns(self, table_item: TableItem, req_options: Optional[RequestOptions] = None) -> None:
+        """
+        Populate the columns of a table item. Sets a fetcher function to
+        retrieve the columns when needed.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_columns
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object to populate columns for.
+
+        req_options : RequestOptions, optional
+            Options to customize the request. If not provided, defaults to None.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the table item is missing an ID.
+        """
         if not table_item.id:
             error = "Table item missing ID. table must be retrieved from server first."
             raise MissingRequiredFieldError(error)
 
         def column_fetcher():
             return Pager(
-                lambda options: self._get_columns_for_table(table_item, options),
+                lambda options: self._get_columns_for_table(table_item, options),  # type: ignore
                 req_options,
             )
 
         table_item._set_columns(column_fetcher)
         logger.info(f"Populated columns for table (ID: {table_item.id}")
 
-    def _get_columns_for_table(self, table_item, req_options=None):
+    def _get_columns_for_table(
+        self, table_item: TableItem, req_options: Optional[RequestOptions] = None
+    ) -> tuple[list[ColumnItem], PaginationItem]:
         url = f"{self.baseurl}/{table_item.id}/columns"
         server_response = self.get_request(url, req_options)
         columns = ColumnItem.from_response(server_response.content, self.parent_srv.namespace)
@@ -91,7 +196,25 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return columns, pagination_item
 
     @api(version="3.5")
-    def update_column(self, table_item, column_item):
+    def update_column(self, table_item: TableItem, column_item: ColumnItem) -> ColumnItem:
+        """
+        Update the description of a column in a table.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_column
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object representing the table.
+
+        column_item : ColumnItem
+            The ColumnItem object representing the column to update.
+
+        Returns
+        -------
+        ColumnItem
+            The updated ColumnItem object.
+        """
         url = f"{self.baseurl}/{table_item.id}/columns/{column_item.id}"
         update_req = RequestFactory.Column.update_req(column_item)
         server_response = self.put_request(url, update_req)
@@ -101,31 +224,31 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return column
 
     @api(version="3.5")
-    def populate_permissions(self, item):
+    def populate_permissions(self, item: TableItem) -> None:
         self._permissions.populate(item)
 
     @api(version="3.5")
-    def update_permissions(self, item, rules):
+    def update_permissions(self, item: TableItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
         return self._permissions.update(item, rules)
 
     @api(version="3.5")
-    def delete_permission(self, item, rules):
+    def delete_permission(self, item: TableItem, rules: list[PermissionsRule]) -> None:
         return self._permissions.delete(item, rules)
 
     @api(version="3.5")
-    def populate_dqw(self, item):
+    def populate_dqw(self, item: TableItem) -> None:
         self._data_quality_warnings.populate(item)
 
     @api(version="3.5")
-    def update_dqw(self, item, warning):
+    def update_dqw(self, item: TableItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.update(item, warning)
 
     @api(version="3.5")
-    def add_dqw(self, item, warning):
+    def add_dqw(self, item: TableItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.add(item, warning)
 
     @api(version="3.5")
-    def delete_dqw(self, item):
+    def delete_dqw(self, item: TableItem) -> None:
         self._data_quality_warnings.clear(item)
 
     @api(version="3.9")

tableauserverclient/server/endpoint/users_endpoint.py

@@ -87,7 +87,7 @@ class Users(QuerysetEndpoint[UserItem]):
 
         if req_options is None:
             req_options = RequestOptions()
-        req_options._all_fields = True
+        req_options.all_fields = True
 
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -381,10 +381,15 @@ class Users(QuerysetEndpoint[UserItem]):
 
     # Get workbooks for user
     @api(version="2.0")
-    def populate_workbooks(self, user_item: UserItem, req_options: Optional[RequestOptions] = None) -> None:
+    def populate_workbooks(
+        self, user_item: UserItem, req_options: Optional[RequestOptions] = None, owned_only: bool = False
+    ) -> None:
         """
         Returns information about the workbooks that the specified user owns
-        and has Read (view) permissions for.
+        or has Read (view) permissions for. If owned_only is set to True,
+        only the workbooks that the user owns are returned. If owned_only is
+        set to False, all workbooks that the user has Read (view) permissions
+        for are returned.
 
         This method retrieves the workbook information for the specified user.
         The REST API is designed to return only the information you ask for
@@ -402,6 +407,10 @@ class Users(QuerysetEndpoint[UserItem]):
         req_options : Optional[RequestOptions]
             Optional request options to filter and sort the results.
 
+        owned_only : bool, default=False
+            If True, only the workbooks that the user owns are returned.
+            If False, all workbooks that the user has Read (view) permissions
+
         Returns
         -------
         None
@@ -423,14 +432,22 @@ class Users(QuerysetEndpoint[UserItem]):
             raise MissingRequiredFieldError(error)
 
         def wb_pager():
-            return Pager(lambda options: self._get_wbs_for_user(user_item, options), req_options)
+            def func(req_options):
+                return self._get_wbs_for_user(user_item, req_options, owned_only=owned_only)
+
+            return Pager(func, req_options)
 
         user_item._set_workbooks(wb_pager)
 
     def _get_wbs_for_user(
-        self, user_item: UserItem, req_options: Optional[RequestOptions] = None
+        self,
+        user_item: UserItem,
+        req_options: Optional[RequestOptions] = None,
+        owned_only: bool = False,
     ) -> tuple[list[WorkbookItem], PaginationItem]:
         url = f"{self.baseurl}/{user_item.id}/workbooks"
+        if owned_only:
+            url += "?ownedBy=true"
         server_response = self.get_request(url, req_options)
         logger.info(f"Populated workbooks for user (ID: {user_item.id})")
         workbook_item = WorkbookItem.from_response(server_response.content, self.parent_srv.namespace)

tableauserverclient/server/query.py

@@ -208,6 +208,42 @@ class QuerySet(Iterable[T], Sized):
             self.request_options.pagesize = kwargs["page_size"]
         return self
 
+    def fields(self: Self, *fields: str) -> Self:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be used in addition to the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        self.request_options.fields |= set(fields) | set(("_default_"))
+        return self
+
+    def only_fields(self: Self, *fields: str) -> Self:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be replaced by the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        self.request_options.fields |= set(fields)
+        return self
+
     @staticmethod
     def _parse_shorthand_filter(key: str) -> tuple[str, str]:
         tokens = key.split("__", 1)