8000 docs: docstrings for custom_views · tableau/server-client-python@62f46c9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 62f46c9

Browse files
jorwoodsjorwoods
committed
docs: docstrings for custom_views
Also adds support for using view_id, workbook_id and owner_id to filter custom_views returned by the REST API
1 parent 3460528 commit 62f46c9

File tree

3 files changed

+248
-17
lines changed

3 files changed

+248
-17
lines changed

‎tableauserverclient/models/custom_view_item.py

Lines changed: 48 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,57 @@
55
from typing import Callable, Optional
66
from collections.abc import Iterator
77

8-
from .exceptions import UnpopulatedPropertyError
9-
from .user_item import UserItem
10-
from .view_item import ViewItem
11-
from .workbook_item import WorkbookItem
12-< 8000 /span>
from ..datetime_helpers import parse_datetime
8+
from tableauserverclient.models.exceptions import UnpopulatedPropertyError
9+
from tableauserverclient.models.user_item import UserItem
10+
from tableauserverclient.models.view_item import ViewItem
11+
from tableauserverclient.models.workbook_item import WorkbookItem
12+
from tableauserverclient.datetime_helpers import parse_datetime
1313

1414

1515
class CustomViewItem:
16+
"""
17+
Represents a Custom View item on Tableau Server.
18+
19+
Parameters
20+
----------
21+
id : Optional[str]
22+
The ID of the Custom View item.
23+
24+
name : Optional[str]
25+
The name of the Custom View item.
26+
27+
Attributes
28+
----------
29+
content_url : Optional[str]
30+
The content URL of the Custom View item.
31+
32+
created_at : Optional[datetime]
33+
The date and time the Custom View item was created.
34+
35+
image: bytes
36+
The image of the Custom View item. Must be populated first.
37+
38+
pdf: bytes
39+
The PDF of the Custom View item. Must be populated first.
40+
41+
csv: Iterator[bytes]
42+
The CSV of the Custom View item. Must be populated first.
43+
44+
shared : Optional[bool]
45+
Whether the Custom View item is shared.
46+
47+
updated_at : Optional[datetime]
48+
The date and time the Custom View item was last updated.
49+
50+
owner : Optional[UserItem]
51+
The id of the owner of the Custom View item.
52+
53+
workbook : Optional[WorkbookItem]
54+
The id of the workbook the Custom View item belongs to.
55+
56+
view : Optional[ViewItem]
57+
The id of the view the Custom View item belongs to.
58+
"""
1659
def __init__(self, id: Optional[str] = None, name: Optional[str] = None) -> None:
1760
self._content_url: Optional[str] = None # ?
1861
self._created_at: Optional["datetime"] = None

‎tableauserverclient/server/endpoint/custom_views_endpoint.py

Lines changed: 197 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import os
44
from contextlib import closing
55
from pathlib import Path
6-
from typing import Optional, Union
6+
from typing import Optional, Union, TYPE_CHECKING
77
from collections.abc import Iterator
88

99
from tableauserverclient.config import BYTES_PER_MB, config
@@ -21,6 +21,9 @@
2121

2222
from tableauserverclient.helpers.logging import logger
2323

24+
if TYPE_CHECKING:
25+
from tableauserverclient.server.query import QuerySet
26+
2427
"""
2528
Get a list of custom views on a site
2629
get the details of a custom view
@@ -51,19 +54,31 @@ def baseurl(self) -> str:
5154
def expurl(self) -> str:
5255
return f"{self.parent_srv._server_address}/api/exp/sites/{self.parent_srv.site_id}/customviews"
5356

54-
"""
55-
If the request has no filter parameters: Administrators will see all custom views.
56-
Other users will see only custom views that they own.
57-
If the filter parameters include ownerId: Users will see only custom views that they own.
58-
If the filter parameters include viewId and/or workbookId, and don't include ownerId:
59-
Users will see those custom views that they have Write and WebAuthoring permissions for.
60-
If site user visibility is not set to Limited, the Users will see those custom views that are "public",
61-
meaning the value of their shared attribute is true.
62-
If site user visibility is set to Limited, ????
63-
"""
64-
6557
@api(version="3.18")
6658
def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[CustomViewItem], PaginationItem]:
59+
"""
60+
Get a list of custom views on a site.
61+
62+
If the request has no filter parameters: Administrators will see all custom views.
63+
Other users will see only custom views that they own.
64+
If the filter parameters include ownerId: Users will see only custom views that they own.
65+
If the filter parameters include viewId and/or workbookId, and don't include ownerId:
66+
Users will see those custom views that they have Write and WebAuthoring permissions for.
67+
If site user visibility is not set to Limited, the Users will see those custom views that are "public",
68+
meaning the value of their shared attribute is true.
69+
If site user visibility is set to Limited, ????
70+
71+
Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#list_custom_views
72+
73+
Parameters
74+
----------
75+
req_options : RequestOptions, optional
76+
Filtering options for the request, by default None
77+
78+
Returns
79+
-------
80+
tuple[list[CustomViewItem], PaginationItem]
81+
"""
6782
logger.info("Querying all custom views on site")
6883
url = self.baseurl
6984
server_response = self.get_request(url, req_options)
@@ -73,6 +88,19 @@ def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[Cust
7388

7489
@api(version="3.18")
7590
def get_by_id(self, view_id: str) -> Optional[CustomViewItem]:
91+
"""
92+
Get the details of a specific custom view.
93+
94+
Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#get_custom_view
95+
96+
Parameters
97+
----------
98+
view_id : str
99+
100+
Returns
101+
-------
102+
Optional[CustomViewItem]
103+
"""
76104
if not view_id:
77105
error = "Custom view item missing ID."
78106
raise MissingRequiredFieldError(error)
@@ -83,6 +111,27 @@ def get_by_id(self, view_id: str) -> Optional[CustomViewItem]:
83111

84112
@api(version="3.18")
85113
def populate_image(self, view_item: CustomViewItem, req_options: Optional["ImageRequestOptions"] = None) -> None:
114+
"""
115+
Populate the image of a custom view.
116+
117+
Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#get_custom_view_image
118+
119+
Parameters
120+
----------
121+
view_item : CustomViewItem
122+
123+
req_options : ImageRequestOptions, optional
124+
Options to customize the image returned, by default None
125+
126+
Returns
127+
-------
128+
None
129+
130+
Raises
131+
------
132+
MissingRequiredFieldError
133+
If the view_item is missing an ID
134+
"""
86135
if not view_item.id:
87136
error = "Custom View item missing ID."
88137
raise MissingRequiredFieldError(error)
@@ -101,6 +150,26 @@ def _get_view_image(self, view_item: CustomViewItem, req_options: Optional["Imag
101150

102151
@api(version="3.23")
103152
def populate_pdf(self, custom_view_item: CustomViewItem, req_options: Optional["PDFRequestOptions"] = None) -> None:
153+
"""
154+
Populate the PDF of a custom view.
155+
156+
Parameters
157+
----------
158+
custom_view_item : CustomViewItem
159+
The custom view item to populate the PDF for.
160+
161+
req_options : PDFRequestOptions, optional
162+
Options to customize the PDF returned, by default None
163+
164+
Returns
165+
-------
166+
None
167+
168+
Raises
169+
------
170+
MissingRequiredFieldError
171+
If the custom view item is missing an ID
172+
"""
104173
if not custom_view_item.id:
105174
error = "Custom View item missing ID."
106175
raise MissingRequiredFieldError(error)
@@ -121,6 +190,26 @@ def _get_custom_view_pdf(
121190

122191
@api(version="3.23")
123192
def populate_csv(self, custom_view_item: CustomViewItem, req_options: Optional["CSVRequestOptions"] = None) -> None:
193+
"""
194+
Populate the CSV of a custom view.
195+
196+
Parameters
197+
----------
198+
custom_view_item : CustomViewItem
199+
The custom view item to populate the CSV for.
200+
201+
req_options : CSVRequestOptions, optional
202+
Options to customize the CSV returned, by default None
203+
204+
Returns
205+
-------
206+
None
207+
208+
Raises
209+
------
210+
MissingRequiredFieldError
211+
If the custom view item is missing an ID
212+
"""
124213
if not custom_view_item.id:
125214
error = "Custom View item missing ID."
126215
raise MissingRequiredFieldError(error)
@@ -141,6 +230,21 @@ def _get_custom_view_csv(
141230

142231
@api(version="3.18")
143232
def update(self, view_item: CustomViewItem) -> Optional[CustomViewItem]:
233+
"""
234+
Updates the name, owner, or shared status of a custom view.
235+
236+
Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#update_custom_view
237+
238+
Parameters
239+
----------
240+
view_item : CustomViewItem
241+
The custom view item to update.
242+
243+
Returns
244+
-------
245+
Optional[CustomViewItem]
246+
The updated custom view item.
247+
"""
144248
if not view_item.id:
145249
error = "Custom view item missing ID."
146250
raise MissingRequiredFieldError(error)
@@ -158,6 +262,25 @@ def update(self, view_item: CustomViewItem) -> Optional[CustomViewItem]:
158262
# Delete 1 view by id
159263
@api(version="3.19")
160264
def delete(self, view_id: str) -> None:
265+
"""
266+
Deletes a single custom view by ID.
267+
268+
Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#delete_custom_view
269+
270+
Parameters
271+
----------
272+
view_id : str
273+
The ID of the custom view to delete.
274+
275+
Returns
276+
-------
277+
None
278+
279+
Raises
280+
------
281+
ValueError
282+
If the view_id is not provided.
283+
"""
161284
if not view_id:
162285
error = "Custom View ID undefined."
163286
raise ValueError(error)
@@ -167,6 +290,27 @@ def delete(self, view_id: str) -> None:
167290

168291
@api(version="3.21")
169292
def download(self, view_item: CustomViewItem, file: PathOrFileW) -> PathOrFileW:
293+
"""
294+
Download the definition of a custom view as json. The file parameter can
295+
be a file path or a file object. If a file path is provided, the file
296+
will be written to that location. If a file object is provided, the file
297+
will be written to that object.
298+
299+
May contain sensitive information.
300+
301+
Parameters
302+
----------
303+
view_item : CustomViewItem
304+
The custom view item to download.
305+
306+
file : PathOrFileW
307+
The file path or file object to write the custom view to.
308+
309+
Returns
310+
-------
311+
PathOrFileW
312+
The file path or file object that the custom view was written to.
313+
"""
170314
url = f"{self.expurl}/{view_item.id}/content"
171315
server_response = self.get_request(url)
172316
if isinstance(file, io_types_w):
@@ -180,6 +324,25 @@ def download(self, view_item: CustomViewItem, file: PathOrFileW) -> PathOrFileW:
180324

181325
@api(version="3.21")
182326
def publish(self, view_item: CustomViewItem, file: PathOrFileR) -> Optional[CustomViewItem]:
327+
"""
328+
Publish a custom view to Tableau Server. The file parameter can be a
329+
file path or a file object. If a file path is provided, the file will be
330+
read from that location. If a file object is provided, the file will be
331+
read from that object.
332+
333+
Parameters
334+
----------
335+
view_item : CustomViewItem
336+
The custom view item to publish.
337+
338+
file : PathOrFileR
339+
The file path or file object to read the custom view from.
340+
341+
Returns
342+
-------
343+
Optional[CustomViewItem]
344+
The published custom view item.
345+
"""
183346
url = self.expurl
184347
if isinstance(file, io_types_r):
185348
size = get_file_object_size(file)
@@ -207,3 +370,25 @@ def publish(self, view_item: CustomViewItem, file: PathOrFileR) -> Optional[Cust
207370

208371
server_response = self.post_request(url, xml_request, content_type)
209372
return CustomViewItem.from_response(server_response.content, self.parent_srv.namespace)
373+
374+
def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> "QuerySet[CustomViewItem]":
375+
"""
376+
Queries the Tableau Server for items using the specified filters. Page
377+
size can be specified to limit the number of items returned in a single
378+
request. If not specified, the default page size is 100. Page size can
379+
be an integer between 1 and 1000.
380+
381+
No positional arguments are allowed. All filters must be specified as
382+
keyword arguments. If you use the equality operator, you can specify it
383+
through <field_name>=<value>. If you want to use a different operator,
384+
you can specify it through <field_name>__<operator>=<value>. Field
385+
names can either be in snake_case or camelCase.
386+
387+
This endpoint supports the following fields and operators:
388+
389+
view_id=...
390+
workbook_id=...
391+
owner_id=...
392+
"""
393+
394+
return super().filter(*invalid, page_size=page_size, **kwargs)

‎tableauserverclient/server/request_options.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ class Field:
122122
NotificationType = "notificationType"
123123
OwnerDomain = "ownerDomain"
124124
OwnerEmail = "ownerEmail"
125+
OwnerId = "ownerId"
125126
OwnerName = "ownerName"
126127
ParentProjectId = "parentProjectId"
127128
Priority = "priority"
@@ -148,8 +149,10 @@ class Field:
148149
UpdatedAt = "updatedAt"
149150
UserCount = "userCount"
150151
UserId = "userId"
152+
ViewId = "viewId"
151153
ViewUrlName = "viewUrlName"
152154
WorkbookDescription = "workbookDescription"
155+
WorkbookId = "workbookId"
153156
WorkbookName = "workbookName"
154157

155158
class Direction:

0 commit comments

Comments
 (0)
0