parse_requirements: Add include_invalid argument

[jayvdb]

Rather than fail on the first invalid requirement,
allow caller to require parser continues and
includes invalid requirements in the results.

[jayvdb]

Worth noting, pip-api doesnt support various requirements which pip did support, because packaging doesnt yet support them.

So this provides a hacky way to allow a valid requirements file to be partially handled by pip-api, leaving the caller to deal with the unhandled requirements. IMO this is necessary because no amount of cajoling is going to convince people with a pip-api parse error that they should try to submit a fix to packaging, which does not appear even interested in matching setuptools/pip functionality, and where patches languish for years.

The objective here is to allow the caller (i.e. pytest-reqs) to manage invalid requirements, and in the case of pytest-reqs allow more results when a requirement is not supported by packaging, and invalid requirements could be ignored (or in file support mode, they could be shown as a test skip.)

[jayvdb]

Hiya @di, could you give your opinion on this. We have a new GSoC about to start, and still no traction on the bugs in pytest-reqs. My patches keep getting broken when you urgently fix incompatibilities created by new pip, and then you do a release, and then nothing else happens. If this keeps happening, I'll create my own plugin so I can get stability for the coala development team's test rig.

If you would prefer a different approach for this patch, I am happy to re-arrange this. e.g. it could still raise an exception, but the exception could include the partial parse information as attributes.

If you dont believe this is useful at all in pip-api, I could add vcs URL parsing to pip-api, which would be enough to finish di/pytest-reqs#26 , but still leaves it unable to report multiple parse failures.