Coverage for src / ezqt_widgets / types.py: 87.10%

1# /////////////////////////////////////////////////////////////// 

2# TYPES - Type Aliases Module 

3# Project: ezqt_widgets 

4# /////////////////////////////////////////////////////////////// 

5 

6""" 

7Type aliases module for ezqt_widgets. 

8 

9This module centralizes common type aliases used throughout the library 

10to improve code readability, maintainability, and type safety. 

11 

12Example: 

13 >>> from ezqt_widgets.types import IconSource, SizeType 

14 >>> from PySide6.QtGui import QIcon 

15 >>> 

16 >>> def create_icon(source: IconSource) -> QIcon: 

17 ... # Use the type alias 

18 ... pass 

19""" 

20 

21from __future__ import annotations 

22 

23# /////////////////////////////////////////////////////////////// 

24# IMPORTS 

25# /////////////////////////////////////////////////////////////// 

26# Standard library imports 

27from collections.abc import Callable 

28from typing import TYPE_CHECKING, Any, TypeAlias 

29 

30# Third-party imports 

31from PySide6.QtCore import QSize 

32from PySide6.QtGui import QColor, QIcon, QPixmap 

33from PySide6.QtWidgets import QWidget 

34 

35# Type-checking-only imports (avoids circular import at runtime) 

36if TYPE_CHECKING: 36 ↛ 37line 36 didn't jump to line 37 because the condition on line 36 was never true

37 from .widgets.misc.theme_icon import ThemeIcon 

38 

39# /////////////////////////////////////////////////////////////// 

40# TYPE ALIASES 

41# /////////////////////////////////////////////////////////////// 

42 

43# ------------------------------------------------ 

44# Icon Types 

45# ------------------------------------------------ 

46 

47IconSource: TypeAlias = QIcon | str | None 

48"""Type alias for icon sources. 

49 

50Accepts: 

51 - QIcon: A Qt icon object (ThemeIcon recommended) 

52 - str: Path to an icon file (local path, resource path, or URL) 

53 - None: No icon 

54 

55Note: 

56 ThemeIcon is a QIcon subclass and is supported wherever QIcon is accepted. 

57 

58Used by: IconButton, DateButton, LoaderButton, etc. 

59""" 

60 

61if TYPE_CHECKING: 61 ↛ 62line 61 didn't jump to line 62 because the condition on line 61 was never true

62 IconSourceExtended: TypeAlias = QIcon | QPixmap | str | bytes | ThemeIcon | None 

63else: 

64 IconSourceExtended: TypeAlias = QIcon | QPixmap | str | bytes | None 

65"""Type alias for extended icon sources (includes QPixmap, ThemeIcon, and bytes). 

66 

67Accepts: 

68 - QIcon: A Qt icon object (ThemeIcon recommended) 

69 - QPixmap: A Qt pixmap object 

70 - str: Path to an icon file (local path, resource path, or URL) 

71 - bytes: Raw SVG or image data (e.g. embedded SVG constants from shared) 

72 - ThemeIcon: A theme-aware icon (subclass of QIcon) 

73 - None: No icon 

74 

75Used by: ToggleIcon, HoverLabel, ThemeIcon, IconButton, LoaderButton, 

76 SearchInput, PasswordInput, and other widgets that support QPixmap. 

77""" 

78 

79# ------------------------------------------------ 

80# Size Types 

81# ------------------------------------------------ 

82 

83SizeType: TypeAlias = QSize | tuple[int, int] 

84"""Type alias for size specifications. 

85 

86Accepts: 

87 - QSize: A Qt size object 

88 - tuple[int, int]: (width, height) tuple 

89 

90Used by: IconButton, widget sizing, etc. 

91""" 

92 

93# ------------------------------------------------ 

94# Color Types 

95# ------------------------------------------------ 

96 

97ColorType: TypeAlias = QColor | str 

98"""Type alias for color specifications. 

99 

100Accepts: 

101 - QColor: A Qt color object 

102 - str: Color string (hex "#RRGGBB", named color "red", etc.) 

103 

104Used by: Widgets with custom painting (ToggleSwitch, CircularTimer, etc.) 

105""" 

106 

107# ------------------------------------------------ 

108# Widget Types 

109# ------------------------------------------------ 

110 

111WidgetParent: TypeAlias = QWidget | None 

112"""Type alias for widget parent parameter. 

113 

114Accepts: 

115 - QWidget: A parent widget 

116 - None: No parent (top-level widget) 

117 

118Used by: All widget constructors. 

119""" 

120 

121# ------------------------------------------------ 

122# Animation Types 

123# ------------------------------------------------ 

124 

125AnimationDuration: TypeAlias = int 

126"""Type alias for animation duration in milliseconds. 

127 

128Used by: Widgets with animations (ToggleSwitch, LoaderButton, etc.) 

129""" 

130 

131# ------------------------------------------------ 

132# Callback Types 

133# ------------------------------------------------ 

134 

135EventCallback: TypeAlias = Callable[[], None] 

136"""Type alias for event callbacks without parameters. 

137 

138Used by: Click handlers, event callbacks, etc. 

139""" 

140 

141ValueCallback: TypeAlias = Callable[[Any], None] 

142"""Type alias for value change callbacks. 

143 

144Used by: Signal handlers, value change callbacks, etc. 

145""" 

146 

147# /////////////////////////////////////////////////////////////// 

148# PUBLIC API 

149# /////////////////////////////////////////////////////////////// 

150 

151__all__ = [ 

152 "AnimationDuration", 

153 "ColorType", 

154 "EventCallback", 

155 "IconSource", 

156 "IconSourceExtended", 

157 "SizeType", 

158 "ValueCallback", 

159 "WidgetParent", 

160]