8000 docs: add docstrings to auth objects and endpoints · tableau/server-client-python@402622f · GitHub
[go: up one dir, main page]
Skip to content

Commit 402622f

Browse files
jorwoodsjorwoods
committed
docs: add docstrings to auth objects and endpoints
1 parent e1b8281 commit 402622f

File tree

2 files changed

+121
-0
lines changed

2 files changed

+121
-0
lines changed

‎tableauserverclient/models/tableau_auth.py

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,43 @@ def deprecate_site_attribute():
3232

3333
# The traditional auth type: username/password
3434
class TableauAuth(Credentials):
35+
"""
36+
The TableauAuth class defines the information you can set in a sign-in
37+
request. The class members correspond to the attributes of a server request
38+
or response payload. To use this class, create a new instance, supplying
39+
user name, password, and site information if necessary, and pass the
40+
request object to the Auth.sign_in method.
41+
42+
Parameters
43+
----------
44+
username : str
45+
The user name for the sign-in request.
46+
47+
password : str
48+
The password for the sign-in request.
49+
50+
site_id : str, optional
51+
This corresponds to the contentUrl attribute in the Tableau REST API.
52+
The site_id is the portion of the URL that follows the /site/ in the
53+
URL. For example, "MarketingTeam" is the site_id in the following URL
54+
MyServer/#/site/MarketingTeam/projects. To specify the default site on
55+
Tableau Server, you can use an empty string '' (single quotes, no
56+
space). For Tableau Cloud, you must provide a value for the site_id.
57+
58+
user_id_to_impersonate : str, optional
59+
Specifies the id (not the name) of the user to sign in as. This is not
60+
available for Tableau Online.
61+
62+
Examples
63+
--------
64+
>>> import tableauserverclient as TSC
65+
66+
>>> tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
67+
>>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
68+
>>> server.auth.sign_in(tableau_auth)
69+
70+
"""
71+
3572
def __init__(
3673
self, username: str, password: str, site_id: Optional[str] = None, user_id_to_impersonate: Optional[str] = None
3774
) -> None:
@@ -55,6 +92,43 @@ def __repr__(self):
5592

5693
# A Tableau-generated Personal Access Token
5794
class PersonalAccessTokenAuth(Credentials):
95+
"""
96+
The PersonalAccessTokenAuth class defines the information you can set in a sign-in
97+
request. The class members correspond to the attributes of a server request
98+
or response payload. To use this class, create a new instance, supplying
99+
token name, token secret, and site information if necessary, and pass the
100+
request object to the Auth.sign_in method.
101+
102+
Parameters
103+
----------
104+
token_name : str
105+
The name of the personal access token.
106+
107+
personal_access_token : str
108+
The personal access token secret for the sign in request.
109+
110+
site_id : str, optional
111+
This corresponds to the contentUrl attribute in the Tableau REST API.
112+
The site_id is the portion of the URL that follows the /site/ in the
113+
URL. For example, "MarketingTeam" is the site_id in the following URL
114+
MyServer/#/site/MarketingTeam/projects. To specify the default site on
115+
Tableau Server, you can use an empty string '' (single quotes, no
116+
space). For Tableau Cloud, you must provide a value for the site_id.
117+
118+
user_id_to_impersonate : str, optional
119+
Specifies the id (not the name) of the user to sign in as. This is not
120+
available for Tableau Online.
121+
122+
Examples
123+
--------
124+
>>> import tableauserverclient as TSC
125+
126+
>>> tableau_auth = TSC.PersonalAccessTokenAuth("token_name", "token_secret", site_id='CONTENTURL')
127+
>>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
128+
>>> server.auth.sign_in(tableau_auth)
129+
130+
"""
131+
58132
def __init__(
59133
self,
60134
token_name: str,
@@ -88,6 +162,42 @@ def __repr__(self):
88162

89163
# A standard JWT generated specifically for Tableau
90164
class JWTAuth(Credentials):
165+
"""
166+
The JWTAuth class defines the information you can set in a sign-in
167+
request. The class members correspond to the attributes of a server request
168+
or response payload. To use this class, create a new instance, supplying
169+
an encoded JSON Web Token, and site information if necessary, and pass the
170+
request object to the Auth.sign_in method.
171+
172+
Parameters
173+
----------
174+
token : str
175+
The encoded JSON Web Token.
176+
177+
site_id : str, optional
178+
This corresponds to the contentUrl attribute in the Tableau REST API.
179+
The site_id is the portion of the URL that follows the /site/ in the
180+
URL. For example, "MarketingTeam" is the site_id in the following URL
181+
MyServer/#/site/MarketingTeam/projects. To specify the default site on
182+
Tableau Server, you can use an empty string '' (single quotes, no
183+
space). For Tableau Cloud, you must provide a value for the site_id.
184+
185+
user_id_to_impersonate : str, optional
186+
Specifies the id (not the name) of the user to sign in as. This is not
187+
available for Tableau Online.
188+
189+
Examples
190+
--------
191+
>>> import jwt
192+
>>> import tableauserverclient as TSC
193+
194+
>>> jwt_token = jwt.encode(...)
195+
>>> tableau_auth = TSC.JWTAuth(token, site_id='CONTENTURL')
196+
>>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
197+
>>> server.auth.sign_in(tableau_auth)
198+
199+
"""
200+
91201
def __init__(self, jwt: str, site_id: Optional[str] = None, user_id_to_impersonate: Optional[str] = None) -> None:
92202
if jwt is None:
93203
raise TabError("Must provide a JWT token when using JWT authentication")

‎tableauserverclient/server/endpoint/auth_endpoint.py

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,14 +70,17 @@ def sign_in(self, auth_req: "Credentials") -> contextmgr:
7070
# The distinct methods are mostly useful for explicitly showing api version support for each auth type
7171
@api(version="3.6")
7272
def sign_in_with_personal_access_token(self, auth_req: "Credentials") -> contextmgr:
73+
"""Passthrough to sign_in method"""
7374
return self.sign_in(auth_req)
7475

7576
@api(version="3.17")
7677
def sign_in_with_json_web_token(self, auth_req: "Credentials") -> contextmgr:
78+
"""Passthrough to sign_in method"""
7779
return self.sign_in(auth_req)
7880

7981
@api(version="2.0")
8082
def sign_out(self) -> None:
83+
"""Sign out of current session."""
8184
url = f"{self.baseurl}/signout"
8285
# If there are no auth tokens you're already signed out. No-op
8386
if not self.parent_srv.is_signed_in():
@@ -88,6 +91,11 @@ def sign_out(self) -> None:
8891

8992
@api(version="2.6")
9093
def switch_site(self, site_item: "SiteItem") -> contextmgr:
94+
"""
95+
Switch to a different site on the server. This will sign out of the
96+
current site and sign in to the new site. If used as a context manager,
97+
will sign out of the new site upon exit.
98+
"""
9199
url = f"{self.baseurl}/switchSite"
92100
switch_req = RequestFactory.Auth.switch_req(site_item.content_url)
93101
try:
@@ -109,6 +117,9 @@ def switch_site(self, site_item: "SiteItem") -> contextmgr:
109117

110118
@api(version="3.10")
111119
def revoke_all_server_admin_tokens(self) -> None:
120+
"""
121+
Revokes all personal access tokens for all server admins on the server.
122+
"""
112123
url = f"{self.baseurl}/revokeAllServerAdminTokens"
113124
self.post_request(url, "")
114125
logger.info("Revoked all tokens for all server admins")

0 commit comments

Comments
 (0)
0