Set settings

Source: data/set_settings.py

Per-set learning and TTS overrides stored as cells on files.csv. An empty cell inherits the matching app setting from TtsPreferences or LearnPreferences. Column rules are in Per-set settings. The screen is /set/settings.

Per-set learning and TTS overrides stored as empty-or-set cells in files.csv.

An empty cell inherits the matching app setting. A non-empty cell is the set's own value. Columns that belong to the other set kind stay empty.

EffectiveSetSettings dataclass

Settings that apply to one set after filling blanks from the app.

Attributes:

Name	Type	Description
kind	str	"words" or "definitions".
language	str	gTTS language code.
auto_speak	bool	Pronounce the definition-card word after Check.
speakers_word_formations	bool	Speaker buttons on word-formation list cards.
speakers_word	bool	Speaker button on a definition card's word.
speakers_definition	bool	Speaker button on a definition card's definition.
retry_until_correct	bool	Require a correct retype before the queue advances.
queue_size	int	Maximum items drawn into the next practice round.
uses_app_defaults	bool	Every override column for this kind is empty.

Source code in src/learning_app/data/set_settings.py

@dataclass(frozen=True)
class EffectiveSetSettings:
    """Settings that apply to one set after filling blanks from the app.

    Attributes:
        kind: ``"words"`` or ``"definitions"``.
        language: gTTS language code.
        auto_speak: Pronounce the definition-card word after Check.
        speakers_word_formations: Speaker buttons on word-formation list cards.
        speakers_word: Speaker button on a definition card's word.
        speakers_definition: Speaker button on a definition card's definition.
        retry_until_correct: Require a correct retype before the queue advances.
        queue_size: Maximum items drawn into the next practice round.
        uses_app_defaults: Every override column for this kind is empty.
    """

    kind: str
    language: str
    auto_speak: bool
    speakers_word_formations: bool
    speakers_word: bool
    speakers_definition: bool
    retry_until_correct: bool
    queue_size: int
    uses_app_defaults: bool

columns_for_kind

columns_for_kind(kind: str) -> tuple[str, ...]

Return catalog columns that a set of kind may override.

Source code in src/learning_app/data/set_settings.py

def columns_for_kind(kind: str) -> tuple[str, ...]:
    """Return catalog columns that a set of ``kind`` may override."""
    if kind == _DEFINITIONS:
        return _DEFINITIONS_COLUMNS
    return _WORDS_COLUMNS

read_override_cells

read_override_cells(file_name: str) -> dict[str, str]

Return stored override text for file_name.

Missing catalog rows and blank cells are empty strings. Empty means the set inherits the app setting for that column.

Parameters:

Name	Type	Description	Default
file_name	str	Set basename or path.	required

Source code in src/learning_app/data/set_settings.py

def read_override_cells(file_name: str) -> dict[str, str]:
    """Return stored override text for ``file_name``.

    Missing catalog rows and blank cells are empty strings. Empty means the
    set inherits the app setting for that column.

    Args:
        file_name: Set basename or path.
    """
    blank = {column: "" for column in _ALL_OVERRIDE_COLUMNS}
    row = _catalog_row(file_name)
    if row is None:
        return blank
    for column in _ALL_OVERRIDE_COLUMNS:
        blank[column] = _cell_text(row[column]) if column in row.index else ""
    return blank

effective_set_settings

effective_set_settings(
    file_name: str,
) -> EffectiveSetSettings

Resolve one set's settings, using app defaults for empty cells.

Non-empty booleans are explicit (false stays off). A non-empty queue size is clamped to the range for the set's kind; unparseable text falls back to the app default. An unknown language code becomes English.

Parameters:

Name	Type	Description	Default
file_name	str	Set basename or path ending in _words.csv or _definitions.csv.	required

Source code in src/learning_app/data/set_settings.py

def effective_set_settings(file_name: str) -> EffectiveSetSettings:
    """Resolve one set's settings, using app defaults for empty cells.

    Non-empty booleans are explicit (``false`` stays off). A non-empty queue
    size is clamped to the range for the set's kind; unparseable text falls
    back to the app default. An unknown language code becomes English.

    Args:
        file_name: Set basename or path ending in ``_words.csv`` or
            ``_definitions.csv``.
    """
    from learning_app.data.app_data import get_kind_of_file_and_validate
    from learning_app.ui.learn_preferences import LearnPreferences
    from learning_app.ui.tts_preferences import TtsPreferences

    kind = get_kind_of_file_and_validate(file_name)
    cells = read_override_cells(file_name)
    applicable = columns_for_kind(kind)

    language_cell = cells[FilesColumns.TTS_LANGUAGE.value]
    language = (
        TtsPreferences.normalize_language(language_cell)
        if language_cell
        else TtsPreferences.language
    )

    if kind == _DEFINITIONS:
        queue_default = LearnPreferences.definitions_queue_size
        auto_speak = _bool_or_default(
            cells[FilesColumns.TTS_AUTO_SPEAK.value],
            TtsPreferences.auto_speak_definitions,
        )
        speakers_word = _bool_or_default(
            cells[FilesColumns.SPEAKERS_WORD.value],
            TtsPreferences.speakers_word,
        )
        speakers_definition = _bool_or_default(
            cells[FilesColumns.SPEAKERS_DEFINITION.value],
            TtsPreferences.speakers_definition,
        )
        speakers_word_formations = TtsPreferences.speakers_word_formations
    else:
        queue_default = LearnPreferences.word_formations_queue_size
        auto_speak = TtsPreferences.auto_speak_definitions
        speakers_word = TtsPreferences.speakers_word
        speakers_definition = TtsPreferences.speakers_definition
        speakers_word_formations = _bool_or_default(
            cells[FilesColumns.SPEAKERS_WORD_FORMATIONS.value],
            TtsPreferences.speakers_word_formations,
        )
    queue_size = _queue_or_default(
        cells[FilesColumns.QUEUE_SIZE.value],
        kind=kind,
        default=queue_default,
    )

    return EffectiveSetSettings(
        kind=kind,
        language=language,
        auto_speak=auto_speak,
        speakers_word_formations=speakers_word_formations,
        speakers_word=speakers_word,
        speakers_definition=speakers_definition,
        retry_until_correct=_bool_or_default(
            cells[FilesColumns.RETRY_UNTIL_CORRECT.value],
            LearnPreferences.retry_until_correct,
        ),
        queue_size=queue_size,
        uses_app_defaults=all(cells[column] == "" for column in applicable),
    )

language_for_set_file

language_for_set_file(file_name: str) -> str

Return the language used when this set's phrases are spoken.

Source code in src/learning_app/data/set_settings.py

def language_for_set_file(file_name: str) -> str:
    """Return the language used when this set's phrases are spoken."""
    return effective_set_settings(file_name).language

catalog_title

catalog_title(file_name: str) -> str

Return the display title for file_name from files.csv.

Falls back to the basename when the catalog row is missing or the title cell is blank.

Source code in src/learning_app/data/set_settings.py

def catalog_title(file_name: str) -> str:
    """Return the display title for ``file_name`` from ``files.csv``.

    Falls back to the basename when the catalog row is missing or the title
    cell is blank.
    """
    row = _catalog_row(file_name)
    if row is None or FilesColumns.TITLE.value not in row.index:
        return os.path.basename(file_name)
    title = _cell_text(row[FilesColumns.TITLE.value])
    return title or os.path.basename(file_name)

enable_set_overrides

enable_set_overrides(file_name: str) -> None

Copy the current app settings into this set's override columns.

Columns for the other kind are cleared. After this call the set no longer follows later changes to the app settings.

Parameters:

Name	Type	Description	Default
file_name	str	Set basename or path present in files.csv.	required

Source code in src/learning_app/data/set_settings.py

def enable_set_overrides(file_name: str) -> None:
    """Copy the current app settings into this set's override columns.

    Columns for the other kind are cleared. After this call the set no longer
    follows later changes to the app settings.

    Args:
        file_name: Set basename or path present in ``files.csv``.
    """
    from learning_app.data.app_data import get_kind_of_file_and_validate

    kind = get_kind_of_file_and_validate(file_name)
    _write_overrides(file_name, _global_values(kind), clear_others=True)

clear_set_overrides

clear_set_overrides(file_name: str) -> None

Blank every override column so the set uses app settings again.

Parameters:

Name	Type	Description	Default
file_name	str	Set basename or path present in files.csv.	required

Source code in src/learning_app/data/set_settings.py

def clear_set_overrides(file_name: str) -> None:
    """Blank every override column so the set uses app settings again.

    Args:
        file_name: Set basename or path present in ``files.csv``.
    """
    _write_overrides(file_name, {}, clear_others=True)

set_override_value

set_override_value(
    file_name: str, column: str, value: str
) -> None

Store one override cell when column applies to this set's kind.

Parameters:

Name	Type	Description	Default
file_name	str	Set basename or path present in files.csv.	required
column	str	A FilesColumns override name.	required
value	str	Explicit stored text, such as "true", "pl", or "8".	required

Source code in src/learning_app/data/set_settings.py

def set_override_value(file_name: str, column: str, value: str) -> None:
    """Store one override cell when ``column`` applies to this set's kind.

    Args:
        file_name: Set basename or path present in ``files.csv``.
        column: A ``FilesColumns`` override name.
        value: Explicit stored text, such as ``"true"``, ``"pl"``, or ``"8"``.
    """
    from learning_app.data.app_data import get_kind_of_file_and_validate

    kind = get_kind_of_file_and_validate(file_name)
    if column not in columns_for_kind(kind):
        return
    _write_overrides(file_name, {column: value}, clear_others=False)