spacr.qt.help_search¶

The search field beside the Help menu, and what each result opens.

spacr.qt.help_index decides WHAT is addressable by name; this module is where a user types a name and where the answer takes them. The two halves are apart because only this one needs a display.

WHAT A RESULT DOES IS REGISTERED, NOT SWITCHED ON. register_opener() binds a kind to (window, entry) -> str; open_entry() looks the kind up. A new kind of thing therefore needs a provider in the index module and an opener here, and no existing function changes – which is the instruction’s “and so on” clause taken literally.

The four that ship:

module: spacr.qt.app.MainWindow.open_module(), which resolves a folded module to the host that took it over.
setting: Opens the module and then reveal_setting(): every category collapsed except the one holding the setting, the row scrolled to and marked. NOT by filtering the panel – the per-module strip already has a filter and it leaves the other categories hidden, so a user who wanted to look around next has to work out what happened to the form.
preference: Opens Preferences on the tab that holds the row and marks the row.
api: Opens the published page WHEN IT IS REACHABLE, and otherwise shows the docstring that is on this machine and says the page is not reachable. A search result is believed, so a result that opens a 404 is worse than no result at all.

NOTHING THIS MODULE DOES ON THE GUI THREAD BLOCKS IT. The index costs about a second to build, so it is built on a worker the first time the field is typed in (_IndexLoader), and the field says so until it lands. Whether the documentation site answers is a network question, so it is asked on a worker too (_DocsReach) and only ever when the user has opened an API result – spaCR does not reach the network because somebody typed.

OPENING A RESULT NEVER DISCARDS SETTINGS. MainWindow._on_nav_selected keeps every screen it has built in self._screens and switches the stack to it, so a half-filled Mask form is still half-filled when the user comes back from Measure. That was true before this field existed and it is now pinned by tests/qt/test_the_help_search_field_lands_where_it_says.py so that a future rebuild-on-navigate cannot quietly take it away.

Classes¶

`ApiEntryDialog`	A symbol's local docstring, shown when its web page cannot be reached.
`HelpSearchField`	The box beside the Help menu.

Functions¶

`api_url`(→ str)	The published page for a dotted symbol.
`docs_reach`(→ _DocsReach)	The one reachability probe, made on first use.
`field_of`(→ Optional[HelpSearchField])	The field installed on `window`, if there is one.
`focus_field`(→ bool)	Put the caret in the help search box.
`install`(→ Optional[HelpSearchField])	Put the search field directly to the right of the Help menu.
`install_window_hooks`(→ Optional[HelpSearchField])	Install the field from `spacr.qt.shortcuts.install()`.
`local_docstring`(→ str)	The docstring of `symbol` as it is on this machine.
`open_entry`(→ str)	Take the user to `entry`.
`opener_kinds`(→ tuple)	The kinds that can be opened, in registration order.
`register_opener`(→ None)	Say what happens when a result of `kind` is chosen.
`reveal_setting`(→ bool)	Open `app_key` with only `key`'s category expanded and `key` shown.
`show_api_entry`(→ ApiEntryDialog)	Show one API entry's local docstring.

Module Contents¶

class spacr.qt.help_search.ApiEntryDialog(symbol: str, url: str, fallback: str = '', parent: PySide6.QtWidgets.QWidget | None = None)[source]¶

Bases: PySide6.QtWidgets.QDialog

A symbol’s local docstring, shown when its web page cannot be reached.

Parameters:

symbol – the dotted symbol.
url – where the page would be.
fallback – the indexed summary, used when the source has no docstring to read.
parent – parent widget.

Build the offline view of one API entry.

class spacr.qt.help_search.HelpSearchField(window: PySide6.QtWidgets.QMainWindow, parent: PySide6.QtWidgets.QWidget | None = None)[source]¶

Bases: PySide6.QtWidgets.QLineEdit

The box beside the Help menu.

Owns the popup, the index and the keyboard. Arrow keys and Return are forwarded to the list while it is open, which is what lets the whole feature be used without the mouse leaving the keyboard: focus, type, Down, Return.

Parameters:

window – the main window results act on.
parent – parent widget.

Build the field, its popup and the debounce timer.

focusOutEvent(event) → None[source]¶

Close the list when the caret leaves the box.

Safe to do unconditionally now that the list takes NoFocus: clicking a row cannot move focus, so a focus-out means the user went somewhere else and the list is in the way of whatever that was.

Parameters:: event – the focus-out event; it is not inspected, only passed on to the base class after the list is hidden.

hide_popup() → None[source]¶: Put the popup away.

index() → List[spacr.qt.help_index.HelpEntry] | None[source]¶: The index, or None while it is still being built.

keyPressEvent(event: PySide6.QtGui.QKeyEvent) → None[source]¶

Steer the list from the box, and let Esc give the window back.

Parameters:: event – the key press.

note() → str[source]¶: The line above the list: what is being built, or what matched.

popup() → PySide6.QtWidgets.QFrame[source]¶: The results popup, so a test can ask whether it is up.

results() → List[spacr.qt.help_index.HelpEntry][source]¶: What the popup is showing, best first.

set_index(entries: List[spacr.qt.help_index.HelpEntry]) → None[source]¶

Use entries instead of building one.

Parameters:: entries – what spacr.qt.help_index.build_index() returned.

type_and_search(text: str) → List[spacr.qt.help_index.HelpEntry][source]¶

Put text in the box and search now, skipping the debounce.

The seam tests drive: typing is the user’s action, and waiting 140 ms for a timer in every assertion would make the suite slower and no more honest about what the field does.

Parameters:: text – what the user typed.
Returns:: the results now on screen.

spacr.qt.help_search.api_url(symbol: str, language: str | None = None) → str[source]¶

The published page for a dotted symbol.

The same shape spacr.qt.screens.settings_model.api_docs_url builds for a settings row – <base>/spacr/core/index.html#spacr.core.f, with ?lang= on a page the reader wants in another language – from the same DOCS_API_BASE, so the search field and a settings row cannot disagree about where the documentation lives.

WHICH PREFIX IS THE MODULE is answered from the disk rather than assumed: spacr.qt.screens.mask is a module and spacr.layers.ShapesLayer.mask is an attribute two levels inside one, and only the file layout knows which of the dots is the last one in the path.

Parameters:

symbol – a dotted symbol name.
language – a language code; the current one when None.

Returns:

an absolute URL.

spacr.qt.help_search.docs_reach() → _DocsReach[source]¶: The one reachability probe, made on first use.

spacr.qt.help_search.field_of(window: PySide6.QtWidgets.QMainWindow) → HelpSearchField | None[source]¶

The field installed on window, if there is one.

Parameters:: window – the main window.
Returns:: the field, or None.

spacr.qt.help_search.focus_field(window: PySide6.QtWidgets.QMainWindow) → bool[source]¶

Put the caret in the help search box.

Parameters:: window – the main window.
Returns:: True when there was a field to focus.

spacr.qt.help_search.install(window: PySide6.QtWidgets.QMainWindow) → HelpSearchField | None[source]¶

Put the search field directly to the right of the Help menu.

IN THE MENU ROW, NOT THE CORNER. The field was first installed in the menu bar’s top-right corner widget, which put it beside the minimise, full screen and close marks at the far right of the window, away from the menus. It belongs directly to the right of Help, so it is placed in the menu row itself: the bar lays its actions out left to right, and Help is the last menu, so the field follows Help and moves with it when the menus are re-translated or re-ordered.

Idempotent: a second call hands back the field the first one installed.

Parameters:: window – the main window.
Returns:: the field, or None when there is no menu bar to hang it on.

spacr.qt.help_search.install_window_hooks(window: PySide6.QtWidgets.QMainWindow) → HelpSearchField | None[source]¶

Install the field from spacr.qt.shortcuts.install().

Named for the convention the other window-scoped installers follow, so that _install_window_hooks reads as one list of the same thing.

Parameters:: window – the main window.
Returns:: the field, or None.

spacr.qt.help_search.local_docstring(symbol: str) → str[source]¶

The docstring of symbol as it is on this machine.

Read from the source with ast rather than by importing: the offline path must not be the one that drags spacr.core and its scientific stack into the process, and a docstring is in the syntax tree.

Parameters:: symbol – a dotted symbol name.
Returns:: the docstring, or "" when it cannot be found.

spacr.qt.help_search.open_entry(window: PySide6.QtWidgets.QMainWindow, entry: spacr.qt.help_index.HelpEntry) → str[source]¶

Take the user to entry.

Parameters:

window – the main window.
entry – the chosen result.

Returns:

what to say in the status bar; "" when nothing was done.

spacr.qt.help_search.opener_kinds() → tuple[source]¶: The kinds that can be opened, in registration order.

spacr.qt.help_search.register_opener(kind: str, opener: Callable[[PySide6.QtWidgets.QMainWindow, spacr.qt.help_index.HelpEntry], str]) → None[source]¶

Say what happens when a result of kind is chosen.

Parameters:

kind – the entry kind, matching a provider in spacr.qt.help_index.
opener – (window, entry) -> str; the string is shown in the status bar.

spacr.qt.help_search.reveal_setting(window: PySide6.QtWidgets.QMainWindow, app_key: str, key: str) → bool[source]¶

Open app_key with only key’s category expanded and key shown.

Goes through the per-module search strip, which already owns the map from a setting key to the section and field widget rendering it. Building a second map here would be a second thing to keep in step with the form.

Parameters:

window – the main window.
app_key – the module to open.
key – the setting to reveal.

Returns:

True when the row was found and revealed.

spacr.qt.help_search.show_api_entry(window: PySide6.QtWidgets.QWidget | None, symbol: str, url: str, fallback: str = '') → ApiEntryDialog[source]¶

Show one API entry’s local docstring.

Parameters:

window – parent widget.
symbol – the dotted symbol.
url – where the published page would be.
fallback – the indexed summary.

Returns:

the dialog, already shown.