.. default-domain:: bash

.. _get_pipenv:

==========
Get Pipenv
==========

.. file:: get_pipenv

Functions to help install pipenv with only python installed and no elevated privileges, no ``pip`` or ``sudo`` required

.. function:: install_pipenv

Install pipenv into a virtualenv. Does not need to have pip already installed and does not use privileged permissions. Makes use of the virtualenv zipapp, as per https://virtualenv.pypa.io/en/latest/installation.html#via-zipapp

While virtualenv documentation recommends download of the virtualenv zipapp file from https://bootstrap.pypa.io/virtualenv, this script instead downloads from https://github.com/pypa/get-virtualenv/ which offered versioned zipapp files.  This avoids possible breaking changes introduced at the pypa bootstrap site.

Prefer use of ``RECIPE_*`` environment variables (e.g., prefer ``RECIPE_PIPENV_VERSION`` over ``PIPENV_VERSION``). Pipenv uses ``PIPENV_{FLAG_NAME}`` to control command line execution via environment variables, as per https://github.com/pypa/pipenv/blob/master/CHANGELOG.rst#features--improvements-4. Use of ``PIPENV_VERSION`` to control the installed pipenv version may cause subsequent calls to pipenv to fail with the error ``Error: Invalid value for '--version': 2020.11.15 is not a valid boolean``.

Environment variables not starting with ``RECIPE_*`` may be deprecated in the future.

:Arguments: [``$1``] - The location of the virtualenv, defaults to ``${RECIPE_PIPENV_VIRTUALENV-${PIPENV_VIRTUALENV-${HOME}/pipenv}}``
:Parameters: * ``RECIPE_PIPENV_PYTHON`` or ``PIPENV_PYTHON`` - Optionally specify which python you want to use. Default is to favor python3, trying ``python3``, ``python``, then finally falling back to ``python2``.
             * ``RECIPE_PIPENV_VERSION`` or ``PIPENV_VERSION`` - The version of pipenv to install, defaults - ``2022.1.8``
             * ``RECIPE_VIRTUALENV_PYZ`` or ``VIRTUALENV_PYZ`` - Name of downloaded ``virtualenv.pyz``, else it will attempt to download it itself.
             * ``RECIPE_VIRTUALENV_VERSION`` or ``VIRTUALENV_VERSION`` - The version of virtualenv to use, affecting both the virtualenv zipapp version and the virtualenv version used by pipenv environment.  defaults to ``20.13.3``


.. function:: setup_container_pipenv

Sets up some additional behavior, useful in a container. Creates a symlink in the path to ``pipenv`` and adds a ``fake_package`` script to the bin directory for faking out local packages in pipenv during container build stages.

:Arguments: * [``$1``] - The location of the virtualenv, defaults to ``${HOME}/pipenv``
            * [``$2``] - The location of the symlink for pipenv, defaults to ``/usr/local/bin/pipenv``