{"id":5954,"library":"hass-web-proxy-lib","title":"Home Assistant Web Proxy Library","description":"hass-web-proxy-lib is a Python library designed to facilitate proxying web traffic through Home Assistant integrations. It provides utilities to generate proxy URLs and execute proxied requests, making external web services accessible securely within the Home Assistant ecosystem. The current version is 0.0.7, with an active development cadence typical for pre-1.0 libraries, meaning frequent updates and potential API changes.","status":"active","version":"0.0.7","language":"en","source_language":"en","source_url":"https://github.com/dermotduffy/hass-web-proxy-lib","tags":["home-assistant","proxy","web-proxy","integration","asyncio"],"install":[{"cmd":"pip install hass-web-proxy-lib","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for asynchronous HTTP client operations and web server functionalities.","package":"aiohttp","optional":false}],"imports":[{"note":"The PyPI package name is 'hass-web-proxy-lib', but the top-level Python package for imports is 'hass_web_proxy'.","wrong":"from hass_web_proxy_lib.web_proxy import WebProxy","symbol":"WebProxy","correct":"from hass_web_proxy.web_proxy import WebProxy"}],"quickstart":{"code":"import asyncio\nfrom hass_web_proxy.web_proxy import WebProxy\n\nasync def main():\n    # In a real Home Assistant environment, 'hass' would be the HA instance\n    # and 'base_url' would be the URL of the HA instance itself.\n    # For this runnable example, we use mock objects to allow instantiation.\n    # A real HA environment is required for actual proxying functionality.\n    class MockHass:\n        async def async_add_executor_job(self, func, *args):\n            # Simulates an executor job, but doesn't run in a separate thread\n            return await func(*args)\n        \n        @property\n        def data(self):\n            return {}\n\n        class config:\n            @staticmethod\n            def path(resource):\n                return \"\" # Dummy path\n\n    mock_hass = MockHass()\n    # In a real HA setup, this would be 'http://your_home_assistant_ip:8123'\n    mock_base_url = \"http://mocked-homeassistant.local:8123\"\n\n    # Instantiate the WebProxy. Requires a 'hass' object and the HA 'base_url'.\n    # This library is specifically designed for Home Assistant custom components.\n    proxy = WebProxy(hass=mock_hass, base_url=mock_base_url)\n\n    # Example: Generating a proxy URL\n    target_external_url = \"https://api.example.com/data\"\n    integration_name = \"my_custom_integration\"\n    proxy_request_path = \"/external_api/get_data\"\n\n    proxy_url = proxy.async_get_proxy_url(\n        integration_name=integration_name,\n        external_url=target_external_url,\n        request_path=proxy_request_path\n    )\n    print(f\"Generated proxy URL: {proxy_url}\")\n\n    # Example: Making a proxied request\n    # Note: This will likely fail outside a real Home Assistant instance\n    # as it relies on HA's internal routing and aiohttp client.\n    print(\"\\nAttempting a proxied request (expected to fail without real HA):\")\n    try:\n        response = await proxy.async_proxy_request(\n            integration_name=integration_name,\n            request_method=\"GET\",\n            request_path=proxy_request_path,\n            request_headers={\n                \"User-Agent\": \"hass-web-proxy-lib-example\",\n                \"Accept\": \"application/json\"\n            },\n            request_body=None\n        )\n        print(f\"Proxy request successful! Status: {response.status}\")\n        # You'd typically process response.text() or response.json() here\n    except Exception as e:\n        print(f\"Proxy request failed as expected: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to instantiate `WebProxy` and use its primary methods `async_get_proxy_url` and `async_proxy_request`. It provides mock objects for `hass` and `base_url` to make the code runnable without a full Home Assistant environment, but a live HA instance is required for actual web proxying to function correctly. The library is intended for use within Home Assistant custom components."},"warnings":[{"fix":"Always pin the exact version in your `requirements.txt` (e.g., `hass-web-proxy-lib==0.0.7`) and consult the GitHub repository's release notes for changes when updating.","message":"As a pre-1.0 release (version 0.0.7), the API is considered unstable and subject to significant breaking changes between minor or even patch versions. Developers should pin exact versions and review release notes carefully upon upgrade.","severity":"breaking","affected_versions":"All versions < 1.0.0"},{"fix":"Ensure `WebProxy` is instantiated within a Home Assistant custom component context, passing the actual `hass` object and `base_url` available in that environment. Mocking these objects will allow instantiation but not functional proxying.","message":"The library is specifically designed for integration with Home Assistant custom components. It requires a `hass` (Home Assistant instance) object and the `base_url` of the HA instance for proper initialization and operation. It is not a general-purpose standalone web proxy library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `from hass_web_proxy.web_proxy import WebProxy` (using underscores) for imports, even though you `pip install hass-web-proxy-lib` (using hyphens).","message":"The Python package name for imports (`hass_web_proxy`) differs from the PyPI package name (`hass-web-proxy-lib`). This is a common source of `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}