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: As supported by the teradata driver.
        Notes:
            1. teradataml expects the client environments are already setup with appropriate
               security mechanisms and are in working conditions.
            2. User must have a valid ticket-granting ticket in order to use KRB5 (Kerberos) logon mechanism.
            3. User must use logdata parameter when using 'JWT' as the logon mechanism.
            4. Browser Authentication is supported for Windows and macOS.
            For more information please refer Teradata Vantage™ - Advanced SQL Engine
            Security Administration at https://www.info.teradata.com/
        Types: str
 
    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
 
    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)