update_lib | Manage files and libs in User Environment | OpenAF - update_lib - Teradata Vantage

Teradata® VantageCloud Lake
Deployment
VantageCloud
Edition
Lake
Product
Teradata Vantage
Published
January 2023
Language
English (United States)
Last Update
2024-04-03
dita:mapPath
phg1621910019905.ditamap
dita:ditavalPath
pny1626732985837.ditaval
dita:id
phg1621910019905

Use the update_lib function to update Python or R libraries that are already installed.

Teradata recommends using this function for the following:
  • To upgrade or downgrade installed packages (not for first time package installation when multiple packages have the same dependency, as the function harms pip package resolution ability).
  • To update packages one at a time to prevent dependency resolution issues.

Optional Arguments

  • Either libs or libs_file_path argument must be specified.
  • For conda environment, when specifying libs or libs_file_path argument, specify only library names, not library version.

    Conda only updates the installed packages to the latest compatible version and cannot update to a specific version.

libs
Specifies the library names.
While passing the libraries as string or list of strings, adhere to the requirements specified by underlying language package manager.
For R environment:
  • Refer to allowed formats at: 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.
  • '==' must be used for exact version, '=' is not allowed.
libs_file_path
Specifies the absolute or relative path of the text file (including file name) which supplies a list of libraries to be updated in remote user environment.
The path specified must include the filename with extension.
The file must contain library names and version number of the libraries.
This file format must adhere to the specification of the requirements file used by underlying language's package manager for updating libraries.
The file must have a ".txt" extension for Python environment. Sample text file contents for Python:
        numpy
        joblib==0.13.2
The file must have a ".txt" or ".json" extension for R environment. Sample json file contents for R:
{
    "cran_packages": [{
        "name": "anytime",
        "version": "0.3.9"
    }, {
        "name": "glm2",
        "version": ">= 1.1.2, < 1.2"
    }]
}

**kwargs: Specifies the keyword arguments.

asynchronous
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.
Default value is False.
Do not use remove_env() on the same environment till the asynchronous call is complete.
timeout
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 you can check the status using the 'claim_id'. If timeout is not specified, then there is no limit on the wait time.
This argument is ignored when argument asynchronous is True.
The return of this function depends on whether libraries are installed asynchronously:
  • If libraries are installed synchronously, it returns a pandas DataFrame.
  • If libraries are installed asynchronously, it returns a string type 'claim_id' to track status.

Examples for Python environment

Example Prerequisite

Create remote user environment for the following examples 1-4.

>>> testenv = create_env('testenv', 'python_3.7.9', 'Test environment')
User environment testenv created.

Example 1: Update a single Python library asynchronously

  • Install Python library 'numpy'.
    >>> 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' library to the specified new version.
    >>> 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

  • Update libraries with specific versions.
    >>> 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 asynchronously

  • Create a requirement.txt file as follows.
    numpy==1.21.6
  • Update libraries specified in the file.
    >>> 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

Uninstall the newer version first to use the older version, as newer version of the package is not automatically uninstalled.
  • Uninstall the current version of the library.
    >>> 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'.
  • Check the status.
    >>> 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
  • Update 'joblib' to 0.13.2 with timeout.
    >>> 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
  • List 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

Example Prerequisite

Create remote R user environment for the following examples 5-8.

  • 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 the 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 the environment

This installs the library with the specified version.

  • Update the library.
    >>> 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 the specific 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 a list of library names

  • Update a list of libraries.
    >>> 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
              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.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 specified in a file synchronously

  • Create a requirement.json file with following 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

  • Update the libraries.
    >>> 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 status using the 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