teradataml.scriptmgmt.UserEnv.UserEnv.install_lib = install_lib(self, libs=None, libs_file_path=None, **kwargs)

DESCRIPTION:
    Function installs Python or R libraries in the remote user environment.
    Note:
        * 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.
 
PARAMETERS:
    libs:
        Optional Argument.
        Specifies the add-on library name(s).
        Notes:
            *   Either "libs" or "libs_file_path" argument must be specified.
            *   Version specified during the installation of R libraries
                is not taken into consideration. The versions specified
                in the parameters are only considered when update_lib()
                is used.
        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 installed in remote user environment.
        Path specified should include the filename with extension.
        The file should contain library names 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 to install 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": ""
                        }, {
                            "name": "glm2",
                            "version": ""
                        }]
                    }
            *   Version specified during the installation of R libraries
                is not taken into consideration. The versions specified in
                the parameters are only considered when update_lib() is used.
        Types: str
 
**kwargs:
    asynchronous:
        Optional Argument.
        Specifies whether to install the library in remote user environment
        synchronously or asynchronously. When set to True, libraries are installed
        asynchronously. Otherwise, libraries are installed 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 installing the libraries. If the library 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:
    Pandas DataFrame when libraries are installed synchronously.
    claim_id, to track status when libraries are installed asynchronously.
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    # Create remote user Python environment.
    >>> env = create_env('testenv', 'python_3.7.9', 'Test environment')
    User environment testenv created.
 
    # Example 1: Install single Python library asynchronously.
    >>> env.install_lib('numpy', asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id '4b062b0e-6e9f-4996-b92b-5b20ac23b0f9'.
 
    # Check the status.
    >>> env.status('4b062b0e-6e9f-4996-b92b-5b20ac23b0f9')
                                   Claim Id File/Libs  Method Name     Stage             Timestamp Additional Details
    0  4b062b0e-6e9f-4996-b92b-5b20ac23b0f9     numpy  install_lib   Started  2022-07-13T11:07:34Z               None
    1  4b062b0e-6e9f-4996-b92b-5b20ac23b0f9     numpy  install_lib  Finished  2022-07-13T11:07:35Z               None
    >>>
 
    # Verify if libraries are installed.
    >>> env.libs
          library version
    0       numpy  1.21.6
    1         pip  20.1.1
    2  setuptools  47.1.0
 
    # Example 2: Install libraries asynchronously by passing them as list of library names.
    >>> env.install_lib(["pandas",
    ...                   "joblib==0.13.2",
    ...                   "scikit-learn",
    ...                   "numpy>=1.17.1",
    ...                   "nltk>=3.3,<3.5"], asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id '90aae7df-5efe-4b5a-af26-150aab35f1fb'.
 
    # Check the status.
    >>> env.status('90aae7df-5efe-4b5a-af26-150aab35f1fb')
                                   Claim Id                                                           File/Libs  Method Name     Stage             Timestamp Additional Details
    0  90aae7df-5efe-4b5a-af26-150aab35f1fb pandas, joblib==0.13.2, scikit-learn, numpy>=1.17.1, nltk>=3.3,<3.5  install_lib   Started  2022-07-13T11:09:39Z               None
    1  90aae7df-5efe-4b5a-af26-150aab35f1fb pandas, joblib==0.13.2, scikit-learn, numpy>=1.17.1, nltk>=3.3,<3.5  install_lib  Finished  2022-07-13T11:09:40Z               None
 
    # Verify if libraries are installed with specific version.
    >>> env.libs
                library version
    0            joblib  0.13.2
    1              nltk   3.4.5
    2             numpy  1.21.6
    3            pandas   1.3.5
    4               pip  20.1.1
    5   python-dateutil   2.8.2
    6              pytz  2022.1
    7      scikit-learn   1.0.2
    8             scipy   1.7.3
    9        setuptools  47.1.0
    10              six  1.16.0
    11    threadpoolctl   3.1.0
 
    # Example 3: Install libraries synchronously by passing them as list of library names.
    >>> env.install_lib(["Flask", "gunicorn"])
                                   Claim Id        File/Libs  Method Name     Stage             Timestamp Additional Details
    0  ebc11a82-4606-4ce3-9c90-9f54d1260f47  Flask, gunicorn  install_lib   Started  2022-08-12T05:35:58Z
    1  ebc11a82-4606-4ce3-9c90-9f54d1260f47  Flask, gunicorn  install_lib  Finished  2022-08-12T05:36:13Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> env.libs
                      name version
    0                click   8.1.3
    1                Flask   2.2.2
    2             gunicorn  20.1.0
    3   importlib-metadata  4.12.0
    4         itsdangerous   2.1.2
    5               Jinja2   3.1.2
    6               joblib  0.13.2
    7           MarkupSafe   2.1.1
    8                 nltk   3.4.5
    9                numpy  1.21.6
    10              pandas   1.3.5
    11                 pip  20.1.1
    12     python-dateutil   2.8.2
    13                pytz  2022.2
    14        scikit-learn   1.0.2
    15               scipy   1.7.3
    16          setuptools  64.0.1
    17                 six  1.16.0
    18       threadpoolctl   3.1.0
    19   typing-extensions   4.3.0
    20            Werkzeug   2.2.2
    21                zipp   3.8.1
    >>>
 
    # Example 4: Install libraries synchronously by passing them as list of library names within a
    #            specific timeout of 5 seconds.
    >>> env.install_lib(["teradataml",  "teradatasqlalchemy"], timeout=5)
    Request to install libraries initiated successfully in the remote user environment 'testenv' but unable to get the status. Check the status using status() with the claim id '30185e0e-bb09-485a-8312-c267fb4b3c1b'.
    '30185e0e-bb09-485a-8312-c267fb4b3c1b'
 
    # Check the status.
    >>> env.status('30185e0e-bb09-485a-8312-c267fb4b3c1b')
                                   Claim Id                       File/Libs  Method Name     Stage             Timestamp Additional Details
    0  30185e0e-bb09-485a-8312-c267fb4b3c1b  teradataml, teradatasqlalchemy  install_lib   Started  2022-08-12T05:42:58Z
    1  30185e0e-bb09-485a-8312-c267fb4b3c1b  teradataml, teradatasqlalchemy  install_lib  Finished  2022-08-12T05:43:29Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> env.libs
                      name    version
    0              certifi  2022.6.15
    1   charset-normalizer      2.1.0
    2                click      8.1.3
    3               docker      5.0.3
    4                Flask      2.2.2
    5             greenlet      1.1.2
    6             gunicorn     20.1.0
    7                 idna        3.3
    8   importlib-metadata     4.12.0
    9         itsdangerous      2.1.2
    10              Jinja2      3.1.2
    11              joblib     0.13.2
    12          MarkupSafe      2.1.1
    13                nltk      3.4.5
    14               numpy     1.21.6
    15              pandas      1.3.5
    16                 pip     20.1.1
    17              psutil      5.9.1
    18        pycryptodome     3.15.0
    19     python-dateutil      2.8.2
    20                pytz     2022.2
    21            requests     2.28.1
    22        scikit-learn      1.0.2
    23               scipy      1.7.3
    24          setuptools     64.0.1
    25                 six     1.16.0
    26          SQLAlchemy     1.4.40
    27          teradataml  17.10.0.1
    28         teradatasql  17.20.0.1
    29  teradatasqlalchemy   17.0.0.3
    30       threadpoolctl      3.1.0
    31   typing-extensions      4.3.0
    32             urllib3    1.26.11
    33    websocket-client      1.3.3
    34            Werkzeug      2.2.2
    35                zipp      3.8.1
    >>>
 
    # Example 5: Install libraries asynchronously by creating requirement.txt file.
    # Create a requirement.txt file with below contents.
    -----------------------------------------------------------
    pandas
    joblib==0.13.2
    scikit-learn
    numpy>=1.17.1
    nltk>=3.3,<3.5
    -----------------------------------------------------------
 
    # Install libraries specified in the file.
    >>> env.install_lib(libs_file_path="requirement.txt", asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id 'f11c7f28-f958-4cae-80a8-926733954bdc'.
 
    # Check the status.
    >>> env.status('8709b464-f144-4c37-8918-ef6a98ecf295')
                                   Claim Id         File/Libs  Method Name     Stage             Timestamp Additional Details
    0  f11c7f28-f958-4cae-80a8-926733954bdc  requirements.txt  install_lib   Started  2022-07-13T11:23:23Z               None
    1  f11c7f28-f958-4cae-80a8-926733954bdc  requirements.txt  install_lib  Finished  2022-07-13T11:25:37Z               None
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> env.libs
                library version
    0            joblib  0.13.2
    1              nltk   3.4.5
    2             numpy  1.21.6
    3            pandas   1.3.5
    4               pip  20.1.1
    5   python-dateutil   2.8.2
    6              pytz  2022.1
    7      scikit-learn   1.0.2
    8             scipy   1.7.3
    9        setuptools  47.1.0
    10              six  1.16.0
    11    threadpoolctl   3.1.0
 
    # Example 6: Install libraries synchronously by creating requirement.txt file.
    # Create a requirement.txt file with below contents.
    -----------------------------------------------------------
    matplotlib
    -----------------------------------------------------------
 
    # Install libraries specified in the file.
    >>> env.install_lib(libs_file_path="requirements.txt")
                                   Claim Id         File/Libs  Method Name     Stage             Timestamp Additional Details
    0  6221681b-f663-435c-80a9-3f99d2af5d83  requirements.txt  install_lib   Started  2022-08-12T05:49:09Z
    1  6221681b-f663-435c-80a9-3f99d2af5d83  requirements.txt  install_lib  Finished  2022-08-12T05:49:41Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> env.libs
                      name    version
    0              certifi  2022.6.15
    1   charset-normalizer      2.1.0
    2                click      8.1.3
    3               cycler     0.11.0
    4               docker      5.0.3
    5                Flask      2.2.2
    6            fonttools     4.34.4
    7             greenlet      1.1.2
    8             gunicorn     20.1.0
    9                 idna        3.3
    10  importlib-metadata     4.12.0
    11        itsdangerous      2.1.2
    12              Jinja2      3.1.2
    13              joblib     0.13.2
    14          kiwisolver      1.4.4
    15          MarkupSafe      2.1.1
    16          matplotlib      3.5.3
    17                nltk      3.4.5
    18               numpy     1.21.6
    19           packaging       21.3
    20              pandas      1.3.5
    21              Pillow      9.2.0
    22                 pip     20.1.1
    23              psutil      5.9.1
    24        pycryptodome     3.15.0
    25           pyparsing      3.0.9
    26     python-dateutil      2.8.2
    27                pytz     2022.2
    28            requests     2.28.1
    29        scikit-learn      1.0.2
    30               scipy      1.7.3
    31          setuptools     64.0.1
    32                 six     1.16.0
    33          SQLAlchemy     1.4.40
    34          teradataml  17.10.0.1
    35         teradatasql  17.20.0.1
    36  teradatasqlalchemy   17.0.0.3
    37       threadpoolctl      3.1.0
    38   typing-extensions      4.3.0
    39             urllib3    1.26.11
    40    websocket-client      1.3.3
    41            Werkzeug      2.2.2
    42                zipp      3.8.1
    >>>
 
    # Create remote user R environment.
    >>> env = create_env('testenv', 'r_4.1', 'Test environment')
    User environment 'testenv' created.
 
    # Example 1: Install single R library asynchronously.
    >>> env.install_lib('glm2', asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id 'd073a1c8-08bc-45d0-99de-65dc189db408'.
 
    # Check the status.
    >>> env.status('d073a1c8-08bc-45d0-99de-65dc189db408')
 
                                Claim Id        File/Libs       Method Name        Stage              Timestamp         Additional Details
    0   d073a1c8-08bc-45d0-99de-65dc189db408    glm2    install_lib        Started        2023-08-29T09:09:30Z
    1   d073a1c8-08bc-45d0-99de-65dc189db408    glm2    install_lib        Finished       2023-08-29T09:09:35Z
    >>>
 
    # Verify if libraries are installed.
    >>> 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
    7    codetools   0.2-18
    8     compiler    4.1.3
    9     datasets    4.1.3
    10     foreign   0.8-82
    11   grDevices    4.1.3
    12    graphics    4.1.3
    13        grid    4.1.3
    14     lattice  0.20-45
    15     methods    4.1.3
    16        mgcv   1.8-39
    17        nlme  3.1-155
    18        nnet   7.3-17
    19    parallel    4.1.3
    20     remotes    2.4.2
    21       rpart   4.1.16
    22     spatial   7.3-15
    23     splines    4.1.3
    24       stats    4.1.3
    25      stats4    4.1.3
    26    survival   3.2-13
    27       tcltk    4.1.3
    28       tools    4.1.3
    29       utils    4.1.3
    30        glm2    1.2.1
    >>>
 
    # Example 2: Install libraries asynchronously by passing them as list of library names.
    >>> env.install_lib(['glm2', 'stringi'], asynchronous=True)
    Request to install libraries initiated successfully in the remote user environment testenv.
    Check the status using status() with the claim id '6b2ca7ac-f113-440c-bf24-1ce75ed59f36'.
 
    # Check the status.
    >>> env.status('90aae7df-5efe-4b5a-af26-150aab35f1fb')
 
                                    Claim Id    File/Libs                   Method Name    Stage          Timestamp                Additional Details
    0   6b2ca7ac-f113-440c-bf24-1ce75ed59f36    glm2==1.2.1, stringi    install_lib        Started        2023-08-29T09:42:39Z
    1   6b2ca7ac-f113-440c-bf24-1ce75ed59f36    glm2==1.2.1, stringi    install_lib        Finished       2023-08-29T09:43:58Z
    >>>
 
    # Verify if libraries are installed or not.
    >>> 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
    7    codetools   0.2-18
    8     compiler    4.1.3
    9     datasets    4.1.3
    10     foreign   0.8-82
    11   grDevices    4.1.3
    12    graphics    4.1.3
    13        grid    4.1.3
    14     lattice  0.20-45
    15     methods    4.1.3
    16        mgcv   1.8-39
    17        nlme  3.1-155
    18        nnet   7.3-17
    19    parallel    4.1.3
    20     remotes    2.4.2
    21       rpart   4.1.16
    22     spatial   7.3-15
    23     splines    4.1.3
    24       stats    4.1.3
    25      stats4    4.1.3
    26    survival   3.2-13
    27       tcltk    4.1.3
    28       tools    4.1.3
    29       utils    4.1.3
    30        glm2    1.2.1
    31     stringi   1.7.12
    >>>
 
    # Example 3: Install libraries synchronously by passing them as list of library names.
    >>> env.install_lib(["lubridate", "zoo"])
                                    Claim Id    File/Libs           Method Name   Stage      Timestamp            Additional Details
    0   7483fa01-dedb-4fb2-9262-403da6b49a3b    lubridate, zoo  install_lib       Started        2023-08-29T09:51:25Z
    1   7483fa01-dedb-4fb2-9262-403da6b49a3b    lubridate, zoo  install_lib       Finished       2023-08-29T09:52:20Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> 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
    7    codetools   0.2-18
    8     compiler    4.1.3
    9     datasets    4.1.3
    10     foreign   0.8-82
    11   grDevices    4.1.3
    12    graphics    4.1.3
    13        grid    4.1.3
    14     lattice  0.20-45
    15     methods    4.1.3
    16        mgcv   1.8-39
    17        nlme  3.1-155
    18        nnet   7.3-17
    19    parallel    4.1.3
    20     remotes    2.4.2
    21       rpart   4.1.16
    22     spatial   7.3-15
    23     splines    4.1.3
    24       stats    4.1.3
    25      stats4    4.1.3
    26    survival   3.2-13
    27       tcltk    4.1.3
    28       tools    4.1.3
    29       utils    4.1.3
    30       cpp11    0.4.6
    31    generics    0.1.3
    32        glm2    1.2.1
    33   lubridate    1.9.2
    34     stringi   1.7.12
    35  timechange    0.2.0
    36         zoo   1.8-12
    >>>
    
    # Example 4: Install libraries synchronously by passing them as list of library names within a
    #            specific timeout of 1 seconds.
    >>> env.install_lib(["stringi",  "glm2"], timeout=1)
    Request to install libraries initiated successfully in the remote user environment 'testenv' but Timed out
    status check. Check the status using status() with the claim id '7303cf6d-acea-4ab0-83b8-e6cf9149fe51'.
 
    # Check the status.
    >>> env.status('7303cf6d-acea-4ab0-83b8-e6cf9149fe51')
                                    Claim Id    File/Libs           Method Name    Stage          Timestamp                Additional Details
    0   7303cf6d-acea-4ab0-83b8-e6cf9149fe51    stringi, glm2   install_lib        Started        2023-08-29T10:18:48Z
    1   7303cf6d-acea-4ab0-83b8-e6cf9149fe51    stringi, glm2   install_lib        Finished       2023-08-29T10:20:08Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> 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
    7    codetools   0.2-18
    8     compiler    4.1.3
    9     datasets    4.1.3
    10     foreign   0.8-82
    11   grDevices    4.1.3
    12    graphics    4.1.3
    13        grid    4.1.3
    14     lattice  0.20-45
    15     methods    4.1.3
    16        mgcv   1.8-39
    17        nlme  3.1-155
    18        nnet   7.3-17
    19    parallel    4.1.3
    20     remotes    2.4.2
    21       rpart   4.1.16
    22     spatial   7.3-15
    23     splines    4.1.3
    24       stats    4.1.3
    25      stats4    4.1.3
    26    survival   3.2-13
    27       tcltk    4.1.3
    28       tools    4.1.3
    29       utils    4.1.3
    30       cpp11    0.4.6
    31    generics    0.1.3
    32        glm2    1.2.1
    33   lubridate    1.9.2
    34     stringi   1.7.12
    35  timechange    0.2.0
    36         zoo   1.8-12
    >>>
 
    # Example 5: Install libraries synchronously by creating requirement.txt file.
    # Create a requirement.txt file with below contents.
    -----------------------------------------------------------
    {
        "cran_packages": [{
            "name": "anytime",
            "version": ""
        }, {
            "name": "glm2",
            "version": ""
        }]
    }
    -----------------------------------------------------------
 
    # Install libraries specified in the file.
    >>> env.install_lib(libs_file_path="requirement.txt")
                                    Claim Id    File/Libs             Method Name       Stage       Timestamp            Additional Details
    0   eab69326-5e14-4c81-8157-408fe0b633c2    requirement.txt   install_lib   Started     2023-08-29T12:18:26Z
    1   eab69326-5e14-4c81-8157-408fe0b633c2    requirement.txt   install_lib   Finished        2023-08-29T12:23:12Z
    >>>
 
    # Verify if libraries are installed with specific version.
    >>> 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
    7    codetools    0.2-18
    8     compiler     4.1.3
    9     datasets     4.1.3
    10     foreign    0.8-82
    11   grDevices     4.1.3
    12    graphics     4.1.3
    13        grid     4.1.3
    14     lattice   0.20-45
    15     methods     4.1.3
    16        mgcv    1.8-39
    17        nlme   3.1-155
    18        nnet    7.3-17
    19    parallel     4.1.3
    20     remotes     2.4.2
    21       rpart    4.1.16
    22     spatial    7.3-15
    23     splines     4.1.3
    24       stats     4.1.3
    25      stats4     4.1.3
    26    survival    3.2-13
    27       tcltk     4.1.3
    28       tools     4.1.3
    29       utils     4.1.3
    30          BH  1.81.0-1
    31        Rcpp    1.0.11
    32     anytime     0.3.9
    33       cpp11     0.4.6
    34    generics     0.1.3
    35        glm2     1.2.1
    36   lubridate     1.9.2
    37     stringi    1.7.12
    38  timechange     0.2.0
    39         zoo    1.8-12
    >>>