Remove maxval validator when c1 flag set (#370)

* check maxval for v3 only if c1 is not set
* maint: adding tests, reworking validation a little to be clearer, adding docs

---------

Co-authored-by: yaleman <james@terminaloutcomes.com>

Author: Marcel43367

README.md

@@ -77,7 +77,7 @@ An example configuration
 
 ## Contributing / Testing
 
-`ruff`, and `mypy` should all pass before submitting a PR.
+`ruff`, `pytest` and `mypy` should all pass before submitting a PR.
 
 ## License
 

pvoutput/base.py

@@ -3,7 +3,7 @@
 from datetime import datetime, time
 from math import floor
 import re
-from typing import Any, AnyStr, Dict, Union
+from typing import Any, Dict, Union
 
 from .exceptions import InvalidRegexpError, DonationRequired
 
@@ -57,7 +57,7 @@ def get_time_by_base(self) -> str:
     @classmethod
     def _validate_format(
         cls,
-        format_string: AnyStr,
+        format_string: str,
         key: str,
         value: Any,
     ) -> None:
@@ -138,10 +138,17 @@ def validate_data(self, data: Dict[str, Any], apiset: Dict[str, Any]) -> bool:
             # check for donation-only keys
             if apiset[key].get("donation_required") and not self.donation_made:
                 raise DonationRequired(f"key {key} requires an account which has donated")
-            # check if you're outside max/min values
-            if apiset[key].get("maxval") and data.get(key) > apiset[key].get("maxval"):
-                raise ValueError(f"{key} cannot be higher than {apiset[key]['maxval']}, is {data[key]}")
-            if apiset[key].get("minval") and data.get(key) < apiset[key].get("minval"):
+
+            # check max/min value constraints
+            # Special case: When c1 flag is set, v3 represents cumulative lifetime energy values
+            # which can exceed the normal maximum validation limit of 200000 Wh
+            should_skip_maxval_check = key == "v3" and data.get("c1") is not None
+
+            if not should_skip_maxval_check:
+                if apiset[key].get("maxval") is not None and data.get(key) > apiset[key].get("maxval"):
+                    raise ValueError(f"{key} cannot be higher than {apiset[key]['maxval']}, is {data[key]}")
+
+            if apiset[key].get("minval") is not None and data.get(key) < apiset[key].get("minval"):
                 raise ValueError(f"{key} cannot be lower than {apiset[key]['minval']}, is {data[key]}")
 
         return True

pvoutput/parameters.py

@@ -107,7 +107,7 @@
         "required": False,
         "description": "Energy Consumption (Wh)",
         "donation_required": False,
-        "maxval": 200000,
+        "maxval": 200000,  # Note: maxval validation is bypassed when c1 flag is set for cumulative values
     },
     "v4": {
         "required": False,
@@ -178,11 +178,18 @@
     "required_oneof": {"keys": ["v1", "v2", "v3", "v4"]},
 }
 """
-Cumulative Energy
-The following values are valid for the c1 flag.
+Cumulative Energy Flag (c1)
+
+The c1 flag indicates when energy values represent cumulative lifetime totals rather than 
+daily incremental values. The following values are valid for the c1 flag:
+
     1 Both v1 and v3 values are lifetime energy values. Consumption and generation energy is reset to 0 at the start of the day.
     2 Only v1 generation is a lifetime energy value.
     3 Only v3 consumption is a lifetime energy value.
+
+Important: When c1 is set (any value 1-3), the normal maximum validation limit for v3 
+(200,000 Wh) is bypassed, as cumulative lifetime energy values can exceed this threshold.
+This is handled automatically in the validation logic in base.py.
 """
 
 ADDOUTPUT_PARAMETERS = {

pyproject.toml

@@ -11,10 +11,7 @@ classifiers = [
 ]
 license = { text = "MIT" }
 requires-python = ">=3.10"
-dependencies = [
-    "requests>=2.27.1",
- "aiohttp>=3.8.1",
-]
+dependencies = ["requests>=2.27.1", "aiohttp>=3.8.1"]
 version = "0.1.0"
 description = "Interface to the PVOutput API"
 readme = "README.md"
@@ -23,7 +20,6 @@ readme = "README.md"
 homepage = "https://yaleman.github.io/pvoutput/"
 repository = "https://github.com/yaleman/pvoutput/"
 
-
 [build-system]
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"

tests/test_parameters.py

@@ -1,17 +1,12 @@
 """tests parameters things"""
 
-# import pytest
-# import pvoutput
-
-
-# def test_parameters_copying():
-#     """checks if the copied values are different"""
-#     assert pvoutput.ADDSTATUS_PARAMETERS["t"] != pvoutput.DELETESTATUS_PARAMETERS["t"]
-
+import copy
 from datetime import datetime
-
-from pvoutput.parameters import ADDSTATUS_PARAMETERS
+from typing import Any, Dict
+import pytest
 from pvoutput import PVOutput
+from pvoutput.base import PVOutputBase
+from pvoutput.parameters import ADDSTATUS_PARAMETERS
 
 
 def test_addstatus_default_date() -> None:
@@ -32,3 +27,91 @@ def testit(test: PVOutput) -> None:
         assert test_data["d"] == "20370111"
 
     testit(test)
+
+def test_parameters_copying() -> None:
+    """checks if the copied values are different"""
+    # This test is commented out but kept for reference
+    # assert pvoutput.ADDSTATUS_PARAMETERS["t"] != pvoutput.DELETESTATUS_PARAMETERS["t"]
+    pass
+
+
+class TestC1V3Validation:
+    """Test cases for c1 flag and v3 validation logic"""
+
+    def setup_method(self) -> None:
+        """Setup test fixtures"""
+        self.pvo_base = PVOutputBase(apikey="test", systemid=123)
+
+    def test_v3_exceeds_maxval_without_c1_flag_should_fail(self) -> None:
+        """Test that v3 values > 200000 fail validation when c1 is not set"""
+        data = {"v3": 250000}  # Exceeds maxval of 200000
+
+        with pytest.raises(ValueError, match="v3 cannot be higher than 200000"):
+            self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+
+    def test_v3_exceeds_maxval_with_c1_flag_should_pass(self) -> None:
+        """Test that v3 values > 200000 pass validation when c1 is set"""
+        data = {"v3": 250000, "c1": 1}  # c1 flag set, should bypass maxval check
+
+        # Should not raise an exception
+        result = self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+        assert result is True
+
+    def test_v3_exceeds_maxval_with_c1_flag_value_2_should_pass(self) -> None:
+        """Test that v3 values > 200000 pass validation when c1=2"""
+        data = {"v3": 300000, "c1": 2}  # c1=2, should bypass maxval check
+
+        result = self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+        assert result is True
+
+    def test_v3_exceeds_maxval_with_c1_flag_value_3_should_pass(self) -> None:
+        """Test that v3 values > 200000 pass validation when c1=3"""
+        data = {"v3": 500000, "c1": 3}  # c1=3, should bypass maxval check
+
+        result = self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+        assert result is True
+
+    def test_v3_within_maxval_without_c1_flag_should_pass(self) -> None:
+        """Test that v3 values <= 200000 pass validation without c1 flag"""
+        data = {"v3": 150000}  # Within maxval limit
+
+        result = self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+        assert result is True
+
+    def test_v3_within_maxval_with_c1_flag_should_pass(self) -> None:
+        """Test that v3 values <= 200000 pass validation with c1 flag"""
+        data = {"v3": 150000, "c1": 1}  # Within limit, c1 set
+
+        result = self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)
+        assert result is True
+
+    def test_other_fields_maxval_validation_unaffected_by_c1(self) -> None:
+        """Test that c1 flag doesn't affect maxval validation of other fields"""
+        # Create a modified parameter set with maxval for testing
+        test_params: Dict[str, Any] = copy.deepcopy(ADDSTATUS_PARAMETERS)
+        test_params["v2"] = {"maxval": 1000, "type": int}
+
+        data = {"v2": 1500, "c1": 1}  # v2 exceeds maxval, c1 set
+
+        with pytest.raises(ValueError, match="v2 cannot be higher than 1000"):
+            self.pvo_base.validate_data(data, test_params)
+
+    def test_v3_minval_validation_still_applies_with_c1(self) -> None:
+        """Test that minval validation for v3 still applies even when c1 is set"""
+        # Create a deep copy of parameters and modify v3 to have minval
+        test_params: Dict[str, Any] = copy.deepcopy(ADDSTATUS_PARAMETERS)
+        test_params["v3"]["minval"] = 0
+
+        data = {"v3": -100, "c1": 1}  # Negative value, c1 set
+
+        with pytest.raises(ValueError, match="v3 cannot be lower than 0"):
+            self.pvo_base.validate_data(data, test_params)
+
+    def test_c1_flag_zero_does_not_bypass_v3_maxval(self) -> None:
+        """Test that c1=0 (if somehow passed) doesn't bypass v3 maxval validation"""
+        data = {"v3": 250000, "c1": 0}  # c1=0 is not a valid flag value
+
+        # This should fail because c1=0 is not considered "set" for our logic
+        # Note: This would also fail format validation, but testing the maxval logic specifically
+        with pytest.raises(ValueError):
+            self.pvo_base.validate_data(data, ADDSTATUS_PARAMETERS)