Fix blocking call warning in Home Assistant by running MQTT connection setup in executor

[eman]

Problem

Home Assistant was detecting blocking calls to open() inside the event loop when the MQTT client attempted to connect, causing this warning:

WARNING (MainThread) [homeassistant.util.loop] Detected blocking call to open with args (PosixPath('/usr/local/lib/python3.13/site-packages/awsiotsdk-1.26.0.dist-info/METADATA'),) inside the event loop by custom integration 'nwp500' at custom_components/nwp500/coordinator.py, line 143: connected = await self.mqtt_client.connect()

The issue occurs because the AWS IoT SDK performs synchronous file I/O operations when reading metadata files during connection setup in mqtt_connection_builder.websockets_with_default_aws_signing().

Solution

This PR wraps the blocking connection setup operations in an asyncio executor to avoid blocking the main event loop. The changes are:

1. Wrapped connection setup in executor: The mqtt_connection_builder.websockets_with_default_aws_signing() call and credential provider creation now run in a thread pool via asyncio.run_in_executor()

2. Moved credential creation into executor: The _create_credentials_provider() call is now inside the executor function to ensure all potentially blocking operations are isolated

3. Added clear documentation: Comments explain why the executor is needed and what operations are being protected

Changes Made

• Modified NavienMqttClient.connect() method in src/nwp500/mqtt_client.py
• No breaking changes - the API remains exactly the same
• All existing functionality is preserved

Benefits

• ✅ Resolves Home Assistant blocking call warnings
• ✅ Maintains full API compatibility (non-breaking change)
• ✅ Preserves all existing functionality
• ✅ Thread-safe implementation using asyncio's default executor
• ✅ Future-proof against other potential blocking operations in AWS IoT SDK

Testing

• All existing tests pass (29/29)
• Code passes linting and formatting checks
• Verified that run_in_executor is properly called during connection setup
• Confirmed the fix addresses the specific Home Assistant warning scenario

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

References

• Home Assistant Async Guidelines: https://developers.home-assistant.io/docs/asyncio_blocking_operations/#open
• Original error traceback shows the blocking call in AWS IoT SDK metadata reading

[Copilot]

Pull Request Overview

This PR addresses a blocking I/O warning in Home Assistant by moving synchronous AWS IoT SDK connection setup off the event loop.

• Wraps MQTT connection and credential provider creation in a thread executor to avoid blocking.
• Adds inline comments explaining the rationale for the executor use.

[eman]

🔄 Improved Implementation

I've updated the implementation based on feedback to use asyncio.to_thread() instead of the custom nested function + run_in_executor pattern. This provides several benefits:

✨ Improvements Made

1. Cleaner Code: No more nested function definitions
2. Better Performance: Avoids redefining _build_connection on every call
3. Clearer Intent: asyncio.to_thread() explicitly shows we're running blocking operations in a thread
4. Modern Approach: Uses the Python 3.9+ recommended pattern for async/blocking integration
5. Implicit Loop Usage: Uses the current event loop automatically

📋 Changes

Before:

def _build_connection():
    credentials_provider = self._create_credentials_provider()
    return mqtt_connection_builder.websockets_with_default_aws_signing(...)

self._connection = await self._loop.run_in_executor(None, _build_connection)

After:

credentials_provider = await asyncio.to_thread(self._create_credentials_provider)
self._connection = await asyncio.to_thread(
    mqtt_connection_builder.websockets_with_default_aws_signing,
    endpoint=self.config.endpoint,
    region=self.config.region,
    credentials_provider=credentials_provider,
    # ... other args
)

✅ Testing

• All existing tests still pass (29/29)
• Code passes linting and formatting checks
• Verified asyncio.to_thread() is called correctly for both operations
• Confirmed the fix still resolves the Home Assistant blocking call warnings

The implementation is now cleaner, more efficient, and follows modern Python async best practices!