8000 tech review fixes, removed groups.get_by_id from examples, fixed data… · tableau/server-client-python@70fa4a0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 70fa4a0

Browse files
d45d45
committed
tech review fixes, removed groups.get_by_id from examples, fixed datasource update example
1 parent 3f8df49 commit 70fa4a0

File tree

1 file changed

+43
-38
lines changed

1 file changed

+43
-38
lines changed

‎docs/docs/api-ref.md

Lines changed: 43 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The TSC API reference is organized by resource. The TSC library is modeled after
2828

2929
## Authentication
3030

31-
You can use the TSC library to manage authentication, so you can sign in and sign out of Tableau Server and Tableau Online. The authentication resources for Tableau Server are defined in the `TableauAuth` class and they correspond to the authentication attributes you can access using the Tableau Server REST API.
31+
You can use the TSC library to sign in and sign out of Tableau Server and Tableau Online. The credentials for signing in are defined in the `TableauAuth` class and they correspond to the attributes you specify when you sign in using the Tableau Server REST API.
3232

3333
<br>
3434
<br>
@@ -38,7 +38,7 @@ You can use the TSC library to manage authentication, so you can sign in and sig
3838
```py
3939
TableauAuth(username, password, site_id='', user_id_to_impersonate=None)
4040
```
41-
The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method.
41+
The `TableauAuth` class defines the information you can set in a sign-in request. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method.
4242

4343

4444
**Note:** In the future, there might be support for additional forms of authorization and authentication (for example, OAuth).
@@ -63,7 +63,7 @@ import tableauserverclient as TSC
6363
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
6464

6565
# create a server instance
66-
# pass the "tableau_auth" request object to server.auth.sign_in()
66+
# pass the "tableau_auth" object to the server.auth.sign_in() method
6767
```
6868

6969
<br>
@@ -87,7 +87,7 @@ auth.sign_in(auth_req)
8787
Signs you in to Tableau Server.
8888

8989

90-
The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see [Server](#server). The authentication token keeps you signed in for 240 minutes, or until you call the `auth.sign_out` method. Before you use this method, you first need to create the sign-in request (`auth_req`) by creating an instance of the `TableauAuth`. To call this method, create a server object for your server. For more information, see [Sign in and Out](sign-in-out).
90+
The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see [Server](#server). The authentication token keeps you signed in for 240 minutes, or until you call the `auth.sign_out` method. Before you use this method, you first need to create the sign-in request (`auth_req`) object by creating an instance of the `TableauAuth`. To call this method, create a server object for your server. For more information, see [Sign in and Out](sign-in-out).
9191

9292
REST API: [Sign In](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_In%3FTocPath%3DAPI%2520Reference%7C_____77){:target="_blank"}
9393

@@ -101,13 +101,13 @@ REST API: [Sign In](http://onlinehelp.tableau.com/current/api/rest_api/en-us/hel
101101
```py
102102
import tableauserverclient as TSC
103103

104-
# create a auth request
104+
# create an auth object
105105
tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
106106

107107
# create an instance for your server
108108
server = TSC.Server('http://SERVER_URL')
109109

110-
# call the sign-in method with the request
110+
# call the sign-in method with the auth object
111111
server.auth.sign_in(tableau_auth)
112112

113113
```
@@ -128,7 +128,7 @@ auth.sign_out()
128128
```
129129
Signs you out of the current session.
130130

131-
The method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out).
131+
The `sign_out()` method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out).
132132

133133
REST API: [Sign Out](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_Out%3FTocPath%3DAPI%2520Reference%7C_____78){:target="_blank"}
134134

@@ -156,7 +156,7 @@ server.auth.sign_out()
156156

157157
## Connections
158158

159-
The connections for Tableau Server data sources and workbooks are represented by a `ConnectionItem` class. You can call data source and view methods to query or update the connection information. The `ConnectionCredentials` class represents the connection information you can update.
159+
The connections for Tableau Server data sources and workbooks are represented by a `ConnectionItem` class. You can call data source and workbook methods to query or update the connection information. The `ConnectionCredentials` class represents the connection information you can update.
160160

161161
### ConnectionItem class
162162

@@ -178,9 +178,9 @@ Name | Description
178178
`connection_type` | The type of connection.
179179
`username` | The username for the connection.
180180
`password` | The password used for the connection.
181-
`embed_password` | (Boolean) Determines whether to embed the passowrd (`True`) for the workbook or data source connection or not (`False`).
181+
`embed_password` | (Boolean) Determines whether to embed the password (`True`) for the workbook or data source connection or not (`False`).
182182
`server_address` | The server address for the connection.
183-
`server_port` | The port used by the server.
183+
`server_port` | The port used for the connection.
184184

185185
Source file: models/connection_item.py
186186

@@ -196,9 +196,9 @@ ConnectionCredentials(name, password, embed=True, oauth=False)
196196
```
197197

198198

199-
The `ConnectionCredentials` class corresponds to workbook and data source connections.
199+
The `ConnectionCredentials` class is used for workbook and data source publish requests.
200+
200201

201-
In the Tableau Server REST API, there are separate endopoints to query and update workbook and data source connections.
202202

203203
**Attributes**
204204

@@ -220,7 +220,7 @@ Source file: models/connection_credentials.py
220220
## Data sources
221221

222222
Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project.
223-
The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about th 23D3 e name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class.
223+
The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, its connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class.
224224

225225
<br>
226226

@@ -318,7 +318,7 @@ Name | Description
318318
:--- | :---
319319
`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server.
320320
`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory.
321-
`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`).
321+
`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5.
322322

323323
**Exceptions**
324324

@@ -546,7 +546,8 @@ The `DatasourceItem` for the data source that was added or appened to.
546546
...
547547

548548
project_id = '3a8b6148-493c-11e6-a621-6f3499394a39'
549-
file_path = 'C:\\temp\\WorldIndicators.tde'
549+
file_path = r'C:\temp\WorldIndicators.tde'
550+
550551

551552
# Use the project id to create new datsource_item
552553
new_datasource = TSC.DatasourceItem(project_id)
@@ -591,19 +592,21 @@ An updated `DatasourceItem`.
591592

592593
**Example**
593594

594-
```py
595-
# from server-client-python/test/test_datasource.py
595+
```py
596+
# import tableauserverclient as TSC
597+
# server = TSC.Server('http://SERVERURL')
598+
# sign in ...
599+
600+
# get the data source item to update
601+
datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b')
602+
603+
# do some updating
604+
datasource.name = 'New Name'
596605

597-
...
606+
# call the update method with the data source item
607+
updated_datasource = server.datasources.update(datasource)
598608

599-
single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74')
600-
# need to specify the ID - this is a workaround.
601-
single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb'
602-
single_datasource._tags = ['a', 'b', 'c']
603-
single_datasource._project_name = 'Tester'
604-
updated_datasource = self.server.datasources.update(single_datasource)
605609

606-
...
607610

608611
```
609612

@@ -667,7 +670,7 @@ The group resources for Tableau Server are defined in the `GroupItem` class. The
667670
GroupItem(name)
668671
```
669672

670-
The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
673+
The `GroupItem` class contains the attributes for the group resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload.
671674

672675
Source file: models/group_item.py
673676

@@ -686,6 +689,8 @@ Name | Description
686689

687690
```py
688691
newgroup = TSC.GroupItem('My Group')
692+
693+
# call groups.create() with new group
689694
```
690695

691696

@@ -735,17 +740,17 @@ None.
735740

736741
```py
737742
# Adding a user to a group
738-
# Using the second group on the site, aleady have all_groups
743+
#
744+
# get the group item
745+
all_groups, pagination_item = server.groups.get()
746+
mygroup = all_groups[1]
747+
739748
# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba'
740749

741-
# add Ian to the second group
742-
server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')
750+
# add Ian to the group
751+
server.groups.add_user(mygroup, '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba')
743752

744-
# populate the GroupItem with the users
745-
pagination_item = server.groups.populate_users(all_groups[1])
746753

747-
for user in all_groups[1].users :
748-
print(user.name)
749754

750755
```
751756

@@ -883,7 +888,7 @@ Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these
883888
# get the groups on the server
884889
all_groups, pagination_item = server.groups.get()
885890

886-
# print the names of the groups
891+
# print the names of the first 100 groups
887892
for group in all_groups :
888893
print(group.name, group.id)
889894
````
@@ -932,14 +937,14 @@ None. A list of `UserItem` objects are added to the group (`group_item.users`).
932937
...
933938

934939
# get the group
935-
mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d')
936-
940+
all_groups, pagination_item = server.groups.get()
941+
mygroup = all_groups[1]
937942

938943
# get the user information
939944
pagination_item = server.groups.populate_users(mygroup)
940945

941946

942-
# print the information about the first connection item
947+
# print the names of the users
943948
for user in mygroup.users :
944949
print(user.name)
945950

@@ -2806,7 +2811,7 @@ Name | Description
28062811
:--- | :---
28072812
`workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server.
28082813
`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`.
2809-
`no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`).
2814+
`no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5.
28102815

28112816

28122817

0 commit comments

Comments
 (0)
0