update more docstrings

Author: SilvestriStefano

doc/conf.py

@@ -52,6 +52,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "swat": ("https://sassoftware.github.io/python-swat/", None),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
@@ -67,7 +68,6 @@
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_ivar = True
-napoleon_use_param = False
 napoleon_use_rtype = False
 
 todo_include_todos = True
@@ -103,7 +103,13 @@
 
 # Suppress warnings 'py:class reference target not found: <type>'
 nitpicky = True
-nitpick_ignore = [('py:class','Response'),('py:class','Request'),('py:class','sasctl._services.service.Service')]
+nitpick_ignore = [
+    ('py:class','optional'),
+    ('py:class','json.encoder.JSONEncoder'), # I don't understand why it can't find it
+    ('py:class','Response'),
+    ('py:class','Request'),
+    ('py:class','sasctl._services.service.Service') # should the Service class be documented?
+]
 
 # -- Options for HTML output -------------------------------------------------
 

src/sasctl/_services/cas_management.py

@@ -324,7 +324,8 @@ def upload_file(
         header : bool, optional
             Whether the first row of data contains column headers.  Defaults to
             True.
-        format_ : {"csv", "xls", "xlsx", "sas7bdat", "sashdat"}, optional
+        format_ : str, optional
+            Choose from {"csv", "xls", "xlsx", "sas7bdat", "sashdat"}.
             File of input `file`.  Not required if format can be discerned from
             the file path.
         detail : dict, optional

src/sasctl/_services/concepts.py

@@ -37,7 +37,7 @@ def assign_concepts(
 
         Parameters
         ----------
-        documents : str or dict or list_like
+        documents : str or dict or list
             Documents to analyze.  May be either the URI to a CAS table where the
             documents are currently stored, or an iterable of strings containing
             the documents' text.
@@ -55,8 +55,9 @@ def assign_concepts(
         model
         output_postfix : str, optional
             Text to be added to the end of all output table names.
-        match_type : {'all', 'longest', 'best'}, optional
-            Type of matches to return.  Defaults to 'all'.
+        match_type : str, optional
+            Choose from ``{'all', 'longest', 'best'}``. 
+            Type of matches to return. Defaults to 'all'.
         enable_facts : bool, optional
             Whether to enable facts in the results.  Defaults to False.
         language : str, optional

src/sasctl/_services/files.py

@@ -40,13 +40,13 @@ def create_file(cls, file, folder=None, filename=None, expiration=None):
 
         Parameters
         ----------
-        file : str or file_like
+        file : str or io.BytesIO
             Path to the file to upload or a file-like object.
         folder : str or dict, optional
             Name or folder information as returned by :meth:`.get_folder`.
         filename : str, optional
             Name to assign to the uploaded file.  Defaults to the filename if `file` is a path, otherwise required.
-        expiration : datetime, optional
+        expiration : datetime.datetime, optional
             A timestamp that indicates when to expire the file.  Defaults to no expiration.
 
         Returns

src/sasctl/_services/microanalytic_score.py

@@ -107,7 +107,7 @@ def execute_module_step(cls, module, step, return_dict=True, **kwargs):
 
         Returns
         -------
-        any
+        Any
             Results of the step execution.  Returned as a dictionary if
             `return_dict` is True, otherwise returned as a tuple if more
             than one value is returned, otherwise the single value.
@@ -180,8 +180,10 @@ def create_module(
         name : str
         description : str
         source : str
-        language : {'python','ds2'}
-        scope : {'public','private'}
+        language : str
+            Choose from ``{'python','ds2'}``
+        scope : str
+            Choose from ``{'public','private'}``
 
         Returns
         -------

src/sasctl/_services/model_management.py

@@ -448,8 +448,8 @@ def create_custom_kpi(
         model : str or dict
             The name or id of the model, or a dictionary representation of the model.
         project : str or dict
-        The name or id of the project, or a dictionary representation of
-        the project.
+            The name or id of the project, or a dictionary representation of
+            the project.
         timeLabel : str or list
             Label associated with the dataset used within the performance definition.
         kpiName : str or list

src/sasctl/_services/model_publish.py

@@ -230,7 +230,8 @@ def create_destination(
         ----------
         name : str
             Name of the publishing destination.
-        type_ : {'cas', 'mas', 'hadoop', 'teradata'}
+        type_ : str
+            Choose from ``{'cas', 'mas', 'hadoop', 'teradata'}``
             Type of publishing definition being created
         cas_server : str, optional
             Name of the CAS server.  Defaults to 'cas-shared-default'.

src/sasctl/_services/model_repository.py

@@ -65,7 +65,7 @@ def get_astore(cls, model):
 
         Returns
         ----------
-        binary?
+        BinaryIO
 
         """
         # TODO: Download binary object?
@@ -296,10 +296,10 @@ def create_model(
         properties : dict, optional
             Custom model properties provided as name: value pairs.
             Allowed types are int, float, string, datetime.date, and datetime.datetime
-        input_variables : array_like, optional
+        input_variables : Iterable, optional
             Model input variables. By default, these are the same as the model
             project.
-        output_variables : array_like, optional
+        output_variables : Iterable, optional
             Model output variables. By default, these are the same as the model
              project.
         project_version : str

src/sasctl/_services/saslogon.py

@@ -46,7 +46,7 @@ def create_client(
             The ID to be assigned to the client.
         client_secret : str
             The client secret used for authentication.
-        scopes : list of string, optional
+        scopes : list of str, optional
             Specifies the levels of access that the client will be able to
             obtain on behalf of users when not using client credential
             authentication.  If `allow_password` or `allow_auth_code` are
@@ -160,7 +160,7 @@ def list_clients(cls, start_index=None, count=None, descending=False):
         ----------
         start_index : int, optional
             Index of first client to return.  Defaults to 1.
-        count : int, optiona;
+        count : int, optional
             Number of clients to retrieve.  Defaults to 100.
         descending : bool, optional
             Whether to clients should be returned in descending order.

src/sasctl/_services/sentiment_analysis.py

@@ -37,7 +37,7 @@ def analyze_sentiment(
 
         Parameters
         ----------
-        documents : str or dict or Iterable:
+        documents : str or dict or Iterable
             Documents to analyze.  May be either the URI to a CAS table where the
             documents are currently stored, or an iterable of strings containing
             the documents' text.