Support `pip install`'s new `--dry-run` and `--report` flags

[woodruffw]

As of version 22.2, pip supports two new flags on pip install: --dry-run to perform a "dry run" of the installation steps, and --report to generate a JSON-formatted installation report.

It'd be nice to have complementary APIs on pip-api's side, particularly for pip-audit's use case!

See https://github.com/pypa/pip/pull/10771

xref https://github.com/trailofbits/pip-audit/issues/321

[woodruffw]

I'm going to take a stab at this today.

@di: do you have any thoughts on whether pip_api.install should support modes that aren't --dry-run? In other words, should we allow a user to do something potentially destructive, like:

pip_api.install("pip==veryoldversion")

[di]

I'm honestly surprised that we haven't gotten a request for an install API yet. I think it's OK for us to only support --dry-run for now and see if we get future requests for actual installs.

[woodruffw]

Sounds good!

[woodruffw]

pip install has a lot of API surface, so here's what I'm thinking:

• pip_api.install_requirements(*reqs): maps each req in reqs into -r req
• pip_api.install_specifiers(*specs): for foo==version specifiers
• pip_api.install_urls(*urls): handles VCS/archive URLs, as appropriate
• pip_api.install_paths(*paths): handles filesystem paths, as appropriate

[di]

Would these be drop in replacements for existing internal pip APIs? Or should we just support pip_api.install which only has limited functionality compared to it's internal equivalent?

[woodruffw]

Or should we just support pip_api.install which only has limited functionality compared to it's internal equivalent?

That maybe makes more sense -- I don't think these proposed APIs currently have direct equivalents internally within pip, and all we really need for pip-audit's purpose is the "specifiers" one, I think.

[sethmlarson]

The --dry-run, --ignore-installed, and --report flags would be super useful for hooking into pip's resolving logic to generate an SBOM given a requirements.txt or some other series of requirements without installing the distributions.

[di]

Just to reiterate: the goal of this project is to provide an importable pip API, which is designed to be be used as a drop-in replacement for existing uses of pip's internal API, not to replace pip's command line API.

This means that anything we introduce here should have an equivalent in pip's internal API. If we can identify which functions those would be, that would be the first step in moving forward with this.