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

teradataml/README.md

@@ -17,6 +17,102 @@ Copyright 2025, Teradata. All Rights Reserved.
 
 ## Release Notes:
 
+#### teradataml 20.00.00.06
+* ##### New Features/Functionality
+  * ###### teradataml: SDK
+    * Added new client `teradataml.sdk.Client` which can be used by user to make REST calls through SDK.
+    * New exception added in `teradataml`, specifically for REST APIs `TeradatamlRestException` that has attribute `json_resonse` providing proper printable json.
+    * Exposed three different ways of authentication through `Client`.
+      * Client credentials Authentication through `ClientCredentialsAuth` class.
+      * Device code Authentication through `DeviceCodeAuth` class.
+      * Bearer Authentication through `BearerAuth` class.
+
+  * ###### teradataml: ModelOps SDK
+    * `teradataml` exposes Python interfaces for all the REST APIs provided by Teradata Vantage ModelOps.
+    * Added support for `blueprint()` method which prints available classes in `modelops` module.
+    * Added new client `ModelOpsClient` with some additional function compared to `teradataml.sdk.Client`.
+    * teradataml classes are added for the schema in ModelOps OpenAPI specification.
+    ```python
+    >>> from teradataml.sdk.modelops import ModelOpsClient, Projects
+    >>> from teradataml.common.exceptions import TeradatamlRestException
+    >>> from teradataml.sdk import DeviceCodeAuth, BearerAuth, ClientCredentialsAuth # Authentication related classes.
+    >>> from teradataml.sdk.modelops import models # All classes related to OpenAPI schema are present in this module.
+
+    # Print available classes in modelops module.
+    >>> from teradataml.sdk.modelops import blueprint
+    >>> blueprint()
+
+    # Create ClientCredentialsAuth object and create ModelOpsClient object.
+    >>> cc_obj = ClientCredentialsAuth(auth_client_id="<client_id>",
+                                       auth_client_secret="<client_secret>",
+                                       auth_token_url="https://<example.com>/token")
+    >>> client = ModelOpsClient(base_url="<base_url>", auth=cc_obj, ssl_verify=False)
+
+    # Create Projects object.
+    >>> p = Projects(client=client)
+
+    # Create project using `body` argument taking object of ProjectRequestBody.
+    >>> project_paylod = {
+            "name": "dummy_project",
+            "description": "dummy_project created for testing",
+            "groupId": "<group_ID>",
+            "gitRepositoryUrl": "/app/built-in/empty",
+            "branch": "<branch>"
+        }
+    >>> p.create_project(body=models.ProjectRequestBody(**project_payload))
+    ```
+
+  * ###### teradataml: Functions
+    * `get_formatters()` - Get the formatters for NUMERIC, DATE and CHAR types.
+
+  * ###### teradataml: DataFrame Methods
+    * `get_snapshot()` - Gets the snapshot data of a teradataml DataFrame created on OTF table for a given snapshot id or timestamp.
+    * `from_pandas()`: Creates a teradataml DataFrame from a pandas DataFrame.
+    * `from_records()`: Creates a teradataml DataFrame from a list.
+    * `from_dict()`: Creates a teradataml DataFrame from a dictionary.
+
+  * ###### teradataml: DataFrame Property
+    * `history` - Returns snapshot history for a DataFrame created on OTF table.
+    * `manifests` - Returns manifest information for a DataFrame created on OTF table.
+    * `partitions` - Returns partition information for a DataFrame created on OTF table.
+    * `snapshots` - Returns snapshot information for a DataFrame created on OTF table.
+
+  * ###### teradataml DataFrameColumn a.k.a. ColumnExpression
+    * `DataFrameColumn.rlike()` - Function to match a string against a regular expression pattern.
+    * `DataFrameColumn.substring_index()` - Function to return the substring from a column before a specified 
+    delimiter, up to a given occurrence count.
+    * `DataFrameColumn.count_delimiters()` - Function to count the total number of occurrences of a specified delimiter.
+
+* ##### Updates
+  * ###### teradataml DataFrameColumn a.k.a. ColumnExpression
+    * `DataFrameColumn.like()`
+      * Added argument `escape_char` to specify the escape character for the LIKE pattern.
+      * Argument `pattern` now accepts DataFrameColumn as input.
+    * `DataFrameColumn.ilike()`
+      * Added argument `escape_char` to specify the escape character for the ILIKE pattern.
+      * Argument `pattern` now accepts DataFrameColumn as input.
+    * `DataFrameColumn.parse_url()` - Added argument `key` to extract a specific query parameter when `url_part` is set to "QUERY".
+
+  * ###### teradataml: DataFrame function
+    * `groupby()`, `cube()` and `rollup()`
+       * Added argument `include_grouping_columns` to include aggregations on the grouping column(s).
+    * `DataFrame()`: New argument `data`, that accepts input data to create a teradataml DataFrame, is added.
+
+  * ###### General functions
+    * `set_auth_token()`
+      * New keyword argument `auth_url` accepts the endpoint URL for a keycloak server.
+      * New keyword argument `rest_client` accepts name of the service for which keycloak token is to be generated.
+      * New keyword argument `validate_jwt` accepts the boolean flag to decide whether to validate generated JWT token or not.
+      * New keyword argument `valid_from` accepts the epoch seconds representing time from which JWT token will be valid.
+
+  * ###### teradataml Options
+    * Configuration Options
+      * `configure.use_short_object_name`
+        Specifies whether to use a shorter name for temporary database objects which are created by teradataml internally.
+
+  * ###### BYOM Function
+    * Supports special characters.
+
 #### teradataml 20.00.00.05
 * ##### New Features/Functionality
   * ##### teradataml: AutoML

teradataml/_version.py

@@ -8,4 +8,4 @@
 # 
 # ################################################################## 
 
-version = "20.00.00.05"
+version = "20.00.00.06"

teradataml/analytics/analytic_function_executor.py

@@ -490,7 +490,7 @@ class _AnlyticFunctionExecutor:
                 arg_value = self._spl_func_obj._add_square_bracket(arg_value)
 
                 # Check if there are columns with non-ASCII characters.
-                if UtilFuncs._is_ascii(arg_value):
+                if UtilFuncs._is_non_ascii(arg_value):
                     arg_value = UtilFuncs._teradata_quote_arg(arg_value, "\"", False)
                 # Handling special case for Teradata reserved keywords or column names with spaces.
                 # If argument is a string or list of strings, then add quotes to the string.

teradataml/analytics/utils.py

@@ -459,19 +459,64 @@ class FuncSpecialCaseHandler():
                            "Matrix2Image": {"type": self._single_quote_arg,
                                             "colormap": self._single_quote_arg
                                            },
-                            "AIAnalyzeSentiment": {"authorization": self._remove_quotes},
-                            "AITextTranslate": {"authorization": self._remove_quotes},
-                            "AITextSummarize": {"authorization": self._remove_quotes},
-                            "AI_TextEmbeddings": {"authorization": self._remove_quotes},
-                            "AITextClassifier": {"authorization": self._remove_quotes},
-                            "AIRecognizePIIEntities": {"authorization": self._remove_quotes},
-                            "AIRecognizeEntities": {"authorization": self._remove_quotes},
-                            "AIMaskPII:": {"authorization": self._remove_quotes},
-                            "AIExtractKeyPhrases": {"authorization": self._remove_quotes},
-                            "AIDetectLanguage": {"authorization": self._remove_quotes},
-                            "AIAskLLM": {"authorization": self._remove_quotes}
+                           "AIAnalyzeSentiment": {"authorization": self._remove_quotes},
+                           "AITextTranslate": {"authorization": self._remove_quotes},
+                           "AITextSummarize": {"authorization": self._remove_quotes},
+                           "AI_TextEmbeddings": {"authorization": self._remove_quotes},
+                           "AITextClassifier": {"authorization": self._remove_quotes},
+                           "AIRecognizePIIEntities": {"authorization": self._remove_quotes},
+                           "AIRecognizeEntities": {"authorization": self._remove_quotes},
+                           "AIMaskPII:": {"authorization": self._remove_quotes},
+                           "AIExtractKeyPhrases": {"authorization": self._remove_quotes},
+                           "AIDetectLanguage": {"authorization": self._remove_quotes},
+                           "AIAskLLM": {"authorization": self._remove_quotes},
+                           "DataikuPredict": {"accumulate": self._handle_byom_args},
+                           "DataRobotPredict": {"accumulate": self._handle_byom_args},
+                           "H2OPredict": {"accumulate": self._handle_byom_args},
+                           "ONNXEmbeddings": {"accumulate": self._handle_byom_args},
+                           "ONNXPredict": {"accumulate": self._handle_byom_args},
+                           "PMMLPredict": {"accumulate": self._handle_byom_args}
                            }
 
+    def _handle_byom_args(self, arg_value, *args, **kwargs):
+        """
+        DESCRIPTION:
+            Function to handle the special function arguments for BYOM functions.
+            Special character(s) are required to be in single quote for BYOM
+            functions. For other SQLE functions, special character(s) to be in double
+            quote. Hence removing double quotes and adding single quotes for
+            special character(s) in the argument value.
+
+        PARAMETERS:
+            arg_value
+                Required Argument.
+                Specifies the argument value to handle special function arguments.
+                Types: str or list of str(s)
+
+        RETURNS:
+            str
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            # Example 1: Handle the special function arguments for BYOM functions.
+            >>> self._handle_byom_args('"alice.deauth"')
+            # result: 'alice.deauth'
+        """
+        arg_values = []
+        if isinstance(arg_value, list):
+            arg_values = (val.strip('"') for val in arg_value)
+            return ", ".join(["'{}'".format(val) for val in arg_values])
+
+        if isinstance(arg_value, str):
+            # If argument value is a string, remove quotes.
+            arg_value = arg_value.strip('"')
+            return "'{}'".format(arg_value)
+
+        return arg_value
+
+
     # Setter method for argument.
     def set_arg_name(self, argument):
         """

teradataml/clients/auth_client.py

@@ -33,6 +33,8 @@ class _AuthWorkflow:
                     5. "username" which is the DB user.
                     5. "expiration_time" which is the expiration time for the token and has a default value of
                        31536000 seconds.
+                    6. "valid_from" which states epoch seconds representing time from which JWT token will be valid
+                        and same is used as iat claim in payload.
                 Types: dict
 
         RETURNS:
@@ -52,7 +54,7 @@ class _AuthWorkflow:
             Generate expiry epoch time.
 
         RETURNS:
-            float
+            tuple
         """
         current_epoch_time = int(time.time())
         expiry_epoch_time = current_epoch_time + self.state.get('expiration_time')
@@ -83,12 +85,11 @@ class _AuthWorkflow:
         RETURNS:
             A dictionary with the JWT payload.
         """
-        iat, exp= self._get_epoch_time()
+        _, exp = self._get_epoch_time()
         payload = {
             "aud": [
                 "td:service:authentication"
             ],
-            "iat": iat,
             "exp": exp,
             "iss": "teradataml",
             "multi-use": True,
@@ -96,6 +97,9 @@ class _AuthWorkflow:
             "pat": self.state['pat_token'],
             "sub": self.state['username']
         }
+        # Add iat if required.
+        if self.state['valid_from']:
+            payload.update({"iat": self.state['valid_from']})
         return payload
 
     def _sign_jwt(self, payload, header):
@@ -128,6 +132,6 @@ class _AuthWorkflow:
         RETURNS:
             str
         """
-        jwt = self._sign_jwt(self._generate_payload(), self._generate_header())
-        self.state['jwt'] = jwt
-        return(jwt)
+        jwt_token = self._sign_jwt(self._generate_payload(), self._generate_header())
+        self.state['jwt'] = jwt_token
+        return jwt_token

teradataml/clients/keycloak_client.py

@@ -0,0 +1,165 @@
+"""
+Unpublished work.
+Copyright (c) 2025 by Teradata Corporation. All rights reserved.
+TERADATA CORPORATION CONFIDENTIAL AND TRADE SECRET
+Primary Owner: shivani.kondewar@teradata.com
+Secondary Owner: aanchal.kavedia@teradata.com
+This file implements _KeycloakManager class used to store data for keycloak token generation.
+"""
+
+import time
+from enum import Enum
+
+from teradataml import TeradataMlException, MessageCodes
+from teradataml.common.constants import HTTPRequest
+from teradataml.context.context import _get_user
+
+
+class GrantType(Enum):
+    PASS = "password"
+    REFRESH = "refresh_token"
+    CLIENT = "client_credentials"
+
+
+class _KeycloakManager():
+
+    def __init__(self, auth_url, client_id):
+        """
+        DESCRIPTION:
+            Constructor to initiate keycloak manager.
+
+        PARAMETERS:
+            auth_url:
+                Required Argument.
+                Specifies the endpoint URL for a keycloak server.
+                Types: str
+
+            client_id:
+                Required Argument.
+                Specifies the client/service for which keycloak server avails a token.
+                Types: str
+
+        RETURNS:
+            Instance of _KeycloakManager.
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            >>> token_generator = _KeycloakManager(auth_url=auth_url,
+            ...                                    username=username,
+            ...                                    client_id=client_id)
+        """
+        self._auth_url = auth_url
+        self._client_id = client_id
+        self._header = {"Content-Type": "application/x-www-form-urlencoded"}
+        self._expires_at = None
+        self._refresh_expires_at = None
+
+    def generate_token(self, username=None, password=None, refresh=False):
+        """
+        DESCRIPTION:
+            Method generates keycloak token.
+            Token can be generated using any one of the following information:
+                * Username and password
+                * Refresh token
+
+        PARAMETERS:
+            username:
+                Optional Argument.
+                Specifies the username for database user for which keycloak token is
+                to be generated. If not specified, then user associated with current
+                connection is used.
+                Types: str
+
+            password:
+                Optional Argument.
+                Specifies the password for database user.
+                Types: str
+
+            refresh:
+                Optional Argument.
+                Specifies the boolean flag to indicate if token needs to be generated
+                using existing refresh token or not.
+                Default value: False
+                Types: Boolean
+
+        RETURNS:
+            Keycloak token
+
+        RAISES:
+            RuntimeError.
+
+        EXAMPLES:
+            # Example 1: Generate the authentication token using username and password.
+            >>> keycloak_obj.generate_token(username="username", password="password")
+
+            # Example 2: Generate the authentication token using default username for
+            #            current session and provided password.
+            >>> keycloak_obj.generate_token(password="password")
+
+            # Example 3: Generate the authentication token using refresh token which is
+            #            already available.
+            >>> keycloak_obj.generate_token(refresh=True)
+            """
+        # Define the payload.
+        if password:
+            payload = {
+                "grant_type": GrantType.PASS.value,
+                "client_id": self._client_id,
+                "username": username if username else _get_user(),
+                "password": password
+            }
+        if refresh:
+            payload = {
+                "grant_type": GrantType.REFRESH.value,
+                "client_id": self._client_id,
+                "refresh_token": self._refresh_token
+            }
+
+        # Make the POST request.
+        # Importing locally to avoid circular import.
+        from teradataml import UtilFuncs
+        response = UtilFuncs._http_request(self._auth_url, HTTPRequest.POST,
+                                           headers=self._header, data=payload)
+
+        # Check the response.
+        if 200 <= response.status_code < 300:
+            response_data = response.json()
+            self._auth_token = response_data['access_token']
+            self._refresh_token = response_data['refresh_token']
+            # 30 is buffer time to assume delay in processing of response_data.
+            self._expires_at = time.time() + response_data['expires_in'] - 30
+            self._refresh_expires_at = time.time() + response_data['refresh_expires_in'] - 30
+        else:
+            raise
+
+        return self._auth_token
+
+    def get_token(self):
+        """
+        DESCRIPTION:
+            Function to get keycloak token.
+            If access token is not expired, existing token is returned.
+            If access token is expired, and refresh token is alive, new access token is generated.
+            If both access token and refresh token are expired, TeradataMlException is raised
+
+        RETURNS:
+            Keycloak token
+
+        RAISES:
+            TeradataMlException.
+
+        """
+        # If existing auth_token is expired, regenerate using refresh token.
+        if self._expires_at and time.time() > self._expires_at:
+            # If refresh token is expired, raise error.
+            if self._refresh_expires_at and time.time() > self._refresh_expires_at:
+                raise TeradataMlException("Refresh token for keycloak is expired."
+                                          " Execute set_auth_token() to set fresh authentication token.",
+                                          MessageCodes.FUNC_EXECUTION_FAILED)
+            else:
+                # Regenerate fresh access token using refresh token.
+                self.generate_token(refresh=True)
+
+        return self._auth_token

teradataml/common/constants.py

@@ -65,6 +65,8 @@ class SQLConstants(Enum):
     SQL_HELP_DATALAKE = 34
     CONSTRAINT = ["check_constraint", "primary_key_constraint",
                   "foreign_key_constraint", "unique_key_constraint"]
+    SQL_TD_OTF_METADATA = 35
+    SQL_TD_OTF_SNAPSHOT = 36
 
 
 class TeradataConstants(Enum):
@@ -1567,3 +1569,11 @@ class AuthMechs(Enum):
     JWT = "JWT"
     PAT = "PAT"
     BASIC = "BASIC"
+    KEYCLOAK = "KEYCLOAK"
+
+class TDServices(Enum):
+    """
+    Enum to hold permitted values for types for services availed on Teradata vantage.
+    """
+    VECTORSTORE = "vectorstore"
+    MOPS = "MODELOPS" # For future reference

teradataml/common/exceptions.py

@@ -12,6 +12,12 @@ teradataml.common.exceptions
 An Error class for the teradataml python module
 """
 
+
+import warnings
+import json
+import pprint
+
+
 class TeradataMlException(Exception):
     """
     Teradata Ml Exception class.
@@ -71,3 +77,29 @@ class TeradataMlException(Exception):
         """
         super(TeradataMlException, self).__init__(msg)
         self.code = code
+
+class TeradatamlRestException(TeradataMlException):
+    def __init__(self, msg, code, raw_message=None):
+        super().__init__(msg, code)
+
+        self._msg = msg
+        self._raw_message = raw_message
+    
+    @property
+    def json_response(self):
+        """
+        Returns the JSON response from the server.
+        """
+        if self._raw_message is not None and self._raw_message.startswith("Error message: "):
+            failure_msg = f"Could not convert msg to json. Message is \n{self._raw_message}"
+            try:
+                json_resp = self._msg.split("Error message: ")[1]
+                json_resp = json.loads(json_resp)
+                return pprint.pformat(json_resp)
+            except json.JSONDecodeError as _:
+                warnings.warn(failure_msg)
+        elif self._raw_message is None:
+            return None
+        else:
+            warnings.warn(failure_msg)
+    

teradataml/common/messagecodes.py

@@ -228,6 +228,21 @@ class ErrorInfoCodes(Enum):
     # OpenAF Error codes starting from 2551 - Reserved till 2560.
     SET_REQUIRED_PARAMS = 'TDML_2551'
 
+    # Error codes for OTF. Reserved till 2570.
+    OTF_TABLE_REQUIRED = 'TDML_2561'
+
+    # Rest Excceptions. Reserved for 2570 - 2580
+    REST_HTTP_ERROR = 'TDML_2570'
+    REST_AUTH_MISSING_ARG = 'TDML_2571'
+    REST_NOT_CONFIGURED = 'TDML_2572'
+    REST_DEVICE_CODE_NO_BOTH = 'TDML_2573'
+    REST_DEVICE_CODE_GEN_FAILED = 'TDML_2574'
+    REST_DEVICE_CODE_AUTH_FAILED = 'TDML_2575'
+
+    # Python SDK Error codes starting from 2580 - Reserved till 2590.
+    INFO_NOT_PROVIDED_USE_DEFAULT = 'TDML_W_2580' # Logger warning.
+
+
 class MessageCodes(Enum):
     """
     MessageCodes contains all the messages that are displayed to the user which are informational
@@ -442,3 +457,15 @@ class MessageCodes(Enum):
                         "explicitly passed to function or specified using a configuration file, or setting up " \
                         "the environment variables."
     DEPENDENT_METHOD = "Method(s) {} must be called before calling '{}'."
+    REST_HTTP_ERROR = "Failed to run rest API:\n{}"
+    REST_AUTH_MISSING_ARG = "For '{}' authentication, '{}' is/are not provided in config file or "\
+                            "environment variable or through constructor argument 'auth'."
+    REST_NOT_CONFIGURED = "The argument '{}' is not set. {} endpoint not configured.\n" \
+                          "Try (re)copy the CLI configuration from {} UI -> Session Details -> CLI Config."
+    REST_DEVICE_CODE_NO_BOTH = "Token does not contain access_token or refresh_token. Received token: {}"
+    REST_DEVICE_CODE_GEN_FAILED = "Error generating the device code. Received code: {}."
+    REST_DEVICE_CODE_AUTH_FAILED = "Error authenticating the device code.\n{}."
+
+    INFO_NOT_PROVIDED_USE_DEFAULT = "{} is not provided in path '{}' method '{}' for operationID '{}' using default {}."
+    OTF_TABLE_REQUIRED = "{} is supported only with OTF table."
+

teradataml/common/messages.py

@@ -196,7 +196,15 @@ class Messages():
             [ErrorInfoCodes.TARGET_COL_NOT_FOUND_FOR_EVALUATE, MessageCodes.TARGET_COL_NOT_FOUND_FOR_EVALUATE],
             [ErrorInfoCodes.SET_REQUIRED_PARAMS, MessageCodes.SET_REQUIRED_PARAMS],
             [ErrorInfoCodes.MISSING_ARGS, MessageCodes.CONNECTION_PARAMS],
-            [ErrorInfoCodes.DEPENDENT_METHOD, MessageCodes.DEPENDENT_METHOD]
+            [ErrorInfoCodes.DEPENDENT_METHOD, MessageCodes.DEPENDENT_METHOD],
+            [ErrorInfoCodes.REST_HTTP_ERROR, MessageCodes.REST_HTTP_ERROR],
+            [ErrorInfoCodes.REST_AUTH_MISSING_ARG, MessageCodes.REST_AUTH_MISSING_ARG],
+            [ErrorInfoCodes.REST_NOT_CONFIGURED, MessageCodes.REST_NOT_CONFIGURED],
+            [ErrorInfoCodes.REST_DEVICE_CODE_NO_BOTH, MessageCodes.REST_DEVICE_CODE_NO_BOTH],
+            [ErrorInfoCodes.REST_DEVICE_CODE_GEN_FAILED, MessageCodes.REST_DEVICE_CODE_GEN_FAILED],
+            [ErrorInfoCodes.REST_DEVICE_CODE_AUTH_FAILED, MessageCodes.REST_DEVICE_CODE_AUTH_FAILED],
+            [ErrorInfoCodes.INFO_NOT_PROVIDED_USE_DEFAULT, MessageCodes.INFO_NOT_PROVIDED_USE_DEFAULT],
+            [ErrorInfoCodes.OTF_TABLE_REQUIRED, MessageCodes.OTF_TABLE_REQUIRED]
     ]
 
     @staticmethod

teradataml/common/sqlbundle.py

@@ -70,8 +70,9 @@ class SQLBundle:
                 [SQLConstants.SQL_EXEC_STORED_PROCEDURE, "call {0}"],
                 [SQLConstants.SQL_SELECT_COLUMNNAMES_WITH_WHERE, "sel {0} from {1} where {2}"],
                 [SQLConstants.SQL_HELP_DATABASE, "HELP DATABASE {0}"],
-                [SQLConstants.SQL_HELP_DATALAKE, "HELP DATALAKE {0}"]
-
+                [SQLConstants.SQL_HELP_DATALAKE, "HELP DATALAKE {0}"],
+                [SQLConstants.SQL_TD_OTF_METADATA, "SELECT * FROM {0}(ON ({1})) D;"],
+                [SQLConstants.SQL_TD_OTF_SNAPSHOT, "SELECT * FROM {0} FOR SNAPSHOT AS OF {1};"]
         ]
         self._add_sql_version()