spacr.qt.tutorials

Which published lesson teaches a module, and the URL that opens it.

The lesson library at <docs>/tutorials/ deep-links with #lesson=<id>, so pointing a reader at the lesson for the module they are hovering is a lookup and a string. The lookup table is spacr/resources/tutorial_index.json, written by tools/build_tutorial_index.py from the docs build’s own lesson catalog – see there for why it is not the catalog itself.

No network access and no heavy imports: this is read on the hover path, from Home and from the dock, so it caches the table on first use and answers "" for anything it cannot resolve. A module with no lesson gets no link, and no exception is raised in a hover handler.

The same table carries the whole lesson list, which spacr-tutorial prints and resolves a lesson number, slug or screen name against; see lessons() and find_lesson().

Functions

find_lesson(→ Tuple[Optional[dict], List[str]])	The lesson name names, or the names closest to it.
has_tutorial(→ bool)	Whether app_key has a lesson to link to.
lesson_for(→ str)	The lesson id that teaches app_key, or "".
lesson_title(→ str)	The lesson's own title, for a tooltip. "" when there is none.
lesson_url(→ str)	The URL that opens one lesson of the library.
lessons(→ List[dict])	Every lesson in the library, in lesson-number order.
tutorial_url(→ str)	The URL that opens app_key's lesson, or "" when it has none.

Module Contents

spacr.qt.tutorials.find_lesson(name: str) → Tuple[dict | None, List[str]]

The lesson name names, or the names closest to it.

name may be a lesson number (7 or 07), a lesson id (07_mask), the key of the screen a lesson covers (measure) or a slug (plaque-assay). Case, hyphens and spaces do not matter. When two lessons answer to one name, the earlier kind in that list wins, and among lessons of one kind the lowest-numbered.

Parameters:

name – what the reader typed.

Returns:

(lesson, []) as lessons() gives it, or (None, suggestions) when nothing matches: up to five slugs and screen names, the closest spellings first, then those containing name.

spacr.qt.tutorials.has_tutorial(app_key: str) → bool

Whether app_key has a lesson to link to.

Parameters:

app_key – the app key looked up in the bundled tutorial_index.json; None or empty gives no lesson.

spacr.qt.tutorials.lesson_for(app_key: str) → str

The lesson id that teaches app_key, or "".

Parameters:

app_key – the app key looked up in the bundled tutorial_index.json; None or empty gives no lesson.

spacr.qt.tutorials.lesson_title(app_key: str) → str

The lesson’s own title, for a tooltip. "" when there is none.

Parameters:

app_key – the app key looked up in the bundled tutorial_index.json; None or empty gives no lesson.

spacr.qt.tutorials.lesson_url(lesson: str) → str

The URL that opens one lesson of the library.

Parameters:

lesson – the lesson id, such as 07_mask.

Returns:

the library URL with the #lesson= fragment it reads.

spacr.qt.tutorials.lessons() → List[dict]

Every lesson in the library, in lesson-number order.

Read once from the bundled table and cached; an unreadable table gives an empty list, as the module lookups give "".

Returns:

one dict per lesson with number (int), lesson (its id, such as 07_mask), slug, title and app_key (the screen it covers, "" for a lesson about no single screen).

spacr.qt.tutorials.tutorial_url(app_key: str) → str

The URL that opens app_key’s lesson, or "" when it has none.

Empty rather than the library’s front page on purpose. The link is drawn only when this answers, so a word that would have dropped the reader at an index of seventy-three lessons is simply not offered – the rule the tooltip footer already follows for Animation.

Parameters:

app_key – the app key looked up in the bundled tutorial_index.json; None or empty gives no lesson.