Teradata Package for Python Function Reference - 17.00 - setup_sandbox_env - Teradata Package for Python

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
April 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)
teradataml.table_operators.sandbox_container_util.setup_sandbox_env = setup_sandbox_env(sandbox_image_location=None, sandbox_image_name=None, container_id=None, timeout=5000)
DESCRIPTION:
    Function to either load sandbox image and start a new docker container by passing
    the "sandbox_image_location" and "sandbox_image_name" or
    start an existing container using the argument "container_id".
    Note:
        1. Teradata recommends to run this function once before running
           test_script() method of Script.
        2. Sandbox image loading on user's system is skipped if the image is already
           loaded.
        3. There can be only one container started from within teradataml at any given
           point.
        4. At the end of the session image loaded / container started by the function
           will be cleaned up.
        5. If the user wishes to manually cleanup image / container started by the
           function, they can use cleanup_sandbox_env().
        6. User should be careful while providing "sandbox_image_location" and
           "sandbox_image_name". If an incorrect "sandbox_image_name" is provided that
           does not match with the name / tag of the image to be loaded then:
               a. The image will not be loaded. User should re-run the function with
                  correct "sandbox_image_name".
               b. If the user's system already has an image with the image name / tag
                  same as the image specified in "sandbox_image_location" then the new image
                  will be loaded and it might replace the old image.
 
PARAMETERS:
    sandbox_image_location:
        Optional Argument.
        Specifies the path to the sandbox image on user's system.
        Types: str
        Notes:
            1. For location to download sandbox image refer teradataml User Guide.
            2. After loading the image, a container will be created and started.
            3. "sandbox_image_location" and "sandbox_image_name" must be
               specified together.
 
    sandbox_image_name:
        Optional Argument.
        Specifies the name of the sandbox image that was used for generating the image.
        This will be used for starting a container.
        Types: str
        Note:
            1. "sandbox_image_location" and "sandbox_image_name" must be
               specified together.
            2. If the "sandbox_image_name" is incorrect then the image will not be
               loaded.
 
    container_id:
        Optional Argument. Required if "sandbox_image_location" and
        "sandbox_image_name" are not specified.
        Specifies id of an existing docker container.
        Types: str
        Note:
            User should be careful while specifying this argument.
            If this argument is specified to start the container then this container
            will be cleaned up at the end of the session.
 
    timeout:
        Optional Argument.
        Specifies timeout value for docker API calls. This is particularly useful
        while loading large sandbox images. User should increase the "timeout" value
        if image loading fails because of timeout.
        Default Value: 5000
        Types: int
 
RETURNS:
    None.
 
RAISES:
    Warning, docker.errors.APIError, docker.errors.NotFound, TeradataMlException,
    Exception.
 
EXAMPLES:
    >>> from teradataml.table_operators.sandbox_container_util import setup_sandbox_env
    # Example 1: Load the image from the location specified in "sandbox_image_location"
    # argument and start a container.
    # This is useful when the user wants to setup sandbox environment with a new image.
    >>> setup_sandbox_env(sandbox_image_location='/tmp/stosandbox.tar.gz',
                          sandbox_image_name='stosandbox:1.0')
        Loading image from /tmp/stosandbox.tar.gz. It may take few minutes.
        Image loaded successfully.
        Container c1dd4d4b722cc54b643ab2bdc57540a3a3e6db98c299defc672227de97d2c345
        started successfully.
 
    # Example 2: Start an existing container specified in "container_id" argument.
    # This is useful when the user wants to run user script in an existing container.
    >>> setup_sandbox_env(container_id='3fadb1e8bac3')
        Container 3fadb1e8bac3 started successfully.