This is a rewrite of commit 6e4b8efe
("Support network cache in Download.download()").

This reverts commit e6e348fa.

Commit c3903c7e was error-prone
because (lambda f1, f2: False) may be wrong in other cases than where
it's currently used.

To be squashed with commit 4ccb79e9.

Like for URL that contain credentials, we still skip auth challenge
because it's faster and:
- we only support one auth scheme (basic)
- netrc provides no way to specify realms, which seem anyway to be
  less and less used (https://stackoverflow.com/q/69303610 reports
  that recent browsers don't display them anymore)

See merge request nexedi/slapos.buildout!25

- Py3: stop using legacy API of urllib.request and
       fix download of http(s) URLs containing user:passwd@
- Py2: avoid OOM when downloading huge files

This is implemented as a method in case we want to make it configurable
via [buildout].

To be dropped once all buildout in the wild are able to upgrade to a
version that supports new names in expression of conditional sections
(see previous commit).

Adding new names for expression is currently not possible because
buildout aborts before it tries to upgrade (in-place or bootstrap).

(cherry picked from commit f1589378)

For example, existing values were not enough to distinguish
'arm-linux-gnueabi' from 'arm-linux-gnueabihf'.

The 'multiarch' value is the output of

  $CC -dumpmachine

where CC defaults to 'gcc'.

See also https://wiki.debian.org/Multiarch/Tuples

Sometimes, most parts are reinstalled for a reason that the user
didn't think about and it can take time to understand why.
Explaining for all parts would be too verbose and useless because
many are reinstalled just because their dependencies changed.

This alternate URL is used in case of HTTPError with the main one.
In any case, the main URL is used for both downloading & uploading
from/to networkcache.

This will be exposed by slapos.recipe.build:download* and
slapos.recipe.cmmi recipes.

An optimization is to avoid temporary file when possible: a rename
(or hard link) is not always possible (different mount points).

Another one is to not check md5sum twice when using cache file.

Fall-back mode is ignored if an MD5 checksum is given.

In case of checksum mismatch for a cached path, remove it and
download again, mainly to cover the following cases:
- the url content changes and the user updates the checksum
- buildout killed while downloading directly to cache
  (see above optimization)
- shutil.copyfile is interrupted

Egg is install from wheel the requested version ends with :whl

This replaces:
  6d9b7483 Avoid installing eggs from wheels when possible
  ff2ee218 Do never install from wheels

This relaxes commit ff2ee218
("Do never install from wheels") because for some eggs like plantuml,
there's no tarball.

About the implementation, no need to sort by version (as it was done)
because the list is already filtered to keep the best one.

See merge request nexedi/slapos.buildout!22

other tests have been disabled by mistake.
test was randomly failing because of glob.

When recipes mutate the options, we should not allow invalid syntax otherwise
it gets written in .installed.cfg and generate invalid configparser syntax.

When recipe mutate options, options values are written to .installed.cfg
without escaping buildout substitution syntax, so if a recipe sets an option
value that could be interpreted as a buildout substitution, it is written as is
in .installed.cfg.
This can be a problem if options read from _read_installed_part_options are
accessed, like it's the case with slapos patched buildout which saves
installed options after an error with part installation or after each part
installation when running in verbose mode.

Contrary to bash, dash filters out environment variables containing
'-' characters. And for example, /bin/sh is dash on Debian.

Rebase instructions:
- squash with 93369b04
  and keep the above commit message

fixup! Fix testing index when /bin/sh is dash (like on Debian)

python ZipFile module does not support updating an entry in place, instead make
a new zip file and copy all entries.

On Python 3, these made the build output very hard to read (e.g., https://travis-ci.org/buildout/buildout/jobs/394026829)

On Python 3.7, these could actually break the doctests.

Closing the files should get us closer to being able to pass the tests with PyPy.

Because updating a section no longer add the section t the end of parts in
.installed, uninstallation happens in this order.

fixup! Add referred parts' hash strings in __buildout_signature__, that invokes rebuild of a part when one of its (recursive) dependencies are modified.

egg signatures are always {egg_name}-{egg_verson}, there should not be a "egg" prefix for setuptools

fixup! Add referred parts' hash strings in __buildout_signature__, that invokes rebuild of a part when one of its (recursive) dependencies are modified.

Comment by Julien Muchembled:

    Maybe we again have the original behaviour because of
    commit dffdeffc.

    Anyway, the behaviour of buildout at this point is meaningless.
    Buildout was previously invoked with install d3 d4 command-line
    arguments and I consider that d2 should have been reinstalled,
    because a section shall not access the option of another section
    if the latter is not properly installed.

Only build egg at this point if we have some patches to apply otherwise
buildout would install dependent egg without logging this operation, which
would cause many tests to fail.

Also cover the whole scenario of egg patching in a new doctest.