Teradata Package for Python Function Reference on VantageCloud Lake - update_lib - Teradata Package for Python - Look here for syntax, methods and examples for the functions included in the Teradata Package for Python.

Teradata® Package for Python Function Reference on VantageCloud Lake

Deployment
VantageCloud
Edition
Lake
Product
Teradata Package for Python
Release Number
20.00.00.03
Published
December 2024
ft:locale
en-US
ft:lastEdition
2024-12-19
dita:id
TeradataPython_FxRef_Lake_2000
Product Category
Teradata Vantage
teradataml.scriptmgmt.UserEnv.UserEnv.update_lib = update_lib(self, libs=None, libs_file_path=None, **kwargs)
DESCRIPTION:
    Function updates Python or R libraries if already installed,
    otherwise installs the libraries in remote user environment.
    Notes:
        * Use "install_lib" API call for first time package installation within
          the environment. Use "update_lib" API only to upgrade or downgrade installed
          packages and do not use it for fresh package installation when multiple
          packages have the same dependency as it messes pip's package resolution ability.
        * Use "update_lib" to update packages one at a time to prevent dependency resolution
          issues.
 
 
PARAMETERS:
    libs:
        Optional Argument.
        Specifies the library name(s).
        Notes:
            *   Either "libs" or "libs_file_path" argument must be specified.
            *   While passing the libraries as string or list of
                strings, one should adhere to the requirements
                specified by underlying language's package manager.
                For conda environment:
                *   Only library name(s) should be specified. Library version
                    cannot be specified.
                    Conda only updates the installed packages to the latest
                    compatible version and cannot update to a specific version.
                For R environment:
                *   Refer to allowed formats here:
                    https://remotes.r-lib.org/reference/install_version.html
                *   Specifying as a character vector is not supported as one
                    of the accepted value.
                *   Whitespace is required between comparator operator(s) and
                    version.
                *   '==' should be used for exact version, '=' is not allowed.
        Types: str OR list of Strings(str)
 
    libs_file_path:
        Optional Argument.
        Specifies the absolute/relative path of the file (including file name)
        which supplies a list of libraries to be updated from the remote user
        environment. Path specified should include the filename with extension.
        The file should contain library name and version number(optional) of
        libraries.
        Notes:
            *   Either "libs" or "libs_file_path" argument must be specified.
            *   The file must have ".txt" extension for Python environment
                and ".txt"/".json" extension for R environment.
            *   The file format should adhere to the specifications of the
                requirements file used by underlying language's package
                manager for updating libraries.
                Sample text file content for Python environment:
                    numpy
                    joblib==0.13.2
                Sample json/txt file content for R environment:
                    {
                        "cran_packages": [{
                            "name": "anytime",
                            "version": "0.3.9"
                        }, {
                            "name": "glm2",
                            "version": ">= 1.1.2, < 1.2"
                        }]
                    }
            * For conda environment:
                The file should only contain the package names.
                Library version cannot be specified. Conda only updates the
                installed packages to the latest compatible version and
                cannot update to a specific version.
        Types: str
 
**kwargs:
    asynchronous:
        Optional Argument.
        Specifies whether to update the library in remote user environment
        synchronously or asynchronously. When set to True, libraries are updated
        asynchronously. Otherwise, libraries are updated synchronously.
        Note:
            One should not use remove_env() on the same environment till the
            asynchronous call is complete.
        Default Value: False
        Types: bool
 
    timeout:
        Optional Argument.
        Specifies the time to wait in seconds for updating the libraries. If the library is
        not updated 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:
    claim_id, to track status.
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    # Examples for Python environment.
    # Create remote Python user environment.
    >>> testenv = create_env('testenv', 'python_3.7.9', 'Test environment')
    User environment testenv created.
 
    # Example 1: Update a single Python library asynchronously.
    # Install a Python library.
    >>> testenv.install_lib(["joblib==0.13.2"], asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id 'f44443a9-42c3-4fd3-b4a2-735d1bfb7c27'.
 
    # Check the status.
    >>> testenv.status('f44443a9-42c3-4fd3-b4a2-735d1bfb7c27')
                                   Claim Id       File/Libs  Method Name     Stage             Timestamp Additional Details
    0  f44443a9-42c3-4fd3-b4a2-735d1bfb7c27  joblib==0.13.2  install_lib  Finished  2022-07-13T11:54:31Z               None
    >>>
 
    # Verify joblib library is installed with specified version.
    >>> testenv.libs
          library version
    0      joblib  0.13.2
    1         pip  20.1.1
    2  setuptools  47.1.0
 
    # Update joblib libary to the new version specified.
    >>> testenv.update_lib("joblib==0.14.1", asynchronous=True)
    Request to update libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id '8bfe55fc-efaa-44c7-9137-af24b6bb9ef8'.
 
    # Check the status.
    >>> testenv.status('8bfe55fc-efaa-44c7-9137-af24b6bb9ef8')
                                   Claim Id       File/Libs Method Name     Stage             Timestamp Additional Details
    0  8bfe55fc-efaa-44c7-9137-af24b6bb9ef8  joblib==0.14.1  update_lib  Finished  2022-07-13T11:55:29Z               None
    >>>
 
    # Verify joblib library version is updated with specified version.
    >>> testenv.libs
          library version
    0      joblib  0.14.1
    1         pip  20.1.1
    2  setuptools  47.1.0
 
    # Example 2: Update multiple Python libraries synchronously.
    >>> testenv.update_lib(["joblib==0.14.1","numpy==1.19.5"])
                                   Claim Id                      File/Libs Method Name     Stage             Timestamp Additional Details
    0  28e0e03e-469b-440c-a939-a0e8a901078f  joblib==0.14.1, numpy==1.19.5  update_lib   Started  2022-07-13T11:56:32Z               None
    1  28e0e03e-469b-440c-a939-a0e8a901078f  joblib==0.14.1, numpy==1.19.5  update_lib  Finished  2022-07-13T11:56:34Z               None
    >>>
 
    # Verify if numpy is installed with the specific version.
    >>> testenv.libs
          library version
    0      joblib  0.14.1
    1       numpy  1.19.5
    2         pip  20.1.1
    3  setuptools  47.1.0
 
    # Example 3: update libraries specified in the requirements text file asynchrnously.
    # Create a requirement.txt file with below contents.
    -----------------------------------------------------------
    numpy==1.21.6
    -----------------------------------------------------------
    >>> testenv.update_lib(libs_file_path="requirement.txt", asynchronous=True)
    Request to update libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id 'd3301da5-f5cb-4248-95dc-a59e77fe9db5'.
 
    # Verify if numpy is updated to the specific version.
    >>> testenv.libs
          library version
    0      joblib  0.14.1
    1       numpy  1.21.6
    2         pip  20.1.1
    3  setuptools  47.1.0
 
    # Example 4: Downgrade the Python library joblib to 0.13.2 synchronously by specifying timeout.
    # As higher version of the package is not automatically uninstalled, we need to uninstall the higher version
    # to use the lower version.
    >>> testenv.uninstall_lib("joblib", asynchronous=True)
    Request to uninstall libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id 'e32d69d9-452b-4600-be4b-1d5c60647a54'.
 
    >>> testenv.status('e32d69d9-452b-4600-be4b-1d5c60647a54')
                                   Claim Id File/Libs    Method Name     Stage             Timestamp Additional Details
    0  e32d69d9-452b-4600-be4b-1d5c60647a54    joblib  uninstall_lib   Started  2022-07-13T11:59:14Z               None
    1  e32d69d9-452b-4600-be4b-1d5c60647a54    joblib  uninstall_lib  Finished  2022-07-13T11:59:17Z               None
    >>>
 
    # Verify if joblib package is uninstalled or not.
    >>> testenv.libs
          library version
    0         pip  20.1.1
    1  setuptools  47.1.0
 
    >>> testenv.update_lib(["joblib==0.13.2"], timeout=1)
    Request to update libraries initiated successfully in the remote user environment 'testenv' but unable to get the status. Check the status using status() with the claim id 'ca669e5b-bd2c-4037-ae65-e0147954b85d'.
    'ca669e5b-bd2c-4037-ae65-e0147954b85d'
 
    # Check the status.
    >>> testenv.status('ca669e5b-bd2c-4037-ae65-e0147954b85d')
                                   Claim Id       File/Libs Method Name     Stage             Timestamp Additional Details
    0  ca669e5b-bd2c-4037-ae65-e0147954b85d  joblib==0.13.2  update_lib   Started  2022-07-13T11:57:41Z               None
    1  ca669e5b-bd2c-4037-ae65-e0147954b85d  joblib==0.13.2  update_lib  Finished  2022-07-13T11:57:47Z               None
    >>>
 
    # Listing the available libraries.
    >>> testenv.libs
          library version
    0      joblib  0.13.2
    1         pip  20.1.1
    2  setuptools  47.1.0
    >>>
 
    # Examples for R environment.
    # Create remote R user environment.
    >>> r_env = create_env('test_r_env', 'r_4.1', 'Test R environment')
    User environment 'test_r_env' created.
    >>>
 
    # Install R libraries in environment.
    >>> r_env.install_lib(['glm2', 'stringi', "plyr"])
                                     Claim Id              File/Libs     Method Name       Stage               Timestamp    Additional Details
    0    6b9c006a-35a6-4f98-ab88-7010af98c3b9    glm2, stringi, plyr     install_lib     Started    2023-09-15T17:14:12Z
    1    6b9c006a-35a6-4f98-ab88-7010af98c3b9    glm2, stringi, plyr     install_lib    Finished    2023-09-15T17:16:37Z
    >>>
 
    # Verify installed libraries.
    >>> r_env.libs
              name  version
    0   KernSmooth  2.23-20
    1         MASS   7.3-55
    2       Matrix    1.4-0
    3         base    4.1.3
    4         boot   1.3-28
    5        class   7.3-20
    6      cluster    2.1.2
    ..         ...      ...
    31        glm2    1.2.1
    32        plyr    1.8.8
    33     stringi   1.7.12
    >>>
 
    # Example 5: Update single R library synchronously which is not present.
    #            in environment. This installs the library with specified
    #            version.
    >>> r_env.update_lib('dplyr== 1.1.1')
                                     Claim Id        File/Libs    Method Name        Stage                Timestamp    Additional Details
    0    44d7ef77-e904-4bb9-bc6f-fd10e6294d2d    dplyr== 1.1.1     update_lib      Started     2023-09-15T17:58:23Z
    1    44d7ef77-e904-4bb9-bc6f-fd10e6294d2d    dplyr== 1.1.1     update_lib     Finished     2023-09-15T18:01:23Z
    >>>
 
    # Verify if library is installed with correct version.
    >>> r_env.libs
              name  version
    0   KernSmooth  2.23-20
    1         MASS   7.3-55
    2       Matrix    1.4-0
    3         base    4.1.3
    ..         ...      ...
    33       dplyr    1.1.1
    ..         ...      ...
    37        glm2    1.2.1
    ..         ...      ...
    43        plyr    1.8.8
    ..         ...      ...
    45     stringi   1.7.12
    ..         ...      ...
    50       withr    2.5.0
    >>>
 
    # Example 6: Downgrade multiple R libraries synchronously
    #            by passing them as a list of library names.
    >>> r_env.update_lib(['stringi== 1.1.5', 'dplyr== 1.0.8'])
                                     Claim Id                         File/Libs      Method Name       Stage                Timestamp    Additional Details
    0    0b481a55-66c5-41b3-bba6-bec553274538    stringi== 1.1.5, dplyr== 1.0.8       update_lib     Started     2023-09-15T18:11:00Z
    1    0b481a55-66c5-41b3-bba6-bec553274538    stringi== 1.1.5, dplyr== 1.0.8       update_lib    Finished     2023-09-15T18:15:11Z
    >>>
 
    # Verify if libraries are downgraded.
    >>> r_env.libs
    0   KernSmooth  2.23-20
    1         MASS   7.3-55
    2       Matrix    1.4-0
    3         base    4.1.3
    ..         ...      ...
    33       dplyr    1.0.8
    ..         ...      ...
    37        glm2    1.2.1
    ..         ...      ...
    43        plyr    1.8.8
    ..         ...      ...
    45     stringi    1.1.5
    ..         ...      ...
    50       withr    2.5.0
    >>>
 
    # Example 7: Update libraries synchronously by specifying
    #            them in a file.
 
    # Create a requirement.json file with below contents.
    -----------------------------------------------------------
    {
        "cran_packages":
            [{
                "name": "dplyr",
                "version": "1.1.1"
            },
            {
                "name": "glm2",
                "version": ">= 1.1.2, < 1.2"
            }]
    }
    -----------------------------------------------------------
 
    # Update libraries specified in the file.
    >>> r_env.update_lib(libs_file_path="requirement.json")
                                     Claim Id           File/Libs    Method Name        Stage               Timestamp    Additional Details
    0    3399d416-8daa-49b5-a608-55e15fcbe89e    requirement.json     update_lib      Started    2023-09-15T18:23:24Z
    1    3399d416-8daa-49b5-a608-55e15fcbe89e    requirement.json     update_lib     Finished    2023-09-15T18:26:33Z
    >>>
 
    # Verify if libraries are updated.
    >>> r_env.libs
              name  version
    0   KernSmooth  2.23-20
    1         MASS   7.3-55
    2       Matrix    1.4-0
    3         base    4.1.3
    ..         ...      ...
    33       dplyr    1.1.1
    ..         ...      ...
    37        glm2    1.1.3
    ..        ...       ...
    43        plyr    1.8.8
    ..        ...       ...
    45     stringi    1.1.5
    ..        ...       ...
    50       withr    2.5.0
    >>>
 
    # Example 8: Update R libraries asynchronously.
    >>> r_env.update_lib(["plyr== 1.0.3", "glm2<= 1.1.1"], asynchronous=True)
    Request to update libraries initiated successfully in the remote user environment r2_env_spk. Check the status using status() with the claim id '81c60527-88c8-4372-9336-c3bd7793b2b1'.
    '81c60527-88c8-4372-9336-c3bd7793b2b1'
    >>>
 
    # Check the status using claim id.
    >>> r_env.status('81c60527-88c8-4372-9336-c3bd7793b2b1')
                                     Claim Id                     File/Libs    Method Name        Stage                Timestamp    Additional Details
    0    81c60527-88c8-4372-9336-c3bd7793b2b1    plyr== 1.0.3, glm2== 1.1.1     update_lib      Started     2023-09-15T18:35:02Z
    1    81c60527-88c8-4372-9336-c3bd7793b2b1    plyr== 1.0.3, glm2== 1.1.1     update_lib     Finished     2023-09-15T18:35:19Z
    >>>
 
    # Verify if libraries are updated.
    >>> r_env.libs
              name  version
    0   KernSmooth  2.23-20
    1         MASS   7.3-55
    2       Matrix    1.4-0
    3         base    4.1.3
    ..         ...      ...
    33       dplyr    1.1.1
    ..         ...      ...
    37        glm2    1.1.1
    ..         ...      ...
    43        plyr    1.0.3
    ..         ...      ...
    45     stringi    1.1.5
    ..         ...      ...
    50       withr    2.5.0
>>>