Fix date timezone, improve error codes and docstrings

growattServer/__init__.py

@@ -2,7 +2,12 @@
 """growattServer package exports."""
 
 from .base_api import GrowattApi, Timespan, hash_password
-from .exceptions import GrowattError, GrowattParameterError, GrowattV1ApiError
+from .exceptions import (
+    GrowattError,
+    GrowattParameterError,
+    GrowattV1ApiError,
+    GrowattV1ApiErrorCode,
+)
 from .open_api_v1 import DeviceType, OpenApiV1
 
 # Package name
@@ -14,6 +19,7 @@
     "GrowattError",
     "GrowattParameterError",
     "GrowattV1ApiError",
+    "GrowattV1ApiErrorCode",
     "OpenApiV1",
     "Timespan",
     "hash_password",

growattServer/base_api.py

@@ -10,7 +10,7 @@
 
 import requests
 
-from .exceptions import GrowattV1ApiError
+from .exceptions import GrowattError
 
 name = "growattServer"
 
@@ -1169,7 +1169,7 @@ def update_tlx_inverter_time_segment(self, serial_number, segment_id, batt_mode,
 
         if not result.get("success", False):
             msg = f"Failed to update TLX inverter time segment: {result.get('msg', 'Unknown error')}"
-            raise GrowattV1ApiError(msg)
+            raise GrowattError(msg)
 
         return result
 

growattServer/exceptions.py

@@ -1,5 +1,5 @@
 """
-Exception classes for the growattServer library.
+Exception classes and error code constants for the growattServer library.
 
 Note that in addition to these custom exceptions, methods may also raise exceptions
 from the underlying requests library (requests.exceptions.RequestException and its
@@ -13,28 +13,52 @@
 - requests.exceptions.RequestException: The base exception for all requests exceptions
 """
 
+from enum import IntEnum
+
+
+class GrowattV1ApiErrorCode(IntEnum):
+    """
+    Generic error codes returned by the Growatt V1 (OpenAPI) endpoints.
+
+    These codes are common across all endpoints. Individual endpoints may also
+    return additional endpoint-specific error codes — see the docstrings of the
+    respective methods for details.
+
+    Reference: https://www.showdoc.com.cn/262556420217021/1494055648380019
+    """
+
+    SUCCESS = 0  # Normal (General)
+    NO_PRIVILEGE = 10011  # No privilege access (generic)
+    RATE_LIMITED = 10012  # Access Frequency Limitation of 5 Minutes/Time (Universal)
+    PAGE_SIZE_TOO_LARGE = (
+        10013  # The number per page cannot be greater than 100 (general)
+    )
+    PAGE_COUNT_TOO_LARGE = (
+        10014  # The number of pages cannot be greater than 250 pages (general)
+    )
+    WRONG_DOMAIN = -1  # Please use the new domain name to access
+
 
 class GrowattError(Exception):
     """Base exception class for all Growatt API related errors."""
 
 
-
 class GrowattParameterError(GrowattError):
     """Raised when invalid parameters are provided to API methods."""
 
 
-
 class GrowattV1ApiError(GrowattError):
     """Raised when a Growatt V1 API request fails or returns an error."""
 
-    def __init__(self, message: str, error_code: int | None = None, error_msg: str | None = None) -> None:
+    def __init__(self, message: str, error_code: int, error_msg: str) -> None:
         """
         Initialize the GrowattV1ApiError.
 
         Args:
             message: Human readable error message.
-            error_code: Optional numeric error code returned by the API.
-            error_msg: Optional detailed error message from the API.
+            error_code: Numeric error code returned by the API.
+                See :class:`GrowattV1ApiErrorCode` for known generic codes.
+            error_msg: Error message returned by the API.
 
         """
         super().__init__(message)