pipfile 0.0.2

Pipfile
=======

``Pipfile``及其姐妹``Pipfile.lock``是现有标准`pip`_'s ``requirements.txt``文件的替代品。

警告：该项目处于积极设计和开发中。在此阶段，一切尚未确定。

此存储库包含``Pipfile``格式的规范设计，以及（很快）一个用于规范的解释器实现，该实现可以被`pip`_和任何其他消费者使用，一旦设计（包括``Pipfile``本身的形式）已经构建并最终确定。

.. _`pip`: https://pip.pythonlang.cn/en/stable/


概念
-----------

``Pipfile``将在许多方面优于``requirements.txt``文件

* 使用`TOML <https://github.com/toml-lang/toml>`_语法声明所有类型的Python依赖项。
* 一个Pipfile（而不是多个``requirements.txt``文件）。

* 现有的需求文件往往扩散到多个文件中 - 例如 ``dev-requirements.txt``、``test-requirements.txt`` 等 - 但 ``Pipfile`` 允许在一个地方无缝地指定依赖项组。
* 这将显示为仅两个内置组 (*default* 和 *development*)。 (见下文注释)

* 以 ``Pipfile.lock`` 的形式提供完全指定（且 *确定性*）的环境。
部署的应用程序可以通过引用 ``Pipfile.lock`` 文件，完全重新部署，所有递归依赖项的版本都与之前相同。

Python 应用程序的具体需求将来自 ``Pipfile``。这包括包的来源及其宽松的版本约束。

环境的详细信息（所有已安装的具有固定版本的包和其他详细信息）将存储在 ``Pipfile.lock`` 中，以确保可重现性。此文件将自动生成，不应由用户修改。

注意：将来可能会添加自定义组。记住，将来添加功能比删除它们更容易。

Composer 社区多年来一直成功地将 *default* 和 *development* 作为组选项。最初将尝试/遵循此模型。


示例
--------

注意：这是一个持续进行中的作品。

``Pipfile``
+++++++++++

::

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

[requires]
python_version = '2.7'

[packages]
requests = { extras = ['socks'] }
Django = '>1.10'
pinax = { git = 'git://github.com/pinax/pinax.git', ref = '1.4', editable = true }

[dev-packages]
nose = '*'

注释

- 将有一个默认的 ``source``。

**PEP 508 支持**
+++++++++++++++++++

::

# 支持所有 PEP 508 标记
[requires]
python_full_version = '3.6.0b1'

platform = 'windows'

``requires`` 利用 `PEP 508`_ ``marker = 'specifier'`` 标记。此功能可能不会立即使用，因为它仅用于在特定平台（例如 Python 版本、平台版本）上断言（因此如果适当则中止）安装。

.. _`PEP 508`: https://pythonlang.cn/dev/peps/pep-0508/#environment-markers

``Pipfile.lock``
++++++++++++++++

::

{
"_meta": {
"hash": {
"sha256": "73d81f4fbe42d1da158c5d4435d921121a4a1013b2f0dfed95367f3c742b88c6",
},
"requires": [
{"marker": "python_version", "specifier": "2.7"}
],
"sources": [
{"url": "https://pypi.python.org/simple", "verify_ssl": true},
]
},
"default": [
{"name": "Django", "version": "1.10.3", "hash": "..."},
{"name": "requests", "version": "2.12.1", "hash": "..."},
{"name": "pinax", "git": "git://...", "ref": "1.4", "editable": true},
{"name": "PySocks", "version": "1.5.6", "hash": "..."},
],
"development": [
{"name": "nose", "version": "1.3.7", "hash": "..."},
]
}

``Pipfile.lock`` 总是生成，不应由用户修改或构建。

请注意，每个依赖项的版本都是递归冻结的，并计算出一个散列值，以便您可以利用 `new pip security features`_

.. _`new pip security features`: https://pip.pythonlang.cn/en/stable/reference/pip_install/#hash-checking-mode

Pip 集成（最终）
++++++++++++++++++++++++++

`pip`_ 将增长新的命令行选项 ``-p`` / ``--pipfile``，以安装 ``Pipfile`` 中指定的版本，类似于它现有的 ``-r`` / ``--requirement`` 参数，用于安装 ``requirements.txt`` 文件。

从 ``Pipfile`` 安装包：

$ pip install -p
! 警告：Pipfile.lock (48d35f) 已过时。更新到 (73d81f)。
从 requirements.piplock... 安装包...
[安装输出]

要手动更新 ``Pipfile.lock``：

$ pip freeze -p different_pipfile
different_pipfile.lock (73d81f) 写入磁盘。

注释：

# -p 接受一个路径参数，默认为 'Pipfile'。
# Pipfile.lock 将在 `install -p` 过程中自动写入，如果不存在的话。

想法：

- 当 ``-p`` 为空时，递归地在父目录中查找 `Pipfile`（限制 3/4？）。


有用的链接
------------

- `pypa/pip#1795`_: Requirements 2.0
- `基本概念概要`_ (源自 @dstufft 的)

.. _`基本概念概要`: https://gist.github.com/kennethreitz/4745d35e57108f5b766b8f6ff396de85
.. _`pypa/pip#1795`: https://github.com/pypa/pip/issues/1795

灵感来源
++++++++++++

- `nvie/pip-tools`_: 一组保持已锁定Python依赖项更新的工具。
- Kenneth Reitz 的《更好的 Pip 工作流程》_
- 从 Composer、Cargo、Yarn、NPM、Bundler 及其朋友那里学到的经验。

.. _`nvie/pip-tools`: https://github.com/nvie/pip-tools
.. _《更好的 Pip 工作流程》: https://www.kennethreitz.org/essays/a-better-pip-workflow


文档
-------------

本项目文档最终将位于 pypi.org。

.. _`文档`: https://pipfile.pypa.io/


讨论
----------

如果遇到错误，您可以在我们的 `问题跟踪器`_ 中提交。您还可以加入 Freenode 的 ``#pypa`` 频道来提问或参与。

.. _`问题跟踪器`: https://github.com/pypa/pipfile/issues


行为准则
---------------

所有与 pipfile 项目的代码库、问题跟踪器、聊天室和邮件列表互动的人应遵循 `PyPA 行为准则`_。

.. _`PyPA 行为准则`: https://www.pypa.io/en/latest/code-of-conduct/

变更日志
---------

16.0 - `master`_
~~~~~~~~~~~~~~~~~

.. note:: 此版本尚未发布，正处于积极开发中。


* 首次发布。


.. _`master`: https://github.com/pypa/pipfile/