spacr.qt.app_catalog

Application metadata and lazy factories for the Qt interface.

DECLARED_APPS is the canonical source for application names, descriptions, navigation sections, documentation links, and factory paths. Screen modules read their metadata from this catalog instead of duplicating the same strings.

LazyScreenFactory imports a screen module only when the application is opened. Keeping this module free of Qt and scientific-computing imports reduces startup work while preserving the ordinary screen-factory interface.

See spacr.qt.app.register_app() for what each field does once it is handed over, and spacr.qt.SELF_REGISTERING_MODULES for the ordering constraint that decides when these rows are registered.

Classes

DeclaredApp	Store the registration metadata for one Qt application.
LazyScreenFactory	Resolve a screen factory when it is first requested.

Functions

declared_app(→ DeclaredApp)	The row declared for app key.
declared_for(module)	The row declared for module, or None if it declares none.
register_declared(module, *[, key, section, stage])	Register the catalog entry for module without loading its screen.

Module Contents

class spacr.qt.app_catalog.DeclaredApp(*, module: str, key: str, name: str, desc: str, section: str, factory=None, stage=None, title: str = '', intro: str = '', cli_note: str = '', api_module: str = '', entry: str = '', defaults_module: str = '', translations=())

Store the registration metadata for one Qt application.

This dependency-light class avoids importing the additional modules used by dataclasses or named tuples during application startup.

Parameters:

• module – dotted name of the module that owns the screen. The identity of the row — declared_for() is keyed on it, and it is what LazyScreenFactory imports.

• key – the app key, unique across the registry.

• name – display name; the sidebar row, the tile and the menu entry.

• desc – one-line summary; the tooltip and status tip.

• section – one of spacr.qt.app.SECTION_ORDER, spelled out rather than referenced. Importing app from here would be a cycle: app reads this table while it is itself being imported. A misspelling is not a silent one — spacr.qt.app.register_app() raises on a section it does not know.

• factory – ATTRIBUTE NAME of the screen factory on module, not the callable. None for an app that takes the generic settings screen.

• stage – one of spacr.qt.app.STAGES; likewise spelled out.

• title – header at the top of the app’s own screen, when it wants the longer form. Defaults to name.

• intro – the paragraph beside that header. Defaults to desc.

• cli_note – for a GUI-only app, the sentence spacr-run <key> prints instead of “unknown module”.

• api_module – module path under the generated API docs, for the info link beside the settings.

• entry – "module:function" the Run button runs.

• defaults_module – the module whose import registers this key’s settings defaults.

• translations – the display name in the nine non-English UI languages, in spacr.qt.i18n.LANGUAGES order.

Record one module’s declaration.

Parameters:

• module – the Python module that declares it.

• key – the registry key everything else dispatches on.

• name – the short name shown in the dock and on Home.

• desc – the one-line blurb.

• section – which Home section it belongs to.

• factory – builds the screen; usually a LazyScreenFactory.

• stage – the release stage, used to gate visibility.

• title – the masthead title, falling back to name.

• intro – the longer blurb shown on the screen itself.

• cli_note – how to reach the same thing from the command line.

• api_module – the module the API help link points at.

• entry – the callable a run enters through.

• defaults_module – where its settings defaults live.

• translations – extra translation catalogues to load with it.

__repr__() → str

Return the key and the module that declared it.

register_kwargs() → dict

Return populated keyword arguments for register_app.

Empty optional fields are omitted so register_app can apply its documented fallbacks. Factory paths are represented by LazyScreenFactory instances and do not import screen modules.

class spacr.qt.app_catalog.LazyScreenFactory(module: str, attribute: str)

Resolve a screen factory when it is first requested.

spacr.qt.app.registered_factory() resolves this proxy before normal screen construction, allowing signature inspection to use the underlying callable. Direct calls are also supported; only keyword arguments accepted by the resolved factory are forwarded unless it accepts **kwargs.

Parameters:

• module – dotted path of the module holding the factory. NOT imported here – that is the whole point: naming a screen must not pull its imports into application startup.

• attribute – the factory’s name inside that module.

Record where a screen class lives, without importing it.

Parameters:

• module – the module to import on first use.

• attribute – the name to take out of it.

__call__(**kwargs)

Import the screen class if needed and build one.

Keyword arguments the factory does not accept are dropped rather than raising, so a caller can offer threaded= or link= to every screen and let each take what it understands. inspect is imported here rather than at module scope: it costs a dozen modules of its own, and this module is read while the splash screen is up to avoid exactly that bill.

Parameters:

kwargs – passed to the factory, filtered to what it accepts unless it takes **kwargs.

Returns:

the constructed screen.

__repr__() → str

Return the target and whether it has been imported yet.

resolve()

Import and cache the underlying screen factory.

Raises:

• ImportError – if the module cannot be imported.

• AttributeError – if it has no such attribute — a declared row naming a factory that does not exist, which the catalog test catches long before a user clicks the tile.

spacr.qt.app_catalog.declared_app(key: str) → DeclaredApp

The row declared for app key.

Parameters:

key – app key to look up, matched exactly against DeclaredApp.key.

Raises:

KeyError – if no declared app has that key.

spacr.qt.app_catalog.declared_for(module: str)

The row declared for module, or None if it declares none.

Parameters:

module – dotted module name of a screen, matched exactly against DeclaredApp.module.

spacr.qt.app_catalog.register_declared(module: str, *, key=None, section=None, stage=None)

Register the catalog entry for module without loading its screen.

Registration is idempotent because startup and direct module registration can reach the same catalog entry. If its key is already registered, this function leaves the registry unchanged.

Parameters:

• module – the dotted module name the row is declared under.

• key – register under this key instead of the declared one. Two of these registrars expose it so a second copy of a screen can be given its own row; the row’s own key is the default and the normal case.

• section – override the declared section. For spacr.qt.layer_viewer.register_layer_viewer_app(), which lets a caller place the app elsewhere.

• stage – override the declared maturity stage, likewise.

Returns:

the registry row that was appended, or None when the key was already registered or no row is declared for module.