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.

src/sasctl/_services/text_categorization.py

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

src/sasctl/_services/text_parsing.py

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

src/sasctl/core.py

@@ -249,7 +249,8 @@ class Session(requests.Session):
     authinfo : str, optional
         Path to a .authinfo or .netrc file from which credentials should be
         pulled.
-    protocol : {'http', 'https'}
+    protocol : str
+        Choose from ``{'http', 'https'}``.
         Whether to use HTTP or HTTPS connections.  Defaults to `https`.
     port : int, optional
         Port number for the connection if a non-standard port is used.

src/sasctl/pzmm/import_model.py

@@ -237,7 +237,7 @@ def import_model(
             The `DataFrame` object contains the training data, and includes only the
             predictor columns. The write_score_code function currently supports int(64),
             float(64), and string data types for scoring. The default value is None.
-        predict_method : [function -> list, list], optional
+        predict_method : Callable or list, optional
             The Python function used for model predictions and the expected output
             types. The expected output types can be passed as example values or as the
             value types. For example, if the model is a Scikit-Learn

src/sasctl/pzmm/mlflow_model.py

@@ -18,8 +18,8 @@ def read_mlflow_model_file(cls, m_path=Path.cwd()):
         Parameters
         ----------
         m_path : str or pathlib.Path, optional
-        Directory path of the MLFlow model files. Default is the current working
-        directory.
+            Directory path of the MLFlow model files. Default is the current working
+            directory.
 
         Returns
         -------

src/sasctl/pzmm/write_json_files.py

@@ -5,7 +5,7 @@
 import ast
 import importlib
 import json
-import math
+# import math #not used 
 import pickle
 import pickletools
 import sys
@@ -1080,7 +1080,7 @@ def bias_dataframes_to_json(
             A list of variable names containing the predicted probability values in the score table. The first element
             should represent the predicted probability of the target class. Required for classification problems. Default
             is None.
-        levels: list of str.
+        levels: list of str
             Required for classification problems, otherwise not used
             List of classes of a nominal target in the order they were passed in `prob_values`. Levels must be passed as a
             string. Default is None.

src/sasctl/pzmm/write_score_code.py

@@ -91,7 +91,7 @@ def write_score_code(
             predictor columns. The write_score_code function currently supports int(64),
             float(64), and string data types for scoring. Providing a list of dict
             objects signals that the model files are being created from an MLFlow model.
-        predict_method : [function -> list, list]
+        predict_method : Callable or list of Any
             The Python function used for model predictions and the expected output
             types. The expected output types can be passed as example values or as the
             value types. For example, if the model is a Scikit-Learn
@@ -317,7 +317,7 @@ def upload_and_copy_score_resources(
         ----------
         model : str, dict, or RestObj
             The name or id of the model, or a dictionary representation of the model.
-        files : list of file objects
+        files : list of Any
             The list of score resource files to upload.
 
         Returns
@@ -1102,7 +1102,7 @@ def _predictions_to_metrics(
             A list of target values for the target variable. The default value is None.
         predict_threshold : float, optional
             The prediction threshold for normalized probability score_metrics. Values
-             are expected to be between 0 and 1. The default value is None.
+            are expected to be between 0 and 1. The default value is None.
         h2o_model : bool, optional
             Flag to indicate that the model is an H2O.ai model. The default value is
             False.

src/sasctl/pzmm/zip_model.py

@@ -1,6 +1,6 @@
 # Copyright (c) 2020, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
-import io
+from io import BytesIO
 import zipfile
 from pathlib import Path
 from typing import Optional, Union
@@ -15,7 +15,7 @@ def _filter_files(file_dir: Union[str, Path], is_viya4: Optional[bool] = False)
     Parameters
     ----------
     file_dir : str or Path
-        Location of *.json, *.pickle, *.mojo, and *Score.py files.
+        Location of \*.json, \*.pickle, \*.mojo, and \*Score.py files.
     is_viya4 : bool, optional
         Boolean to indicate difference in logic between SAS Viya 3.5 and SAS Viya 4. For
         Viya 3.5 models, ignore score code that is already in place in the file
@@ -47,7 +47,7 @@ def zip_files(
         model_files: Union[dict, str, Path],
         model_prefix: str,
         is_viya4: Optional[bool] = False,
-    ) -> io.BytesIO:
+    ) -> BytesIO:
         """
         Combines all JSON files with the model pickle file and associated score code
         file into a single archive ZIP file.
@@ -70,13 +70,13 @@ def zip_files(
             directory provided. Default value is False.
         """
         if isinstance(model_files, dict):
-            zip_buffer = io.BytesIO()
+            zip_buffer = BytesIO()
             with zipfile.ZipFile(
                 zip_buffer, "a", zipfile.ZIP_DEFLATED, False
             ) as zip_file:
                 for file_name, data in model_files.items():
                     zip_file.writestr(file_name, str(data))
-                return io.BytesIO(zip_buffer.getvalue())
+                return BytesIO(zip_buffer.getvalue())
         else:
             file_names = _filter_files(model_files, is_viya4)
             with zipfile.ZipFile(
@@ -88,4 +88,4 @@ def zip_files(
             with open(
                 str(Path(model_files) / (model_prefix + ".zip")), "rb"
             ) as zip_file:
-                return io.BytesIO(zip_file.read())
+                return BytesIO(zip_file.read())

src/sasctl/tasks.py

@@ -271,14 +271,15 @@ def register_model(
     repository : str or dict, optional
         The name or id of the repository, or a dictionary representation of
         the repository.  If omitted, the default repository will be used.
-    input : pandas.DataFrame, type, list of type, or dict of str: type, optional
+    input : pandas.DataFrame, type, list of type, or dict of str, optional
         The expected type for each input value of the target function.
         Can be omitted if target function includes type hints.  If a DataFrame
         is provided, the columns will be inspected to determine type
         information.  If a single type is provided, all columns will be assumed
         to be that type, otherwise a list of column types or a dictionary of
         column_name: type may be provided.
-    version : {'new', 'latest', int}, optional
+    version : str or int, optional
+        If str choose from ``{'new', 'latest'}``.
         Version number of the project in which the model should be created.
         Defaults to 'new'.
     files : list
@@ -713,7 +714,7 @@ def update_model_performance(data, model, label, refresh=True):
 
     Parameters
     ----------
-    data : Dataframe
+    data : pandas.DataFrame
     model : str or dict
         The name or id of the model, or a dictionary representation of
         the model.
@@ -726,12 +727,12 @@ def update_model_performance(data, model, label, refresh=True):
 
     Returns
     -------
-    CASTable
+    swat.cas.table.CASTable
         The CAS table containing the performance data.
 
     See Also
     --------
-     :meth:`model_management.create_performance_definition <.ModelManagement.create_performance_definition>`
+    :meth:`model_management.create_performance_definition <.ModelManagement.create_performance_definition>`
 
     .. versionadded:: v1.3
 
@@ -930,7 +931,7 @@ def get_project_kpis(
         Column value to be filtered, by default None
     Returns
     -------
-    kpiTableDf : DataFrame
+    kpiTableDf : pandas.DataFrame
         A pandas DataFrame representing the MM_STD_KPI table. Note that SAS
         missing values are replaced with pandas valid missing values.
     """