From 3dd76da317f2c78d9ebb32db74b367ae0d982672 Mon Sep 17 00:00:00 2001 From: Chris Shin Date: Fri, 26 Jun 2020 14:33:57 -0700 Subject: [PATCH 1/3] Update docs with maxage info Docs for #635 and #639 --- docs/api-ref.md | 82 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 70 insertions(+), 12 deletions(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index b571905fc..3ad7a82ed 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -1595,9 +1595,15 @@ Name | Description ### CSVRequestOptions class ```py -CSVRequestOptions() +CSVRequestOptions(maxage=-1) ``` -Use this class to specify view filters to be applied when the CSV data is generated. See `views.populate_csv`. +Use this class to specify view filters to be applied when the CSV data is generated. This class can also be used to specify the maxage of the cached CSV data on server. See `views.populate_csv`. + +**Attributes** + +Name | Description +:--- | :--- +`maxage` | The maximum number of minutes the CSV data will be cached on server before being refreshed. 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 default server behavior. **Example** @@ -1607,7 +1613,7 @@ Use this class to specify view filters to be applied when the CSV data is genera # sign in, get a specific view, etc. # set view filters -csv_req_option = TSC.CSVRequestOptions() +csv_req_option = TSC.CSVRequestOptions(maxage=5) csv_req_option.vf('Region', 'South') csv_req_option.vf('Category', 'Furniture') @@ -1618,15 +1624,16 @@ server.views.populate_csv(view_item, csv_req_option) ### ImageRequestOptions class ```py -ImageRequestOptions(imageresolution=None) +ImageRequestOptions(imageresolution=None, maxage=-1) ``` -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`. +Use this class to specify the resolution of the view or the maxage of the cached image on server. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`. **Attributes** Name | Description :--- | :--- `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. +`maxage` | The maximum number of minutes the image will be cached on server before being refreshed. 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 default server behavior. **View Filters** @@ -1640,7 +1647,7 @@ You can use the `vf('filter_name', 'filter_value')` method to add view filters. # sign in, get a specific view, etc. # set the image request option -image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High) +image_req_option = TSC.ImageRequestOptions(imageresolution=TSC.ImageRequestOptions.Resolution.High, maxage=1) # (optional) set a view filter image_req_option.vf('Category', 'Furniture') @@ -1653,9 +1660,9 @@ server.views.populate_image(view_item, image_req_option) ### PDFRequestOptions class ```py -PDFRequestOptions(page_type=None, orientation=None) +PDFRequestOptions(page_type=None, orientation=None, maxage=-1) ``` -Use this class to specify the format of the PDF that is returned for the view. See `views.populate_pdf`. +Use this class to specify the format of the PDF that is returned for the view. This class can also be used to specify the maxage of the cached PDF render on server. See `views.populate_pdf`. **Attributes** @@ -1663,6 +1670,7 @@ Name | Description :--- | :--- `page_type` | The type of page returned in PDF format for the view. The page_type is set using the `PageType` class:
`PageType.A3`
`PageType.A4`
`PageType.A5`
`PageType.B5`
`PageType.Executive`
`PageType.Folio`
`PageType.Ledger`
`PageType.Legal`
`PageType.Letter`
`PageType.Note`
`PageType.Quarto`
`PageType.Tabloid` `orientation` | The orientation of the page. The options are portrait and landscape. The options are set using the `Orientation` class:
`Orientation.Portrait`
`Orientation.Landscape` +`maxage` | The maximum number of minutes the PDF render will be cached on server before being refreshed. 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 default server behavior. **View Filters** 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. # sign in, get a specific view, etc. # set the PDF request options -pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4, orientation=TSC.PDFRequestOptions.Orientation.Landscape) +pdf_req_option = TSC.PDFRequestOptions(page_type=TSC.PDFRequestOptions.PageType.A4, + orientation=TSC.PDFRequestOptions.Orientation.Landscape, + maxage=1) # (optional) set a view filter pdf_req_option.vf('Region', 'West') @@ -3259,7 +3269,7 @@ This endpoint is available with REST API version 2.5 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`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. +`req_options` | (Optional) You can pass in request options to specify the image resolution and the maxage of the cached view image on server. By default, the image will be in low resolution and cached for 240 minutes. You can also specify view filters to be applied when the image is generated. See [ImageRequestOptions class](#imagerequestoptions-class) for more details. **Exceptions** @@ -3306,7 +3316,7 @@ This endpoint is available with REST API version 2.7 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`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. +`req_options` | (Optional) You can pass in a request object to specify view filters to be applied when the CSV data is generated. You can also specify the maxage of the cached view data on server, which is cached for 240 minutes by default. See [CSVRequestOptions class](#csvrequestoptions-class) for more details. **Exceptions** @@ -3354,7 +3364,7 @@ This endpoint is available with REST API version 2.7 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`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. +`req_options` | (Optional) You can pass in a request object to specify the page type and orientation of the PDF content, as well as the maxage of the cached PDF render on server. If not specified, PDF content will have default page type and orientation, and will be cached for 240 minutes. You can also specify view filters to be applied when the PDF is generated. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details. **Exceptions** @@ -3995,6 +4005,9 @@ None. The preview image is added to the view. ``` +
+
+ #### workbooks.update_connection ```py @@ -4042,4 +4055,49 @@ server.workbooks.update_conn(workbook, connection)

+#### workbooks.populate_pdf +``` +workbooks.populate_pdf(workbook_item, req_options=None) +``` + +Populates the PDF content of the specified workbook. + +This method uses the `id` field to query the PDF content, and populates the content as the `pdf` field. + +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"} + +**Version** + +This endpoint is available with REST API version 3.4 and up. + +**Parameters** + +Name | description +:--- | :--- +`workbook_item` | Specifies the workbook to populate. +`req_options` | (Optional) You can pass in a request object to specify the page type and orientation of the PDF content, as well as the maxage of the cached PDF render on server. If not specified, PDF content will have default page type and orientation, and will be cached for 240 minutes. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details. + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook item missing ID` | Raises an error if the ID of the workbook is missing. + +**Returns** + +None. The PDF content is added to the `workbook_item` and can be accessed by its `pdf` field. + +**Example** +```py +# Sign in, get view, etc. + +# Populate and save the workbook pdf as 'workbook_pdf.pdf' +server.workbooks.populate_pdf(workbook_item) +with open('./workbook_pdf.pdf', 'wb') as f: + f.write(workbook_item.pdf) +``` + +
+
+ From 1375c7e60ea98ec802dd8184f8e7512ad2558d15 Mon Sep 17 00:00:00 2001 From: Chris Shin Date: Mon, 29 Jun 2020 13:51:51 -0700 Subject: [PATCH 2/3] Addresses feedback for request options part of docs --- docs/api-ref.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index 3ad7a82ed..50d395711 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -1597,13 +1597,13 @@ Name | Description ```py CSVRequestOptions(maxage=-1) ``` -Use this class to specify view filters to be applied when the CSV data is generated. This class can also be used to specify the maxage of the cached CSV data on server. See `views.populate_csv`. +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`. **Attributes** Name | Description :--- | :--- -`maxage` | The maximum number of minutes the CSV data will be cached on server before being refreshed. 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 default server behavior. +`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. **Example** @@ -1626,14 +1626,14 @@ server.views.populate_csv(view_item, csv_req_option) ```py ImageRequestOptions(imageresolution=None, maxage=-1) ``` -Use this class to specify the resolution of the view or the maxage of the cached image on server. You can also use this class to specify view filters to be applied when the image is generated. See `views.populate_image`. +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`. **Attributes** Name | Description :--- | :--- `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. -`maxage` | The maximum number of minutes the image will be cached on server before being refreshed. 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 default server behavior. +`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. **View Filters** @@ -1662,7 +1662,7 @@ server.views.populate_image(view_item, image_req_option) ```py PDFRequestOptions(page_type=None, orientation=None, maxage=-1) ``` -Use this class to specify the format of the PDF that is returned for the view. This class can also be used to specify the maxage of the cached PDF render on server. See `views.populate_pdf`. +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`. **Attributes** @@ -1670,7 +1670,7 @@ Name | Description :--- | :--- `page_type` | The type of page returned in PDF format for the view. The page_type is set using the `PageType` class:
`PageType.A3`
`PageType.A4`
`PageType.A5`
`PageType.B5`
`PageType.Executive`
`PageType.Folio`
`PageType.Ledger`
`PageType.Legal`
`PageType.Letter`
`PageType.Note`
`PageType.Quarto`
`PageType.Tabloid` `orientation` | The orientation of the page. The options are portrait and landscape. The options are set using the `Orientation` class:
`Orientation.Portrait`
`Orientation.Landscape` -`maxage` | The maximum number of minutes the PDF render will be cached on server before being refreshed. 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 default server behavior. +`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. **View Filters** 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. From d36bec9fcc841566076b5b37dff0bd0988c6fb42 Mon Sep 17 00:00:00 2001 From: Chris Shin Date: Mon, 29 Jun 2020 14:17:09 -0700 Subject: [PATCH 3/3] Addresses remaining feedback to view and workbook methods --- docs/api-ref.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index 50d395711..51e4b4e26 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -3269,7 +3269,7 @@ This endpoint is available with REST API version 2.5 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`req_options` | (Optional) You can pass in request options to specify the image resolution and the maxage of the cached view image on server. By default, the image will be in low resolution and cached for 240 minutes. You can also specify view filters to be applied when the image is generated. See [ImageRequestOptions class](#imagerequestoptions-class) for more details. +`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. **Exceptions** @@ -3316,7 +3316,7 @@ This endpoint is available with REST API version 2.7 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`req_options` | (Optional) You can pass in a request object to specify view filters to be applied when the CSV data is generated. You can also specify the maxage of the cached view data on server, which is cached for 240 minutes by default. See [CSVRequestOptions class](#csvrequestoptions-class) for more details. +`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. **Exceptions** @@ -3351,7 +3351,7 @@ views.populate_pdf(view_item, req_options=None) Populates the PDF content of the specified view. -This method uses the `id` field to query the PDF content, and populates the content as the `pdf` field. +This method populates a PDF with image(s) of the view you specify. 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"} @@ -3364,7 +3364,7 @@ This endpoint is available with REST API version 2.7 and up. Name | description :--- | :--- `view_item` | Specifies the view to populate. -`req_options` | (Optional) You can pass in a request object to specify the page type and orientation of the PDF content, as well as the maxage of the cached PDF render on server. If not specified, PDF content will have default page type and orientation, and will be cached for 240 minutes. You can also specify view filters to be applied when the PDF is generated. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details. +`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. **Exceptions** @@ -4062,7 +4062,7 @@ workbooks.populate_pdf(workbook_item, req_options=None) Populates the PDF content of the specified workbook. -This method uses the `id` field to query the PDF content, and populates the content as the `pdf` field. +This method populates a PDF with image(s) of the workbook view(s) you specify. 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"} @@ -4075,7 +4075,7 @@ This endpoint is available with REST API version 3.4 and up. Name | description :--- | :--- `workbook_item` | Specifies the workbook to populate. -`req_options` | (Optional) You can pass in a request object to specify the page type and orientation of the PDF content, as well as the maxage of the cached PDF render on server. If not specified, PDF content will have default page type and orientation, and will be cached for 240 minutes. See [PDFRequestOptions class](#pdfrequestoptions-class) for more details. +`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. **Exceptions**