teradataml.scriptmgmt.UserEnv.UserEnv.install_file = install_file(self, file_path, replace=False, **kwargs)

DESCRIPTION:
    Function installs or replaces a file from client machine to the remote user environment created in
    Vantage Languages Ecosystem.
    * If the size of the file is more than 10 MB, the function installs the file synchronously
      and returns the status of installation when 'asynchronous' is set to False. Otherwise, the
      function installs the file asynchronously and returns claim-id to check the installation status
      using status().
    * If the size of the file is less than or equal to 10 MB, the function installs the
      file synchronously and returns the status of installation.
 
PARAMETERS:
    file_path:
        Required Argument.
        Specifies absolute or relative path of the file (including file name) to be installed in the
        remote user environment.
        Types: str
 
    replace:
        Optional Argument.
        Specifies if the file should be forcefully replaced in remote user environment.
        * When set to True,
           * If the file already exists in remote user environment, it will be replaced with the file
             specified by argument "file_path".
           * If the file does not already exist in remote user environment, then the specified file will
             be installed.
        * Argument is ignored when file size <= 10MB.
        Default Value: False
        Types: bool
 
**kwargs:
    Specifies the keyword arguments.
        suppress_output:
            Optional Argument.
            Specifies whether to print the output message or not.
            When set to True, then the output message is not printed.
            Default Value: False
            Types: bool
 
    asynchronous:
        Optional Argument.
        Specifies whether to install the file in remote user environment
        synchronously or asynchronously. When set to True, file is installed
        asynchronously. Otherwise, file is installed synchronously.
        Note:
            Argument is ignored when file size <= 10MB.
        Default Value: False
        Types: bool
 
    timeout:
        Optional Argument.
        Specifies the time to wait in seconds for installing the file. If the file is
        not installed with in "timeout" seconds, the function returns a claim-id and one
        can check the status using the claim-id. If "timeout" is not specified, then there
        is no limit on the wait time.
        Note:
             Argument is ignored when "asynchronous" is True.
        Types: int OR float
 
RETURNS:
    True, if the file size is less than or equal to 10 MB and operation is successful.
    str(claim-id), if the file size is greater than 10 MB.
 
RAISES:
    TeradataMlException.
 
EXAMPLES:
    # Create remote user environment.
    >>> env = create_env('testenv', 'python_3.7.9', 'Test environment')
    User environment testenv created.
 
    # Create conda environment.
    >>> testenv_conda = create_env('testenv_conda', 'python_3.8', 'Test conda environment', conda_env=True)
    Conda environment creation initiated
    User environment 'testenv_conda' created.
 
    # Example 1: Install the file mapper.py in the 'testenv' environment.
    >>> import os, teradataml
    >>> file_path = os.path.join(os.path.dirname(teradataml.__file__), "data", "scripts", "mapper.py")
    >>> env.install_file(file_path = file_path)
    File 'mapper.py' installed successfully in the remote user environment 'testenv'.
 
    # Example 2: Replace the file mapper.py.
    >>> file_path = os.path.join(os.path.dirname(teradataml.__file__), "data", "scripts", "mapper.py")
    >>> env.install_file(file_path = file_path, replace=True)
    File 'mapper.py' replaced successfully in the remote user environment 'testenv'.
 
    # Example 3: Install the file 'large_file' asynchronously with 'large_file' found in
                 temp folder and check the status of installation.
    # Note:
    #     Running this example creates a file 'large_file' with size
    #     approximately 11MB in the temp folder.
    >>> import tempfile, os
    >>> def create_large_file():
    ...     file_name = os.path.join(tempfile.gettempdir(),"large_file")
    ...     with open(file_name, 'xb') as fp:
    ...         fp.seek((1024 * 1024 * 11) - 1)
    ...         fp.write(b' ')
    ...
    >>> create_large_file()
    >>> claim_id = env.install_file(file_path = os.path.join(tempfile.gettempdir(),"large_file"), asynchronous=True)
    File installation is initiated. Check the status using status() with the claim id 76588d13-6e20-4892-9686-37768adcfadb.
    >>> env.status(claim_id)
                                    Claim Id              File/Libs    Method Name               Stage             Timestamp Additional Details
    0   76588d13-6e20-4892-9686-37768adcfadb             large_file   install_file       File Uploaded  2022-07-13T10:34:02Z               None
    >>> env.status(claim_id, stack=True)
                                    Claim Id              File/Libs    Method Name               Stage             Timestamp Additional Details
    0   76588d13-6e20-4892-9686-37768adcfadb             large_file   install_file  Endpoint Generated  2022-07-13T10:34:00Z               None
    1   76588d13-6e20-4892-9686-37768adcfadb             large_file   install_file       File Uploaded  2022-07-13T10:34:02Z               None
    2   76588d13-6e20-4892-9686-37768adcfadb             large_file   install_file      File Installed  2022-07-13T10:34:08Z               None
 
    # Example 4: Install the file 'large_file' synchronously with 'large_file' found in
                 temp folder and check the status of installation.
    # Note:
    #     Running this example creates a file 'large_file' with size
    #     approximately 11MB in the temp folder.
    >>> import tempfile, os
    >>> def create_large_file():
    ...     file_name = os.path.join(tempfile.gettempdir(), "large_file")
    ...     with open(file_name, 'xb') as fp:
    ...         fp.seek((1024 * 1024 * 11) - 1)
    ...         fp.write(b' ')
    ...
    >>> create_large_file()
    >>> result = env.install_file(file_path = os.path.join(tempfile.gettempdir(),"large_file"))
 
    >>> result
                                    Claim Id              File/Libs    Method Name               Stage             Timestamp Additional Details
    0   87588d13-5f20-3461-9686-46668adcfadb             large_file   install_file  Endpoint Generated  2022-07-13T10:34:00Z               None
    1   87588d13-5f20-3461-9686-46668adcfadb             large_file   install_file       File Uploaded  2022-07-13T10:34:02Z               None
    2   87588d13-5f20-3461-9686-46668adcfadb             large_file   install_file      File Installed  2022-07-13T10:34:08Z               None
 
    >>> os.remove(os.path.join(tempfile.gettempdir(),"large_file")) # Remove the file created using function 'create_large_file'.
 
    # Example 5: Install the file mapper.py in the 'testenv_conda' environment.
    >>> import os, teradataml
    >>> file_path = os.path.join(os.path.dirname(teradataml.__file__), "data", "scripts", "mapper.py")
    >>> testenv_conda.install_file(file_path = file_path)
    File 'mapper.py' installed successfully in the remote user environment 'testenv_conda'.
 
    # Remove the environment.
    >>> remove_env('testenv')
    User environment 'testenv' removed.
    >>> remove_env("testenv_conda")
    User environment 'testenv_conda' removed.