Add support for multiple solar planes (#275)

artspb · Junie · klaasnicolaas · web-flow · commit 770343892c2d · 2026-02-21T22:42:56.000+01:00
* Add support for multiple solar planes (#171) Add the ability to specify multiple planes for solar panel configurations. - Add new Plane dataclass with declination, azimuth, and kwp fields - Add planes parameter to ForecastSolar class - Build multi-plane URL paths for estimate and validate_plane methods - Silently ignore additional planes when no API key is provided - Update README with documentation and usage examples - Add comprehensive tests for multi-plane functionality Co-authored-by: Junie <noreply@jb.gg> * Fix linter errors in test_models.py - Remove unused snapshot parameter from test_planes_ignored_without_api_key - Split long comment to comply with line length limit * Add linting section to README.md - Add recommendation to run ruff linter before committing - Include commands for checking and auto-fixing linting issues * Revert "Add linting section to README.md" This reverts commit 685cc7d. * Add example file demonstrating multiple planes functionality Co-authored-by: Junie <noreply@jb.gg> * Update examples/planes.py Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com> * docs: clarify subscription requirements for multiple planes and actual parameter Co-authored-by: Junie <noreply@jb.gg> * fix: handle 404 errors in API requests Explicitly handle HTTP 404 status codes in _request method and raise ForecastSolarRequestError. Added tests to verify the behavior. Co-authored-by: Junie <junie@jetbrains.com> --------- Co-authored-by: Junie <noreply@jb.gg> Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com> Co-authored-by: Junie <junie@jetbrains.com>
diff --git a/README.md b/README.md
@@ -85,23 +85,68 @@ async def main() -> None:
         print(estimate)
 
 
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Multiple Planes
+
+If you have solar panels facing different directions, you can specify multiple planes.
+
+**Note:** Using multiple planes requires both an API key and a Personal Plus (or higher) subscription. If no API key is provided, additional planes will be silently ignored. See the [subscription plan overview][forecast-subscription] for more information.
+
+```python
+import asyncio
+
+from forecast_solar import ForecastSolar, Plane
+
+
+async def main() -> None:
+    """Show example with multiple planes."""
+    async with ForecastSolar(
+        api_key="YOUR_API_KEY",
+        latitude=52.16,
+        longitude=4.47,
+        # First plane (primary)
+        declination=20,
+        azimuth=10,
+        kwp=2.160,
+        # Additional planes
+        planes=[
+            Plane(declination=30, azimuth=-90, kwp=1.5),  # Second plane
+            Plane(declination=25, azimuth=90, kwp=1.0),   # Third plane
+        ],
+    ) as forecast:
+        estimate = await forecast.estimate()
+        print(estimate)
+
+
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
 ## ForecastSolar object
 
+| Parameter | value type | Description                                                                                                 |
+| --------- | ---------- |-------------------------------------------------------------------------------------------------------------|
+| `api_key` | `str` | Your API key from [forecast.solar](https://forecast.solar) (optional)                                       |
+| `declination` | `int` | The tilt of the solar panels (required)                                                                     |
+| `azimuth` | `int` | The direction the solar panels are facing (required)                                                        |
+| `kwp` | `float` | The size of the solar panels in kWp (required)                                                              |
+| `damping` | `float` | The damping of the solar panels, [read this][forecast-damping] for more information (optional)              |
+| `damping_morning` | `float` | The damping of the solar panels in the morning (optional)                                                   |
+| `damping_evening` | `float` | The damping of the solar panels in the evening (optional)                                                   |
+| `inverter` | `float` | The maximum power of your inverter in kilo watts (optional)                                                 |
+| `horizon` | `str` | A list of **comma separated** degrees values, [read this][forecast-horizon] for more information (optional) |
+| `planes` | `list[Plane]` | A list of additional Plane objects for multi-plane setups. Only used when an API key is provided (optional)                                                  |
+
+## Plane object
+
 | Parameter | value type | Description |
 | --------- | ---------- | ----------- |
-| `api_key` | `str` | Your API key from [forecast.solar](https://forecast.solar) (optional) |
-| `declination` | `int` | The tilt of the solar panels (required) |
-| `azimuth` | `int` | The direction the solar panels are facing (required) |
+| `declination` | `float` | The tilt of the solar panels (required) |
+| `azimuth` | `float` | The direction the solar panels are facing (required) |
 | `kwp` | `float` | The size of the solar panels in kWp (required) |
-| `damping` | `float` | The damping of the solar panels, [read this][forecast-damping] for more information (optional) |
-| `damping_morning` | `float` | The damping of the solar panels in the morning (optional) |
-| `damping_evening` | `float` | The damping of the solar panels in the evening (optional) |
-| `inverter` | `float` | The maximum power of your inverter in kilo watts (optional) |
-| `horizon` | `str` | A list of **comma separated** degrees values, [read this][forecast-horizon] for more information (optional) |
 
 ## estimate() method
 
@@ -192,6 +237,7 @@ SOFTWARE.
 <!-- LINKS -->
 [forecast-horizon]: https://doc.forecast.solar/doku.php?id=api#horizon
 [forecast-damping]: https://doc.forecast.solar/doku.php?id=damping
+[forecast-subscription]: https://doc.forecast.solar/account_models
 
 <!-- MARKDOWN LINKS & IMAGES -->
 [maintenance-shield]: https://img.shields.io/maintenance/yes/2025.svg?style=for-the-badge
diff --git a/examples/planes.py b/examples/planes.py
@@ -0,0 +1,88 @@
+"""Example of how to use multiple planes with the Forecast.Solar API."""
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+from pprint import pprint  # noqa: F401
+
+from forecast_solar import ForecastSolar, ForecastSolarRatelimitError, Plane
+
+
+async def main() -> None:
+    """Get an estimate from the Forecast.Solar API using multiple planes.
+
+    This example demonstrates how to configure multiple solar panel arrays
+    (planes) with different orientations. Using multiple planes requires both
+    an API key and a Personal Plus or higher subscription.
+    """
+    async with ForecastSolar(
+        api_key="your-api-key",  # API key is required for multiple planes
+        latitude=52.16,
+        longitude=4.47,
+        # First plane configuration (main roof)
+        declination=20,
+        azimuth=10,
+        kwp=2.160,
+        # Additional planes (e.g., garage roof, secondary array)
+        planes=[
+            Plane(declination=30, azimuth=-90, kwp=1.5),  # West-facing plane
+            Plane(declination=30, azimuth=90, kwp=1.5),  # East-facing plane
+        ],
+    ) as forecast:
+        try:
+            estimate = await forecast.estimate()
+        except ForecastSolarRatelimitError as err:
+            print("Ratelimit reached")
+            print(f"Rate limit resets at {err.reset_at}")
+            reset_period = err.reset_at - datetime.now(UTC)
+            # Strip microseconds as they are not informative
+            reset_period -= timedelta(microseconds=reset_period.microseconds)
+            print(f"That's in {reset_period}")
+            return
+
+        # Uncomment this if you want to see what's in the estimate arrays
+        # pprint(dataclasses.asdict(estimate))
+        print()
+        print(f"energy_production_today: {estimate.energy_production_today}")
+        print(
+            "energy_production_today_remaining: "
+            f"{estimate.energy_production_today_remaining}"
+        )
+        print(
+            f"power_highest_peak_time_today: {estimate.power_highest_peak_time_today}"
+        )
+        print(f"energy_production_tomorrow: {estimate.energy_production_tomorrow}")
+        print(
+            "power_highest_peak_time_tomorrow: "
+            f"{estimate.power_highest_peak_time_tomorrow}"
+        )
+        print()
+        print(f"power_production_now: {estimate.power_production_now}")
+        print(
+            "power_production in 1 hour: "
+            f"{estimate.power_production_at_time(estimate.now() + timedelta(hours=1))}"
+        )
+        print(
+            "power_production in 6 hours: "
+            f"{estimate.power_production_at_time(estimate.now() + timedelta(hours=6))}"
+        )
+        print(
+            "power_production in 12 hours: "
+            f"{estimate.power_production_at_time(estimate.now() + timedelta(hours=12))}"
+        )
+        print(
+            "power_production in 24 hours: "
+            f"{estimate.power_production_at_time(estimate.now() + timedelta(hours=24))}"
+        )
+        print()
+        print(f"energy_current_hour: {estimate.energy_current_hour}")
+        print(f"energy_production next hour: {estimate.sum_energy_production(1)}")
+        print(f"energy_production next 6 hours: {estimate.sum_energy_production(6)}")
+        print(f"energy_production next 12 hours: {estimate.sum_energy_production(12)}")
+        print(f"energy_production next 24 hours: {estimate.sum_energy_production(24)}")
+        print(f"timezone: {estimate.timezone}")
+        print(f"account_type: {estimate.account_type}")
+        print(forecast.ratelimit)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/src/forecast_solar/__init__.py b/src/forecast_solar/__init__.py
@@ -9,7 +9,7 @@
     ForecastSolarRequestError,
 )
 from .forecast_solar import ForecastSolar
-from .models import AccountType, Estimate, Ratelimit
+from .models import AccountType, Estimate, Plane, Ratelimit
 
 __all__ = [
     "AccountType",
@@ -21,5 +21,6 @@
     "ForecastSolarError",
     "ForecastSolarRatelimitError",
     "ForecastSolarRequestError",
+    "Plane",
     "Ratelimit",
 ]
diff --git a/src/forecast_solar/forecast_solar.py b/src/forecast_solar/forecast_solar.py
@@ -16,7 +16,7 @@
     ForecastSolarRatelimitError,
     ForecastSolarRequestError,
 )
-from .models import Estimate, Ratelimit
+from .models import Estimate, Plane, Ratelimit
 
 
 @dataclass
@@ -34,13 +34,30 @@ class ForecastSolar:
     damping_morning: float | None = None
     damping_evening: float | None = None
     horizon: str | None = None
+    planes: list[Plane] | None = None
 
     session: ClientSession | None = None
     ratelimit: Ratelimit | None = None
     inverter: float | None = None
     _close_session: bool = False
     _base_url = URL("https://api.forecast.solar")
 
+    def _build_plane_path(self) -> str:
+        """Build the plane path segment for API URLs.
+
+        Returns
+        -------
+            A string containing the plane parameters for all planes.
+            Additional planes are only included if an API key is provided.
+
+        """
+        path = f"{self.declination}/{self.azimuth}/{self.kwp}"
+        # Only include additional planes if an API key is provided
+        if self.planes and self.api_key is not None:
+            for plane in self.planes:
+                path += f"/{plane.declination}/{plane.azimuth}/{plane.kwp}"
+        return path
+
     async def _request(
         self,
         uri: str,
@@ -118,6 +135,10 @@ async def _request(
             data = await response.json()
             raise ForecastSolarRatelimitError(data["message"])
 
+        if response.status == 404:
+            data = await response.json()
+            raise ForecastSolarRequestError(data["message"])
+
         if rate_limit and response.status == 200:
             self.ratelimit = Ratelimit.from_response(response)
 
@@ -142,8 +163,7 @@ async def validate_plane(self) -> bool:
 
         """
         await self._request(
-            f"check/{self.latitude}/{self.longitude}"
-            f"/{self.declination}/{self.azimuth}/{self.kwp}",
+            f"check/{self.latitude}/{self.longitude}/{self._build_plane_path()}",
             rate_limit=False,
             authenticate=False,
         )
@@ -187,8 +207,7 @@ async def estimate(self, actual: float = 0) -> Estimate:
             params["actual"] = str(actual)
 
         data = await self._request(
-            f"estimate/{self.latitude}/{self.longitude}"
-            f"/{self.declination}/{self.azimuth}/{self.kwp}",
+            f"estimate/{self.latitude}/{self.longitude}/{self._build_plane_path()}",
             params=params,
         )
 
diff --git a/src/forecast_solar/models.py b/src/forecast_solar/models.py
@@ -50,6 +50,23 @@ class AccountType(StrEnum):
     PROFESSIONAL = "professional"
 
 
+@dataclass
+class Plane:
+    """Represents a solar plane configuration.
+
+    Attributes
+    ----------
+        declination: The tilt of the solar panels (0-90 degrees).
+        azimuth: The direction the solar panels are facing (-180 to 180 degrees).
+        kwp: The size of the solar panels in kWp.
+
+    """
+
+    declination: float
+    azimuth: float
+    kwp: float
+
+
 @dataclass
 class Estimate:
     """Object holding estimate forecast results from Forecast.Solar.
diff --git a/tests/__snapshots__/test_models.ambr b/tests/__snapshots__/test_models.ambr
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -5,7 +5,7 @@
 import pytest
 from aiohttp import ClientSession
 
-from forecast_solar import ForecastSolar
+from forecast_solar import ForecastSolar, Plane
 
 
 @pytest.fixture(name="forecast_client")
@@ -46,3 +46,24 @@ async def client_api_key() -> AsyncGenerator[ForecastSolar, None]:
         ) as forecast_key_client,
     ):
         yield forecast_key_client
+
+
+@pytest.fixture(name="forecast_multi_plane_client")
+async def client_multi_plane() -> AsyncGenerator[ForecastSolar, None]:
+    """Return a Forecast.Solar client with multiple planes."""
+    async with (
+        ClientSession() as session,
+        ForecastSolar(
+            api_key="myapikey",
+            latitude=52.16,
+            longitude=4.47,
+            declination=20,
+            azimuth=10,
+            kwp=2.160,
+            planes=[
+                Plane(declination=30, azimuth=-90, kwp=1.5),
+            ],
+            session=session,
+        ) as forecast_multi_plane_client,
+    ):
+        yield forecast_multi_plane_client
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
@@ -128,3 +128,24 @@ async def test_status_502(
     )
     with pytest.raises(ForecastSolarConnectionError):
         assert await forecast_client._request("test")
+
+
+async def test_status_404(
+    aresponses: ResponsesMockServer,
+    forecast_client: ForecastSolar,
+) -> None:
+    """Test response status 404."""
+    aresponses.add(
+        "api.forecast.solar",
+        "/test",
+        "GET",
+        aresponses.Response(
+            status=404,
+            headers={
+                "Content-Type": "application/json",
+            },
+            text='{"message": {"code": 404, "text": "Not Found"}}',
+        ),
+    )
+    with pytest.raises(ForecastSolarRequestError):
+        assert await forecast_client._request("test")
diff --git a/tests/test_models.py b/tests/test_models.py

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`ForecastSolarRequestError,`
`10`	`10`	`)`
`11`	`11`	`from .forecast_solar import ForecastSolar`
`12`		`-from .models import AccountType, Estimate, Ratelimit`
	`12`	`+from .models import AccountType, Estimate, Plane, Ratelimit`
`13`	`13`
`14`	`14`	`__all__ = [`
`15`	`15`	`"AccountType",`
`@@ -21,5 +21,6 @@`
`21`	`21`	`"ForecastSolarError",`
`22`	`22`	`"ForecastSolarRatelimitError",`
`23`	`23`	`"ForecastSolarRequestError",`
	`24`	`+ "Plane",`
`24`	`25`	`"Ratelimit",`
`25`	`26`	`]`