pykoplenti 1.0.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

pykoplenti/cli.py

@@ -7,13 +7,14 @@ from pprint import pprint
 import re
 import tempfile
 import traceback
-from typing import Callable
+from typing import Any, Awaitable, Callable, Dict, Union
 
 from aiohttp import ClientSession, ClientTimeout
 import click
 from prompt_toolkit import PromptSession, print_formatted_text
 
 from pykoplenti import ApiClient
+from pykoplenti.extended import ExtendedApiClient
 
 
 class SessionCache:
@@ -22,7 +23,7 @@ class SessionCache:
     def __init__(self, host):
         self.host = host
 
-    def read_session_id(self) -> str:
+    def read_session_id(self) -> Union[str, None]:
         file = os.path.join(tempfile.gettempdir(), f"pykoplenti-session-{self.host}")
         if os.path.isfile(file):
             with open(file, "rt") as f:
@@ -77,7 +78,8 @@ class ApiShell:
         # Test commands:
         # get_settings
         # get_setting_values 'devices:local' 'Battery:MinSoc'
-        # get_setting_values 'devices:local' ['Battery:MinSoc','Battery:MinHomeComsumption']
+        # get_setting_values 'devices:local' ['Battery:MinSoc', \
+        # 'Battery:MinHomeComsumption']
         # get_setting_values 'scb:time'
         # set_setting_values 'devices:local' {'Battery:MinSoc':'15'}
 
@@ -93,7 +95,8 @@ class ApiShell:
                 if text.strip() == "":
                     continue
                 else:
-                    # TODO split does not know about lists or dicts or strings with spaces
+                    # TODO split does not know about lists or dicts or strings
+                    # with spaces
                     method_name, *arg_values = text.strip().split()
 
                     if method_name == "help":
@@ -152,17 +155,17 @@ class ApiShell:
 
 async def repl_main(host, port, passwd):
     async with ClientSession(timeout=ClientTimeout(total=10)) as session:
-        client = ApiClient(session, host=host, port=port)
+        client = ExtendedApiClient(session, host=host, port=port)
 
         shell = ApiShell(client)
         await shell.run(passwd)
 
 
 async def command_main(
-    host: str, port: int, passwd: str, fn: Callable[[ApiClient], None]
+    host: str, port: int, passwd: str, fn: Callable[[ApiClient], Awaitable[Any]]
 ):
     async with ClientSession(timeout=ClientTimeout(total=10)) as session:
-        client = ApiClient(session, host=host, port=port)
+        client = ExtendedApiClient(session, host=host, port=port)
         session_cache = SessionCache(host)
 
         # Try to reuse an existing session
@@ -171,7 +174,8 @@ async def command_main(
         if not me.is_authenticated:
             # create a new session
             await client.login(passwd)
-            session_cache.write_session_id(client.session_id)
+            if client.session_id is not None:
+                session_cache.write_session_id(client.session_id)
 
         await fn(client)
 
@@ -231,7 +235,8 @@ def read_events(global_args, lang, count):
         data = await client.get_events(lang=lang, max_count=count)
         for event in data:
             print(
-                f"{event.is_active < 5} {event.start_time} {event.end_time} {event.description}"
+                f"{event.is_active < 5} {event.start_time} {event.end_time} "
+                "{event.description}"
             )
 
     asyncio.run(
@@ -253,7 +258,7 @@ def download_log(global_args, out, begin, end):
     """Download the log data from the inverter to a file."""
 
     async def fn(client: ApiClient):
-        data = await client.download_logdata(writer=out, begin=begin, end=end)
+        await client.download_logdata(writer=out, begin=begin, end=end)
 
     asyncio.run(
         command_main(global_args.host, global_args.port, global_args.passwd, fn)
@@ -309,7 +314,7 @@ def read_processdata(global_args, ids):
             values = await client.get_process_data_values(query)
 
         for k, v in values.items():
-            for x in v:
+            for x in v.values():
                 print(f"{k}/{x.id}={x.value}")
 
     asyncio.run(
@@ -348,7 +353,8 @@ def read_settings(global_args, ids):
     \b
     Examples:
         read-settings devices:local/Battery:MinSoc
-        read-settings devices:local/Battery:MinSoc devices:local/Battery:MinHomeComsumption
+        read-settings devices:local/Battery:MinSoc \
+            devices:local/Battery:MinHomeComsumption
     """
 
     async def fn(client: ApiClient):
@@ -388,7 +394,7 @@ def write_settings(global_args, id_values):
     """
 
     async def fn(client: ApiClient):
-        query = defaultdict(dict)
+        query: Dict[str, Dict[str, str]] = defaultdict(dict)
         for id_value in id_values:
             m = re.match(
                 r"(?P<module_id>.+)/(?P<setting_id>.+)=(?P<value>.+)", id_value
@@ -414,4 +420,4 @@ def write_settings(global_args, id_values):
 if __name__ == "__main__":
     import sys
 
-    cli(sys.argv[1:])
+    cli(sys.argv[1:], auto_envvar_prefix="PYKOPLENTI")

pykoplenti/extended.py

@@ -0,0 +1,239 @@
+"""Extended ApiClient which provides virtual process data values."""
+
+from abc import ABC, abstractmethod
+from collections import ChainMap, defaultdict
+from typing import Final, Iterable, Literal, Mapping, MutableMapping, Union
+
+from aiohttp import ClientSession
+
+from .api import ApiClient
+from .model import ProcessData, ProcessDataCollection
+
+_VIRT_MODUL_ID: Final = "_virt_"
+
+
+class _VirtProcessDataItemBase(ABC):
+    """Base class for all virtual process data items."""
+
+    def __init__(self, processid: str, process_data: dict[str, set[str]]) -> None:
+        self.processid = processid
+        self.process_data = process_data
+        self.available_process_data: dict[str, set[str]] = {}
+
+    def update_actual_process_ids(
+        self, available_process_ids: Mapping[str, Iterable[str]]
+    ):
+        """Update which process data for this item are available."""
+        self.available_process_data.clear()
+        for module_id, process_ids in self.process_data.items():
+            if module_id in available_process_ids:
+                matching_process_ids = process_ids.intersection(
+                    available_process_ids[module_id]
+                )
+                if len(matching_process_ids) > 0:
+                    self.available_process_data[module_id] = matching_process_ids
+
+    @abstractmethod
+    def get_value(
+        self, process_values: Mapping[str, ProcessDataCollection]
+    ) -> ProcessData:
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        ...
+
+
+class _VirtProcessDataItemSum(_VirtProcessDataItemBase):
+    def get_value(
+        self, process_values: Mapping[str, ProcessDataCollection]
+    ) -> ProcessData:
+        values: list[float] = []
+        for module_id, process_ids in self.available_process_data.items():
+            values += (process_values[module_id][pid].value for pid in process_ids)
+
+        return ProcessData(id=self.processid, unit="W", value=sum(values))
+
+    def is_available(self) -> bool:
+        return len(self.available_process_data) > 0
+
+
+class _VirtProcessDataItemEnergyToGrid(_VirtProcessDataItemBase):
+    def __init__(
+        self, processid: str, scope: Literal["Total", "Year", "Month", "Day"]
+    ) -> None:
+        super().__init__(
+            processid,
+            {
+                "scb:statistic:EnergyFlow": {
+                    f"Statistic:Yield:{scope}",
+                    f"Statistic:EnergyHomeBat:{scope}",
+                    f"Statistic:EnergyHomePv:{scope}",
+                }
+            },
+        )
+        self.scope = scope
+
+    def get_value(
+        self, process_values: Mapping[str, ProcessDataCollection]
+    ) -> ProcessData:
+        statistics = process_values["scb:statistic:EnergyFlow"]
+        energy_yield = statistics[f"Statistic:Yield:{self.scope}"].value
+        energy_home_bat = statistics[f"Statistic:EnergyHomeBat:{self.scope}"].value
+        energy_home_pv = statistics[f"Statistic:EnergyHomePv:{self.scope}"].value
+
+        return ProcessData(
+            id=self.processid,
+            unit="Wh",
+            value=energy_yield - energy_home_pv - energy_home_bat,
+        )
+
+    def is_available(self) -> bool:
+        return self.available_process_data == self.process_data
+
+
+class _VirtProcessDataManager:
+    """Manager for all virtual process data items."""
+
+    def __init__(self) -> None:
+        self._virt_process_data: Iterable[_VirtProcessDataItemBase] = [
+            _VirtProcessDataItemSum(
+                "pv_P",
+                {
+                    "devices:local:pv1": {"P"},
+                    "devices:local:pv2": {"P"},
+                    "devices:local:pv3": {"P"},
+                },
+            ),
+            _VirtProcessDataItemEnergyToGrid("Statistic:EnergyGrid:Total", "Total"),
+            _VirtProcessDataItemEnergyToGrid("Statistic:EnergyGrid:Year", "Year"),
+            _VirtProcessDataItemEnergyToGrid("Statistic:EnergyGrid:Month", "Month"),
+            _VirtProcessDataItemEnergyToGrid("Statistic:EnergyGrid:Day", "Day"),
+        ]
+
+    def initialize(self, available_process_data: Mapping[str, Iterable[str]]):
+        """Initialize the virtual items with the list of available process ids."""
+        for vpd in self._virt_process_data:
+            vpd.update_actual_process_ids(available_process_data)
+
+    def adapt_process_data_response(
+        self, process_data: dict[str, list[str]]
+    ) -> Mapping[str, list[str]]:
+        """Adapt the reponse of reading process data."""
+        virt_process_data: dict[str, list[str]] = {_VIRT_MODUL_ID: []}
+
+        for vpd in self._virt_process_data:
+            if vpd.is_available():
+                virt_process_data[_VIRT_MODUL_ID].append(vpd.processid)
+
+        return ChainMap(process_data, virt_process_data)
+
+    def adapt_process_value_request(
+        self, process_data: Mapping[str, Iterable[str]]
+    ) -> Mapping[str, Iterable[str]]:
+        """Adapt the request for process values."""
+        result: MutableMapping[str, set[str]] = defaultdict(set)
+
+        for mid, pids in process_data.items():
+            result[mid].update(pids)
+
+        for requested_virtual_process_id in result.pop(_VIRT_MODUL_ID):
+            for virtual_process_data in self._virt_process_data:
+                if virtual_process_data.is_available():
+                    if requested_virtual_process_id == virtual_process_data.processid:
+                        # add ids for virtual if they are missing
+                        for (
+                            mid,
+                            pids,
+                        ) in virtual_process_data.available_process_data.items():
+                            result[mid].update(pids)
+                        break
+            else:
+                raise ValueError(
+                    f"No virtual process data '{requested_virtual_process_id}'."
+                )
+
+        return result
+
+    def adapt_process_value_response(
+        self,
+        values: Mapping[str, ProcessDataCollection],
+        request_data: Mapping[str, Iterable[str]],
+    ) -> Mapping[str, ProcessDataCollection]:
+        """Adapt the reponse for process values."""
+        result = {}
+
+        # add virtual items
+        virtual_process_data_values = []
+        for id in request_data[_VIRT_MODUL_ID]:
+            for vpd in self._virt_process_data:
+                if vpd.processid == id:
+                    virtual_process_data_values.append(vpd.get_value(values))
+        result["_virt_"] = ProcessDataCollection(virtual_process_data_values)
+
+        # add all values which was requested but not the extra ids for the virtual ids
+        for mid, pdc in values.items():
+            if mid in request_data:
+                pids = [x for x in pdc.values() if x.id in request_data[mid]]
+                if len(pids) > 0:
+                    result[mid] = ProcessDataCollection(pids)
+
+        return result
+
+
+class ExtendedApiClient(ApiClient):
+    """Extend ApiClient with virtual process data."""
+
+    def __init__(self, websession: ClientSession, host: str, port: int = 80):
+        super().__init__(websession, host, port)
+
+        self._virt_process_data = _VirtProcessDataManager()
+        self._virt_process_data_initialized = False
+
+    async def get_process_data(self) -> Mapping[str, Iterable[str]]:
+        process_data = await super().get_process_data()
+
+        self._virt_process_data.initialize(process_data)
+        self._virt_process_data_initialized = True
+        return self._virt_process_data.adapt_process_data_response(process_data)
+
+    async def get_process_data_values(
+        self,
+        module_id: Union[str, Mapping[str, Iterable[str]]],
+        processdata_id: Union[str, Iterable[str], None] = None,
+    ) -> Mapping[str, ProcessDataCollection]:
+        contains_virt_process_data = (
+            isinstance(module_id, str) and _VIRT_MODUL_ID == module_id
+        ) or (isinstance(module_id, dict) and _VIRT_MODUL_ID in module_id)
+
+        if not contains_virt_process_data:
+            # short-cut if no virtual process is requested
+            return await super().get_process_data_values(module_id, processdata_id)
+
+        process_data: dict[str, Iterable[str]] = {}
+        if isinstance(module_id, str) and processdata_id is None:
+            process_data[module_id] = []
+        elif isinstance(module_id, str) and isinstance(processdata_id, str):
+            process_data[module_id] = [processdata_id]
+        elif (
+            isinstance(module_id, str)
+            and processdata_id is not None
+            and hasattr(processdata_id, "__iter__")
+        ):
+            process_data[module_id] = list(processdata_id)
+        elif isinstance(module_id, Mapping) and processdata_id is None:
+            process_data.update(module_id)
+        else:
+            raise TypeError("Invalid combination of module_id and processdata_id.")
+
+        if not self._virt_process_data_initialized:
+            pd = await self.get_process_data()
+            self._virt_process_data.initialize(pd)
+            self._virt_process_data_initialized = True
+
+        process_values = await super().get_process_data_values(
+            self._virt_process_data.adapt_process_value_request(process_data)
+        )
+        return self._virt_process_data.adapt_process_value_response(
+            process_values, process_data
+        )

pykoplenti/model.py

@@ -0,0 +1,99 @@
+from datetime import datetime
+from typing import Iterator, Mapping
+
+from pydantic import BaseModel, Field
+
+
+class MeData(BaseModel):
+    """Represent the data of the 'me'-request."""
+
+    is_locked: bool = Field(alias="locked")
+    is_active: bool = Field(alias="active")
+    is_authenticated: bool = Field(alias="authenticated")
+    permissions: list[str] = Field()
+    is_anonymous: bool = Field(alias="anonymous")
+    role: str
+
+
+class VersionData(BaseModel):
+    """Represent the data of the 'version'-request."""
+
+    api_version: str
+    hostname: str
+    name: str
+    sw_version: str
+
+
+class ModuleData(BaseModel):
+    """Represents a single module."""
+
+    id: str
+    type: str
+
+
+class ProcessData(BaseModel):
+    """Represents a single process data."""
+
+    id: str
+    unit: str
+    value: float
+
+
+class ProcessDataCollection(Mapping):
+    """Represents a collection of process data value."""
+
+    def __init__(self, process_data: list[ProcessData]):
+        self._process_data = process_data
+
+    def __len__(self) -> int:
+        return len(self._process_data)
+
+    def __iter__(self) -> Iterator[str]:
+        return (x.id for x in self._process_data)
+
+    def __getitem__(self, item) -> ProcessData:
+        try:
+            return next(x for x in self._process_data if x.id == item)
+        except StopIteration:
+            raise KeyError(item)
+
+    def __eq__(self, __other: object) -> bool:
+        if not isinstance(__other, ProcessDataCollection):
+            return False
+
+        return self._process_data == __other._process_data
+
+    def __str__(self):
+        return "[" + ",".join(str(x) for x in self._process_data) + "]"
+
+    def __repr__(self):
+        return (
+            "ProcessDataCollection(["
+            + ",".join(repr(x) for x in self._process_data)
+            + "])"
+        )
+
+
+class SettingsData(BaseModel):
+    """Represents a single settings data."""
+
+    min: str | None
+    max: str | None
+    default: str | None
+    access: str
+    unit: str | None
+    id: str
+    type: str
+
+
+class EventData(BaseModel):
+    """Represents an event of the inverter."""
+
+    start_time: datetime
+    end_time: datetime
+    code: int
+    long_description: str
+    category: str
+    description: str
+    group: str
+    is_active: bool

{pykoplenti-1.0.0.dist-info → pykoplenti-1.2.1.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: pykoplenti
-Version: 1.0.0
+Version: 1.2.1
 Summary: Python REST-Client for Kostal Plenticore Solar Inverters
 Home-page: https://github.com/stegm/pyclient_koplenti
 Author: @stegm
-License: UNKNOWN
+Project-URL: repository, https://github.com/stegm/pyclient_koplenti
+Project-URL: changelog, https://github.com/stegm/pykoplenti/blob/master/CHANGELOG.md
+Project-URL: issues, https://github.com/stegm/pykoplenti/issues
 Keywords: rest kostal plenticore solar
-Platform: UNKNOWN
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -16,11 +17,13 @@ Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Topic :: Software Development :: Libraries
 Description-Content-Type: text/markdown
-Requires-Dist: aiohttp (>=3.6)
-Requires-Dist: pycryptodome (>=3.9)
+License-File: LICENSE
+Requires-Dist: aiohttp ~=3.8.5
+Requires-Dist: pycryptodome ~=3.19
+Requires-Dist: pydantic ~=1.10
 Provides-Extra: cli
-Requires-Dist: prompt-toolkit (>=3.0) ; extra == 'cli'
-Requires-Dist: click (>=7.1) ; extra == 'cli'
+Requires-Dist: prompt-toolkit >=3.0 ; extra == 'cli'
+Requires-Dist: click >=7.1 ; extra == 'cli'
 
 # Python Library for Accessing Kostal Plenticore Inverters
 
@@ -32,14 +35,15 @@ This library is not affiliated with Kostal and is no offical product. It uses th
 
 ## Features
 
-* Authenticate
-* Read/Write settings
-* Read process data
-* Read events
-* Download of log data
-* Full async-Support for reading and writing data
-* Commandline interface for shell access
-* Dynamic data model
+- Authenticate
+- Read/Write settings
+- Read process data
+- Read events
+- Download of log data
+- Full async-Support for reading and writing data
+- [Commandline interface](doc/command_line.md) for shell access
+- Dynamic data model - adapts automatically to new process data or settings
+- [Virtual Process Data](doc/virtual_process_data.md) values
 
 ## Getting Started
 
@@ -49,12 +53,11 @@ You will need Python >=3.7.
 
 ### Installing the library
 
-Packages of this library are released on [PyPI](https://pypi.org/project/kostal-plenticore/) and can be 
-installed with `pip`. Alternatively the packages can also be downloaded from 
+Packages of this library are released on [PyPI](https://pypi.org/project/kostal-plenticore/) and can be
+installed with `pip`. Alternatively the packages can also be downloaded from
 [GitHub](https://github.com/stegm/pykoplenti/releases/).
 
-
-I recommend to use a [virtual environment](https://docs.python.org/3/library/venv.html) for this, 
+I recommend to use a [virtual environment](https://docs.python.org/3/library/venv.html) for this,
 because it installs the dependecies independently from the system. The installed CLI tools can then be called
 without activating the virtual environment it.
 
@@ -68,7 +71,6 @@ $ pip install pykoplenti
 
 ### Using the command line interface
 
-
 Installing the libray with `CLI` provides a new command.
 
 ```shell
@@ -133,16 +135,28 @@ home_p = device_local['Home_P']
 
 See the full example here: [read_process_data.py](examples/read_process_data.py).
 
+If you should need installer access use the master key (printed on a label at the side of the inverter)
+and additionally pass your service code:
+
+```python
+await client.login(my_master_key, service_code=my_service_code)
+```
 
 ## Documentation
 
-*  [Command Line Interface](doc/command_line.md)
-*  [Examples](examples/)
+- [Command Line Interface](doc/command_line.md)
+- [Examples](examples/)
+- [Virtual Process Data](doc/virtual_process_data.md)
 
 ## Built With
 
-* [AIOHTTPO](https://docs.aiohttp.org/en/stable/) - asyncio for HTTP
-* [click](https://click.palletsprojects.com/) - command line interface framework
+- [AIOHTTPO](https://docs.aiohttp.org/en/stable/) - asyncio for HTTP
+- [click](https://click.palletsprojects.com/) - command line interface framework
+- [black](https://github.com/psf/black) - Python code formatter
+- [ruff](https://github.com/astral-sh/ruff) - Python linter
+- [pytest](https://docs.pytest.org/) - Python test framework
+- [mypy](https://mypy-lang.org/) - Python type checker
+- [setuptools](https://github.com/pypa/setuptools) - Python packager
 
 ## License
 
@@ -150,8 +164,4 @@ apache-2.0
 
 ## Acknowledgments
 
-
-
-* [kilianknoll](https://github.com/kilianknoll) for the kostal-RESTAPI project 
-
-
+- [kilianknoll](https://github.com/kilianknoll) for the kostal-RESTAPI project

pykoplenti-1.2.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+pykoplenti/__init__.py,sha256=w9ooy6_JaT9lGvMDAaBHyvYu1uTFTkb1g21WRxp3Kzw,756
+pykoplenti/api.py,sha256=gYWWd8yZ9winj7qPt1-rzx4stX_DLPfy5nOduuamtH4,26431
+pykoplenti/cli.py,sha256=LAiQHlSgoJz07kTtFh0bNyahyYz7gCenhRfradex5wE,12972
+pykoplenti/extended.py,sha256=_MCDtP-6BaAiTFqJ44CLK_Ihkh6nCC0vWWv1lsQfEFs,9311
+pykoplenti/model.py,sha256=g-KyYTF1M1p6OAebyA74OAP_-561u6Hylhgy_jnpMto,2266
+pykoplenti/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pykoplenti-1.2.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pykoplenti-1.2.1.dist-info/METADATA,sha256=ztvYvxRUUOWJYIbUJ4icUf1X14C_55BJMoA6GiN3ABI,5577
+pykoplenti-1.2.1.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
+pykoplenti-1.2.1.dist-info/entry_points.txt,sha256=Ix-p1uzKNyOMTK0TOlAC0nsfWS6ATXVuaNDJ5-TwBJw,56
+pykoplenti-1.2.1.dist-info/top_level.txt,sha256=Bi915FGIFYzCujwn5Kwhu3B-sxElgc7gX3gNaYjl4j8,11
+pykoplenti-1.2.1.dist-info/RECORD,,

{pykoplenti-1.0.0.dist-info → pykoplenti-1.2.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.36.2)
+Generator: bdist_wheel (0.41.3)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pykoplenti-1.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pykoplenti = pykoplenti.cli:cli [CLI]