Skip to content

Commit 20a1ee4

Browse files
cstenaccstenac
committed
Documentation fixes
1 parent 6656ace commit 20a1ee4

File tree

2 files changed

+77
-108
lines changed

2 files changed

+77
-108
lines changed

‎dataikuapi/dss/meaning.py‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@ def get_definition(self):
1717
1818
Note: this call requires an API key with admin rights
1919
20-
Returns:
21-
the meaning definition, as a JSON object
20+
:returns: the meaning definition, as a dict. The precise structure of the dict depends on the meaning type and is not documented.
2221
"""
2322
return self.client._perform_json(
2423
"GET", "/meanings/%s" % self.id)
@@ -29,8 +28,7 @@ def set_definition(self, definition):
2928
3029
Note: this call requires an API key with admin rights
3130
32-
Args:
33-
definition: the definition for the meaning, as a JSON object
31+
:param dict definition: the definition for the meaning, as a dict. You should only ``set_definition`` on a modified version of a dict you retrieved via :py:meth:`get_definition`
3432
"""
3533
return self.client._perform_json(
3634
"PUT", "/meanings/%s" % self.id,

‎dataikuapi/dssclient.py‎

Lines changed: 75 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,11 @@ def list_futures(self, as_objects=False, all_users=False):
4545
"""
4646
List the currently-running long tasks (a.k.a futures)
4747
48-
Returns:
49-
list of futures. Each object contains at least a 'jobId' field
48+
:param boolean as_objects: if True, each returned item will be a :class:`dataikuapi.dss.future.DSSFuture`
49+
:param boolean all_users: if True, returns futures for all users (requires admin privileges). Else, only returns futures for the user associated with the current authentication context (if any)
50+
51+
:return: list of futures. if as_objects is True, each future in the list is a :class:`dataikuapi.dss.future.DSSFuture`. Else, each future in the list is a dict. Each dict contains at least a 'jobId' field
52+
:rtype: list of :class:`dataikuapi.dss.future.DSSFuture` or list of dict
5053
"""
5154
list = self._perform_json("GET", "/futures/", params={"withScenarios":False, "withNotScenarios":True, 'allUsers' : all_users})
5255
if as_objects:
@@ -58,21 +61,21 @@ def list_running_scenarios(self, all_users=False):
5861
"""
5962
List the running scenarios
6063
61-
Returns:
62-
the list of scenarios, each one as a JSON object containing a jobId field for the
63-
future hosting the scenario run, and a payload field with scenario identifiers
64+
:param boolean all_users: if True, returns scenarios for all users (requires admin privileges). Else, only returns scenarios for the user associated with the current authentication context (if any)
65+
66+
:return: list of running scenarios, each one as a dict containing at least a "jobId" field for the
67+
future hosting the scenario run, and a "payload" field with scenario identifiers
68+
:rtype: list of dicts
6469
"""
6570
return self._perform_json("GET", "/futures/", params={"withScenarios":True, "withNotScenarios":False, 'allUsers' : all_users})
6671

6772
def get_future(self, job_id):
6873
"""
69-
Get a handle to interact with a specific long task (a.k.a future).
70-
71-
Args:
72-
job_id: the job_id key of the desired future
74+
Get a handle to interact with a specific long task (a.k.a future). This notably allows aborting this future.
7375
74-
Returns:
75-
A :class:`dataikuapi.dss.future.DSSFuture`
76+
:param str job_id: the identifier of the desired future (which can be returned by :py:meth:`list_futures` or :py:meth:`list_running_scenarios`)
77+
:returns: A handle to interact the future
78+
:rtype: :class:`dataikuapi.dss.future.DSSFuture`
7679
"""
7780
return DSSFuture(self, job_id)
7881

@@ -83,10 +86,12 @@ def get_future(self, job_id):
8386

8487
def list_running_notebooks(self, as_objects=True):
8588
"""
86-
List the currently-running notebooks
89+
List the currently-running Jupyter notebooks
8790
88-
Returns:
89-
list of notebooks. Each object contains at least a 'name' field
91+
:param boolean as_objects: if True, each returned item will be a :class:`dataikuapi.dss.notebook.DSSNotebook`
92+
93+
:return: list of notebooks. if as_objects is True, each entry in the list is a :class:`dataikuapi.dss.notebook.DSSNotebook`. Else, each item in the list is a dict which contains at least a "name" field.
94+
:rtype: list of :class:`dataikuapi.dss.notebook.DSSNotebook` or list of dict
9095
"""
9196
list = self._perform_json("GET", "/admin/notebooks/")
9297
if as_objects:
@@ -103,46 +108,42 @@ def list_project_keys(self):
103108
"""
104109
List the project keys (=project identifiers).
105110
106-
Returns:
107-
list of identifiers (=strings)
111+
:returns: list of project keys identifiers, as strings
112+
:rtype: list of strings
108113
"""
109114
return [x["projectKey"] for x in self._perform_json("GET", "/projects/")]
110115

111116
def list_projects(self):
112117
"""
113118
List the projects
114119
115-
Returns:
116-
list of objects. Each object contains at least a 'projectKey' field
120+
:returns: a list of projects, each as a dict. Each dictcontains at least a 'projectKey' field
121+
:rtype: list of dicts
117122
"""
118123
return self._perform_json("GET", "/projects/")
119124

120125
def get_project(self, project_key):
121126
"""
122127
Get a handle to interact with a specific project.
123128
124-
Args:
125-
project_key: the project key of the desired project
126-
127-
Returns:
128-
A :class:`dataikuapi.dss.project.DSSProject`
129+
:param str project_key: the project key of the desired project
130+
:returns: A :class:`dataikuapi.dss.project.DSSProject` to interact with this project
129131
"""
130132
return DSSProject(self, project_key)
131133

132134
def create_project(self, project_key, name, owner, description=None, settings=None):
133135
"""
134-
Create a project, and return a project handle to interact with it.
136+
Creates a new project, and return a project handle to interact with it.
135137
136-
Note: this call requires an API key with admin rights
138+
Note: this call requires an API key with admin rights or the rights to create a project
137139
138-
Args:
139-
project_key: the identifier to use for the project.
140-
name: the name for the project.
141-
owner: the owner of the project.
142-
description: a short description for the project.
140+
:param str project_key: the identifier to use for the project. Must be globally unique
141+
:param str name: the display name for the project.
142+
:param str owner: the login of the owner of the project.
143+
:param str description: a description for the project.
144+
:param dict settings: Initial settings for the project (can be modified later). The exact possible settings are not documented.
143145
144-
Returns:
145-
A :class:`dataikuapi.dss.project.DSSProject` project handle
146+
:returns: A class:`dataikuapi.dss.project.DSSProject` project handle to interact with this project
146147
"""
147148
resp = self._perform_text(
148149
"POST", "/projects/", body={
@@ -162,20 +163,16 @@ def list_plugins(self):
162163
"""
163164
List the installed plugins
164165
165-
Returns:
166-
list of objects. Each object contains at least a 'projectKey' field
166+
:returns: list of dict. Each dict contains at least a 'id' field
167167
"""
168168
return self._perform_json("GET", "/plugins/")
169169

170170
def get_plugin(self, plugin_id):
171171
"""
172-
Get a handle to interact with a specific dev plugin.
172+
Get a handle to interact with a specific plugin (plugin in "development" mode only).
173173
174-
Args:
175-
plugin_id: the identifier of the desired plugin
176-
177-
Returns:
178-
A :class:`dataikuapi.dss.project.DSSPlugin`
174+
:param str plugin_id: the identifier of the desired plugin
175+
:returns: A :class:`dataikuapi.dss.project.DSSPlugin`
179176
"""
180177
return DSSPlugin(self, plugin_id)
181178

@@ -190,17 +187,15 @@ def sql_query(self, query, connection=None, database=None, dataset_full_name=Non
190187
passing a connection name, or by passing a database name, or by passing a dataset full name
191188
(whose connection is then used to retrieve the database)
192189
193-
Args:
194-
query: the query to run
195-
connection: the connection on which the query should be run (exclusive of database and dataset_full_name)
196-
database: the database on which the query should be run (exclusive of connection and dataset_full_name)
197-
dataset_full_name: the dataset on the connection of which the query should be run (exclusive of connection and database)
198-
pre_queries: (optional) array of queries to run before the query
199-
post_queries: (optional) array of queries to run after the query
200-
type: the type of query : either 'sql', 'hive' or 'impala'
190+
:param str query: the query to run
191+
:param str connection: the connection on which the query should be run (exclusive of database and dataset_full_name)
192+
:param str database: the database on which the query should be run (exclusive of connection and dataset_full_name)
193+
:param str dataset_full_name: the dataset on the connection of which the query should be run (exclusive of connection and database)
194+
:param list pre_queries: (optional) array of queries to run before the query
195+
:param list post_queries: (optional) array of queries to run after the query
196+
:param str type: the type of query : either 'sql', 'hive' or 'impala'
201197
202-
Returns:
203-
A :class:`dataikuapi.dss.sqlquery.DSSSQLQuery` query handle
198+
:returns: A :class:`dataikuapi.dss.sqlquery.DSSSQLQuery` query handle
204199
"""
205200
return DSSSQLQuery(self, query, connection, database, dataset_full_name, pre_queries, post_queries, type, extra_conf)
206201

@@ -214,7 +209,8 @@ def list_users(self):
214209
215210
Note: this call requires an API key with admin rights
216211
217-
:return: A list of users, as an array of dicts.
212+
:return: A list of users, as a list of dicts
213+
:rtype: list of dicts
218214
"""
219215
return self._perform_json(
220216
"GET", "/admin/users/")
@@ -265,8 +261,8 @@ def list_groups(self):
265261
266262
Note: this call requires an API key with admin rights
267263
268-
Returns:
269-
A list of groups, as an array of JSON objects
264+
:returns: A list of groups, as an list of dicts
265+
:rtype: list of dicts
270266
"""
271267
return self._perform_json(
272268
"GET", "/admin/groups/")
@@ -275,11 +271,8 @@ def get_group(self, name):
275271
"""
276272
Get a handle to interact with a specific group
277273
278-
Args:
279-
name: the name of the desired group
280-
281-
Returns:
282-
A :class:`dataikuapi.dss.admin.DSSGroup` group handle
274+
:param str name: the name of the desired group
275+
:returns: A :class:`dataikuapi.dss.admin.DSSGroup` group handle
283276
"""
284277
return DSSGroup(self, name)
285278

@@ -289,13 +282,11 @@ def create_group(self, name, description=None, source_type='LOCAL'):
289282
290283
Note: this call requires an API key with admin rights
291284
292-
Args:
293-
name: the name of the new group
294-
description: a description of the new group
295-
source_type: the type of the new group. Admissible values are 'LOCAL', 'LDAP', 'SAAS'
285+
:param str name: the name of the new group
286+
:param str description: (optional) a description of the new group
287+
:param source_type: the type of the new group. Admissible values are 'LOCAL' and 'LDAP'
296288
297-
Returns:
298-
A :class:`dataikuapi.dss.admin.DSSGroup` group handle
289+
:returns: A :class:`dataikuapi.dss.admin.DSSGroup` group handle
299290
"""
300291
resp = self._perform_text(
301292
"POST", "/admin/groups/", body={
@@ -315,8 +306,8 @@ def list_connections(self):
315306
316307
Note: this call requires an API key with admin rights
317308
318-
Returns:
319-
All connections, as a map of connection name to connection definition
309+
:returns: All connections, as a dict of connection name to connection definition
310+
:rtype: :dict
320311
"""
321312
return self._perform_json(
322313
"GET", "/admin/connections/")
@@ -325,11 +316,8 @@ def get_connection(self, name):
325316
"""
326317
Get a handle to interact with a specific connection
327318
328-
Args:
329-
name: the name of the desired connection
330-
331-
Returns:
332-
A :class:`dataikuapi.dss.admin.DSSConnection` connection handle
319+
:param str name: the name of the desired connection
320+
:returns: A :class:`dataikuapi.dss.admin.DSSConnection` connection handle
333321
"""
334322
return DSSConnection(self, name)
335323

@@ -348,7 +336,6 @@ def create_connection(self, name, type, params={}, usable_by='ALL', allowed_grou
348336
of names of the groups whose users are allowed to use the new connection
349337
350338
:returns: A :class:`dataikuapi.dss.admin.DSSConnection` connection handle
351-
352339
"""
353340
resp = self._perform_text(
354341
"POST", "/admin/connections/", body={
@@ -370,8 +357,7 @@ def list_code_envs(self):
370357
371358
Note: this call requires an API key with admin rights
372359
373-
Returns:
374-
List code envs (name, type, language)
360+
:returns: a list of code envs. Each code env is a dict containing at least "name", "type" and "language"
375361
"""
376362
return self._perform_json(
377363
"GET", "/admin/code-envs/")
@@ -380,11 +366,8 @@ def get_code_env(self, env_lang, env_name):
380366
"""
381367
Get a handle to interact with a specific code env
382368
383-
Args:
384-
name: the name of the desired code env
385-
386-
Returns:
387-
A :class:`dataikuapi.dss.admin.DSSCodeEnv` code env handle
369+
:param str name: the name of the desired code env
370+
:returns: A :class:`dataikuapi.dss.admin.DSSCodeEnv` code env handle
388371
"""
389372
return DSSCodeEnv(self, env_lang, env_name)
390373

@@ -394,13 +377,11 @@ def create_code_env(self, env_lang, env_name, deployment_mode, params=None):
394377
395378
Note: this call requires an API key with admin rights
396379
397-
:param env_lang: the language (Python, R) of the new code env
380+
:param env_lang: the language (PYTHON or R) of the new code env
398381
:param env_name: the name of the new code env
399382
:param deployment_mode: the type of the new code env
400383
:param params: the parameters of the new code env, as a JSON object
401-
402384
:returns: A :class:`dataikuapi.dss.admin.DSSCodeEnv` code env handle
403-
404385
"""
405386
params = params if params is not None else {}
406387
params['deploymentMode'] = deployment_mode
@@ -422,8 +403,7 @@ def list_global_api_keys(self):
422403
423404
Note: this call requires an API key with admin rights
424405
425-
Returns:
426-
All global API keys, as a list
406+
:returns: All global API keys, as a list of dicts
427407
"""
428408
return self._perform_json(
429409
"GET", "/admin/globalAPIKeys/")
@@ -432,11 +412,8 @@ def get_global_api_key(self, key):
432412
"""
433413
Get a handle to interact with a specific Global API key
434414
435-
Args:
436-
key: the secret key of the desired API key
437-
438-
Returns:
439-
A :class:`dataikuapi.dss.admin.DSSGlobalApiKey` API key handle
415+
:param str key: the secret key of the desired API key
416+
:returns: A :class:`dataikuapi.dss.admin.DSSGlobalApiKey` API key handle
440417
"""
441418
return DSSGlobalApiKey(self, key)
442419

@@ -446,13 +423,10 @@ def create_global_api_key(self, label=None, description=None, admin=False):
446423
447424
Note: this call requires an API key with admin rights
448425
449-
Args:
450-
label: the label of the new API key
451-
description: the description of the new API key
452-
admin: has the new API key admin rights (True or False)
453-
454-
Returns:
455-
A :class:`dataikuapi.dss.admin.DSSGlobalApiKey` API key handle
426+
:param str label: the label of the new API key
427+
:param str description: the description of the new API key
428+
:param str admin: has the new API key admin rights (True or False)
429+
:returns: A :class:`dataikuapi.dss.admin.DSSGlobalApiKey` API key handle
456430
"""
457431
resp = self._perform_json(
458432
"POST", "/admin/globalAPIKeys/", body={
@@ -481,8 +455,8 @@ def list_meanings(self):
481455
482456
Note: this call requires an API key with admin rights
483457
484-
Returns:
485-
A list of meanings, as an array of JSON objects
458+
:returns: A list of meanings. Each meaning is a dict
459+
:rtype: list of dicts
486460
"""
487461
return self._perform_json(
488462
"GET", "/meanings/")
@@ -493,11 +467,8 @@ def get_meaning(self, id):
493467
494468
Note: this call requires an API key with admin rights
495469
496-
Args:
497-
id: the ID of the desired meaning
498-
499-
Returns:
500-
A :class:`dataikuapi.dss.meaning.DSSMeaning` meaning handle
470+
:param str id: the ID of the desired meaning
471+
:returns: A :class:`dataikuapi.dss.meaning.DSSMeaning` meaning handle
501472
"""
502473
return DSSMeaning(self, id)
503474

@@ -558,7 +529,7 @@ def list_logs(self):
558529
List all available log files on the DSS instance
559530
This call requires an API key with admin rights
560531
561-
:returns: A list of log names
532+
:returns: A list of log file names
562533
"""
563534
return self._perform_json(
564535
"GET", "/admin/logs/")

0 commit comments

Comments
 (0)