fix: Enhance environment connection error handling

[Mr-Sunglasses]

fix: #455

Add PodmanConnectionError to improve debugging of connection failures when
initializing client from environment variables. The new error provides:

• Detailed error messages with connection host and environment state
• Preservation of original exception information
• Better context for common failure modes (invalid config, connection failures)

Previously, raw exceptions from connection attempts could be confusing to
diagnose, especially when involving environment variables. This change makes it
clearer what went wrong during client initialization.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Mr-Sunglasses
Once this PR has been reviewed and has the lgtm label, please assign lsm5 for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[inknos]

It would be nice to test these exceptions if possible.

I'll give you an idea of what I was thinking to test it.

What do you think? :)

--- a/podman/tests/integration/test_system.py
+++ b/podman/tests/integration/test_system.py
@@ -64,3 +64,10 @@ class SystemIntegrationTest(base.IntegrationTest):
     def test_from_env(self):
         """integration: from_env() no error"""
         PodmanClient.from_env()
+
+    def test_from_env_exceptions(self):
+        """integration: from_env() returns exceptions"""
+        with self.assertRaises(PodmanConnectionError):
+            PodmanClient.from_env(base_url="unix:///path/to/nonexistent.sock")

[inknos]

For code clarity, I would prefer to use python's exception handling here.

except ValueError as e:
    error_msg = "Invalid environment configuration for Podman client"
    raise PodmanConnectionError(
        message=error_msg, environment=environment, host=host, original_error=e)
except (ConnectionError, TimeoutError) as e:
    error_msg = "Failed to connect to Podman service"
    raise PodmanConnectionError(
         message=error_msg, environment=environment, host=host, original_error=e)
except Exception as e:
    error_msg = "Failed to initialize Podman client from environment"
    raise PodmanConnectionError(
         message=error_msg, environment=environment, host=host, original_error=e)

I would avoid filtering exceptions with if conditions in the except block, unless you have a strong reason to do so.