8000 Update docs with maxage info (#640) · tableau/server-client-python@585a622 · GitHub
[go: up one dir, main page]
Skip to content

Commit 585a622

Browse files
author
Chris Shin
authored
Update docs with maxage info (#640)
* Update docs with maxage info Docs for #635 and #639 * Addresses feedback for request options part of docs * Addresses remaining feedback to view and workbook methods
1 parent 7dec872 commit 585a622

File tree

1 file changed

+71
-13
lines changed

1 file changed

+71
-13
lines changed

‎docs/api-ref.md

Lines changed: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1595,9 +1595,15 @@ Name | Description
15951595
### CSVRequestOptions class
15961596

15971597
```py
1598-
CSVRequestOptions()
1598+
CSVRequestOptions(maxage=-1)
15991599
```
1600-
Use this class to specify view filters to be applied when the CSV data is generated. See `views.populate_csv`.
1600+
Use this class to specify view filters to be applied when the CSV data is generated. Optionally, you can specify the maximum age of the CSV data cached on the server by providing a `maxage` value. See `views.populate_csv`.
1601+
1602+
**Attributes**
1603+
1604+
Name | Description
1605+
:--- | :---
1606+
`maxage` | Optional. The maximum number of minutes the CSV data will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
16011607

16021608
**Example**
16031609

@@ -1607,7 +1613,7 @@ Use this class to specify view filters to be applied when the CSV data is genera
16071613
# sign in, get a specific view, etc.
16081614

16091615
# set view filters
1610-
csv_req_option = TSC.CSVRequestOptions()
1616+
csv_req_option = TSC.CSVRequestOptions(maxage=5)
16111617
csv_req_option.vf('Region', 'South')
16121618
csv_req_option.vf('Category', 'Furniture')
16131619

@@ -1618,15 +1624,16 @@ server.views.populate_csv(view_item, csv_req_option)
16181624
### ImageRequestOptions class
16191625

16201626
```py
1621-
ImageRequestOptions(imageresolution=None)
1627+
ImageRequestOptions(imageresolution=None, maxage=-1)
16221628
```
1623-
Use this class to specify the resolution of the view returned as an image. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`.
1629+
Use this class to specify the resolution of the view and, optionally, the maximum age of the image cached on the server. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`.
16241630

16251631
**Attributes**
16261632

16271633
Name | Description
16281634
:--- | :---
16291635
`imageresolution` | The resolution of the view returned as an image. You set this option with the `Resolution` class. If unspecified, the `views.populate_image` method returns an image with standard resolution (the width of the returned image is 784 pixels). If you set this parameter value to high (`Resolution.High`), the width of the returned image is 1568 pixels. For both resolutions, the height varies to preserve the aspect ratio of the view.
1636+
`maxage` | Optional. The maximum number of minutes the image will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
16301637

16311638
**View Filters**
16321639

@@ -1640,7 +1647,7 @@ You can use the `vf('filter_name', 'filter_value')` method to add view filters.
16401647
# sign in, get a specific view, etc.
16411648

16421649
# set the image request option
1643-
image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High)
1650+
image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High, maxage=1)
16441651

16451652
# (optional) set a view filter
16461653
image_req_option.vf('Category', 'Furniture')
@@ -1653,16 +1660,17 @@ server.views.populate_image(view_item, image_req_option)
16531660
### PDFRequestOptions class
16541661

16551662
```py
1656-
PDFRequestOptions(page_type=None, orientation=None)
1663+
PDFRequestOptions(page_type=None, orientation=None, maxage=-1)
16571664
```
1658-
Use this class to specify the format of the PDF that is returned for the view. See `views.populate_pdf`.
1665+
Use this class to specify the format of the PDF that is returned for the view. Optionally, you can specify the maximum age of the rendered PDF that is cached on the server by providing a `maxage` value. See `views.populate_pdf`.
16591666

16601667
**Attributes**
16611668

16621669
Name | Description
16631670
:--- | :---
16641671
`page_type` | The type of page returned in PDF format for the view. The page_type is set using the `PageType` class: <br> `PageType.A3`<br> `PageType.A4`<br> `PageType.A5`<br> `PageType.B5`<br> `PageType.Executive`<br> `PageType.Folio`<br> `PageType.Ledger`<br> `PageType.Legal`<br> `PageType.Letter`<br> `PageType.Note`<br> `PageType.Quarto`<br> `PageType.Tabloid`
16651672
`orientation` | The orientation of the page. The options are portrait and landscape. The options are set using the `Orientation` class: <br>`Orientation.Portrait`<br> `Orientation.Landscape`
1673+
`maxage` | Optional. The maximum number of minutes the rendered PDF will be cached on the server before being refreshed. The value must be an integer between `1` and `240` minutes. `0` will be interpreted as 1 minute on server, as that is the shortest interval allowed. By default, `maxage` is set to `-1`, indicating the default behavior configured in server settings.
16661674

16671675
**View Filters**
16681676
You can use the `vf('filter_name', 'filter_value')` method to add view filters. When the PDF is generated, the specified filters will be applied to the view.
@@ -1675,7 +1683,9 @@ You can use the `vf('filter_name', 'filter_value')` method to add view filters.
16751683
# sign in, get a specific view, etc.
16761684

16771685
# set the PDF request options
1678-
pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4, orientation=TSC.PDFRequestOptions.Orientation.Landscape)
1686+
pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4,
1687+
orientation=TSC.PDFRequestOptions.Orientation.Landscape,
1688+
maxage=1)
16791689

16801690
# (optional) set a view filter
16811691
pdf_req_option.vf('Region', 'West')
@@ -3259,7 +3269,7 @@ This endpoint is available with REST API version 2.5 and up.
32593269
Name | description
32603270
:--- | :---
32613271
`view_item` | Specifies the view to populate.
3262-
`req_options` | (Optional) You can pass in a request object to specify a high resolution image. By default, the image will be in low resolution. You can also specify view filters to be applied when the image is generated. See [ImageRequestOptions class](#imagerequestoptions-class) for more details.
3272+
`req_options` | (Optional) You can pass in request options to specify the image resolution and the maximum age of the view image cached on the server. By default, the image will be in low resolution. The maximum image cache time is the value of `maxage` in minutes, and must be an integer between 1 and 240. A value of zero will cause the minimum cache time of 1 minute. A value of -1 will cache images for the time configured in server settings. You can also specify view filters to be applied when the image is generated. See [ImageRequestOptions class](#imagerequestoptions-class) for more details.
32633273

32643274
**Exceptions**
32653275

@@ -3306,7 +3316,7 @@ This endpoint is available with REST API version 2.7 and up.
33063316
Name | description
33073317
:--- | :---
33083318
`view_item` | Specifies the view to populate.
3309-
`req_options` | (Optional) You can pass in a request object to specify view filters to be applied when the CSV data is generated. See [CSVRequestOptions class](#csvrequestoptions-class) for more details.
3319+
`req_options` | (Optional) You can pass in request options to specify the maximum age of the CSV cached on the server. The maximum CSV cache time is the value of `maxage` in minutes, and must be an integer between 1 and 240. A value of zero will cause the minimum cache time of 1 minute. A value of -1 will cache CSV files for the time configured in server settings. You can also specify view filters to be applied when the data is generated. See [CSVRequestOptions class](#csvrequestoptions-class) for more details.
33103320

33113321
**Exceptions**
33123322

@@ -3341,7 +3351,7 @@ views.populate_pdf(view_item, req_options=None)
33413351

33423352
Populates the PDF content of the specified view.
33433353

3344-
This method uses the `id` field to query the PDF content, and populates the content as the `pdf` field.
3354+
This method populates a PDF with image(s) of the view you specify.
33453355

33463356
REST API: [Query View PDF](https://onlinehelp.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_view_pdf){:target="_blank"}
33473357

@@ -3354,7 +3364,7 @@ This endpoint is available with REST API version 2.7 and up.
33543364
Name | description
33553365
:--- | :---
33563366
`view_item` | Specifies the view to populate.
3357-
`req_options` | (Optional) You can pass in a request object to specify the page type and orientation of the PDF content. If not specified, PDF content will have default page type and orientation. You can also specify view filters to be applied when the PDF is generated. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details.
3367+
`req_options` | (Optional) You can pass in request options to specify the page type and orientation of the PDF content, as well as the maximum age of the PDF rendered on the server. If not specified, PDF content will have default page type and orientation. The maximum PDF cache time is the value of `maxage` in minutes, and must be an integer between 1 and 240. A value of zero will cause the minimum cache time of 1 minute. A value of -1 will cache PDF files for the time configured in server settings. You can also specify view filters to be applied when the PDF is generated. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details.
33583368

33593369
**Exceptions**
33603370

@@ -3995,6 +4005,9 @@ None. The preview image is added to the view.
39954005

39964006
```
39974007

4008+
<br>
4009+
<br>
4010+
39984011
#### workbooks.update_connection
39994012

40004013
```py
@@ -4042,4 +4055,49 @@ server.workbooks.update_conn(workbook, connection)
40424055
<br>
40434056
<br>
40444057

4058+
#### workbooks.populate_pdf
4059+
```
4060+
workbooks.populate_pdf(workbook_item, req_options=None)
4061+
```
4062+
4063+
Populates the PDF content of the specified workbook.
4064+
4065+
This method populates a PDF with image(s) of the workbook view(s) you specify.
4066+
4067+
REST API: [Download Workbook PDF](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooksviews.htm#download_workbook_pdf){:target="_blank"}
4068+
4069+
**Version**
4070+
4071+
This endpoint is available with REST API version 3.4 and up.
4072+
4073+
**Parameters**
4074+
4075+
Name | description
4076+
:--- | :---
4077+
`workbook_item` | Specifies the workbook to populate.
4078+
`req_options` | (Optional) You can pass in request options to specify the page type and orientation of the PDF content, as well as the maximum age of the PDF rendered on the server. If not specified, PDF content will have default page type and orientation. The maximum PDF cache time is the value of `maxage` in minutes, and must be an integer between 1 and 240. A value of zero will cause the minimum cache time of 1 minute. A value of -1 will cache PDF files for the time configured in server settings. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details.
4079+
4080+
**Exceptions**
4081+
4082+
Error | Description
4083+
:--- | :---
4084+
`Workbook item missing ID` | Raises an error if the ID of the workbook is missing.
4085+
4086+
**Returns**
4087+
4088+
None. The PDF content is added to the `workbook_item` and can be accessed by its `pdf` field.
4089+
4090+
**Example**
4091+
```py
4092+
# Sign in, get view, etc.
4093+
4094+
# Populate and save the workbook pdf as 'workbook_pdf.pdf'
4095+
server.workbooks.populate_pdf(workbook_item)
4096+
with open('./workbook_pdf.pdf', 'wb') as f:
4097+
f.write(workbook_item.pdf)
4098+
```
4099+
4100+
<br>
4101+
<br>
4102+
40454103

0 commit comments

Comments
 (0)
0