8000 docs: docstrings for Pager and RequestOptions (#1498) · tableau/server-client-python@b9c36c1 · GitHub
[go: up one dir, main page]
Skip to content

Commit b9c36c1

Browse files
jorwoodsjorwoods
authored
docs: docstrings for Pager and RequestOptions (#1498)
* docs: docstrings for filter tooling * docs: docstring for Sort --------- Co-authored-by: Jordan Woods <13803242+jorwoods@users.noreply.github.com>
1 parent e373cf4 commit b9c36c1

File tree

3 files changed

+161
-2
lines changed

3 files changed

+161
-2
lines changed

‎tableauserverclient/server/pager.py

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,30 @@ class Pager(Iterable[T]):
2727
(users in a group, views in a workbook, etc) by passing a different endpoint.
2828
2929
Will loop over anything that returns (list[ModelItem], PaginationItem).
30+
31+
Will make a copy of the `RequestOptions` object passed in so it can be reused.
32+
33+
Makes a call to the Server for each page of items, then yields each item in the list.
34+
35+
Parameters
36+
----------
37+
endpoint: CallableEndpoint[T] or Endpoint[T]
38+
The endpoint to call to get the items. Can be a callable or an Endpoint object.
39+
Expects a tuple of (list[T], PaginationItem) to be returned.
40+
41+
request_opts: RequestOptions, optional
42+
The request options to pass to the endpoint. If not provided, will use default RequestOptions.
43+
Filters, sorts, page size, starting page number, etc can be set here.
44+
45+
Yields
46+
------
47+
T
48+
The items returned from the endpoint.
49+
50+
Raises
51+
------
52+
ValueError
53+
If the endpoint is not a callable or an Endpoint object.
3054
"""
3155

3256
def __init__(

‎tableauserverclient/server/request_options.py

Lines changed: 123 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,28 @@ def apply_query_params(self, url):
3535

3636

3737
class RequestOptions(RequestOptionsBase):
38+
"""
39+
This class is used to manage the options that can be used when querying content on the server.
40+
Optionally initialize with a page number and page size to control the number of items returned.
41+
42+
Additionally, you can add sorting and filtering options to the request.
43+
44+
The `sort` and `filter` options are set-like objects, so you can only add a field once. If you add the same field
45+
multiple times, only the last one will be used.
46+
47+
The list of fields that can be sorted on or filtered by can be found in the `Field`
48+
class contained within this class.
49+
50+
Parameters
51+
----------
< 8000 /code>52+
pagenumber: int, optional
53+
The page number to start the query on. Default is 1.
54+
55+
pagesize: int, optional
56+
The number of items to return per page. Default is 100. Can also read
57+
from the environment variable `TSC_PAGE_SIZE`
58+
"""
59+
3860
def __init__(self, pagenumber=1, pagesize=None):
3961
self.pagenumber = pagenumber
4062
self.pagesize = pagesize or config.PAGE_SIZE
@@ -199,13 +221,43 @@ def get_query_params(self):
199221

200222
def vf(self, name: str, value: str) -> Self:
201223
"""Apply a filter based on a column within the view.
202-
Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'"""
224+
Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'
225+
226+
For more detail see: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views
227+
228+
Parameters
229+
----------
230+
name: str
231+
The name of the column to filter on
232+
233+
value: str
234+
The value to filter on
235+
236+
Returns
237+
-------
238+
Self
239+
The current object
240+
"""
203241
self.view_filters.append((name, value))
204242
return self
205243

206244
def parameter(self, name: str, value: str) -> Self:
207245
"""Apply a filter based on a parameter within the workbook.
208-
Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'"""
246+
Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'
247+
248+
Parameters
249+
----------
250+
name: str
251+
The name of the parameter to filter on
252+
253+
value: str
254+
The value to filter on
255+
256+
Returns
257+
-------
258+
Self
259+
The current object
260+
"""
209261
self.view_parameters.append((name, value))
210262
return self
211263

@@ -257,14 +309,60 @@ def get_query_params(self) -> dict:
257309

258310

259311
class CSVRequestOptions(_DataExportOptions):
312+
"""
313+
Options that can be used when exporting a view to CSV. Set the maxage to control the age of the data exported.
314+
Filters to the underlying data can be applied using the `vf` and `parameter` methods.
315+
316+
Parameters
317+
----------
318+
maxage: int, optional
319+
The maximum age of the data to export. Shortest possible duration is 1
320+
minute. No upper limit. Default is -1, which means no limit.
321+
"""
322+
260323
extension = "csv"
261324

262325

263326
class ExcelRequestOptions(_DataExportOptions):
327+
"""
328+
Options that can be used when exporting a view to Excel. Set the maxage to control the age of the data exported.
329+
Filters to the underlying data can be applied using the `vf` and `parameter` methods.
330+
331+
Parameters
332+
----------
333+
maxage: int, optional
334+
The maximum age of the data to export. Shortest possible duration is 1
335+
minute. No upper limit. Default is -1, which means no limit.
336+
"""
337+
264338
extension = "xlsx"
265339

266340

267341
class ImageRequestOptions(_ImagePDFCommonExportOptions):
342+
"""
343+
Options that can be used when exporting a view to an image. Set the maxage to control the age of the data exported.
344+
Filters to the underlying data can be applied using the `vf` and `parameter` methods.
345+
346+
Parameters
347+
----------
348+
imageresolution: str, optional
349+
The resolution of the image to export. Valid values are "high" or None. Default is None.
350+
Image width and actual pixel density are determined by the display context
351+
of the image. Aspect ratio is always preserved. Set the value to "high" to
352+
ensure maximum pixel density.
353+
354+
maxage: int, optional
355+
The maximum age of the data to export. Shortest possible duration is 1
356+
minute. No upper limit. Default is -1, which means no limit.
357+
358+
viz_height: int, optional
359+
The height of the viz in pixels. If specified, viz_width must also be specified.
360+
361+
viz_width: int, optional
362+
The width of the viz in pixels. If specified, viz_height must also be specified.
363+
364+
"""
365+
268366
extension = "png"
269367

270368
# if 'high' isn't specified, the REST API endpoint returns an image with standard resolution
@@ -283,6 +381,29 @@ def get_query_params(self):
283381

284382

285383
class PDFRequestOptions(_ImagePDFCommonExportOptions):
384+
"""
385+
Options that can be used when exporting a view to PDF. Set the maxage to control the age of the data exported.
386+
Filters to the underlying data can be applied using the `vf` and `parameter` methods.
387+
388+
Parameters
389+
----------
390+
page_type: str, optional
391+
The page type of the PDF to export. Valid values are accessible via the `PageType` class.
392+
393+
orientation: str, optional
394+
The orientation of the PDF to export. Valid values are accessible via the `Orientation` class.
395+
396+
maxage: int, optional
397+
The maximum age of the data to export. Shortest possible duration is 1
398+
minute. No upper limit. Default is -1, which means no limit.
399+
400+
viz_height: int, optional
401+
The height of the viz in pixels. If specified, viz_width must also be specified.
402+
403+
viz_width: int, optional
404+
The width of the viz in pixels. If specified, viz_height must also be specified.
405+
"""
406+
286407
class PageType:
287408
A3 = "a3"
288409
A4 = "a4"

‎tableauserverclient/server/sort.py

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
11
class Sort:
2+
"""
3+
Used with request options (RequestOptions) where you can filter and sort on
4+
the results returned from the server.
5+
6+
Parameters
7+
----------
8+
field : str
9+
Sets the field to sort on. The fields are defined in the RequestOption class.
10+
11+
direction : str
12+
The direction to sort, either ascending (Asc) or descending (Desc). The
13+
options are defined in the RequestOptions.Direction class.
14+
"""
15+
216
def __init__(self, field, direction):
317
self.field = field
418
self.direction = direction

0 commit comments

Comments
 (0)
0