Skip to content

Commit 1554c25

Browse files
cstenaccstenac
committed
API doc improvements
1 parent 5548510 commit 1554c25

File tree

2 files changed

+42
-48
lines changed

2 files changed

+42
-48
lines changed

‎dataikuapi/dss/project.py‎

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@
1515

1616
class DSSProject(object):
1717
"""
18-
A project on the DSS instance
18+
A handle to interact with a project on the DSS instance. Do not create this class directly,
19+
instead use ``client.api_client`` where ``client`` is a DSSClient
1920
"""
2021
def __init__(self, client, project_key):
2122
self.client = client
@@ -29,7 +30,7 @@ def delete(self):
2930
"""
3031
Delete the project
3132
32-
Note: this call requires an API key with admin rights
33+
This call requires an API key with admin rights
3334
"""
3435
return self.client._perform_empty(
3536
"DELETE", "/projects/%s" % self.project_key)
@@ -41,8 +42,7 @@ def delete(self):
4142
def get_export_stream(self, options = {}):
4243
"""
4344
Return a stream of the exported project
44-
45-
Warning: this stream will monopolize the DSSClient until closed
45+
You need to close the stream after download. Failure to do so will reuse in the DSSClient becoming unusable.
4646
"""
4747
return self.client._perform_raw(
4848
"POST", "/projects/%s/export" % self.project_key, body=options).raw
@@ -434,10 +434,13 @@ def preload_bundle(self, bundle_id):
434434

435435
def list_scenarios(self):
436436
"""
437-
List the scenarios in this project
437+
List the scenarios in this project.
438438
439-
Returns:
440-
the list of scenarios, each one as a JSON object.
439+
This method returns a list of Python dictionaries. Each dictionary represents
440+
a scenario. Each dictionary contains at least a "id" field, that you can then pass
441+
to the :meth:`get_scenario`
442+
443+
:returns: the list of scenarios, each one as a Python dictionary
441444
"""
442445
return self.client._perform_json(
443446
"GET", "/projects/%s/scenarios/" % self.project_key)
@@ -446,25 +449,23 @@ def get_scenario(self, scenario_id):
446449
"""
447450
Get a handle to interact with a specific scenario
448451
449-
Args:
450-
scenario_id: the ID of the desired scenario
452+
:param str: scenario_id: the ID of the desired scenario
451453
452-
Returns:
453-
A :class:`dataikuapi.dss.scenario.DSSScenario` scenario handle
454+
:returns: a :class:`dataikuapi.dss.scenario.DSSScenario` scenario handle
454455
"""
455456
return DSSScenario(self.client, self.project_key, scenario_id)
456457

457458
def create_scenario(self, scenario_name, type, definition={}):
458459
"""
459460
Create a new scenario in the project, and return a handle to interact with it
460-
461-
Args:
462-
scenario_name: the name for the new scenario
463-
type: the type of the scenario ('step_based' or 'custom_python')
464-
definition: the definition of the scenario, as a JSON object
465-
466-
Returns:
467-
A :class:`dataikuapi.dss.scenario.DSSScenario` scenario handle
461+
462+
:param str scenario_name: The name for the new scenario. This does not need to be unique
463+
(although this is strongly recommended)
464+
:param str type: The type of the scenario. MUst be one of 'step_based' or 'custom_python'
465+
:param object definition: the JSON definition of the scenario. Use ``get_definition`` on an
466+
existing ``DSSScenario`` object in order to get a sample definition object
467+
468+
:returns: a :class:`.scenario.DSSScenario` handle to interact with the newly-created scenario
468469
"""
469470
definition['type'] = type
470471
definition['name'] = scenario_name

‎dataikuapi/dssclient.py‎

Lines changed: 22 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -543,27 +543,21 @@ def create_meaning(self, id, label, type, description=None,
543543

544544
def list_logs(self):
545545
"""
546-
List all logs on the DSS instance
546+
List all available log files on the DSS instance
547+
This call requires an API key with admin rights
547548
548-
Note: this call requires an API key with admin rights
549-
550-
Returns:
551-
A list of log names
549+
:returns: A list of log names
552550
"""
553551
return self._perform_json(
554552
"GET", "/admin/logs/")
555553

556554
def get_log(self, name):
557555
"""
558-
Get a specific log
559-
560-
Note: this call requires an API key with admin rights
556+
Get the contents of a specific log file
557+
This call requires an API key with admin rights
561558
562-
Args:
563-
name: the name of the desired log
564-
565-
Returns:
566-
The full log, as a string
559+
:param str name: the name of the desired log file (obtained with :meth:`list_logs`)
560+
:returns: The full content of the log file, as a string
567561
"""
568562
return self._perform_json(
569563
"GET", "/admin/logs/%s" % name)
@@ -574,24 +568,25 @@ def get_log(self, name):
574568

575569
def get_variables(self):
576570
"""
577-
Get the DSS instance's variables
571+
Get the DSS instance's variables, as a Python dictionary
578572
579-
Note: this call requires an API key with admin rights
573+
This call requires an API key with admin rights
580574
581-
Returns:
582-
A JSON object
575+
:returns: a Python dictionary of the instance-level variables
583576
"""
584577
return self._perform_json(
585578
"GET", "/admin/variables/")
586579

587580
def set_variables(self, variables):
588581
"""
589-
Set the DSS instance's variables
582+
Updates the DSS instance's variables
590583
591-
Note: this call requires an API key with admin rights
592-
593-
Args:
594-
variables: the new state of all variables of the instance, as a JSON object
584+
This call requires an API key with admin rights
585+
586+
It is not possible to update a single variable, you must set all of them at once. Thus, you
587+
should only use a ``variables`` parameter that has been obtained using :meth:`get_variables`.
588+
589+
:param dict variables: the new dictionary of all variables of the instance
595590
596591
"""
597592
return self._perform_empty(
@@ -604,12 +599,11 @@ def set_variables(self, variables):
604599

605600
def get_general_settings(self):
606601
"""
607-
Get a handle to interact with the general settings.
602+
Gets a handle to interact with the general settings.
608603
609-
Note: this call requires an API key with admin rights
604+
This call requires an API key with admin rights
610605
611-
Returns:
612-
A :class:`dataikuapi.dss.admin.DSSGeneralSettings`
606+
:returns: a :class:`dataikuapi.dss.admin.DSSGeneralSettings` handle
613607
"""
614608
return DSSGeneralSettings(self)
615609

@@ -633,9 +627,8 @@ def prepare_project_import(self, f):
633627
"""
634628
Prepares import of a project archive
635629
636-
@param: fp: the input stream, as a file-like object
637-
638-
Returns a handle for the prepared import
630+
:param file-like fp: the input stream, as a file-like object
631+
:returns: a :class:`TemporaryImportHandle` to interact with the prepared import
639632
"""
640633
val = self._perform_json_upload(
641634
"POST", "/projects/import/upload",

0 commit comments

Comments
 (0)