music-assistant-server

2.5 KB•PY

setup_flow.py

2.5 KB • 60 lines • python

1"""
2DEMO/TEMPLATE interactive setup flow for a Music Assistant provider.
3
4A provider ships a ``setup_flow.py`` module ONLY when adding an instance requires user
5input (credentials, a token, an OAuth/QR login, picking a device on the network, ...).
6When present, the server imports it and drives its ``run_setup`` coroutine when the user
7adds the provider via ``config/providers/setup``; when absent, the instance is created
8immediately with no input.
9
10The flow talks to the user through the ``SetupSession``:
11
12* ``await session.form(entries, step_id=..., errors=..., last_step=...)`` shows a form of
13  ``ConfigEntry`` objects and returns the submitted ``{key: value}`` dict. Call it as many
14  times as you need (multi-step wizards, re-prompts on error, ...).
15* ``await session.finish(setup_data)`` persists ``setup_data`` (secrets are encrypted at
16  rest by the server) and loads the provider. The collected values are read back in the
17  provider via ``self.get_setup_value(<key>)`` - NOT via ``get_config_entries``, which now
18  only describes the (runtime) options of an already set-up instance.
19
20Refused/failed setup: raise ``AbortFlow(reason)`` to end the flow, or let a
21``SetupFlowError`` from ``finish()`` bubble up to re-prompt with an error.
22
23This demo collects nothing and finishes immediately; delete this file for a provider that
24needs no setup input, or replace the body with a real form (see e.g. the opensubsonic or
25deezer providers).
26"""
27
28from __future__ import annotations
29
30from typing import TYPE_CHECKING
31
32if TYPE_CHECKING:
33    from music_assistant.models.setup_flow import SetupSession
34
35
36async def run_setup(session: SetupSession) -> None:
37    """
38    Drive the interactive setup flow for a new provider instance.
39
40    :param session: The setup flow session used to interact with the user.
41    """
42    # Example of a single-step form (uncomment and adapt for a real provider):
43    #
44    # from music_assistant_models.config_entries import ConfigEntry
45    # from music_assistant_models.enums import ConfigEntryType
46    # from music_assistant.constants import CONF_USERNAME, CONF_PASSWORD
47    #
48    # values = await session.form(
49    #     [
50    #         ConfigEntry(key=CONF_USERNAME, type=ConfigEntryType.STRING, required=True),
51    #         ConfigEntry(key=CONF_PASSWORD, type=ConfigEntryType.SECURE_STRING, required=True),
52    #     ],
53    #     step_id="user",
54    #     last_step=True,
55    # )
56    # await session.finish(values)  # validate + persist (as setup_data) + load the provider
57    #
58    # This demo collects nothing and finishes right away.
59    await session.finish({})
60

1""" 2DEMO/TEMPLATE interactive setup flow for a Music Assistant provider. 3 4A provider ships a ``setup_flow.py`` module ONLY when adding an instance requires user 5input (credentials, a token, an OAuth/QR login, picking a device on the network, ...). 6When present, the server imports it and drives its ``run_setup`` coroutine when the user 7adds the provider via ``config/providers/setup``; when absent, the instance is created 8immediately with no input. 9 10The flow talks to the user through the ``SetupSession``: 11 12* ``await session.form(entries, step_id=..., errors=..., last_step=...)`` shows a form of 13 ``ConfigEntry`` objects and returns the submitted ``{key: value}`` dict. Call it as many 14 times as you need (multi-step wizards, re-prompts on error, ...). 15* ``await session.finish(setup_data)`` persists ``setup_data`` (secrets are encrypted at 16 rest by the server) and loads the provider. The collected values are read back in the 17 provider via ``self.get_setup_value(<key>)`` - NOT via ``get_config_entries``, which now 18 only describes the (runtime) options of an already set-up instance. 19 20Refused/failed setup: raise ``AbortFlow(reason)`` to end the flow, or let a 21``SetupFlowError`` from ``finish()`` bubble up to re-prompt with an error. 22 23This demo collects nothing and finishes immediately; delete this file for a provider that 24needs no setup input, or replace the body with a real form (see e.g. the opensubsonic or 25deezer providers). 26""" 27 28from __future__ import annotations 29 30from typing import TYPE_CHECKING 31 32if TYPE_CHECKING: 33 from music_assistant.models.setup_flow import SetupSession 34 35 36async def run_setup(session: SetupSession) -> None: 37 """ 38 Drive the interactive setup flow for a new provider instance. 39 40 :param session: The setup flow session used to interact with the user. 41 """ 42 # Example of a single-step form (uncomment and adapt for a real provider): 43 # 44 # from music_assistant_models.config_entries import ConfigEntry 45 # from music_assistant_models.enums import ConfigEntryType 46 # from music_assistant.constants import CONF_USERNAME, CONF_PASSWORD 47 # 48 # values = await session.form( 49 # [ 50 # ConfigEntry(key=CONF_USERNAME, type=ConfigEntryType.STRING, required=True), 51 # ConfigEntry(key=CONF_PASSWORD, type=ConfigEntryType.SECURE_STRING, required=True), 52 # ], 53 # step_id="user", 54 # last_step=True, 55 # ) 56 # await session.finish(values) # validate + persist (as setup_data) + load the provider 57 # 58 # This demo collects nothing and finishes right away. 59 await session.finish({}) 60