pycforge 0.15.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. pycforge/__init__.py +8 -0
  2. pycforge/__main__.py +2 -0
  3. pycforge/_version.py +1 -0
  4. pycforge/converter/__init__.py +0 -0
  5. pycforge/converter/analysis/__init__.py +5 -0
  6. pycforge/converter/analysis/functions.py +723 -0
  7. pycforge/converter/analysis/model.py +158 -0
  8. pycforge/converter/analysis/planning.py +464 -0
  9. pycforge/converter/analysis/stage.py +1976 -0
  10. pycforge/converter/analysis/symbols.py +237 -0
  11. pycforge/converter/analysis/validation.py +2166 -0
  12. pycforge/converter/c_output/__init__.py +2 -0
  13. pycforge/converter/c_output/conformance.py +297 -0
  14. pycforge/converter/c_output/renderer.py +220 -0
  15. pycforge/converter/conditional_regions/__init__.py +71 -0
  16. pycforge/converter/conditional_regions/analysis.py +481 -0
  17. pycforge/converter/conditional_regions/lowering.py +579 -0
  18. pycforge/converter/conditional_regions/model.py +243 -0
  19. pycforge/converter/conditional_regions/validation.py +690 -0
  20. pycforge/converter/containers/__init__.py +19 -0
  21. pycforge/converter/containers/analysis.py +542 -0
  22. pycforge/converter/containers/lowering.py +290 -0
  23. pycforge/converter/containers/model.py +146 -0
  24. pycforge/converter/contracts/__init__.py +0 -0
  25. pycforge/converter/contracts/configuration.py +178 -0
  26. pycforge/converter/contracts/identifiers.py +68 -0
  27. pycforge/converter/contracts/versions.py +71 -0
  28. pycforge/converter/core/__init__.py +0 -0
  29. pycforge/converter/core/artifact_io.py +87 -0
  30. pycforge/converter/core/cancellation.py +7 -0
  31. pycforge/converter/core/canonicalization.py +254 -0
  32. pycforge/converter/core/context.py +13 -0
  33. pycforge/converter/core/diagnostics.py +95 -0
  34. pycforge/converter/core/enums.py +23 -0
  35. pycforge/converter/core/fingerprint.py +22 -0
  36. pycforge/converter/core/pipeline.py +8 -0
  37. pycforge/converter/core/progress.py +25 -0
  38. pycforge/converter/core/request.py +50 -0
  39. pycforge/converter/core/resource_policy.py +31 -0
  40. pycforge/converter/core/result.py +23 -0
  41. pycforge/converter/core/serialization.py +36 -0
  42. pycforge/converter/core/stage.py +10 -0
  43. pycforge/converter/core/stage_artifact.py +80 -0
  44. pycforge/converter/core/stage_outcome.py +15 -0
  45. pycforge/converter/decision_trace/__init__.py +0 -0
  46. pycforge/converter/decision_trace/recorder.py +52 -0
  47. pycforge/converter/facade.py +459 -0
  48. pycforge/converter/frontend/__init__.py +4 -0
  49. pycforge/converter/frontend/normalizer.py +59 -0
  50. pycforge/converter/frontend/parser.py +20 -0
  51. pycforge/converter/frontend/source_document.py +93 -0
  52. pycforge/converter/frontend/stages.py +518 -0
  53. pycforge/converter/frontend/validation.py +76 -0
  54. pycforge/converter/io/__init__.py +0 -0
  55. pycforge/converter/io/atomic_writer.py +33 -0
  56. pycforge/converter/ir/__init__.py +1 -0
  57. pycforge/converter/ir/c_ir/__init__.py +4 -0
  58. pycforge/converter/ir/c_ir/builder.py +26 -0
  59. pycforge/converter/ir/c_ir/model.py +318 -0
  60. pycforge/converter/ir/c_ir/serialization.py +88 -0
  61. pycforge/converter/ir/c_ir/validation.py +834 -0
  62. pycforge/converter/ir/python_ir/__init__.py +17 -0
  63. pycforge/converter/ir/python_ir/nodes.py +86 -0
  64. pycforge/converter/keyword_calls/__init__.py +68 -0
  65. pycforge/converter/keyword_calls/analysis.py +458 -0
  66. pycforge/converter/keyword_calls/lowering.py +271 -0
  67. pycforge/converter/keyword_calls/model.py +304 -0
  68. pycforge/converter/keyword_calls/validation.py +802 -0
  69. pycforge/converter/keyword_only_calls/__init__.py +68 -0
  70. pycforge/converter/keyword_only_calls/analysis.py +640 -0
  71. pycforge/converter/keyword_only_calls/lowering.py +376 -0
  72. pycforge/converter/keyword_only_calls/model.py +328 -0
  73. pycforge/converter/keyword_only_calls/validation.py +1357 -0
  74. pycforge/converter/lowering.py +1000 -0
  75. pycforge/converter/modules/__init__.py +13 -0
  76. pycforge/converter/modules/analysis.py +1250 -0
  77. pycforge/converter/modules/lowering.py +200 -0
  78. pycforge/converter/modules/model.py +73 -0
  79. pycforge/converter/modules/stage.py +192 -0
  80. pycforge/converter/numeric_semantics/__init__.py +23 -0
  81. pycforge/converter/numeric_semantics/analysis.py +420 -0
  82. pycforge/converter/numeric_semantics/lowering.py +153 -0
  83. pycforge/converter/numeric_semantics/model.py +123 -0
  84. pycforge/converter/records/__init__.py +34 -0
  85. pycforge/converter/records/analysis.py +1394 -0
  86. pycforge/converter/records/lowering.py +393 -0
  87. pycforge/converter/records/model.py +319 -0
  88. pycforge/converter/rules/__init__.py +3 -0
  89. pycforge/converter/support_templates/__init__.py +49 -0
  90. pycforge/converter/support_templates/assembly.py +106 -0
  91. pycforge/converter/support_templates/factories.py +348 -0
  92. pycforge/converter/support_templates/model.py +159 -0
  93. pycforge/converter/support_templates/registry.py +388 -0
  94. pycforge/converter/telemetry/__init__.py +0 -0
  95. pycforge/converter/telemetry/sink.py +39 -0
  96. pycforge/ide/__init__.py +19 -0
  97. pycforge/ide/__main__.py +5 -0
  98. pycforge/ide/_worker_event_codec.py +276 -0
  99. pycforge/ide/_worker_protocol_json.py +197 -0
  100. pycforge/ide/_worker_protocol_types.py +90 -0
  101. pycforge/ide/_worker_request_codec.py +200 -0
  102. pycforge/ide/_worker_request_data.py +260 -0
  103. pycforge/ide/_worker_result_data.py +343 -0
  104. pycforge/ide/action_contract.py +469 -0
  105. pycforge/ide/action_validation.py +229 -0
  106. pycforge/ide/command_palette.py +223 -0
  107. pycforge/ide/controller.py +904 -0
  108. pycforge/ide/controller_conversion.py +546 -0
  109. pycforge/ide/controller_io.py +205 -0
  110. pycforge/ide/editor.py +951 -0
  111. pycforge/ide/editor_commands_qt.py +274 -0
  112. pycforge/ide/editor_lexical.py +43 -0
  113. pycforge/ide/editor_sidebars.py +236 -0
  114. pycforge/ide/editor_syntax.py +243 -0
  115. pycforge/ide/find_replace.py +535 -0
  116. pycforge/ide/icons.py +91 -0
  117. pycforge/ide/io_service.py +196 -0
  118. pycforge/ide/model.py +164 -0
  119. pycforge/ide/panels.py +903 -0
  120. pycforge/ide/positions.py +220 -0
  121. pycforge/ide/process_worker.py +130 -0
  122. pycforge/ide/qt.py +230 -0
  123. pycforge/ide/qt_actions.py +418 -0
  124. pycforge/ide/qt_close.py +169 -0
  125. pycforge/ide/qt_command_palette.py +297 -0
  126. pycforge/ide/qt_contract.py +220 -0
  127. pycforge/ide/qt_documents.py +590 -0
  128. pycforge/ide/qt_editor_buffers.py +113 -0
  129. pycforge/ide/qt_editor_surfaces.py +112 -0
  130. pycforge/ide/qt_menus.py +324 -0
  131. pycforge/ide/qt_projection.py +500 -0
  132. pycforge/ide/qt_shell.py +348 -0
  133. pycforge/ide/qt_shell_interactions.py +320 -0
  134. pycforge/ide/qt_state.py +393 -0
  135. pycforge/ide/qt_workspace_features.py +398 -0
  136. pycforge/ide/qt_workspace_navigation.py +208 -0
  137. pycforge/ide/qt_workspace_observers.py +173 -0
  138. pycforge/ide/qt_workspace_panels.py +545 -0
  139. pycforge/ide/qt_workspace_widgets.py +228 -0
  140. pycforge/ide/resources/icons/about.svg +1 -0
  141. pycforge/ide/resources/icons/add-document.svg +1 -0
  142. pycforge/ide/resources/icons/brand-mark.svg +1 -0
  143. pycforge/ide/resources/icons/bundle-search.svg +1 -0
  144. pycforge/ide/resources/icons/cancel.svg +1 -0
  145. pycforge/ide/resources/icons/check.svg +1 -0
  146. pycforge/ide/resources/icons/chevron-right.svg +1 -0
  147. pycforge/ide/resources/icons/close.svg +1 -0
  148. pycforge/ide/resources/icons/collapse-all.svg +1 -0
  149. pycforge/ide/resources/icons/command-palette.svg +1 -0
  150. pycforge/ide/resources/icons/convert.svg +1 -0
  151. pycforge/ide/resources/icons/copy.svg +1 -0
  152. pycforge/ide/resources/icons/cut.svg +1 -0
  153. pycforge/ide/resources/icons/decision-trace.svg +1 -0
  154. pycforge/ide/resources/icons/details.svg +1 -0
  155. pycforge/ide/resources/icons/diagnostics.svg +1 -0
  156. pycforge/ide/resources/icons/duplicate-line.svg +1 -0
  157. pycforge/ide/resources/icons/exit.svg +1 -0
  158. pycforge/ide/resources/icons/expand-all.svg +1 -0
  159. pycforge/ide/resources/icons/export.svg +1 -0
  160. pycforge/ide/resources/icons/find.svg +1 -0
  161. pycforge/ide/resources/icons/go-to-line.svg +1 -0
  162. pycforge/ide/resources/icons/go-to-output.svg +1 -0
  163. pycforge/ide/resources/icons/go-to-source.svg +1 -0
  164. pycforge/ide/resources/icons/history.svg +1 -0
  165. pycforge/ide/resources/icons/indent.svg +1 -0
  166. pycforge/ide/resources/icons/link-c.svg +1 -0
  167. pycforge/ide/resources/icons/mappings.svg +1 -0
  168. pycforge/ide/resources/icons/module.svg +1 -0
  169. pycforge/ide/resources/icons/move-down.svg +1 -0
  170. pycforge/ide/resources/icons/move-line-down.svg +1 -0
  171. pycforge/ide/resources/icons/move-line-up.svg +1 -0
  172. pycforge/ide/resources/icons/move-up.svg +1 -0
  173. pycforge/ide/resources/icons/next.svg +1 -0
  174. pycforge/ide/resources/icons/open.svg +1 -0
  175. pycforge/ide/resources/icons/outdent.svg +1 -0
  176. pycforge/ide/resources/icons/outline.svg +1 -0
  177. pycforge/ide/resources/icons/paste.svg +1 -0
  178. pycforge/ide/resources/icons/previous.svg +1 -0
  179. pycforge/ide/resources/icons/primary-module.svg +1 -0
  180. pycforge/ide/resources/icons/redo.svg +1 -0
  181. pycforge/ide/resources/icons/remove-document.svg +1 -0
  182. pycforge/ide/resources/icons/replace.svg +1 -0
  183. pycforge/ide/resources/icons/save-as.svg +1 -0
  184. pycforge/ide/resources/icons/save.svg +1 -0
  185. pycforge/ide/resources/icons/select-all.svg +1 -0
  186. pycforge/ide/resources/icons/settings.svg +1 -0
  187. pycforge/ide/resources/icons/show-c.svg +1 -0
  188. pycforge/ide/resources/icons/split-view.svg +1 -0
  189. pycforge/ide/resources/icons/summary.svg +1 -0
  190. pycforge/ide/resources/icons/telemetry.svg +1 -0
  191. pycforge/ide/resources/icons/toggle-comment.svg +1 -0
  192. pycforge/ide/resources/icons/toggle-fold.svg +1 -0
  193. pycforge/ide/resources/icons/undo.svg +1 -0
  194. pycforge/ide/resources/icons/whitespace.svg +1 -0
  195. pycforge/ide/revisions.py +400 -0
  196. pycforge/ide/search_service.py +280 -0
  197. pycforge/ide/session_history.py +150 -0
  198. pycforge/ide/source_editing.py +417 -0
  199. pycforge/ide/source_structure.py +558 -0
  200. pycforge/ide/source_structure_async.py +191 -0
  201. pycforge/ide/supervisor.py +503 -0
  202. pycforge/ide/theme.py +119 -0
  203. pycforge/ide/theme_stylesheet.py +598 -0
  204. pycforge/ide/theme_workspace_stylesheet.py +155 -0
  205. pycforge/ide/visual_tokens.py +142 -0
  206. pycforge/ide/worker_protocol.py +80 -0
  207. pycforge/ide/workspace_search.py +462 -0
  208. pycforge/ide/workspace_session.py +256 -0
  209. pycforge/laboratory/__init__.py +6 -0
  210. pycforge/laboratory/audits.py +2244 -0
  211. pycforge/laboratory/checkpoint_e.py +2685 -0
  212. pycforge/laboratory/cli.py +119 -0
  213. pycforge/laboratory/exit_codes.py +11 -0
  214. pycforge/laboratory/keyword_audit.py +661 -0
  215. pycforge/laboratory/keyword_only_audit.py +481 -0
  216. pycforge-0.15.2.dist-info/METADATA +209 -0
  217. pycforge-0.15.2.dist-info/RECORD +221 -0
  218. pycforge-0.15.2.dist-info/WHEEL +5 -0
  219. pycforge-0.15.2.dist-info/entry_points.txt +5 -0
  220. pycforge-0.15.2.dist-info/licenses/LICENSE +674 -0
  221. pycforge-0.15.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,112 @@
1
+ """Construction helpers for split source and tabbed generated-C surfaces."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from PyQt5.QtCore import Qt
6
+ from PyQt5.QtWidgets import (
7
+ QFrame,
8
+ QHBoxLayout,
9
+ QLabel,
10
+ QSizePolicy,
11
+ QSplitter,
12
+ QTabWidget,
13
+ QVBoxLayout,
14
+ )
15
+
16
+ from .editor import CodeEditor
17
+
18
+
19
+ def build_source_editor_surface(owner) -> QFrame:
20
+ """Build the primary and optional synchronized Python source views."""
21
+
22
+ panel = QFrame()
23
+ panel.setObjectName("SourceEditorSurface")
24
+ panel.setProperty("role", "source-surface")
25
+ layout = QVBoxLayout(panel)
26
+ layout.setContentsMargins(0, 0, 0, 0)
27
+ layout.setSpacing(0)
28
+ owner.source_splitter = QSplitter(Qt.Horizontal)
29
+ owner.source_splitter.setObjectName("PythonSourceViewSplitter")
30
+ owner.source_splitter.setChildrenCollapsible(False)
31
+ owner.source = CodeEditor(language="python")
32
+ owner.source.setObjectName("PythonSourceEditor")
33
+ owner.source.setPlaceholderText(
34
+ "Enter supported Python source, or open a source "
35
+ "bundle document…"
36
+ )
37
+ owner.source.setAccessibleName("Primary Python source editor")
38
+ owner.source_secondary = CodeEditor(
39
+ language="python",
40
+ highlighting=False,
41
+ )
42
+ owner.source_secondary.setObjectName("PythonSourceEditorSecondary")
43
+ owner.source_secondary.setAccessibleName(
44
+ "Secondary synchronized Python source editor"
45
+ )
46
+ owner.source_secondary.setAccessibleDescription(
47
+ "A second view of the same active Python source document."
48
+ )
49
+ owner.source_secondary.setVisible(False)
50
+ owner.source_splitter.addWidget(owner.source)
51
+ owner.source_splitter.addWidget(owner.source_secondary)
52
+ owner.source_splitter.setStretchFactor(0, 1)
53
+ owner.source_splitter.setStretchFactor(1, 1)
54
+ layout.addWidget(owner.source_splitter)
55
+ return panel
56
+
57
+
58
+ def build_generated_c_surface(owner) -> QFrame:
59
+ """Build one explicit read-only generated-C editor tab."""
60
+
61
+ panel = QFrame()
62
+ panel.setObjectName("GeneratedCPanel")
63
+ layout = QVBoxLayout(panel)
64
+ layout.setContentsMargins(0, 0, 0, 0)
65
+ layout.setSpacing(4)
66
+ header = QHBoxLayout()
67
+ title = QLabel("GENERATED C · READ ONLY")
68
+ title.setProperty("role", "panel-title")
69
+ owner.output_state_label = QLabel("NO RESULT")
70
+ owner.output_state_label.setProperty("role", "status-chip")
71
+ owner.output_state_label.setProperty("status", "neutral")
72
+ owner.linked_c_label = QLabel("C link: not set")
73
+ owner.linked_c_label.setObjectName("PathLabel")
74
+ owner.linked_c_label.setToolTip("Linked destination used by Save C")
75
+ owner.linked_c_label.setMinimumWidth(0)
76
+ owner.linked_c_label.setSizePolicy(
77
+ QSizePolicy.Ignored,
78
+ QSizePolicy.Preferred,
79
+ )
80
+ header.addWidget(title)
81
+ header.addStretch(1)
82
+ layout.addLayout(header)
83
+ link_row = QHBoxLayout()
84
+ link_row.addWidget(owner.output_state_label)
85
+ link_row.addWidget(owner.linked_c_label, 1)
86
+ layout.addLayout(link_row)
87
+
88
+ owner.output_tabs = QTabWidget()
89
+ owner.output_tabs.setObjectName("GeneratedCEditorTabs")
90
+ owner.output_tabs.setDocumentMode(True)
91
+ owner.output_tabs.setTabsClosable(True)
92
+ owner.output_tabs.setAccessibleName("Generated C read-only tabs")
93
+ owner.output = CodeEditor(language="c")
94
+ owner.output.setObjectName("GeneratedCEditor")
95
+ owner.output.setReadOnly(True)
96
+ owner.output.setAccessibleName("Generated C read-only viewer")
97
+ owner.output.setTextInteractionFlags(
98
+ Qt.TextSelectableByMouse | Qt.TextSelectableByKeyboard
99
+ )
100
+ owner.output_tabs.addTab(owner.output, "generated.c")
101
+ owner.output_tabs.tabCloseRequested.connect(
102
+ lambda _index: owner._set_output_visible(False)
103
+ )
104
+ layout.addWidget(owner.output_tabs, 1)
105
+ panel.setVisible(False)
106
+ return panel
107
+
108
+
109
+ __all__ = [
110
+ "build_generated_c_surface",
111
+ "build_source_editor_surface",
112
+ ]
@@ -0,0 +1,324 @@
1
+ """Native-semantics PyQt menu surfaces for the PyCForge action registry."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from typing import Any
7
+
8
+ from .action_contract import (
9
+ MAIN_MENU_SURFACES,
10
+ SURFACE_SPECS,
11
+ PlacementKind,
12
+ SurfaceKind,
13
+ SurfaceSpec,
14
+ )
15
+ from .qt_actions import QT_ACTIONS_AVAILABLE, QtActionRegistry
16
+
17
+
18
+ if QT_ACTIONS_AVAILABLE:
19
+ from PyQt5.QtCore import QPoint, Qt
20
+ from PyQt5.QtWidgets import (
21
+ QAbstractScrollArea,
22
+ QAction,
23
+ QMenu,
24
+ QMenuBar,
25
+ QToolBar,
26
+ QToolButton,
27
+ QWidget,
28
+ )
29
+ from .visual_tokens import PYCFORGE_METRICS
30
+ QT_MENUS_AVAILABLE = True
31
+ _QT_ERROR = None
32
+ else:
33
+ QT_MENUS_AVAILABLE = False
34
+ _QT_ERROR = RuntimeError("PyQt5 is unavailable")
35
+
36
+
37
+ if QT_MENUS_AVAILABLE:
38
+ class PyCForgeMenu(QMenu):
39
+ """A styled QMenu that leaves native interaction semantics intact."""
40
+
41
+ def __init__(
42
+ self,
43
+ surface: SurfaceSpec,
44
+ parent: QWidget | None = None,
45
+ ) -> None:
46
+ super().__init__(surface.title, parent)
47
+ self.surface_id = surface.surface_id
48
+ self.setObjectName("PyCForgeMenu")
49
+ self.setAccessibleName(surface.accessible_name)
50
+ self.setProperty("pycforgeSurfaceId", surface.surface_id)
51
+ self.setProperty("pycforgeTone", "normal")
52
+ self.setSeparatorsCollapsible(True)
53
+ self.setToolTipsVisible(True)
54
+ self.setProperty(
55
+ "pycforgeIconSize", PYCFORGE_METRICS.icon_menu
56
+ )
57
+ self.hovered.connect(self._project_hover_tone)
58
+ self.aboutToHide.connect(self._clear_hover_tone)
59
+
60
+ def _project_hover_tone(self, action: QAction) -> None:
61
+ tone = str(action.property("pycforgeTone") or "normal")
62
+ if tone != self.property("pycforgeTone"):
63
+ self.setProperty("pycforgeTone", tone)
64
+ self._refresh_style()
65
+
66
+ def _clear_hover_tone(self) -> None:
67
+ if self.property("pycforgeTone") != "normal":
68
+ self.setProperty("pycforgeTone", "normal")
69
+ self._refresh_style()
70
+
71
+ def _refresh_style(self) -> None:
72
+ self.style().unpolish(self)
73
+ self.style().polish(self)
74
+ self.update()
75
+
76
+
77
+ class QtMenuFactory:
78
+ """Compose menus and toolbars solely from declared action placements."""
79
+
80
+ def __init__(
81
+ self,
82
+ registry: QtActionRegistry,
83
+ parent: QWidget,
84
+ ) -> None:
85
+ if not isinstance(registry, QtActionRegistry):
86
+ raise TypeError("registry must be a QtActionRegistry")
87
+ if parent is None:
88
+ raise TypeError("parent must be a QWidget")
89
+ self.registry = registry
90
+ self.parent = parent
91
+ self._menus: dict[str, PyCForgeMenu] = {}
92
+ self._context_targets: dict[str, object] = {}
93
+ self._main_menus: tuple[PyCForgeMenu, ...] = ()
94
+ self._context_connections: list[
95
+ tuple[QWidget, Callable[[QPoint], None]]
96
+ ] = []
97
+
98
+ def menu(self, surface_id: str) -> PyCForgeMenu:
99
+ """Return one persistent native menu for a declared menu surface."""
100
+
101
+ surface = self._surface(surface_id)
102
+ if surface.kind is SurfaceKind.TOOLBAR:
103
+ raise ValueError(
104
+ f"toolbar cannot be materialized as a menu: {surface_id}"
105
+ )
106
+ existing = self._menus.get(surface_id)
107
+ if existing is not None:
108
+ return existing
109
+ menu = PyCForgeMenu(surface, self.parent)
110
+ self._menus[surface_id] = menu
111
+ self._populate(menu, surface)
112
+ menu.aboutToShow.connect(
113
+ lambda menu=menu, surface=surface:
114
+ self._menu_opening(menu, surface)
115
+ )
116
+ menu.aboutToHide.connect(
117
+ lambda surface_id=surface_id:
118
+ self._menu_closing(surface_id)
119
+ )
120
+ return menu
121
+
122
+ def install_main_menus(
123
+ self, menu_bar: QMenuBar
124
+ ) -> tuple[PyCForgeMenu, ...]:
125
+ """Install the declared top-level menus exactly once."""
126
+
127
+ if not isinstance(menu_bar, QMenuBar):
128
+ raise TypeError("menu_bar must be a QMenuBar")
129
+ if self._main_menus:
130
+ return self._main_menus
131
+ menu_bar.setObjectName("PyCForgeMenuBar")
132
+ menu_bar.setAccessibleName("PyCForge application menus")
133
+ menu_bar.setNativeMenuBar(False)
134
+ menus = tuple(
135
+ self.menu(surface_id)
136
+ for surface_id in MAIN_MENU_SURFACES
137
+ )
138
+ for menu in menus:
139
+ menu_bar.addMenu(menu)
140
+ self._main_menus = menus
141
+ return menus
142
+
143
+ def populate_toolbar(
144
+ self,
145
+ toolbar: QToolBar,
146
+ surface_id: str = "toolbar.workspace",
147
+ ) -> tuple[QAction, ...]:
148
+ """Populate one toolbar with the registry's QAction identities."""
149
+
150
+ if not isinstance(toolbar, QToolBar):
151
+ raise TypeError("toolbar must be a QToolBar")
152
+ surface = self._surface(surface_id)
153
+ if surface.kind is not SurfaceKind.TOOLBAR:
154
+ raise ValueError(
155
+ f"surface is not a toolbar: {surface_id}"
156
+ )
157
+ toolbar.clear()
158
+ toolbar.setWindowTitle(surface.title)
159
+ toolbar.setAccessibleName(surface.accessible_name)
160
+ toolbar.setProperty("pycforgeSurfaceId", surface.surface_id)
161
+ added: list[QAction] = []
162
+ for placement in surface.placements:
163
+ if placement.kind is PlacementKind.SEPARATOR:
164
+ toolbar.addSeparator()
165
+ continue
166
+ if placement.kind is not PlacementKind.ACTION:
167
+ raise ValueError(
168
+ f"unsupported toolbar placement: {placement.kind}"
169
+ )
170
+ action = self.registry.action(placement.target)
171
+ toolbar.addAction(action)
172
+ added.append(action)
173
+ for action in added:
174
+ button = toolbar.widgetForAction(action)
175
+ if isinstance(button, QToolButton):
176
+ action_id = str(action.data())
177
+ self.registry.bind_tool_button(action_id, button)
178
+ return tuple(added)
179
+
180
+ def exec_context(
181
+ self,
182
+ surface_id: str,
183
+ target: object,
184
+ global_position: QPoint,
185
+ ) -> QAction | None:
186
+ """Execute a context menu with Qt's native placement/dismissal."""
187
+
188
+ surface = self._surface(surface_id)
189
+ if surface.kind is not SurfaceKind.CONTEXT:
190
+ raise ValueError(
191
+ f"surface is not a context menu: {surface_id}"
192
+ )
193
+ menu = self.menu(surface_id)
194
+ self._context_targets[surface_id] = target
195
+ self.registry.set_active_context(surface_id, target)
196
+ try:
197
+ return menu.exec_(global_position)
198
+ finally:
199
+ self._context_targets.pop(surface_id, None)
200
+ if self.registry.active_surface_id == surface_id:
201
+ self.registry.clear_active_context()
202
+
203
+ def install_context_menu(
204
+ self,
205
+ widget: QWidget,
206
+ surface_id: str,
207
+ *,
208
+ target_resolver: Callable[[], object] | None = None,
209
+ ) -> None:
210
+ """Replace a widget's implicit menu with a declared surface."""
211
+
212
+ surface = self._surface(surface_id)
213
+ if surface.kind is not SurfaceKind.CONTEXT:
214
+ raise ValueError(
215
+ f"surface is not a context menu: {surface_id}"
216
+ )
217
+ widget.setContextMenuPolicy(Qt.CustomContextMenu)
218
+
219
+ def requested(position: QPoint) -> None:
220
+ target = (
221
+ target_resolver()
222
+ if target_resolver is not None else widget
223
+ )
224
+ coordinate_widget = (
225
+ widget.viewport()
226
+ if isinstance(widget, QAbstractScrollArea)
227
+ else widget
228
+ )
229
+ anchor = (
230
+ coordinate_widget.rect().center()
231
+ if position.x() < 0 or position.y() < 0
232
+ else position
233
+ )
234
+ self.exec_context(
235
+ surface_id,
236
+ target,
237
+ coordinate_widget.mapToGlobal(anchor),
238
+ )
239
+
240
+ widget.customContextMenuRequested.connect(requested)
241
+ self._context_connections.append((widget, requested))
242
+
243
+ def action_ids(self, surface_id: str) -> tuple[str, ...]:
244
+ """Return static action IDs in exact visual order."""
245
+
246
+ surface = self._surface(surface_id)
247
+ return tuple(
248
+ placement.target
249
+ for placement in surface.placements
250
+ if placement.kind is PlacementKind.ACTION
251
+ )
252
+
253
+ def _populate(
254
+ self, menu: PyCForgeMenu, surface: SurfaceSpec
255
+ ) -> None:
256
+ for placement in surface.placements:
257
+ if placement.kind is PlacementKind.ACTION:
258
+ menu.addAction(
259
+ self.registry.action(placement.target)
260
+ )
261
+ elif placement.kind is PlacementKind.SEPARATOR:
262
+ menu.addSeparator()
263
+ elif placement.kind is PlacementKind.SUBMENU:
264
+ menu.addMenu(self.menu(placement.target))
265
+ elif placement.kind is PlacementKind.DYNAMIC:
266
+ menu.addActions(
267
+ self.registry.dynamic_actions(placement.target)
268
+ )
269
+
270
+ def _menu_opening(
271
+ self, menu: PyCForgeMenu, surface: SurfaceSpec
272
+ ) -> None:
273
+ target = self._context_targets.get(surface.surface_id)
274
+ self.registry.set_active_context(
275
+ surface.surface_id, target
276
+ )
277
+ if any(
278
+ item.kind is PlacementKind.DYNAMIC
279
+ for item in surface.placements
280
+ ):
281
+ menu.clear()
282
+ self._populate(menu, surface)
283
+
284
+ def _menu_closing(self, surface_id: str) -> None:
285
+ if (
286
+ surface_id not in self._context_targets
287
+ and self.registry.active_surface_id == surface_id
288
+ ):
289
+ self.registry.clear_active_context()
290
+
291
+ @staticmethod
292
+ def _surface(surface_id: str) -> SurfaceSpec:
293
+ try:
294
+ return SURFACE_SPECS[surface_id]
295
+ except KeyError as exc:
296
+ raise KeyError(
297
+ f"unknown PyCForge action surface: {surface_id}"
298
+ ) from exc
299
+
300
+
301
+ else:
302
+ class PyCForgeMenu:
303
+ """Import-safe placeholder for a damaged installation without PyQt5."""
304
+
305
+ def __init__(self, *_args, **_kwargs) -> None:
306
+ raise RuntimeError(
307
+ "PyQt5 is required for PyCForge menus"
308
+ ) from _QT_ERROR
309
+
310
+
311
+ class QtMenuFactory:
312
+ """Import-safe placeholder for a damaged installation without PyQt5."""
313
+
314
+ def __init__(self, *_args, **_kwargs) -> None:
315
+ raise RuntimeError(
316
+ "PyQt5 is required for PyCForge menus"
317
+ ) from _QT_ERROR
318
+
319
+
320
+ __all__ = [
321
+ "PyCForgeMenu",
322
+ "QT_MENUS_AVAILABLE",
323
+ "QtMenuFactory",
324
+ ]