python-openevse-http 0.4.4__tar.gz → 1.0.0__tar.gz

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/.github/workflows/autolabeler.yml

@@ -6,11 +6,13 @@ on:
       - opened
       - synchronize
       - reopened
+      - edited
   pull_request_target:
     types:
       - opened
       - synchronize
       - reopened
+      - edited
 
 permissions: {}
 

python_openevse_http-1.0.0/EXTERNAL_SESSION.md

@@ -0,0 +1,91 @@
+# HTTP Session Management
+
+## Overview
+
+The `python-openevse-http` library requires you to pass an external `aiohttp.ClientSession` to `OpenEVSE`. Session ownership stays with the caller, so the library no longer constructs temporary HTTP clients internally.
+
+## Benefits
+
+- **Session Reuse**: Share a single session across multiple OpenEVSE instances or other `aiohttp` clients
+- **Custom Configuration**: Configure timeouts, connectors, proxies, and SSL behavior yourself
+- **Resource Management**: Keep connection pooling and cleanup in one place
+- **Predictable Lifecycle**: Avoid hidden session creation inside request and websocket code paths
+
+## Usage
+
+### Basic Usage
+
+```python
+import aiohttp
+from openevsehttp import OpenEVSE
+
+async def main():
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        charger = OpenEVSE("openevse.local", session=session)
+        await charger.update()
+        print(f"Status: {charger.status}")
+        await charger.ws_disconnect()
+```
+
+### Sharing a Session
+
+```python
+import aiohttp
+from openevsehttp import OpenEVSE
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        charger1 = OpenEVSE("charger1.local", session=session)
+        charger2 = OpenEVSE("charger2.local", session=session)
+
+        await charger1.update()
+        await charger2.update()
+```
+
+### Websocket Startup
+
+Start websocket listening from the same event loop that owns the
+`aiohttp.ClientSession`:
+
+```python
+import aiohttp
+from openevsehttp import OpenEVSE
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        charger = OpenEVSE("openevse.local", session=session)
+        await charger.ws_start()
+        await charger.ws_disconnect()
+```
+
+`ws_start()` is async so websocket tasks are created on the event loop that owns
+the configured `aiohttp.ClientSession`. This prevents using a session from a
+private background loop it was not created on.
+
+## API Notes
+
+- `OpenEVSE(..., session=session)` uses the provided session for HTTP requests.
+- `OpenEVSEWebsocket(..., session=session)` uses the provided session for websocket connections.
+- If no session is configured, HTTP requests and websocket startup raise `RuntimeError`.
+- Call `await charger.ws_start()` from the event loop that owns the session.
+- Externally provided sessions are never closed by the library.
+
+## Migration
+
+Before:
+
+```python
+charger = OpenEVSE("openevse.local")
+await charger.update()
+```
+
+After:
+
+```python
+import aiohttp
+
+async with aiohttp.ClientSession() as session:
+    charger = OpenEVSE("openevse.local", session=session)
+    await charger.update()
+```

{python_openevse_http-0.4.4/python_openevse_http.egg-info → python_openevse_http-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python_openevse_http
-Version: 0.4.4
+Version: 1.0.0
 Summary: Python wrapper for OpenEVSE HTTP API
 Home-page: https://github.com/firstof9/python-openevse-http
 Download-URL: https://github.com/firstof9/python-openevse-http
@@ -62,28 +62,24 @@ pip install python_openevse_http
 
 ```python
 import asyncio
+import aiohttp
 from openevsehttp import OpenEVSE
 
 async def main():
-    # Initialize the charger
-    charger = OpenEVSE("192.168.1.30")
+    async with aiohttp.ClientSession() as session:
+        charger = OpenEVSE("192.168.1.30", session=session)
+        await charger.update()
 
-    # Update state
-    await charger.update()
+        print(f"Charger State: {charger.status}")
+        print(f"Current Charge: {charger.charge_current}A")
 
-    print(f"Charger State: {charger.status}")
-    print(f"Current Charge: {charger.charge_current}A")
+        if charger.shaper_active:
+            print("Shaper is active, disabling...")
+        else:
+            print("Shaper is inactive, enabling...")
 
-    # Toggle the Shaper feature
-    if charger.shaper_active:
-        print("Shaper is active, disabling...")
-    else:
-        print("Shaper is inactive, enabling...")
-
-    await charger.toggle_shaper()
-
-    # Clean up
-    await charger.close()
+        await charger.toggle_shaper()
+        await charger.ws_disconnect()
 
 if __name__ == "__main__":
     asyncio.run(main())

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/README.md

@@ -29,28 +29,24 @@ pip install python_openevse_http
 
 ```python
 import asyncio
+import aiohttp
 from openevsehttp import OpenEVSE
 
 async def main():
-    # Initialize the charger
-    charger = OpenEVSE("192.168.1.30")
+    async with aiohttp.ClientSession() as session:
+        charger = OpenEVSE("192.168.1.30", session=session)
+        await charger.update()
 
-    # Update state
-    await charger.update()
+        print(f"Charger State: {charger.status}")
+        print(f"Current Charge: {charger.charge_current}A")
 
-    print(f"Charger State: {charger.status}")
-    print(f"Current Charge: {charger.charge_current}A")
+        if charger.shaper_active:
+            print("Shaper is active, disabling...")
+        else:
+            print("Shaper is inactive, enabling...")
 
-    # Toggle the Shaper feature
-    if charger.shaper_active:
-        print("Shaper is active, disabling...")
-    else:
-        print("Shaper is inactive, enabling...")
-
-    await charger.toggle_shaper()
-
-    # Clean up
-    await charger.close()
+        await charger.toggle_shaper()
+        await charger.ws_disconnect()
 
 if __name__ == "__main__":
     asyncio.run(main())

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/example_external_session.py

@@ -31,19 +31,6 @@ async def example_with_external_session():
         await charger.ws_disconnect()
 
 
-async def example_without_external_session():
-    """Demonstrate without external session (backward compatible)."""
-    # The library will create and manage its own sessions
-    charger = OpenEVSE("openevse.local")
-
-    # Use the charger normally
-    await charger.update()
-    print(f"Status: {charger.status}")
-    print(f"Current: {charger.charging_current}A")
-
-    await charger.ws_disconnect()
-
-
 async def example_shared_session():
     """Demonstrate sharing a session between multiple clients."""
     async with aiohttp.ClientSession() as session:

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/openevsehttp/client.py

@@ -17,6 +17,8 @@ from awesomeversion.exceptions import AwesomeVersionCompareException
 
 from .commands import CommandsMixin
 from .const import (
+    ERROR_SESSION_LOOP_MISMATCH,
+    ERROR_SESSION_REQUIRED,
     ERROR_TIMEOUT,
     UPDATE_TRIGGERS,
 )
@@ -68,7 +70,17 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         self._owns_loop = False
         self._loop_thread: threading.Thread | None = None
         self._session = session
-        self._session_external = session is not None
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        """Return the configured HTTP session or fail fast."""
+        if self._session is None:
+            raise RuntimeError(ERROR_SESSION_REQUIRED)
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return self._session
+        self._validate_session_loop(loop)
+        return self._session
 
     async def process_request(
         self,
@@ -86,16 +98,10 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         if self._user and self._pwd:
             auth = aiohttp.BasicAuth(self._user, self._pwd)
 
-        # Use provided session or create a temporary one
-        if (session := self._session) is None:
-            async with aiohttp.ClientSession() as session:
-                return await self._process_request_with_session(
-                    session, url, method, data, rapi, auth
-                )
-        else:
-            return await self._process_request_with_session(
-                session, url, method, data, rapi, auth
-            )
+        session = self._get_session()
+        return await self._process_request_with_session(
+            session, url, method, data, rapi, auth
+        )
 
     def _normalize_response(self, response: Any) -> dict[str, Any] | list[Any]:
         """Normalize response to a dict or list."""
@@ -259,36 +265,37 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         data = {"serial": serial, "model": model}
         return data
 
-    def ws_start(self) -> None:
+    async def ws_start(self) -> None:
         """Start the websocket listener."""
         if self.websocket and self.websocket.state != STATE_STOPPED:
             raise AlreadyListening
 
-        # Detect loop mismatch
-        use_session = self._session
-        try:
-            asyncio.get_running_loop()
-        except RuntimeError:
-            # We are about to create a private loop in _start_listening
-            # If we have a session, it's likely bound to another loop
-            if self._session:
-                _LOGGER.warning(
-                    "Caller-provided session may not work on private event loop. "
-                    "Creating a loop-local session."
-                )
-                use_session = None
-                # Clear self._session so subsequent await self.update() uses
-                # a loop-local session as well.
-                self._session = None
-                self._session_external = False
+        self._get_session()
 
         if not self.websocket or self.websocket.state == STATE_STOPPED:
-            self.websocket = OpenEVSEWebsocket(
-                self.url, self._update_status, self._user, self._pwd, use_session
-            )
+            self._create_websocket()
 
         self._start_listening()
 
+    def _create_websocket(self) -> None:
+        """Create a websocket using the configured session."""
+        self.websocket = OpenEVSEWebsocket(
+            self.url,
+            self._update_status,
+            self._user,
+            self._pwd,
+            self._session,
+        )
+
+    def _validate_session_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        """Ensure the configured session belongs to the active event loop."""
+        session_loop = getattr(self._session, "_loop", None)
+        if (
+            isinstance(session_loop, asyncio.AbstractEventLoop)
+            and session_loop is not loop
+        ):
+            raise RuntimeError(ERROR_SESSION_LOOP_MISMATCH)
+
     def _start_listening(self) -> None:
         """Start the websocket listener."""
         if not self._loop:

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/openevsehttp/commands.py

@@ -25,7 +25,7 @@ class CommandsMixin:
     url: str
     _status: dict[str, Any]
     _config: dict[str, Any]
-    _session: Any
+    _session: aiohttp.ClientSession | None
 
     # These are defined in client.py
     def _version_check(self, min_version: str, max_version: str = "") -> bool:
@@ -46,6 +46,10 @@ class CommandsMixin:
         """Normalize response to a dict or list."""
         raise NotImplementedError
 
+    def _get_session(self) -> aiohttp.ClientSession:
+        """Return the configured HTTP session."""
+        raise NotImplementedError
+
     def _flag_ota_if_started(self, response: Any) -> None:
         """Flag OTA as active if response indicates firmware update has started."""
         normalized = self._normalize_response(response)
@@ -409,12 +413,8 @@ class CommandsMixin:
             return None
 
         try:
-            if (session := self._session) is None:
-                async with aiohttp.ClientSession() as session:
-                    return await self._firmware_check_with_session(session, url, method)
-            else:
-                return await self._firmware_check_with_session(session, url, method)
-
+            session = self._get_session()
+            return await self._firmware_check_with_session(session, url, method)
         except (TimeoutError, ServerTimeoutError):
             _LOGGER.error("%s: %s", "Timeout while updating", url)
         except ContentTypeError as err:

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/openevsehttp/const.py

@@ -62,3 +62,10 @@ RAPI_ERRORS = [
 ]
 
 SUCCESS_ANSWERS = ["OK", "done", "no change", "Created", "Updated", "Deleted"]
+
+ERROR_SESSION_REQUIRED = (
+    "An aiohttp.ClientSession must be provided via the session argument."
+)
+ERROR_SESSION_LOOP_MISMATCH = (
+    "The aiohttp.ClientSession is bound to a different event loop."
+)

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0}/openevsehttp/websocket.py

@@ -11,6 +11,11 @@ from typing import Any
 
 import aiohttp
 
+from .const import (
+    ERROR_SESSION_LOOP_MISMATCH,
+    ERROR_SESSION_REQUIRED,
+)
+
 _LOGGER = logging.getLogger(__name__)
 
 MAX_FAILED_ATTEMPTS = 5
@@ -40,7 +45,6 @@ class OpenEVSEWebsocket:
     ) -> None:
         """Initialize a OpenEVSEWebsocket instance."""
         self.session = session
-        self._session_external = session is not None
         self.uri = self._get_uri(server)
         self._user = user
         self._password = password
@@ -224,10 +228,17 @@ class OpenEVSEWebsocket:
             self._listener_loop = None
 
     async def _ensure_session(self) -> None:
-        """Ensure aiohttp.ClientSession exists."""
+        """Ensure an external aiohttp.ClientSession exists."""
         if self.session is None:
-            self.session = aiohttp.ClientSession()
-            self._session_external = False
+            raise RuntimeError(ERROR_SESSION_REQUIRED)
+
+        loop = asyncio.get_running_loop()
+        session_loop = getattr(self.session, "_loop", None)
+        if (
+            isinstance(session_loop, asyncio.AbstractEventLoop)
+            and session_loop is not loop
+        ):
+            raise RuntimeError(ERROR_SESSION_LOOP_MISMATCH)
 
     async def close(self) -> None:
         """Close the listening websocket."""
@@ -242,10 +253,6 @@ class OpenEVSEWebsocket:
         if self._client is not None:
             await self._client.close()
             self._client = None
-        # Only close the session if we created it
-        if not self._session_external and self.session is not None:
-            await self.session.close()
-            self.session = None
 
     async def keepalive(self) -> None:
         """Send ping requests to websocket."""

{python_openevse_http-0.4.4 → python_openevse_http-1.0.0/python_openevse_http.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python_openevse_http
-Version: 0.4.4
+Version: 1.0.0
 Summary: Python wrapper for OpenEVSE HTTP API
 Home-page: https://github.com/firstof9/python-openevse-http
 Download-URL: https://github.com/firstof9/python-openevse-http
@@ -62,28 +62,24 @@ pip install python_openevse_http
 
 ```python
 import asyncio
+import aiohttp
 from openevsehttp import OpenEVSE
 
 async def main():
-    # Initialize the charger
-    charger = OpenEVSE("192.168.1.30")
+    async with aiohttp.ClientSession() as session:
+        charger = OpenEVSE("192.168.1.30", session=session)
+        await charger.update()
 
-    # Update state
-    await charger.update()
+        print(f"Charger State: {charger.status}")
+        print(f"Current Charge: {charger.charge_current}A")
 
-    print(f"Charger State: {charger.status}")
-    print(f"Current Charge: {charger.charge_current}A")
+        if charger.shaper_active:
+            print("Shaper is active, disabling...")
+        else:
+            print("Shaper is inactive, enabling...")
 
-    # Toggle the Shaper feature
-    if charger.shaper_active:
-        print("Shaper is active, disabling...")
-    else:
-        print("Shaper is inactive, enabling...")
-
-    await charger.toggle_shaper()
-
-    # Clean up
-    await charger.close()
+        await charger.toggle_shaper()
+        await charger.ws_disconnect()
 
 if __name__ == "__main__":
     asyncio.run(main())