EOS/tests/testdata/docs/_generated/configpvforecast.md at 1abdd345c47b3db5b59b7989491ee1f43fd0fa49

Mirrors/EOS

Fork 0

mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-09-11 10:26:38 +00:00

Files

T

1abdd345c4 fix: unify mypy environments for local checks and CI (#1291 )

The isolated pre-commit mypy hook previously omitted runtime type information that
make mypy used, hiding errors involving dependencies such as Pydantic and Pendulum.
Makefile, pre-commit and CI now run the same full-project typing policy in the
development environment defined by uv.lock.

- Use uv run --locked --exact --extra dev and the same mypy arguments for Makefile
and the local hook. Check all of src and tests, including on configuration-only
changes.
- Pin Python 3.13 for local development and the pre-commit CI job, and install the
locked pre-commit version in CI.
- Disable incremental analysis because existing Pendulum cache state changes mypy 2.3.1
diagnostics. Document the policy, the performance tradeoff and the existing typing debt.
- Add a regression test that exercises Makefile, the hook and the CI command in a
temporary project, accepting valid dependency types and detecting deliberate
Pydantic/Pendulum assignment errors.

Resolve the newly detected mypy diagnostics.

- Enable the numpydantic and Pydantic mypy plugins, retaining strict Pydantic
constructor typing with init_typed = true. Validate raw/coercible payloads through model_validate.
- Propagate concrete record, provider and time-window types through generic collections,
factories and lookup methods. Preserve runtime field inspection and generated time-window
documentation.
- Align Pendulum annotations with actual factory/arithmetic results while retaining Pydantic
validation adapters at runtime. Correct optional values, array boundaries, REST handlers
and plotting interfaces.
- Add pinned scipy-stubs and types-psutil, update uv.lock, and supply the plugins' dependencies.
- Add runtime regression coverage for validated path defaults, normalized time-series metadata,
generic field inspection, invalid timestamps and unsupported provider imports.

Runtime and compatibility details:

- Validate path defaults as Path objects while retaining raw string defaults needed by
migration serialization with exclude_defaults.
- Normalize feed-in tariff lists and default charge rates to NumPy arrays; reject missing
timestamps/uninitialized values explicitly. Importing into a provider without import support
returns HTTP 400.
- Public JSON schemas and OpenAPI structure match main (excluding the generated version).

Signed-off-by: dr-dimitry

Signed-off-by: dr-dimitry
Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: dr-dimitri <87113560+dr-dimitri@users.noreply.github.com>
Co-authored-by: Normann <github@koldrack.com>

2026-09-10 23:20:35 +02:00

18 KiB

Raw Blame History

PV Forecast Configuration

:::{table} pvforecast :widths: 10 20 10 5 5 30 :align: left

Name	Environment Variable	Type	Read-Only	Default	Description
forecastsolar	`EOS_PVFORECAST__FORECASTSOLAR`	`PVForecastForecastSolarCommonSettings`	`rw`	`required`	ForecastSolar provider settings
homeassistant	`EOS_PVFORECAST__HOMEASSISTANT`	`PVForecastHomeAssistantCommonSettings`	`rw`	`required`	Home Assistant provider settings
max_planes	`EOS_PVFORECAST__MAX_PLANES`	`int	None`	`rw`	`0`
planes	`EOS_PVFORECAST__PLANES`	`list[akkudoktoreos.prediction.pvforecast.PVForecastPlaneSetting]	None`	`rw`	`None`
planes_azimuth		`List[float]`	`ro`	`N/A`	Compute a list of the azimuths per active planes.
planes_inverter_paco		`Any`	`ro`	`N/A`	Compute a list of the maximum power rating of the inverter per active planes.
planes_peakpower		`List[float]`	`ro`	`N/A`	Compute a list of the peak power per active planes.
planes_tilt		`List[float]`	`ro`	`N/A`	Compute a list of the tilts per active planes.
planes_userhorizon		`Any`	`ro`	`N/A`	Compute a list of the user horizon per active planes.
provider	`EOS_PVFORECAST__PROVIDER`	`str	None`	`rw`	`None`
providers		`list[str]`	`ro`	`N/A`	Available PVForecast provider ids.
pvforecastimport	`EOS_PVFORECAST__PVFORECASTIMPORT`	`PVForecastImportCommonSettings`	`rw`	`required`	PV forecast import provider settings
pvlib	`EOS_PVFORECAST__PVLIB`	`PVForecastPVLibCommonSettings`	`rw`	`required`	PVLib provider settings
pvnode	`EOS_PVFORECAST__PVNODE`	`PVForecastPVNodeCommonSettings`	`rw`	`required`	PVNode provider settings
solcast	`EOS_PVFORECAST__SOLCAST`	`PVForecastSolcastCommonSettings`	`rw`	`required`	Solcast provider settings
vrm	`EOS_PVFORECAST__VRM`	`PVForecastVrmCommonSettings`	`rw`	`required`	Victron Remote Management (VRM) provider settings
:::

Example Input

   {
       "pvforecast": {
           "provider": "PVForecastAkkudoktor",
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": null
           },
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           },
           "homeassistant": {
               "entity_id": "sensor.pv_forecast",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": null,
               "token": null
           },
           "pvlib": {},
           "pvnode": {
               "api_key": "",
               "site_id": null,
               "forecast_days": 2
           },
           "forecastsolar": {
               "api_key": null
           },
           "solcast": {
               "api_key": "",
               "site_id": ""
           },
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               },
               {
                   "surface_tilt": 20.0,
                   "surface_azimuth": 90.0,
                   "userhorizon": [
                       5.0,
                       15.0,
                       25.0
                   ],
                   "peakpower": 3.5,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 1,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 4000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ],
           "max_planes": 1
       }
   }

Example Output

   {
       "pvforecast": {
           "provider": "PVForecastAkkudoktor",
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": null
           },
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           },
           "homeassistant": {
               "entity_id": "sensor.pv_forecast",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": null,
               "token": null
           },
           "pvlib": {},
           "pvnode": {
               "api_key": "",
               "site_id": null,
               "forecast_days": 2
           },
           "forecastsolar": {
               "api_key": null
           },
           "solcast": {
               "api_key": "",
               "site_id": ""
           },
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               },
               {
                   "surface_tilt": 20.0,
                   "surface_azimuth": 90.0,
                   "userhorizon": [
                       5.0,
                       15.0,
                       25.0
                   ],
                   "peakpower": 3.5,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 1,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 4000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ],
           "max_planes": 1,
           "providers": [
               "PVForecastAkkudoktor",
               "PVForecastForecastSolar",
               "PVForecastHomeAssistant",
               "PVForecastImport",
               "PVForecastPVLib",
               "PVForecastPVNode",
               "PVForecastSolcast",
               "PVForecastVrm"
           ],
           "planes_peakpower": [
               5.0,
               3.5
           ],
           "planes_azimuth": [
               180.0,
               90.0
           ],
           "planes_tilt": [
               10.0,
               20.0
           ],
           "planes_userhorizon": [
               [
                   10.0,
                   20.0,
                   30.0
               ],
               [
                   5.0,
                   15.0,
                   25.0
               ]
           ],
           "planes_inverter_paco": [
               6000.0,
               4000.0
           ]
       }
   }

Common settings for PV forecast VRM API

:::{table} pvforecast::vrm :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
site_id	`int`	`rw`	`12345`	VRM-Installation-ID
token	`str`	`rw`	`your-token`	Access token for connecting to the Victron Remote Management (VRM) API
:::

Example Input/Output

   {
       "pvforecast": {
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           }
       }
   }

Common settings for the Solcast PV forecast provider

:::{table} pvforecast::solcast :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
api_key	`str`	`rw`	``	Solcast API key (Bearer auth). Required.
site_id	`str`	`rw`	``	Solcast rooftop site (resource) id. Required.
:::

Example Input/Output

   {
       "pvforecast": {
           "solcast": {
               "api_key": "your-solcast-key",
               "site_id": "abcd-1234-efgh-5678"
           }
       }
   }

Common settings for the pvnode.com PV forecast provider

:::{table} pvforecast::pvnode :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
api_key	`str`	`rw`	``	pvnode.com API key (Bearer auth). Required.
forecast_days	`int`	`rw`	`2`	Forecast horizon in days (1-7, capped by the pvnode plan).
site_id	`str	None`	`rw`	`None`
:::

Example Input/Output

   {
       "pvforecast": {
           "pvnode": {
               "api_key": "pvn_live_xxxxxxxxxxxxxxxx",
               "site_id": "abcd-1234",
               "forecast_days": 2
           }
       }
   }

Common settings for pvforecast data calculation with PVLib

:::{table} pvforecast::pvlib :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
:::

Example Input/Output

   {
       "pvforecast": {
           "pvlib": {}
       }
   }

Common settings for pvforecast data import from file or JSON string

:::{table} pvforecast::pvforecastimport :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
import_file_path	`str	pathlib.Path	None`	`rw`
import_json	`str	None`	`rw`	`None`
:::

Example Input/Output

   {
       "pvforecast": {
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": "{\"pvforecast_ac_power\": [0, 8.05, 352.91]}"
           }
       }
   }

PV Forecast Plane Configuration

:::{table} pvforecast::planes::list :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
albedo	`float	None`	`rw`	`0.2`
inverter_model	`str	None`	`rw`	`None`
inverter_paco	`int	None`	`rw`	`None`
loss	`float	None`	`rw`	`14.0`
module_model	`str	None`	`rw`	`None`
modules_per_string	`int	None`	`rw`	`None`
mountingplace	`str	None`	`rw`	`building`
optimal_surface_tilt	`bool	None`	`rw`	`False`
optimalangles	`bool	None`	`rw`	`False`
peakpower	`float	None`	`rw`	`None`
pvtechchoice	`str	None`	`rw`	`crystSi`
strings_per_inverter	`int	None`	`rw`	`None`
surface_azimuth	`float	None`	`rw`	`180.0`
surface_tilt	`float	None`	`rw`	`30.0`
trackingtype	`int	None`	`rw`	`None`
userhorizon	`List[float]	None`	`rw`	`None`
:::

Example Input/Output

   {
       "pvforecast": {
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "building",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ]
       }
   }

Common settings for pvforecast data from a Home Assistant entity

:::{table} pvforecast::homeassistant :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
attribute	`str`	`rw`	`forecast`	Entity attribute holding the forecast list.
base_url	`str	None`	`rw`	`None`
datetime_key	`str`	`rw`	`datetime`	Key for the timestamp in each forecast entry.
entity_id	`str`	`rw`	`sensor.pv_forecast`	Home Assistant entity providing the PV forecast.
token	`str	None`	`rw`	`None`
value_key	`str`	`rw`	`watts`	Key for the AC power value in each forecast entry.
value_unit	`Literal['W', 'kW']`	`rw`	`W`	Unit of the forecast value. Converted to W internally.
:::

Example Input/Output

   {
       "pvforecast": {
           "homeassistant": {
               "entity_id": "sensor.pv1_power_now",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": "http://homeassistant.local:8123",
               "token": null
           }
       }
   }

Common settings for the Forecast.Solar PV forecast provider

:::{table} pvforecast::forecastsolar :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
api_key	`str	None`	`rw`	`None`
:::

Example Input/Output

   {
       "pvforecast": {
           "forecastsolar": {
               "api_key": null
           }
       }
   }

18 KiB Raw Blame History

PV Forecast Configuration

Common settings for PV forecast VRM API

Common settings for the Solcast PV forecast provider

Common settings for the pvnode.com PV forecast provider

Common settings for pvforecast data calculation with PVLib

Common settings for pvforecast data import from file or JSON string

PV Forecast Plane Configuration

Common settings for pvforecast data from a Home Assistant entity

Common settings for the Forecast.Solar PV forecast provider

18 KiB

Raw Blame History