teradataml 20.0.0.3__py3-none-any.whl → 20.0.0.5__py3-none-any.whl

teradataml/scriptmgmt/UserEnv.py

@@ -14,25 +14,28 @@
 import functools
 import inspect
 import json
+import os
+import tempfile
+import time
+from concurrent.futures import ThreadPoolExecutor, wait
 from json.decoder import JSONDecodeError
-import os, time
+from urllib.parse import urlparse
 import pandas as pd
 import requests
-import tempfile
+
 from teradataml import configure
-from teradataml.utils.internal_buffer import _InternalBuffer
-from concurrent.futures import ThreadPoolExecutor, wait
-from teradataml.clients.pkce_client import _DAWorkflow
 from teradataml.clients.auth_client import _AuthWorkflow
-from teradataml.context.context import _get_user
-from teradataml.common.constants import HTTPRequest, CloudProvider
+from teradataml.clients.pkce_client import _DAWorkflow
+from teradataml.common.constants import (AsyncOpStatus, CloudProvider,
+                                         HTTPRequest)
 from teradataml.common.exceptions import TeradataMlException
-from teradataml.common.messages import Messages
 from teradataml.common.messagecodes import MessageCodes
+from teradataml.common.messages import Messages
 from teradataml.common.utils import UtilFuncs
-from teradataml.utils.validators import _Validators
-from urllib.parse import urlparse
+from teradataml.context.context import _get_user
 from teradataml.telemetry_utils.queryband import collect_queryband
+from teradataml.utils.internal_buffer import _InternalBuffer
+from teradataml.utils.validators import _Validators
 
 
 def _get_ues_url(env_type="users", **kwargs):
@@ -86,8 +89,8 @@ def _get_ues_url(env_type="users", **kwargs):
         raise TeradataMlException(error_msg, MessageCodes.FUNC_EXECUTION_FAILED)
 
     if configure.ues_url is None:
-        error_msg = Messages.get_message(MessageCodes.DEPENDENT_ARGUMENT,
-                                         api_name, 'configure.ues_url')
+        error_msg = Messages.get_message(MessageCodes.SET_REQUIRED_PARAMS,
+                                         'Authentication Token', api_name, 'set_auth_token')
         raise RuntimeError(error_msg)
 
     ues_url = "{}/{}".format(configure.ues_url, env_type)
@@ -205,7 +208,8 @@ def _process_ues_response(api_name, response, success_status_code=None):
 def _get_auth_token():
     """
     DESCRIPTION:
-        Internal function to get Authentication token for all CCP enabled REST calls
+        Internal function to get authentication token required to access services
+        running on Teradata Vantage.
 
     PARAMETERS:
         None
@@ -237,14 +241,43 @@ def _get_auth_token():
             configure._auth_token_expiry_time = time.time() + token_data["expires_in"] - 15
 
             # Store the jwt token in internal class attribute.
-            _InternalBuffer.add(auth_token=_AuthToken(token=token_data["access_token"]))
-    if _InternalBuffer.get("auth_token"):
-        return {"Authorization": "Bearer {}".format(_InternalBuffer.get("auth_token").value)}
+            _InternalBuffer.add(auth_token=_AuthToken(token=token_data["access_token"],
+                                                      auth_type='bearer'))
+
+    auth_token = _InternalBuffer.get("auth_token")
+    if auth_token:
+        return auth_token.get_header()
+
+
+def _get_ccp_url(base_url):
+    """
+    DESCRIPTION:
+        Internal function to get ccp URL from base_url.
+
+    PARAMETERS:
+        base_url:
+            Required Argument.
+            Specifies the base url.
+            Types: str
+
+    RETURNS:
+        str
+
+    RAISES:
+        None
+
+    EXAMPLES:
+        >>> base_url = 'https://<part_1>.<part_2>.<part_3>.com/<part_4>/<part_5>/<part_6>'
+        >>> _get_ccp_url(base_url)
+        'https://<part_1>.<part_2>.<part_3>.com'
+    """
+    parsed_url = urlparse(base_url)
+    return f"{parsed_url.scheme}://{parsed_url.netloc}"
 
 
 class UserEnv:
 
-    def __init__(self, env_name, base_env, desc=None):
+    def __init__(self, env_name, base_env, desc=None, conda_env=False):
         """
         DESCRIPTION:
             Represents remote user environment from Vantage Languages Ecosystem.
@@ -267,6 +300,13 @@ class UserEnv:
                 Optional Argument.
                 Specifies description associated with the remote user environment.
                 Types: str
+            
+            conda_env:
+                Optional Argument.
+                Specifies whether the environment to be created is a conda environment or not.
+                When set to True, conda environment is created. Otherwise, non conda environment is created.
+                Default value: False
+                Types: bool
 
         RETURNS:
             Instance of the class UserEnv.
@@ -293,6 +333,10 @@ class UserEnv:
         self.base_env = base_env
         self.desc = desc
 
+        self.conda_env = conda_env
+        # Initialize variable for R environment.
+        self._r_env = True if self.base_env.lower().startswith("r_") else False
+
         # Initialize variables to store files, libraries and models from
         # the remote user environment.
         self.__files = None
@@ -434,7 +478,7 @@ class UserEnv:
 
             # Create conda environment.
             >>> testenv_conda = create_env('testenv_conda', 'python_3.8', 'Test conda environment', conda_env=True)
-            Conda environment creation initiated
+            Conda environment creation initiated.
             User environment 'testenv_conda' created.
 
             # Example 1: Install the file mapper.py in the 'testenv' environment.
@@ -1336,7 +1380,10 @@ class UserEnv:
             if self.base_env.lower().startswith('python_'):
                 _Validators._validate_file_extension(libs_file_path, ['txt'])
             elif self.base_env.lower().startswith('r_'):
-                _Validators._validate_file_extension(libs_file_path, ['txt', 'json'])
+                if self.conda_env:
+                    _Validators._validate_file_extension(libs_file_path, ['txt'])
+                else:
+                    _Validators._validate_file_extension(libs_file_path, ['txt', 'json'])
 
             _Validators._check_empty_file(libs_file_path)
 
@@ -1446,7 +1493,8 @@ class UserEnv:
         Returns:
             None
         """
-        if self.base_env.lower().startswith("python"):
+        # Check if the env is python or conda env
+        if not self._r_env or self.conda_env:
             if isinstance(libs, list):
                 return '\n'.join(libs)
             return libs
@@ -1475,6 +1523,11 @@ class UserEnv:
                   the environment. Use "update_lib" API only to upgrade or downgrade installed
                   packages and do not use it for fresh package installation when multiple
                   packages have the same dependency as it messes pip's package resolution ability.
+                * For Conda R environment:
+                  * The library version cannot be specified. Conda only install packages to the
+                    latest compatible version and cannot install to a specific version.
+                  * The libraries should have "r-" prefix in the library name.
+
 
         PARAMETERS:
             libs:
@@ -1498,6 +1551,7 @@ class UserEnv:
                     *   Either "libs" or "libs_file_path" argument must be specified.
                     *   The file must have ".txt" extension for Python environment
                         and ".txt"/".json" extension for R environment.
+                    *   The file must have ".txt" extension for conda environment.
                     *   The file format should adhere to the specifications of the
                         requirements file used by underlying language's package
                         manager to install libraries.
@@ -2063,11 +2117,97 @@ class UserEnv:
             39         zoo    1.8-12
             >>>
 
+            # Create remote user conda R environment.
+            >>> env = create_env('testenv', base_env='r_4.3', desc='Test environment', conda_env=True)
+            Conda environment creation initiated.
+            User environment 'testenv' created.
+
+            # Example 1: Install single R library asynchronously.
+            >>> env.install_lib('r-glm2', asynchronous=True)
+            Request to install libraries initiated successfully in the remote user environment testenv.
+            Check the status using status() with the claim id 'cccc29fe-ca45-49a6-9565-3d50bf310c92'.
+
+            # Check the status.
+            >>> env.status('cccc29fe-ca45-49a6-9565-3d50bf310c92')
+            Claim Id                                 File/Libs/Model   Method Name   Stage    Timestamp              Additional Details
+            cccc29fe-ca45-49a6-9565-3d50bf310c92     r-glm2            install_lib   Started  2024-12-27T08:42:10Z   
+            cccc29fe-ca45-49a6-9565-3d50bf310c92     r-glm2            install_lib   Finished 2024-12-27T08:42:20Z
+
+            # Verify if libraries are installed.
+            >>> env.libs[env.libs['name'].isin(['r-glm2'])]
+            	name	version
+            91	r-glm2	1.2.1
+
+            # Example 2: Install libraries asynchronously by passing them as list of library names.
+            >>> env.install_lib(['r-ggplot2', 'r-dplyr'], asynchronous=True)
+            Request to install libraries initiated successfully in the remote user environment testenv.
+            Check the status using status() with the claim id '1125fa9e-b0f4-49cb-9c9f-d4931a22222d'.
+
+            # Check the status.
+            >>> env.status('1125fa9e-b0f4-49cb-9c9f-d4931a22222d')
+            Claim Id                                 File/Libs/Model     Method Name   Stage    Timestamp              Additional Details
+            1125fa9e-b0f4-49cb-9c9f-d4931a22222d     r-ggplot2, r-dplyr  install_lib   Started  2024-12-27T08:42:10Z   
+            1125fa9e-b0f4-49cb-9c9f-d4931a22222d     r-ggplot2, r-dplyr  install_lib   Finished 2024-12-27T08:42:20Z
+
+            # Verify if libraries are installed or not.
+            >>> env.libs[env.libs['name'].isin(['r-ggplot2', 'r-dplyr'])]
+            	name	    version
+            79	r-dplyr     1.1.3
+            90	r-ggplot2   3.4.4
+
+            # Example 3: Install libraries synchronously by passing them as list of library names.
+            >>> env.install_lib(["r-lubridate", "r-zoo"])
+            Claim Id                                 File/Libs/Model      Method Name   Stage    Timestamp              Additional Details
+            7a026a0d-6616-4398-bd89-9f8d0e06a54f     r-lubridate, r-zoo   install_lib   Started  2024-12-27T08:46:55Z   
+            7a026a0d-6616-4398-bd89-9f8d0e06a54f     r-lubridate, r-zoo   install_lib   Finished 2024-12-27T08:47:06Z
+
+            # Verify if libraries are installed.
+            >>> env.libs[env.libs['name'].isin(['r-lubridate', 'r-zoo'])]
+            	name	    version
+            108	r-lubridate 1.9.3
+            157	r-zoo       1.8_12
+
+            # Example 4: Install libraries synchronously by passing them as list of library names within a
+            #            specific timeout of 1 seconds.
+            >>> env.install_lib(["r-stringi",  "r-glm2"], timeout=1)
+            Request to install libraries initiated successfully in the remote user environment 'testenv' but Timed out status check. 
+            Check the status using status() with the claim id '440eff39-c6d7-4efc-b797-1201a5906065'.
+
+            # Check the status.
+            >>> env.status('440eff39-c6d7-4efc-b797-1201a5906065')
+            Claim Id                                 File/Libs/Model      Method Name   Stage    Timestamp              Additional Details
+            440eff39-c6d7-4efc-b797-1201a5906065     r-stringi, r-glm2    install_lib   Started  2024-12-27T08:49:17Z   
+            440eff39-c6d7-4efc-b797-1201a5906065     r-stringi, r-glm2    install_lib   Finished 2024-12-27T08:49:27Z
+
+            # Verify if libraries are installed.
+            >>> env.libs[env.libs['name'].isin(['r-stringi', 'r-glm2'])]
+                    name	version
+            91	   r-glm2	1.2.1
+            140	 r-stringi	1.7.12
+            
+            # Example 5: Install libraries synchronously by creating requirement.txt file.
+            # Create a requirement.txt file with below contents.
+            -----------------------------------------------------------
+            r-caret
+            r-forecast
+            -----------------------------------------------------------
+
+            # Install libraries specified in the file.
+            >>> env.install_lib(libs_file_path="requirement.txt")
+            Claim Id                               File/Libs/Model    Method Name   Stage    Timestamp              Additional Details
+            f3963a46-2225-412d-a470-17f26c759b42   requirement.txt    install_lib   Started  2024-12-27T08:52:28Z   
+            f3963a46-2225-412d-a470-17f26c759b42   requirement.txt    install_lib   Finished 2024-12-27T08:53:32Z
+
+            # Verify if libraries are installed.
+            >>> env.libs[env.libs['name'].isin(['r-caret', 'r-forecast'])]
+                name	    version
+            68	r-caret	    6.0_94
+            85	r-forecast  8.21.1
         """
         asynchronous = kwargs.get("asynchronous", False)
         timeout = kwargs.get("timeout")
-        claim_id = self.__manage_libraries(libs, libs_file_path, "INSTALL", asynchronous, timeout)
-        return (claim_id)
+        async_task_info = self.__manage_libraries(libs, libs_file_path, "INSTALL", asynchronous, timeout)
+        return async_task_info
 
     @collect_queryband(queryband="UninstlLbs")
     def uninstall_lib(self, libs=None, libs_file_path=None, **kwargs):
@@ -2075,6 +2215,8 @@ class UserEnv:
         DESCRIPTION:
             Function uninstalls libraries from corresponding Python or R
             remote user environment.
+            Note:
+                * For Conda R environment, the libraries should have "r-" prefix in the library name.
 
         PARAMETERS:
             libs:
@@ -2094,6 +2236,7 @@ class UserEnv:
                     *   Either "libs" or "libs_file_path" argument must be specified.
                     *   The file must have ".txt" extension for Python environment
                         and ".txt"/".json" extension for R environment.
+                    *   The file must have ".txt" extension for conda environment.
                     *   The file format should adhere to the specifications of the
                         requirements file used by underlying language's package
                         manager for uninstalling libraries.
@@ -2504,11 +2647,65 @@ class UserEnv:
             65	     waldo	  0.5.1
             66       withr    2.5.0
             >>>
+
+            # Examples for conda R environment.
+            # Create remote conda R user environment.
+            >>> conda_r_env = create_env('test_conda_r_env', 'r_4.3', 'Test conda R environment', conda_env=True)
+            Conda environment creation initiated.
+            User environment 'test_conda_r_env' created.
+
+            # Install R libraries in conda environment.
+            >>> conda_r_env.install_lib(['r-caret', 'r-forecast', 'r-glm2', 'r-anytime'])
+            Claim Id                                 File/Libs/Model                          Method Name   Stage    Timestamp              Additional Details
+            ec6c087e-aee5-42fd-8677-a5f2a8bc5050     r-caret, r-forecast, r-glm2, r-anytime   install_lib   Started  2024-12-27T10:23:34Z   
+            ec6c087e-aee5-42fd-8677-a5f2a8bc5050     r-caret, r-forecast, r-glm2, r-anytime   install_lib   Finished 2024-12-27T10:28:15Z
+
+            # Verify installed libraries.
+            >>> conda_r_env.libs[conda_r_env.libs['name'].isin(['r-caret', 'r-forecast', 'r-glm2', 'r-anytime'])]
+                      name  version
+            67   r-anytime  0.3.9
+            70     r-caret  6.0_94
+            87  r-forecast  8.21.1
+            93      r-glm2  1.2.1
+
+            # Uninstall single R library asynchronously.
+            >>> conda_r_env.uninstall_lib('r-caret', asynchronous=True)
+            Request to uninstall libraries initiated successfully in the remote user environment testenv.
+            Check the status using status() with the claim id '77db7baf-1c4f-4de0-8019-d0f72718b90f'.
+
+            # Check the status.
+            >>> conda_r_env.status('77db7baf-1c4f-4de0-8019-d0f72718b90f')
+            Claim Id                                 File/Libs   Method Name    Stage    Timestamp              Additional Details
+            77db7baf-1c4f-4de0-8019-d0f72718b90f     r-caret    uninstall_lib  Started  2024-12-27T08:49:17Z   
+            77db7baf-1c4f-4de0-8019-d0f72718b90f     r-caret    uninstall_lib  Finished 2024-12-27T08:49:19Z
+
+
+            # Verify if library is uninstalled.
+            >>> conda_r_env.libs[conda_r_env.libs['name'].isin(['r-caret'])]
+                name	version
+
+            # Example 5: Uninstall libraries synchronously by creating requirement.txt file.
+            # Create a requirement.txt file with below contents.
+            -----------------------------------------------------------
+            r-glm2
+            r-anytime
+            -----------------------------------------------------------
+
+            # Uninstall libraries specified in the file.
+            >>> conda_r_env.uninstall_lib(libs_file_path="requirement.txt")
+            Claim Id                                 File/Libs        Method Name   Stage    Timestamp              Additional Details
+            0f3963a46-2225-412d-a470-17f26c759b42   requirement.txt  install_lib   Started  2024-12-27T08:52:28Z   
+            0f3963a46-2225-412d-a470-17f26c759b42   requirement.txt  install_lib   Finished 2024-12-27T08:52:32Z
+
+            # Verify if libraries are uninstalled.
+            >>> conda_r_env.libs[conda_r_env.libs['name'].isin(['r-glm2', 'r-anytime'])]
+                name  version
+ 
         """
         asynchronous = kwargs.get("asynchronous", False)
         timeout = kwargs.get("timeout")
-        claim_id = self.__manage_libraries(libs, libs_file_path, "UNINSTALL", asynchronous, timeout)
-        return (claim_id)
+        async_task_info = self.__manage_libraries(libs, libs_file_path, "UNINSTALL", asynchronous, timeout)
+        return async_task_info
 
     @collect_queryband(queryband="UpdtLbs")
     def update_lib(self, libs=None, libs_file_path=None, **kwargs):
@@ -2523,7 +2720,10 @@ class UserEnv:
                   packages have the same dependency as it messes pip's package resolution ability.
                 * Use "update_lib" to update packages one at a time to prevent dependency resolution
                   issues.
-
+                * For Conda R environment:
+                  * The library version cannot be specified. Conda only updates the installed packages to the
+                    latest compatible version and cannot update to a specific version.
+                  * The libraries should have "r-" prefix in the library name.
 
         PARAMETERS:
             libs:
@@ -2577,10 +2777,14 @@ class UserEnv:
                                 }]
                             }
                     * For conda environment:
-                        The file should only contain the package names.
-                        Library version cannot be specified. Conda only updates the
-                        installed packages to the latest compatible version and
-                        cannot update to a specific version.
+                        * The file should only contain the package names.
+                          Library version cannot be specified. Conda only updates the
+                          installed packages to the latest compatible version and
+                          cannot update to a specific version.
+                        * The file should have ".txt" extension for R environment.
+                          Sample text file content for R conda environment:
+                            r-glm2
+                            r-anytime
                 Types: str
 
         **kwargs:
@@ -2881,12 +3085,55 @@ class UserEnv:
             45     stringi    1.1.5
             ..         ...      ...
             50       withr    2.5.0
-        >>>
+
+            # Example 9: Update Conda R libraries.
+            # Create remote R conda user environment.
+            >>> r_env = create_env('test_r_env', 'r_4.3', 'Test R environment', conda_env=True)
+            Conda environment creation initiated
+            User environment 'test_r_env' created.
+
+            # Install R libraries in environment.
+            # Create a requirement.txt file with below contents.
+            -----------------------------------------------------------
+            r-glm2
+            r-anytime
+            r-ggplot2
+            -----------------------------------------------------------
+
+            >>> r_env.install_lib(libs_file_path="requirement.txt")
+                Claim Id                                File/Libs/Model Method Name Stage       Timestamp            Additional Details
+            0	10afb2ae-8517-4858-8cf9-82bc54abd7ed    requirement.txt install_lib Started     2024-12-17T07:17:26Z	
+            1	10afb2ae-8517-4858-8cf9-82bc54abd7ed    requirement.txt install_lib Finished    2024-12-17T07:21:06Z	
+
+            # update the libraries in the environment through libs
+            >>> r_env.update_lib(libs=["r-glm2", "r-anytime"])
+                Claim Id                                File/Libs/Model  Method Name  Stage     Timestamp            Additional Details
+            0	7106cb78-2dcf-4638-ab91-500fe8144787    libs.txt         update_lib   Started   2024-12-17T07:23:57Z	
+            1	7106cb78-2dcf-4638-ab91-500fe8144787    libs.txt         update_lib   Finished  2024-12-17T07:24:11Z	
+
+            # update the libraries in the environment through libs_file_path
+            >>> r_env.update_lib(libs_file_path="requirement.txt")
+                Claim Id                                File/Libs/Model Method Name Stage       Timestamp            Additional Details
+            0	6d6a3b3d-7b9d-4b0b-8f7f-1d1c7b4b3b5a    requirement.txt update_lib  Started     2024-12-17T07:25:35Z
+            1	6d6a3b3d-7b9d-4b0b-8f7f-1d1c7b4b3b5a    requirement.txt update_lib  Finished	2024-12-17T07:25:49Z
+
+            # Verify if libraries are updated.
+            >>> r_env.libs
+                        name	version
+            0	_libgcc_mutex	0.1
+            1	_openmp_mutex	5.1
+            2	     _r-mutex   1.0.0
+            ...	      ...	    ...
+            103	       tzdata	2024b
+            104	        wheel   0.44.0
+            105	           xz   5.4.6
+            106	         zlib   1.2.13
+            107	         zstd   1.5.6
         """
         asynchronous = kwargs.get("asynchronous", False)
         timeout = kwargs.get("timeout")
-        claim_id = self.__manage_libraries(libs, libs_file_path, "UPDATE", asynchronous, timeout)
-        return (claim_id)
+        async_task_info = self.__manage_libraries(libs, libs_file_path, "UPDATE", asynchronous, timeout)
+        return async_task_info
 
     @collect_queryband(queryband="EnvRfrsh")
     def refresh(self):
@@ -3373,7 +3620,11 @@ class UserEnv:
                             "File/Libs/Model": self.__claim_ids.get(claim_id, {}).get("value", "Unknown")}
 
         try:
-            response = UtilFuncs._http_request(_get_ues_url(env_type="fm", claim_id=claim_id, api_name="status"),
+            # TODO: _get_status() from teradataml.scriptmgmt.lls_utils does similar job.
+            #  _get_status() can be reused.
+            response = UtilFuncs._http_request(_get_ues_url(env_type="fm",
+                                                            claim_id=claim_id,
+                                                            api_name="status"),
                                                headers=_get_auth_token())
             data = _process_ues_response(api_name="status", response=response).json()
             # if claim_id is for install_file - 'data' looks as below:
@@ -3407,7 +3658,7 @@ class UserEnv:
 
         except Exception as e:
             # For any errors, construct a row with error reason in 'additional_details' column.
-            record = {"Additional Details": str(e), "Timestamp": None, "Stage": "Errored"}
+            record = {"Additional Details": str(e), "Timestamp": None, "Stage": AsyncOpStatus.ERRED.value}
             record.update(claim_id_details)
             return [record]
 
@@ -3503,11 +3754,11 @@ class UserEnv:
         action = self.__claim_ids.get(claim_id, {}).get("action")
         if action in ["install_file", "install_model"]:
             for record in records:
-                if record["Stage"] in ["File Installed", "Errored"]:
-                    if record["Stage"] == "File Installed":
+                if record["Stage"] in [AsyncOpStatus.FILE_INSTALLED.value, AsyncOpStatus.ERRED.value]:
+                    if record["Stage"] == AsyncOpStatus.FILE_INSTALLED.value:
                         print("Request for {} is {}.".format(action, "completed successfully"))
-                    elif record["Stage"] == "errored":
-                        print("Request for {} is {}.".format(action, "errored"))
+                    elif record["Stage"] == AsyncOpStatus.ERRED.value:
+                        print("Request for {} is {}.".format(action, AsyncOpStatus.ERRED.value))
                         print("Check the status using status() with the claim id '{}'".format(claim_id))
                     return records
             return False
@@ -3785,11 +4036,27 @@ class UserEnv:
 
 class _AuthToken:
     """
-    Internal class for storing details of Authentication Token.
+    Internal class for storing details of authentication data to be used in headers.
     """
-    def __init__(self, token=None):
+    def __init__(self, token, auth_type):
         self.__value = token
+        self.__auth_type = auth_type
 
     @property
     def value(self):
         return self.__value
+
+    @property
+    def auth_type(self):
+        return self.__auth_type
+
+    def get_header(self):
+        """
+        Method for generating header using authentication data and type.
+        """
+        if self.auth_type.lower() == "basic":
+            # Form the Authorization header value by prepending 'Basic ' to the encoded credentials string.
+            return {"Authorization": "Basic {}".format(self.value)}
+        elif self.auth_type.lower() == "bearer":
+            # Form the Authorization header value by prepending 'Bearer ' to the JWT token.
+            return {"Authorization": "Bearer {}".format(self.value)}