| Server IP : 82.208.35.60 / Your IP : 216.73.217.33 Web Server : Apache/2.4.55 (FreeBSD) OpenSSL/1.1.1q-freebsd PHP/7.3.31 System : FreeBSD server7.d2m.cz 12.4-RELEASE-p9 FreeBSD 12.4-RELEASE-p9 GENERIC amd64 User : studiokobylisy_cz ( 1008) PHP Version : 7.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /usr/local/share/doc/py36-pip/development/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Vendoring Policy — pip 19.1.1 documentation</title>
<link rel="stylesheet" href="../_static/pypa.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '19.1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Release Notes" href="../news.html" />
<link rel="prev" title="Release process" href="release-process.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../news.html" title="Release Notes"
accesskey="N">next</a></li>
<li class="right" >
<a href="release-process.html" title="Release process"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://pypa.io">PyPA</a> »</li>
<a href="../index.html">pip 19.1.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Development</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="vendoring-policy">
<h1>Vendoring Policy<a class="headerlink" href="#vendoring-policy" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li>Vendored libraries <strong>MUST</strong> not be modified except as required to
successfully vendor them.</li>
<li>Vendored libraries <strong>MUST</strong> be released copies of libraries available on
PyPI.</li>
<li>Vendored libraries <strong>MUST</strong> be accompanied with LICENSE files.</li>
<li>The versions of libraries vendored in pip <strong>MUST</strong> be reflected in
<code class="docutils literal"><span class="pre">pip/_vendor/vendor.txt</span></code>.</li>
<li>Vendored libraries <strong>MUST</strong> function without any build steps such as <code class="docutils literal"><span class="pre">2to3</span></code> or
compilation of C code, practically this limits to single source 2.x/3.x and
pure Python.</li>
<li>Any modifications made to libraries <strong>MUST</strong> be noted in
<code class="docutils literal"><span class="pre">pip/_vendor/README.rst</span></code> and their corresponding patches <strong>MUST</strong> be
included <code class="docutils literal"><span class="pre">tasks/vendoring/patches</span></code>.</li>
<li>Vendored libraries should have corresponding <code class="docutils literal"><span class="pre">vendored()</span></code> entries in
<code class="docutils literal"><span class="pre">pip/_vendor/__init__.py</span></code>.</li>
</ul>
<div class="section" id="rationale">
<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
<p>Historically pip has not had any dependencies except for <code class="docutils literal"><span class="pre">setuptools</span></code> itself,
choosing instead to implement any functionality it needed to prevent needing
a dependency. However, starting with pip 1.5, we began to replace code that was
implemented inside of pip with reusable libraries from PyPI. This brought the
typical benefits of reusing libraries instead of reinventing the wheel like
higher quality and more battle tested code, centralization of bug fixes
(particularly security sensitive ones), and better/more features for less work.</p>
<p>However, there is several issues with having dependencies in the traditional
way (via <code class="docutils literal"><span class="pre">install_requires</span></code>) for pip. These issues are:</p>
<ul class="simple">
<li><strong>Fragility.</strong> When pip depends on another library to function then if for
whatever reason that library either isn’t installed or an incompatible
version is installed then pip ceases to function. This is of course true for
all Python applications, however for every application <em>except</em> for pip the
way you fix it is by re-running pip. Obviously, when pip can’t run, you can’t
use pip to fix pip, so you’re left having to manually resolve dependencies and
installing them by hand.</li>
<li><strong>Making other libraries uninstallable.</strong> One of pip’s current dependencies is
the <code class="docutils literal"><span class="pre">requests</span></code> library, for which pip requires a fairly recent version to run.
If pip depended on <code class="docutils literal"><span class="pre">requests</span></code> in the traditional manner, then we’d either
have to maintain compatibility with every <code class="docutils literal"><span class="pre">requests</span></code> version that has ever
existed (and ever will), OR allow pip to render certain versions of <code class="docutils literal"><span class="pre">requests</span></code>
uninstallable. (The second issue, although technically true for any Python
application, is magnified by pip’s ubiquity; pip is installed by default in
Python, in <code class="docutils literal"><span class="pre">pyvenv</span></code>, and in <code class="docutils literal"><span class="pre">virtualenv</span></code>.)</li>
<li><strong>Security.</strong> This might seem puzzling at first glance, since vendoring
has a tendency to complicate updating dependencies for security updates,
and that holds true for pip. However, given the <em>other</em> reasons for avoiding
dependencies, the alternative is for pip to reinvent the wheel itself.
This is what pip did historically. It forced pip to re-implement its own
HTTPS verification routines as a workaround for the Python standard library’s
lack of SSL validation, which resulted in similar bugs in the validation routine
in <code class="docutils literal"><span class="pre">requests</span></code> and <code class="docutils literal"><span class="pre">urllib3</span></code>, except that they had to be discovered and
fixed independently. Even though we’re vendoring, reusing libraries keeps pip
more secure by relying on the great work of our dependencies, <em>and</em> allowing for
faster, easier security fixes by simply pulling in newer versions of dependencies.</li>
<li><strong>Bootstrapping.</strong> Currently most popular methods of installing pip rely
on pip’s self-contained nature to install pip itself. These tools work by bundling
a copy of pip, adding it to <code class="docutils literal"><span class="pre">sys.path</span></code>, and then executing that copy of pip.
This is done instead of implementing a “mini installer” (to reduce duplication);
pip already knows how to install a Python package, and is far more battle-tested
than any “mini installer” could ever possibly be.</li>
</ul>
<p>Many downstream redistributors have policies against this kind of bundling, and
instead opt to patch the software they distribute to debundle it and make it
rely on the global versions of the software that they already have packaged
(which may have its own patches applied to it). We (the pip team) would prefer
it if pip was <em>not</em> debundled in this manner due to the above reasons and
instead we would prefer it if pip would be left intact as it is now. The one
exception to this, is it is acceptable to remove the
<code class="docutils literal"><span class="pre">pip/_vendor/requests/cacert.pem</span></code> file provided you ensure that the
<code class="docutils literal"><span class="pre">ssl.get_default_verify_paths().cafile</span></code> API returns the correct CA bundle for
your system. This will ensure that pip will use your system provided CA bundle
instead of the copy bundled with pip.</p>
<p>In the longer term, if someone has a <em>portable</em> solution to the above problems,
other than the bundling method we currently use, that doesn’t add additional
problems that are unreasonable then we would be happy to consider, and possibly
switch to said method. This solution must function correctly across all of the
situation that we expect pip to be used and not mandate some external mechanism
such as OS packages.</p>
</div>
<div class="section" id="modifications">
<h2>Modifications<a class="headerlink" href="#modifications" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">setuptools</span></code> is completely stripped to only keep <code class="docutils literal"><span class="pre">pkg_resources</span></code></li>
<li><code class="docutils literal"><span class="pre">pkg_resources</span></code> has been modified to import its dependencies from <code class="docutils literal"><span class="pre">pip._vendor</span></code></li>
<li><code class="docutils literal"><span class="pre">packaging</span></code> has been modified to import its dependencies from <code class="docutils literal"><span class="pre">pip._vendor</span></code></li>
<li><code class="docutils literal"><span class="pre">html5lib</span></code> has been modified to <code class="docutils literal"><span class="pre">import</span> <span class="pre">six</span> <span class="pre">from</span> <span class="pre">pip._vendor</span></code></li>
<li><code class="docutils literal"><span class="pre">CacheControl</span></code> has been modified to import its dependencies from <code class="docutils literal"><span class="pre">pip._vendor</span></code></li>
<li><code class="docutils literal"><span class="pre">requests</span></code> has been modified to import its other dependencies from <code class="docutils literal"><span class="pre">pip._vendor</span></code>
and to <em>not</em> load <code class="docutils literal"><span class="pre">simplejson</span></code> (all platforms) and <code class="docutils literal"><span class="pre">pyopenssl</span></code> (Windows).</li>
</ul>
</div>
<div class="section" id="automatic-vendoring">
<h2>Automatic Vendoring<a class="headerlink" href="#automatic-vendoring" title="Permalink to this headline">¶</a></h2>
<p>Vendoring is automated via the <code class="docutils literal"><span class="pre">vendoring.update</span></code> task (defined in
<code class="docutils literal"><span class="pre">tasks/vendoring/__init__.py</span></code>) from the content of
<code class="docutils literal"><span class="pre">pip/_vendor/vendor.txt</span></code> and the different patches in
<code class="docutils literal"><span class="pre">tasks/vendoring/patches/</span></code>.
Launch it via <code class="docutils literal"><span class="pre">invoke</span> <span class="pre">vendoring.update</span></code> (requires <code class="docutils literal"><span class="pre">invoke>=0.13.0</span></code>).</p>
</div>
<div class="section" id="debundling">
<h2>Debundling<a class="headerlink" href="#debundling" title="Permalink to this headline">¶</a></h2>
<p>As mentioned in the rationale, we, the pip team, would prefer it if pip was not
debundled (other than optionally <code class="docutils literal"><span class="pre">pip/_vendor/requests/cacert.pem</span></code>) and that
pip was left intact. However, if you insist on doing so, we have a
semi-supported method (that we don’t test in our CI) and requires a bit of
extra work on your end in order to solve the problems described above.</p>
<ol class="arabic simple">
<li>Delete everything in <code class="docutils literal"><span class="pre">pip/_vendor/</span></code> <strong>except</strong> for
<code class="docutils literal"><span class="pre">pip/_vendor/__init__.py</span></code>.</li>
<li>Generate wheels for each of pip’s dependencies (and any of their
dependencies) using your patched copies of these libraries. These must be
placed somewhere on the filesystem that pip can access (<code class="docutils literal"><span class="pre">pip/_vendor</span></code> is
the default assumption).</li>
<li>Modify <code class="docutils literal"><span class="pre">pip/_vendor/__init__.py</span></code> so that the <code class="docutils literal"><span class="pre">DEBUNDLED</span></code> variable is
<code class="docutils literal"><span class="pre">True</span></code>.</li>
<li>Upon installation, the <code class="docutils literal"><span class="pre">INSTALLER</span></code> file in pip’s own <code class="docutils literal"><span class="pre">dist-info</span></code>
directory should be set to something other than <code class="docutils literal"><span class="pre">pip</span></code>, so that pip
can detect that it wasn’t installed using itself.</li>
<li><em>(optional)</em> If you’ve placed the wheels in a location other than
<code class="docutils literal"><span class="pre">pip/_vendor/</span></code>, then modify <code class="docutils literal"><span class="pre">pip/_vendor/__init__.py</span></code> so that the
<code class="docutils literal"><span class="pre">WHEEL_DIR</span></code> variable points to the location you’ve placed them.</li>
<li><em>(optional)</em> Update the <code class="docutils literal"><span class="pre">pip_version_check</span></code> logic to use the
appropriate logic for determining the latest available version of pip and
prompt the user with the correct upgrade message.</li>
</ol>
<p>Note that partial debundling is <strong>NOT</strong> supported. You need to prepare wheels
for all dependencies for successful debundling.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installing.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide.html">User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">Reference Guide</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing.html">Contributing</a></li>
<li class="toctree-l2"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Vendoring Policy</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#rationale">Rationale</a></li>
<li class="toctree-l3"><a class="reference internal" href="#modifications">Modifications</a></li>
<li class="toctree-l3"><a class="reference internal" href="#automatic-vendoring">Automatic Vendoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debundling">Debundling</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../news.html">Release Notes</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="release-process.html"
title="previous chapter">Release process</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../news.html"
title="next chapter">Release Notes</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../news.html" title="Release Notes"
>next</a></li>
<li class="right" >
<a href="release-process.html" title="Release process"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://pypa.io">PyPA</a> »</li>
<a href="../index.html">pip 19.1.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="index.html" >Development</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2008-2017, PyPA.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on Nov 14, 2019.
<a href="https://github.com/pypa/pip/issues">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>