Check for pip configuration when an externally managed environment is detected.

[nuclearsandwich]

rosdep is designed to treat pip like an alternative system-level package manager. Deviating from this approach is not easily achievable without a significant rethinking of how pip packages are managed. In the meantime, we can at least instruct users how to restore the prior functionality.

Rather than inject the environment variable / config on behalf of the user, this change instructs them to make the necessary config changes themself, keeping them informed of the change their making to the system's new default.

I added a documentation page specific to this issue with additional configuration details and recipes for CI.

Seeks to reduce friction related to #978

[nuclearsandwich]

In addition to the test failures, this actually doesn't work as intended because sudo is stripping the environment. I'm hesitant to recommend the pip global config file as a default because the default location is variable. Alternatively, we could override the sudo_command for the pip installer to pass that environment variable through.

[ros-discourse]

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/rosdep-for-pip-is-broken-on-jazzy/38981/5

[nuclearsandwich]

In addition to the test failures, this actually doesn't work as intended because sudo is stripping the environment. I'm hesitant to recommend the pip global config file as a default because the default location is variable. Alternatively, we could override the sudo_command for the pip installer to pass that environment variable through.

As of 2c76686 the installer is configured to pass PIP_BREAK_SYSTEM_PACKAGES through from the user environment. This works by default on each of my tested sudo environments (Archlinux, Ubuntu, Fedora) but a locked down sudo that disallows environment preservation or has an explicit allowlist will still create problems. My hope was to detect that the check passed but the install failed due to the externally managed target anyway and give a hint about sudo to suggest an alternative configuration method. But without changes, the pip installer never gets control back from install_resolved() so we'd have to add pip-specific hooks elsewhere in the code and I'm hesitant. I think I'm content to leave it here but with more robust documentation.

[nuclearsandwich]

Note that this documentation won't actually be live until the PR is merged and docs rebuild the next day. This will only affect those using rosdep from mainline or this branch. I'll wait until the docs rebuild to make a new rosdep release with this change.

[christophebedard]

Minor comments!

[nuclearsandwich]

I'm not super up on why imports are done per test function here but I am propagating the convention until I understand it better.

[christophebedard]

If you want, a more Pythonic way could be:

Suggested change

	try:
	installer.get_install_command(['whatever'])
	assert False, 'should have raised'
	except InstallFailed as e:
	assert e.failures == [('pip', EXTERNALLY_MANAGED_EXPLAINER)]
	with pytest.raises(InstallFailed) as exception_info:
	installer.get_install_command(['whatever'])
	assert exception_info.value.failures == [('pip', EXTERNALLY_MANAGED_EXPLAINER)]

and make sure to import pytest

[nuclearsandwich]

Thanks for the suggestion. I'm actually going to keep this as is for now, because I don't believe the infrastructure packages ever explicitly require pytest. I think pytest is supposed to be compatible with stdlib unittest as well and utilizing that may be the preferred approach.

[christophebedard]

Aside from my last minor suggestions, this looks good to me!