Home Assistant Web Proxy Library

0.0.7 · active · verified Tue Apr 14

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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`.
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).

Install

pip install hass-web-proxy-lib Install stable version

Imports

WebProxy
```
from hass_web_proxy.web_proxy import WebProxy
```
The PyPI package name is 'hass-web-proxy-lib', but the top-level Python package for imports is 'hass_web_proxy'.

Quickstart

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.

import asyncio
from hass_web_proxy.web_proxy import WebProxy

async def main():
    # In a real Home Assistant environment, 'hass' would be the HA instance
    # and 'base_url' would be the URL of the HA instance itself.
    # For this runnable example, we use mock objects to allow instantiation.
    # A real HA environment is required for actual proxying functionality.
    class MockHass:
        async def async_add_executor_job(self, func, *args):
            # Simulates an executor job, but doesn't run in a separate thread
            return await func(*args)
        
        @property
        def data(self):
            return {}

        class config:
            @staticmethod
            def path(resource):
                return "" # Dummy path

    mock_hass = MockHass()
    # In a real HA setup, this would be 'http://your_home_assistant_ip:8123'
    mock_base_url = "http://mocked-homeassistant.local:8123"

    # Instantiate the WebProxy. Requires a 'hass' object and the HA 'base_url'.
    # This library is specifically designed for Home Assistant custom components.
    proxy = WebProxy(hass=mock_hass, base_url=mock_base_url)

    # Example: Generating a proxy URL
    target_external_url = "https://api.example.com/data"
    integration_name = "my_custom_integration"
    proxy_request_path = "/external_api/get_data"

    proxy_url = proxy.async_get_proxy_url(
        integration_name=integration_name,
        external_url=target_external_url,
        request_path=proxy_request_path
    )
    print(f"Generated proxy URL: {proxy_url}")

    # Example: Making a proxied request
    # Note: This will likely fail outside a real Home Assistant instance
    # as it relies on HA's internal routing and aiohttp client.
    print("\nAttempting a proxied request (expected to fail without real HA):")
    try:
        response = await proxy.async_proxy_request(
            integration_name=integration_name,
            request_method="GET",
            request_path=proxy_request_path,
            request_headers={
                "User-Agent": "hass-web-proxy-lib-example",
                "Accept": "application/json"
            },
            request_body=None
        )
        print(f"Proxy request successful! Status: {response.status}")
        # You'd typically process response.text() or response.json() here
    except Exception as e:
        print(f"Proxy request failed as expected: {e}")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →