teradataml.context.context.create_context = create_context(host=None, username=None, password=None, tdsqlengine=None, temp_database_name=None, logmech=None, logdata=None, database=None, url_encode=True, **kwargs)

DESCRIPTION:
    Creates a connection to the Teradata Vantage using the teradatasql + teradatasqlalchemy DBAPI and dialect
    combination. Users can pass all required parameters (host, username, password) for establishing a connection to
    Vantage, or pass a sqlalchemy engine to the tdsqlengine parameter to override the default DBAPI and dialect
    combination.
 
    Note:
        1. teradataml requires that the user has certain permissions on the user's default database or the initial
           default database specified using the database argument, or the temporary database when specified using
           temp_database_name. These permissions allow the user to:
            a. Create tables and views to save results of teradataml analytic functions.
            b. Create views in the background for results of DataFrame APIs such as assign(),
               filter(), etc., whenever the result for these APIs are accessed using a print().
            c. Create view in the background on the query passed to the DataFrame.from_query() API.
 
           It is expected that the user has the correct permissions to create these objects in the database that
           will be used.
           The access to the views created may also require issuing additional GRANT SELECT ... WITH GRANT OPTION
           permission depending on which database is used and which object the view being created is based on.
 
        2. The temp_database_name and database parameters play a crucial role in determining which database
           is used by default to lookup for tables/views while creating teradataml DataFrame using 'DataFrame()'
           and 'DataFrame.from_table()' and which database is used to create all internal temporary objects.
           +------------------------------------------------------+---------------------------------------------+
           |                     Scenario                         |            teradataml behaviour             |
           +------------------------------------------------------+---------------------------------------------+
           | Both temp_database_name and database are provided    | Internal temporary objects are created in   |
           |                                                      | temp_database_name, and database table/view |
           |                                                      | lookup is done from database.               |
           +------------------------------------------------------+---------------------------------------------+
           | database is provided but temp_database_name is not   | Database table/view lookup and internal     |
           |                                                      | temporary objects are created in database.  |
           +------------------------------------------------------+---------------------------------------------+
           | temp_database_name is provided but database is not   | Internal temporary objects are created in   |
           |                                                      | temp_database_name, database table/view     |
           |                                                      | lookup from the users default database.     |
           +------------------------------------------------------+---------------------------------------------+
           | Neither temp_database_name nor database are provided | Database table/view lookup and internal     |
           |                                                      | temporary objects are created in users      |
           |                                                      | default database.                           |
           +------------------------------------------------------+---------------------------------------------+
 
PARAMETERS:
    host:
        Optional Argument.
        Specifies the fully qualified domain name or IP address of the Teradata System.
        Types: str
    
    username:
        Optional Argument.
        Specifies the username for logging onto the Teradata Vantage.
        Types: str
    
    password:
        Optional Argument.
        Specifies the password required for the username.
        Types: str
        Note:
            * Encrypted passwords can also be passed to this argument, using Stored Password Protection feature.
              Examples section below demonstrates passing encrypted password to 'create_context'.
              More details on Stored Password Protection and how to generate key and encrypted password file
              can be found at https://pypi.org/project/teradatasql/#StoredPasswordProtection
            * Special characters that may be used in the password are encoded by default, except '~'.
              The encoding is done using urllib.parse library and can be
              disabled by setting "url_encode" = False.
              For example, if the password is: "kx%jj5/g", then this password is encoded as below:
              "kx%25jj5%2Fg"
               where,
                  %25 represents the '%' character and
                  %2F represents the '/' character
              The details of how the special characters are replaced can be found in the below link:
              "https://docs.microfocus.com/OMi/10.62/Content/OMi/ExtGuide/ExtApps/URL_encoding.htm".
              Note:
                  When password contains a space:
                    * "url_encode" must be set to False.
                    * In addition to space, other special characters in this password should be manually encoded,
                      following the link: https://docs.microfocus.com/OMi/10.62/Content/OMi/ExtGuide/ExtApps/URL_encoding.htm
                      Refer Example 16 in examples section for a detailed demonstration.
                  
                  When password contains unreserved characters like tilde("~"), dot("."), underscore("_"), hyphen("-"):
                    * Character is not URL encoded by default.
                    * If unreserved character in passed needs to be encoded then,
                      it must be encoded manually and encoded password must be passed, along with "url_encode" set to False.
                    * The unreserved characters differ from one Python version to another Python version.
                      For example, The encoding standards for Python version 3.7 found in the below link:
                      "https://docs.python.org/3/library/urllib.parse.html#url-quoting".
                  
        
    tdsqlengine:
        Optional Argument.
        Specifies Teradata Vantage sqlalchemy engine object that should be used to establish a Teradata Vantage
        connection.
        Types: str
        
    temp_database_name:
        Optional Argument.
        Specifies the temporary database name where temporary tables, views will be created.
        Types: str
        
    logmech:
        Optional Argument.
        Specifies the type of logon mechanism to establish a connection to Teradata Vantage. 
        Permitted Values: 'TD2', 'TDNEGO', 'LDAP', 'KRB5' & 'JWT'.
            TD2: 
                The Teradata 2 (TD2) mechanism provides authentication using a 
                Vantage username and password. This is the default logon mechanism
                using which the connection is established to Vantage.
            TDNEGO:
                A security mechanism that automatically determines the actual 
                mechanism required, based on policy, without user's involvement.
                The actual mechanism is determined by the TDGSS server configuration
                and by the security policy's mechanism restrictions.
            LDAP:
                A directory-based user logon to Vantage with a directory username
                and password and is authenticated by the directory.
            KRB5 (Kerberos):
                A directory-based user logon to Vantage with a domain username
                and password and is authenticated by Kerberos (KRB5 mechanism).
                Note: User must have a valid ticket-granting ticket in order to use this logon mechanism.
            JWT: 
                The JSON Web Token (JWT) authentication mechanism enables single 
                sign-on (SSO) to the Vantage after the user successfully authenticates
                to Teradata UDA User Service.
                Note: User must use logdata parameter when using 'JWT' as the logon mechanism.
        Types: str
 
        Note:
            teradataml expects the client environments are already setup with appropriate
            security mechanisms and are in working conditions.
            For more information please refer Teradata Vantage™ - Advanced SQL Engine
            Security Administration at https://www.info.teradata.com/
    
    logdata:
        Optional Argument.
        Specifies parameters to the LOGMECH command beyond those needed by the logon mechanism, such as 
        user ID, password and tokens (in case of JWT) to successfully authenticate the user.
        Types: str
 
    database:
        Optional Argument.
        Specifies the initial database to use after logon, instead of the user's default database.
        Types: str
 
    url_encode:
        Optional Argument.
        Specifies whether the password should be URL encoded or not.
        When set to True, passwords are URL encoded, otherwise not.
        Default Value: True
        Types: bool
 
    kwargs:
        Specifies the keyword-value pairs of connection parameters that are passed to Teradata SQL Driver for
        Python. Please refer to https://github.com/Teradata/python-driver#ConnectionParameters to get information
        on connection parameters of the driver.
        Note: When the type of a connection parameter is integer or boolean (eg: log, lob_support etc,.), pass
              integer or boolean value, instead of quoted integer or quoted boolean as suggested in the
              documentation. Please check the examples for usage.
 
RETURNS:
    A Teradata sqlalchemy engine object.
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    >>> from teradataml.context.context import *
 
    # Example 1: Create context using hostname, username and password
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword')
 
    # Example 2: Create context using already created sqlalchemy engine
    >>> from sqlalchemy import create_engine
    >>> sqlalchemy_engine  = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost)
    >>> td_context = create_context(tdsqlengine = sqlalchemy_engine)
 
    # Example 3: Creating context for Vantage with default logmech 'TD2'
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TD2')
 
   # Example 4: Creating context for Vantage with logmech as 'TDNEGO'
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TDNEGO')
 
    # Example 5: Creating context for Vantage with logmech as 'LDAP'
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP')
 
    # Example 6: Creating context for Vantage with logmech as 'KRB5'
    >>> td_context = create_context(host = 'tdhost', logmech='KRB5')
 
    # Example 7: Creating context for Vantage with logmech as 'JWT'
    >>> td_context = create_context(host = 'tdhost', logmech='JWT', logdata='token=eyJpc...h8dA')
 
    # Example 8: Create context using encrypted password and key passed to 'password' parameter.
    # The password should be specified in the format mentioned below:
    # ENCRYPTED_PASSWORD(file:<PasswordEncryptionKeyFileName>, file:<EncryptedPasswordFileName>)
    # The PasswordEncryptionKeyFileName specifies the name of a file that contains the password encryption key
    # and associated information.
    # The EncryptedPasswordFileName specifies the name of a file that contains the encrypted password and
    # associated information.
    # Each filename must be preceded by the 'file:' prefix. The PasswordEncryptionKeyFileName must be separated
    # from the EncryptedPasswordFileName by a single comma.
    >>> encrypted_password = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)"
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = encrypted_password)
 
    # Example 9: Create context using encrypted password in LDAP logon mechanism.
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = encrypted_password,
                                    logmech='LDAP')
 
   # Example 10: Create context using hostname, username, password and database parameters, and connect to a
   # different initial database by setting the database parameter.
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', database =
                                    'database_name')
 
    # Example 11: Create context using already created sqlalchemy engine, and connect to a different initial
    # database by setting the database parameter.
    >>> from sqlalchemy import create_engine
    >>> sqlalchemy_engine = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost +
                                           '/?DATABASE=database_name')
    >>> td_context = create_context(tdsqlengine = sqlalchemy_engine)
 
    # Example 12: Create context for Vantage with logmech as 'LDAP', and connect to a different initial
    # database by setting the database parameter.
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP',
                                    database = 'database_name')
 
    # Example 13: Create context using 'tera' mode with log value set to 8 and lob_support disabled.
    >>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', tmode = 'tera',
                                    log = 8, lob_support = False)
 
    # Example 14: Create context when password has special characters.
    # In this example password "alice@pass" is encoded by default.
    >>> td_context = create_context(host = 'tdhost', username='alice_pass', password = 'alice@pass')
        UserWarning: Warning: Password is URL encoded.
 
    # Example 15: Create context when password contains space and special characters.
    # "url_encode" must be set to False and special characters should be manually encoded in the password.
    # For example, let's say password is: "kx%jj5/ g"
    # then password should be manually encoded as: "kx%25jj5%2F g"
    # where,
    #     %25 represents the '%' character and
    #     %2F represents the '/' character
    #     space is not encoded.
    >>> td_context = create_context(host = 'tdhost', username='alice_pass', password = 'kx%25jj5%2F g',
                                    url_encode=False)