Pipenv 的基本用法 — pipenv 文档

Pipenv 的基本用法

https://farm4.staticflickr.com/3931/33173826122_b7ee8f1a26_k_d.jpg 本文档涵盖了 Pipenv 的一些更基本的功能。

☤ 示例 Pipfile 和 Pipfile.lock

Pipfiles 包含项目依赖项的信息，并取代了大多数 Python 项目中使用的 requirements.txt 文件。 您应该在 Git 存储库中添加一个 Pipfile，让克隆存储库的用户知道唯一需要的是在机器上安装 Pipenv 并输入 pipenv install。 Pipenv 是使用 Pipfile 的参考实现。

这是一个 Pipfile 和结果 Pipfile.lock 的简单示例。

示例 Pipfile

[[../source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"


[dev-packages]
pytest = "*"

示例 Pipfile.lock

{
    "_meta": {
        "hash": {
            "sha256": "8d14434df45e0ef884d6c3f6e8048ba72335637a8631cc44792f52fd20b6f97a"
        },
        "host-environment-markers": {
            "implementation_name": "cpython",
            "implementation_version": "3.6.1",
            "os_name": "posix",
            "platform_machine": "x86_64",
            "platform_python_implementation": "CPython",
            "platform_release": "16.7.0",
            "platform_system": "Darwin",
            "platform_version": "Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64",
            "python_full_version": "3.6.1",
            "python_version": "3.6",
            "sys_platform": "darwin"
        },
        "pipfile-spec": 5,
        "requires": {},
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.python.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {
        "certifi": {
            "hashes": [
                "sha256:54a07c09c586b0e4c619f02a5e94e36619da8e2b053e20f594348c0611803704",
                "sha256:40523d2efb60523e113b44602298f0960e900388cf3bb6043f645cf57ea9e3f5"
            ],
            "version": "==2017.7.27.1"
        },
        "chardet": {
            "hashes": [
                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691",
                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae"
            ],
            "version": "==3.0.4"
        },
        "idna": {
            "hashes": [
                "sha256:8c7309c718f94b3a625cb648ace320157ad16ff131ae0af362c9f21b80ef6ec4",
                "sha256:2c6a5de3089009e3da7c5dde64a141dbc8551d5b7f6cf4ed7c2568d0cc520a8f"
            ],
            "version": "==2.6"
        },
        "requests": {
            "hashes": [
                "sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b",
                "sha256:9c443e7324ba5b85070c4a818ade28bfabedf16ea10206da1132edaa6dda237e"
            ],
            "version": "==2.18.4"
        },
        "urllib3": {
            "hashes": [
                "sha256:06330f386d6e4b195fbfc736b297f58c5a892e4440e54d294d7004e3a9bbea1b",
                "sha256:cc44da8e1145637334317feebd728bd869a35285b93cbb4cca2577da7e62db4f"
            ],
            "version": "==1.22"
        }
    },
    "develop": {
        "py": {
            "hashes": [
                "sha256:2ccb79b01769d99115aa600d7eed99f524bf752bba8f041dc1c184853514655a",
                "sha256:0f2d585d22050e90c7d293b6451c83db097df77871974d90efd5a30dc12fcde3"
            ],
            "version": "==1.4.34"
        },
        "pytest": {
            "hashes": [
                "sha256:b84f554f8ddc23add65c411bf112b2d88e2489fd45f753b1cae5936358bdf314",
                "sha256:f46e49e0340a532764991c498244a60e3a37d7424a532b3ff1a6a7653f1a403a"
            ],
            "version": "==3.2.2"
        }
    }
}

☤ 一般建议和版本控制

• 通常，将 Pipfile 和 Pipfile.lock 都保留在版本控制中。
• 如果针对多个版本的 Python，不要将 Pipfile.lock 保留在版本控制中。
• 在 Pipfile 的 [requires] 部分中指定目标 Python 版本。 理想情况下，您应该只有一个目标 Python 版本，因为这是一个部署工具。 python_version 的格式应为 X.Y（或 X），而 python_full_version 的格式应为 X.Y.Z。
• pipenv install 与 pip install 语法完全兼容，完整文档可在 此处 找到。
• 请注意，Pipfile 使用 TOML Spec。

☤ Pipenv 工作流示例

克隆/创建项目存储库：

$ cd myproject

从 Pipfile 安装，如果有的话：

$ pipenv install

或者，向您的新项目添加一个包：

$ pipenv install <package>

如果不存在，这将创建一个 Pipfile。 如果确实存在，它将自动使用您提供的新包进行编辑。

接下来，激活 Pipenv shell：

$ pipenv shell
$ python --version

这将产生一个新的 shell 子进程，可以使用 exit 停用它。

☤ Pipenv 升级工作流程示例

• 找出上游发生了什么变化：$ pipenv update --outdated。
• *; 升级包，两种选择：

  *;# 想要升级一切？ 只需做 $ pipenv update。

  1. 想要一次升级一个软件包？ $ pipenv update <pkg> 每个过时的包。

☤ 从requirements.txt 导入

如果你在运行 pipenv install 时只有一个 requirements.txt 文件可用，pipenv 会自动导入这个文件的内容并为你创建一个 Pipfile。

您还可以指定 $ pipenv install -r path/to/requirements.txt 来导入需求文件。

如果您的需求文件已固定版本号，您可能需要编辑新的 Pipfile 以删除它们，并让 pipenv 跟踪固定。 如果您想暂时保留 Pipfile.lock 中的固定版本，请运行 pipenv lock --keep-outdated。 确保尽快升级！

☤ 指定包的版本

您可以使用 语义版本控制方案 （即 major.minor.micro）。

例如，要安装请求，您可以使用：

$ pipenv install requests~=1.2

Pipenv 将安装版本 1.2 和任何小更新，但不会安装 2.0。

这将自动更新您的 Pipfile 以反映此要求。

通常，Pipenv 使用与 pip 相同的说明符格式。 但是，请注意，根据 PEP 440 ，您不能使用包含连字符或加号的版本。

要进行包含或排除版本比较，您可以使用：

$ pipenv install "requests>=1.4"   # will install a version equal or larger than 1.4.0
$ pipenv install "requests<=2.13"  # will install a version equal or lower than 2.13.0
$ pipenv install "requests>2.19"   # will install 2.19.1 but not 2.19.0

笔记

在包和版本规范周围使用双引号（即 强烈建议使用 "requests>2.19") 以避免在基于 Unix 的操作系统中出现 输入和输出重定向 问题。

使用 ~= 优于 == 标识符，因为后者阻止 pipenv 更新包：

$ pipenv install "requests~=2.2"  # locks the major version of the package (this is equivalent to using ==2.*)

为了避免安装特定版本，您可以使用 != 标识符。

有关有效标识符和更复杂用例的深入解释，请查看 PEP-440 的相关部分。

☤ 指定 Python 的版本

要创建一个新的 virtualenv，使用您已安装的特定版本的 Python（并在您的 PATH 上），使用 --python VERSION 标志，如下所示：

使用 Python 3：

$ pipenv --python 3

使用 Python3.6：

$ pipenv --python 3.6

使用 Python 2.7.14：

$ pipenv --python 2.7.14

当给定 Python 版本时，像这样，Pipenv 将自动扫描您的系统以查找与该给定版本匹配的 Python。

如果尚未创建 Pipfile，则会为您创建一个，如下所示：

[[../source]]
url = "https://pypi.python.org/simple"
verify_ssl = true

[dev-packages]

[packages]

[requires]
python_version = "3.6"

笔记

包含 [requires] python_version = "3.6" 指定您的应用程序需要此版本的 Python，并且将在将来针对此 Pipfile 运行 pipenv install 时自动使用（例如 在其他机器上）。 如果这不是真的，请随意删除此部分。

如果您没有在命令行中指定 Python 版本，则 [requires] python_full_version 或 python_version 将被自动选择，回退到您系统的默认值 python 安装是，在执行的时候。

☤ 可编辑的依赖项（例如 -e . )

你可以告诉 Pipenv 安装一个可编辑的路径——这通常在处理包时对当前工作目录很有用：

$ pipenv install --dev -e .

$ cat Pipfile
...
[dev-packages]
"e1839a8" = {path = ".", editable = true}
...

笔记

所有子依赖项也将添加到 Pipfile.lock 中。 如果您不使用 -e 选项，则子依赖项将 不会 添加到 Pipfile.lock。

☤ 使用 Pipenv 进行环境管理

您将用于管理 pipenv 环境的三个主要命令是 $ pipenv install、$ pipenv uninstall 和 $ pipenv lock。

$ pipenv 安装

$ pipenv install 用于将软件包安装到 pipenv 虚拟环境中并更新您的 Pipfile。

连同采用以下形式的基本安装命令：

$ pipenv install [package names]

用户可以提供这些附加参数：

• --two — 使用系统 python2 链接在 virtualenv 中执行安装。
• --three — 使用系统 python3 链接在 virtualenv 中执行安装。
• --python — 使用提供的 Python 解释器在 virtualenv 中执行安装。

警告

以上命令均不应一起使用。 它们也是 破坏性 并且会在用适当版本的虚拟环境替换之前删除您当前的 virtualenv。

笔记

Pipenv 创建的 virtualenv 可能与您期望的不同。 危险字符（即 $`!*@" 以及空格、换行、回车和制表符）转换为下划线。 此外，当前文件夹的完整路径被编码为“slug 值”并附加以确保 virtualenv 名称是唯一的。

• --dev — 从 Pipfile 安装 develop 和 default 软件包。
• --system — 使用系统 pip 命令，而不是来自您的 virtualenv 的命令。
• --deploy — 确保包在 Pipfile.lock 中正确锁定，如果锁定文件已过期则中止。
• --ignore-pipfile — 忽略 Pipfile 并从 Pipfile.lock 安装。
• --skip-lock — 忽略 Pipfile.lock 并从 Pipfile 安装。 另外，不要写出反映Pipfile变化的Pipfile.lock。

$ pipenv 卸载

$ pipenv uninstall 支持 pipenv install 中的所有参数，以及两个附加选项，--all 和 --all-dev。

• --all — 此参数将从虚拟环境中清除所有文件，但保持 Pipfile 不变。
• --all-dev — 此参数将从虚拟环境中删除所有开发包，并将它们从 Pipfile 中删除。

$ pipenv 锁

$ pipenv lock 用于创建一个 Pipfile.lock，它声明您的项目的 all 依赖项（和子依赖项）、它们的最新可用版本以及下载的当前哈希值文件。 这确保了可重复，最重要的是 确定性 构建。

☤ 关于外壳配置

外壳通常被错误配置为子外壳使用，因此 $ pipenv shell --fancy 可能会产生意想不到的结果。 如果是这种情况，请尝试使用“兼容模式”的 $ pipenv shell，尽管配置错误，它仍会尝试生成子 shell。

正确的 shell 配置仅在登录会话期间设置环境变量，例如 PATH，而不是在每个子 shell 生成期间（因为它们通常被配置为这样做）。 在鱼中，这看起来像这样：

if status --is-login
    set -gx PATH /usr/local/bin $PATH
end

你也应该在你的 shell 中这样做，在你的 ~/.profile 或 ~/.bashrc 或任何合适的地方。

笔记

shell 以交互模式启动。 这意味着，如果您的 shell 从交互模式的特定文件中读取其配置（例如 bash 默认为交互模式查找 ~/.bashrc 配置文件），然后您需要修改（或创建）此文件。

如果您在使用 $ pipenv shell 时遇到问题，只需检查 PIPENV_SHELL 环境变量，如果可用，$ pipenv shell 将使用该环境变量。 具体参见【X16X】☤ 带环境变量的配置【X62X】。

☤ 关于 VCS 依赖的注意事项

您可以使用根据以下规则格式化的 URL 从 git 和其他版本控制系统安装带有 pipenv 的包：

<vcs_type>+<scheme>://<location>/<user_or_organization>/<repository>@<branch_or_tag>#egg=<package_name>

唯一的可选部分是 @<branch_or_tag> 部分。 当通过 SSH 使用 git 时，您可以使用速记 vcs 和方案别名 git+git@<location>:<user_or_organization>/<repository>@<branch_or_tag>#<package_name>。 请注意，这在解析时会转换为 git+ssh://git@<location>。

请注意，强烈建议 在可编辑模式下安装任何版本控制的依赖项，使用 pipenv install -e，以确保可以使用最新的副本执行依赖项解析每次执行时都包含存储库，并且它包含所有已知的依赖项。

下面是一个示例用法，它从标签 v2.20.1 安装位于 https://github.com/requests/requests.git 的 git 存储库作为包名称 requests：

$ pipenv install -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests
Creating a Pipfile for this project...
Installing -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests...
[...snipped...]
Adding -e git+https://github.com/requests/requests.git@v2.20.1#egg=requests to Pipfile's [packages]...
[...]

$ cat Pipfile
[packages]
requests = {git = "https://github.com/requests/requests.git", editable = true, ref = "v2.20.1"}

<vcs_type> 的有效值包括 git、bzr、svn 和 hg。 <scheme> 的有效值包括 http、https、ssh 和 file。 在特定情况下，您还可以使用其他方案：svn 可以与 svn 组合作为方案，而 bzr 可以与 sftp 和 [ X168X]。

您可以在此处 阅读更多关于 pip 实现 VCS 支持的信息 。 有关指定 VCS 依赖项时可用的其他选项的更多信息，请查看 Pipfile 规范 。

☤ Pipfile.lock 安全功能

Pipfile.lock 利用了 pip 中一些重要的新安全改进。 默认情况下，Pipfile.lock 将使用每个下载包的 sha256 哈希值生成。 这将允许 pip 保证您在受感染的网络上安装您打算安装的内容，或从不受信任的 PyPI 端点下载依赖项。

我们强烈建议通过将项目从开发环境提升到生产来进行部署。 您可以使用 pipenv lock 编译您对开发环境的依赖项，并将编译后的 Pipfile.lock 部署到您的所有生产环境以进行可重现的构建。

笔记

如果您想要锁定文件的 requirements.txt 输出，请运行 $ pipenv lock -r。 然而，这将包括所有散列（这很棒！）。 要获得没有哈希值的 requirements.txt，请使用 $ pipenv run pip freeze。