Merge pull request #1 from Class-Widgets/refactor/notification_api

chore: type hints

Author: IsHPDuwu

ClassWidgets/SDK/__init__.py

@@ -4,7 +4,7 @@
 import sys
 from typing import TYPE_CHECKING
 
-__version__ = '0.3.2'
+__version__ = '0.4.0'
 __author__ = 'Class Widgets Official'
 
 if TYPE_CHECKING:

ClassWidgets/SDK/__init__.pyi

@@ -20,6 +20,7 @@ __all__ = [
     'NotificationProvider',
     'NotificationLevel',
     'NotificationData',
+    'NotificationProviderConfig',
     "__version__",
     "__author__",
 ]

ClassWidgets/SDK/api.pyi

@@ -1,15 +1,69 @@
-from typing import Dict, List, Optional, Any, Union
+from typing import Dict, List, Optional, Any, Union, TypedDict
 from datetime import datetime
 from pathlib import Path
+from enum import Enum
 
+from .notification import NotificationPayload, NotificationProvider
+from .base_model import QObject, Signal
 
-class QObject: ...
 
+class ConfigBaseModel: ...
 
-class Signal: ...
 
+class RuntimeMetaPayload(TypedDict):
+    id: str
+    version: int
+    maxWeekCycle: int
+    startDate: str
 
-class ConfigBaseModel: ...
+
+class RuntimeEntryPayload(TypedDict):
+    id: str
+    type: str
+    startTime: str
+    endTime: str
+    subjectId: Optional[str]
+    title: Optional[str]
+
+
+class RuntimeEntryChangedPayload(TypedDict, total=False):
+    id: str
+    type: str
+    startTime: str
+    endTime: str
+    subjectId: Optional[str]
+    title: Optional[str]
+
+
+class RuntimeSubjectPayload(TypedDict):
+    id: str
+    name: str
+    simplifiedName: Optional[str]
+    teacher: Optional[str]
+    icon: Optional[str]
+    color: Optional[str]
+    location: Optional[str]
+    isLocalClassroom: bool
+
+
+class RuntimeRemainingTimePayload(TypedDict):
+    minute: int
+    second: int
+
+
+class SettingsPagePayload(TypedDict):
+    id: str
+    page: str
+    title: str
+    icon: str
+
+
+class EntryType(str, Enum):
+    CLASS = "class"
+    BREAK = "break"
+    FREE = "free"
+    ACTIVITY = "activity"
+    UNKNOWN = "unknown"
 
 
 # WidgetsAPI
@@ -29,7 +83,7 @@ class WidgetsAPI:
 
 # NotificationAPI
 class NotificationAPI(QObject):
-    pushed: Signal  # Signal(str)
+    pushed: Signal[NotificationPayload]
 
     def __init__(self, app: Any) -> None: ...
 
@@ -39,15 +93,15 @@ class NotificationAPI(QObject):
         name: Optional[str] = ...,
         icon: Optional[Union[str, Path]] = ...,
         use_system_notify: bool = ...
-    ) -> Any: ...
+    ) -> NotificationProvider: ...
 
     def register_provider(
         self,
         provider_id: str,
         name: Optional[str] = ...,
         icon: Optional[Union[str, Path]] = ...,
         use_system_notify: bool = ...
-    ) -> Any: ...
+    ) -> NotificationProvider: ...
 
 
 # ScheduleAPI
@@ -61,7 +115,7 @@ class ScheduleAPI:
 
 # ThemeAPI
 class ThemeAPI(QObject):
-    changed: Signal  # Signal(str)
+    changed: Signal[str]
 
     def __init__(self, app: Any) -> None: ...
 
@@ -70,9 +124,9 @@ class ThemeAPI(QObject):
 
 # RuntimeAPI
 class RuntimeAPI(QObject):
-    updated: Signal  # Signal()
-    statusChanged: Signal  # Signal(str)
-    entryChanged: Signal  # Signal(dict)
+    updated: Signal
+    statusChanged: Signal[str]
+    entryChanged: Signal[RuntimeEntryChangedPayload]
 
     def __init__(self, app: Any) -> None: ...
 
@@ -94,19 +148,19 @@ class RuntimeAPI(QObject):
 
     # 日程属性
     @property
-    def schedule_meta(self) -> Optional[Dict[str, Any]]: ...
+    def schedule_meta(self) -> Optional[RuntimeMetaPayload]: ...
 
     @property
-    def current_day_entries(self) -> List[Dict[str, Any]]: ...
+    def current_day_entries(self) -> List[RuntimeEntryPayload]: ...
 
     @property
-    def current_entry(self) -> Optional[Dict[str, Any]]: ...
+    def current_entry(self) -> Optional[RuntimeEntryPayload]: ...
 
     @property
-    def next_entries(self) -> List[Dict[str, Any]]: ...
+    def next_entries(self) -> List[RuntimeEntryPayload]: ...
 
     @property
-    def remaining_time(self) -> Dict[str, int]: ...
+    def remaining_time(self) -> RuntimeRemainingTimePayload: ...
 
     @property
     def progress(self) -> float: ...
@@ -115,7 +169,7 @@ class RuntimeAPI(QObject):
     def current_status(self) -> str: ...
 
     @property
-    def current_subject(self) -> Optional[Dict[str, Any]]: ...
+    def current_subject(self) -> Optional[RuntimeSubjectPayload]: ...
 
     @property
     def current_title(self) -> Optional[str]: ...
@@ -129,7 +183,7 @@ class ConfigAPI:
 
     def get_plugin_model(self, plugin_id: str) -> Optional[ConfigBaseModel]: ...
 
-    def save(self) -> None: ...
+    def save(self) -> Any: ...
 
 
 # AutomationAPI
@@ -141,12 +195,12 @@ class AutomationAPI:
 
 # UiAPI
 class UiAPI(QObject):
-    settingsPageRegistered: Signal  # Signal()
+    settingsPageRegistered: Signal
 
-    def __init__(self) -> None: ...
+    def __init__(self, app: Any) -> None: ...
 
     @property
-    def pages(self) -> List[Dict[str, Any]]: ...
+    def pages(self) -> List[SettingsPagePayload]: ...
 
     def unregister_settings_page(self, qml_path: Union[str, Path]) -> None: ...
 
@@ -162,6 +216,11 @@ class UiAPI(QObject):
 class PluginAPI:
     def __init__(self, app: Any) -> None: ...
 
+    def set_current_plugin(self, plugin: Any) -> None: ...
+
+    @property
+    def current_plugin(self) -> Any: ...
+
     widgets: WidgetsAPI
     notification: NotificationAPI
     schedule: ScheduleAPI
@@ -173,6 +232,13 @@ class PluginAPI:
 
 
 __all__ = [
+    'RuntimeMetaPayload',
+    'RuntimeEntryPayload',
+    'RuntimeEntryChangedPayload',
+    'RuntimeSubjectPayload',
+    'RuntimeRemainingTimePayload',
+    'SettingsPagePayload',
+    'EntryType',
     'WidgetsAPI',
     'NotificationAPI',
     'ScheduleAPI',

ClassWidgets/SDK/base_model.pyi

@@ -0,0 +1,11 @@
+from typing import Any, Generic, TypeVar, Callable
+
+class QObject: ...
+
+T = TypeVar("T")
+
+# 模拟信号类，支持索引语法
+class Signal(Generic[T]):
+    def connect(self, slot: Callable[..., Any]) -> None: ...
+    def emit(self, *args: Any) -> None: ...
+    def disconnect(self, slot: Callable[..., Any]) -> None: ...

ClassWidgets/SDK/config.pyi

@@ -1,6 +1,8 @@
 from typing import Dict, List, Optional, Any, Union
 from enum import Enum
 
+from .base_model import Signal
+
 
 # Enums
 class LayoutAnchor(str, Enum):
@@ -126,7 +128,7 @@ class RootConfig(ConfigBaseModel):
 
 # ============ Config Manager ============
 class ConfigManager:
-    configChanged: Any = ...  # Signal 类型
+    configChanged: Signal[str] = ...  
 
     def __init__(self, path: Any, filename: str) -> None: ...
 

ClassWidgets/SDK/notification.pyi

@@ -1,4 +1,4 @@
-from typing import Optional, Union, Any, TYPE_CHECKING
+from typing import Optional, Union, Any, TypedDict, TYPE_CHECKING
 from pathlib import Path
 from enum import IntEnum
 from pydantic import BaseModel
@@ -30,6 +30,18 @@ class NotificationData(BaseModel):
     silent: bool = False
     use_system: bool = False
 
+# 与 NotificationData 对应的字典结构
+class NotificationPayload(TypedDict):
+    provider_id: str
+    level: int
+    title: str
+    message: Optional[str]
+    icon: Optional[Union[str, Path]]
+    duration: int
+    closable: bool
+    silent: bool
+    use_system: bool
+
 
 class NotificationProviderConfig(BaseModel):
     """
@@ -80,5 +92,6 @@ __all__ = [
     'NotificationLevel',
     'NotificationData',
     'NotificationProviderConfig',
-    'NotificationProvider'
+    'NotificationProvider',
+    'NotificationPayload'
 ]

ClassWidgets/SDK/plugin_base.pyi

@@ -3,15 +3,9 @@ from pathlib import Path
 from enum import IntEnum
 from pydantic import BaseModel
 
-# 为非检查时提供的抽象基类
-class QObject: ...
-
-class Signal:
-    def emit(self, *args) -> None:
-        pass
-
 from .api import PluginAPI
 
+from .base_model import QObject, Signal
 
 class ConfigBaseModel(BaseModel):
     """