backlogops 0.1__py3-none-any.whl

backlogops/io_config.py

@@ -0,0 +1,277 @@
+#! /usr/local/bin/python3
+"""Configuration for reading and writing tables with TableIO.
+
+A backlog and its releases are read from and written to tabular files
+(Excel, ODS, CSV, and more) using TableIO. The durable TableIO settings
+for one input or one output are stored as a :class:`TioJsonConfig`. On
+top of that this module adds a per-endpoint column-name map, so the
+columns shown to a user can have other names than the internal field
+names of the data model.
+
+An input endpoint is described by an :class:`InputFormatConfig` and an
+output endpoint by an :class:`OutputFormatConfig`. Both wrap one
+``TioJsonConfig`` and one direction-specific name map:
+
+* an input map (``to_internal``) translates an external column name to
+  an internal field name, and several external names may map to the same
+  internal field;
+* an output map (``to_external``) translates an internal field name to
+  the external column name to write.
+
+:func:`resolve_input_config` and :func:`resolve_output_config` turn a
+command-line value into such a configuration. The value may be empty
+(then the format is inferred from the data file name extension), a preset
+name (looked up among named presets stored elsewhere, typically in the
+teams configuration file), or the name of a stand-alone configuration
+file.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import ClassVar, Optional, TextIO, override
+from config_as_json import Config, ConfigNesting, ConfigNestingKind, \
+    DictKeyValueTypesValidator, MemberValidationStep, NestedConfigs, \
+    PathOrStr, ValidationPlan
+from tableio import Capabilities, FileAccess, access_capabilities
+from tableio_cfg_json import TioJsonConfig, tio_json_config_default
+
+EXTENSION_FORMATS: dict[str, str] = {
+    '.csv': 'CSV', '.xlsx': 'Excel', '.xls': 'Excel', '.ods': 'ODS',
+    '.html': 'HTML', '.htm': 'HTML', '.tex': 'LaTeX', '.md': 'md',
+    '.docx': 'docx', '.odt': 'odt', '.pdf': 'pdf', '.rst': 'reST',
+    '.rtf': 'rtf', '.txt': 'txt'}
+"""Map a data file name extension to a TableIO format name."""
+
+PRESET_NAME_RE = re.compile(r'^[A-Za-z0-9]+$')
+"""A configuration value made only of letters and digits is a preset."""
+
+
+def _capabilities(file_access: FileAccess, stderr_file: TextIO
+                  ) -> Capabilities:
+    """Return the TableIO capabilities implied by a file access mode."""
+    return access_capabilities(file_access, error_file=stderr_file)
+
+
+def _tio_default(file_access: FileAccess, format_name: Optional[str] = None,
+                 stderr_file: TextIO = sys.stderr) -> TioJsonConfig:
+    """Return a default TableIO config for a format and file access."""
+    return tio_json_config_default(
+        capabilities=_capabilities(file_access, stderr_file),
+        file_access=file_access, format_name=format_name,
+        stderr_file=stderr_file)
+
+
+def _tio_from_json(file_access: FileAccess, from_json_data_text: Optional[str],
+                   from_json_filename: Optional[PathOrStr],
+                   stderr_file: TextIO) -> TioJsonConfig:
+    """Return a TableIO config read from JSON for a file access mode."""
+    return TioJsonConfig(capabilities=_capabilities(file_access, stderr_file),
+                         file_access=file_access,
+                         from_json_data_text=from_json_data_text,
+                         from_json_filename=from_json_filename,
+                         stderr_file=stderr_file)
+
+
+class _FormatConfig(Config):
+    """Shared behavior for one input or output TableIO endpoint config.
+
+    A concrete subclass fixes the file access mode and the name of its
+    column-name map member, and declares that map member before calling
+    the constructor. The wrapped ``TioJsonConfig`` is created here and
+    declared as a nested configuration so it reads and writes itself.
+    """
+
+    _FILE_ACCESS: ClassVar[FileAccess]
+    _MAP_NAME: ClassVar[str]
+
+    def __init__(self, from_json_data_text: Optional[str] = None,
+                 from_json_filename: Optional[PathOrStr] = None,
+                 stderr_file: TextIO = sys.stderr) -> None:
+        """Create default settings or read them from a JSON source."""
+        self.tableio: TioJsonConfig = _tio_default(self._FILE_ACCESS,
+                                                   stderr_file=stderr_file)
+        self._unchecked_dicts = [self._MAP_NAME]
+        Config.__init__(self, from_json_data_text=from_json_data_text,
+                        from_json_filename=from_json_filename,
+                        stderr_file=stderr_file)
+
+    def _tio_factory(self, *, from_json_data_text: Optional[str] = None,
+                     from_json_filename: Optional[PathOrStr] = None,
+                     stderr_file: TextIO = sys.stderr) -> TioJsonConfig:
+        """Construct the nested TableIO config from JSON when reading."""
+        return _tio_from_json(self._FILE_ACCESS, from_json_data_text,
+                              from_json_filename, stderr_file)
+
+    @override
+    def nested_configs(self) -> NestedConfigs:
+        """Declare the wrapped TableIO config as a nested configuration."""
+        return {'tableio': ConfigNesting(kind=ConfigNestingKind.MEMBER,
+                                         config_type=TioJsonConfig,
+                                         factory_function=self._tio_factory)}
+
+    @override
+    def get_validation_plan(self, stderr_file: TextIO) -> ValidationPlan:
+        """Check that the column-name map is a mapping of string to string."""
+        _ = stderr_file
+        return [MemberValidationStep(
+            member_names=[self._MAP_NAME],
+            validator=DictKeyValueTypesValidator(str, str))]
+
+
+class InputFormatConfig(_FormatConfig):
+    """TableIO input endpoint with an external-to-internal column map."""
+
+    _FILE_ACCESS = FileAccess.READ
+    _MAP_NAME = 'to_internal'
+    to_internal: dict[str, str]
+
+    def __init__(self, from_json_data_text: Optional[str] = None,
+                 from_json_filename: Optional[PathOrStr] = None,
+                 stderr_file: TextIO = sys.stderr) -> None:
+        """Create the input map default, then run the shared constructor."""
+        self.to_internal = {}
+        _FormatConfig.__init__(self, from_json_data_text=from_json_data_text,
+                               from_json_filename=from_json_filename,
+                               stderr_file=stderr_file)
+
+
+class OutputFormatConfig(_FormatConfig):
+    """TableIO output endpoint with an internal-to-external column map."""
+
+    _FILE_ACCESS = FileAccess.CREATE
+    _MAP_NAME = 'to_external'
+    to_external: dict[str, str]
+
+    def __init__(self, from_json_data_text: Optional[str] = None,
+                 from_json_filename: Optional[PathOrStr] = None,
+                 stderr_file: TextIO = sys.stderr) -> None:
+        """Create the output map default, then run the shared constructor."""
+        self.to_external = {}
+        _FormatConfig.__init__(self, from_json_data_text=from_json_data_text,
+                               from_json_filename=from_json_filename,
+                               stderr_file=stderr_file)
+
+
+def make_input_config(tableio: TioJsonConfig, to_internal: dict[str, str],
+                      stderr_file: TextIO = sys.stderr) -> InputFormatConfig:
+    """Return an input config from a TableIO config and a column map."""
+    config = InputFormatConfig(stderr_file=stderr_file)
+    config.tableio = tableio
+    config.to_internal = dict(to_internal)
+    return config
+
+
+def make_output_config(tableio: TioJsonConfig, to_external: dict[str, str],
+                       stderr_file: TextIO = sys.stderr) -> OutputFormatConfig:
+    """Return an output config from a TableIO config and a column map."""
+    config = OutputFormatConfig(stderr_file=stderr_file)
+    config.tableio = tableio
+    config.to_external = dict(to_external)
+    return config
+
+
+def _format_from_suffix(data_file: PathOrStr) -> str:
+    """Return the TableIO format name implied by a data file extension."""
+    suffix = Path(data_file).suffix.lower()
+    format_name = EXTENSION_FORMATS.get(suffix)
+    if format_name is None:
+        known = ', '.join(sorted(EXTENSION_FORMATS))
+        raise ValueError(f'Cannot infer a TableIO format from {suffix!r}. '
+                         f'Known extensions: {known}.')
+    return format_name
+
+
+def _default_input(data_file: PathOrStr,
+                   stderr_file: TextIO) -> InputFormatConfig:
+    """Return an input config with the format inferred from the file name."""
+    config = InputFormatConfig(stderr_file=stderr_file)
+    config.tableio = _tio_default(FileAccess.READ,
+                                  _format_from_suffix(data_file), stderr_file)
+    return config
+
+
+def _default_output(data_file: PathOrStr,
+                    stderr_file: TextIO) -> OutputFormatConfig:
+    """Return an output config with the format inferred from the file name."""
+    config = OutputFormatConfig(stderr_file=stderr_file)
+    config.tableio = _tio_default(FileAccess.CREATE,
+                                  _format_from_suffix(data_file), stderr_file)
+    return config
+
+
+def _preset(value: str, presets: Optional[Mapping[str, _FormatConfig]]
+            ) -> _FormatConfig:
+    """Return the named preset, or raise when it cannot be found."""
+    if presets is None or value not in presets:
+        available = ', '.join(sorted(presets)) if presets else 'none'
+        raise ValueError(f'Unknown configuration preset {value!r}. '
+                         f'Available presets: {available}.')
+    return presets[value]
+
+
+def resolve_input_config(
+        value: Optional[str], *, data_file: PathOrStr,
+        presets: Optional[dict[str, InputFormatConfig]] = None,
+        stderr_file: TextIO = sys.stderr) -> InputFormatConfig:
+    """Resolve a command-line input config value to an input config.
+
+    An empty ``value`` infers the format from ``data_file``. A value of
+    only letters and digits is a preset name looked up in ``presets``.
+    Any other value is the path of a stand-alone input config file.
+
+    Args:
+        value: The ``--input-config`` value, or None for inference.
+        data_file: The input data file, used for format inference.
+        presets: Named input presets, typically from the teams config.
+        stderr_file: Stream used for user-facing diagnostics.
+
+    Returns:
+        The resolved input configuration.
+
+    Raises:
+        ValueError: The format cannot be inferred or the preset is unknown.
+    """
+    if value is None:
+        return _default_input(data_file, stderr_file)
+    if PRESET_NAME_RE.match(value):
+        preset = _preset(value, presets)
+        assert isinstance(preset, InputFormatConfig)
+        return preset
+    return InputFormatConfig(from_json_filename=value, stderr_file=stderr_file)
+
+
+def resolve_output_config(
+        value: Optional[str], *, data_file: PathOrStr,
+        presets: Optional[dict[str, OutputFormatConfig]] = None,
+        stderr_file: TextIO = sys.stderr) -> OutputFormatConfig:
+    """Resolve a command-line output config value to an output config.
+
+    An empty ``value`` infers the format from ``data_file``. A value of
+    only letters and digits is a preset name looked up in ``presets``.
+    Any other value is the path of a stand-alone output config file.
+
+    Args:
+        value: The ``--output-config`` value, or None for inference.
+        data_file: The output data file, used for format inference.
+        presets: Named output presets, typically from the teams config.
+        stderr_file: Stream used for user-facing diagnostics.
+
+    Returns:
+        The resolved output configuration.
+
+    Raises:
+        ValueError: The format cannot be inferred or the preset is unknown.
+    """
+    if value is None:
+        return _default_output(data_file, stderr_file)
+    if PRESET_NAME_RE.match(value):
+        preset = _preset(value, presets)
+        assert isinstance(preset, OutputFormatConfig)
+        return preset
+    return OutputFormatConfig(from_json_filename=value,
+                              stderr_file=stderr_file)

backlogops/key_list_io.py

@@ -0,0 +1,227 @@
+#! /usr/bin/env python3
+"""Read and write a key list as its own file.
+
+A key list is an ordered list of backlog item keys stored on its own,
+separate from the backlog. The file format is chosen from the file name
+extension: a ``.txt`` or ``.dat`` file is plain UTF-8 text, and any
+extension that TableIO supports (such as ``.csv``, ``.ods`` or ``.xlsx``)
+is a one column table.
+
+Two options apply to both shapes and describe whether the file carries a
+column name. ``skip_column_names`` tells the reader that the first
+row/line is a column name to skip, and ``add_column_name`` tells the
+writer to write such a column name (``Keys``).
+
+For a text file without a column name every whitespace separated word is
+a key, in the order the words appear; with a column name the heading line
+is skipped and every following non empty line holds exactly one key.
+
+For a table file without a column name every row is data (read with list
+reading); with a column name the first row names the column (read with
+dict reading). A single column table usually has no column name, but it
+may have one. Either way the table must have exactly one column.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from pathlib import Path
+from typing import TextIO
+from collections.abc import Sequence
+import sys
+from config_as_json import PathOrStr
+from tableio import DictData, FileAccess, ListData, Value, \
+    access_capabilities, tio_config_create
+from backlogops.backlog_helpers import report_bad_value
+from backlogops.io_config import resolve_input_config
+from backlogops.table_create import create_output_table
+
+TEXT_EXTENSIONS = {'.txt', '.dat'}
+"""File name extensions read and written as plain UTF-8 text."""
+
+KEY_COLUMN_NAME = 'Keys'
+"""Column name of the single column of a key list table."""
+
+
+def _is_text(file_name: PathOrStr) -> bool:
+    """Return whether a key list file is plain text rather than a table."""
+    return Path(file_name).suffix.lower() in TEXT_EXTENSIONS
+
+
+def _column_keys(text: str, stderr_file: TextIO) -> list[str]:
+    """Return one key per line of a column text file, after the heading.
+
+    The first line is the column heading and is skipped. Every following
+    non empty line must hold exactly one word, which is the key.
+    """
+    keys: list[str] = []
+    for line in text.splitlines()[1:]:
+        words = line.split()
+        if not words:
+            continue
+        if len(words) > 1:
+            report_bad_value('key', line.strip(),
+                             'a column key list allows only one key per line',
+                             stderr_file, 'Key list')
+        keys.append(words[0])
+    return keys
+
+
+def _read_text(file_name: PathOrStr, skip_column_names: bool,
+               stderr_file: TextIO) -> list[str]:
+    """Return the keys of a plain text key list file."""
+    text = Path(file_name).read_text(encoding='utf-8')
+    if skip_column_names:
+        return _column_keys(text, stderr_file)
+    return text.split()
+
+
+def _check_one_column(width: int, stderr_file: TextIO) -> None:
+    """Report a table that does not have exactly one column."""
+    if width > 1:
+        report_bad_value('columns', width,
+                         'a key list table must have exactly one column',
+                         stderr_file, 'Key list')
+
+
+def _cell_keys(values: list[Value]) -> list[str]:
+    """Return the non empty cell values of one table column as strings."""
+    return [str(value) for value in values
+            if value is not None and str(value) != '']
+
+
+def _keys_from_dict(rows: DictData[Value], stderr_file: TextIO) -> list[str]:
+    """Return the keys of a one column table read with dict reading."""
+    if not rows:
+        return []
+    _check_one_column(len(rows[0]), stderr_file)
+    column = next(iter(rows[0]))
+    return _cell_keys([row[column] for row in rows])
+
+
+def _keys_from_list(rows: ListData[Value], stderr_file: TextIO) -> list[str]:
+    """Return the keys of a one column table read with list reading."""
+    if not rows:
+        return []
+    _check_one_column(len(rows[0]), stderr_file)
+    return _cell_keys([row[0] for row in rows])
+
+
+def _read_table(file_name: PathOrStr, skip_column_names: bool,
+                stderr_file: TextIO) -> list[str]:
+    """Return the keys of a key list stored as a one column table."""
+    config = resolve_input_config(None, data_file=file_name,
+                                  stderr_file=stderr_file).tableio
+    capabilities = access_capabilities(FileAccess.READ, error_file=stderr_file)
+    with tio_config_create(config=config, file_name=file_name,
+                           file_access=FileAccess.READ,
+                           capabilities=capabilities) as tableio:
+        if skip_column_names:
+            keys = _keys_from_dict(tableio.read_table_dictdata().data,
+                                   stderr_file)
+        else:
+            keys = _keys_from_list(tableio.read_table_listdata().data,
+                                   stderr_file)
+    return keys
+
+
+def read_key_list(file_name: PathOrStr, *, skip_column_names: bool = False,
+                  stderr_file: TextIO = sys.stderr) -> list[str]:
+    """Read a key list from a file.
+
+    The file type is chosen from the file name extension. A ``.txt`` or
+    ``.dat`` file is read as UTF-8 text; any other extension is read as a
+    TableIO table whose single column holds the keys.
+
+    ``skip_column_names`` tells whether the file starts with a column
+    name. For a text file, when it is False the file is a free word list
+    and every whitespace separated word is a key, in the order the words
+    appear; when it is True the first line is a column heading and is
+    skipped, and every following non empty line must hold exactly one
+    word, which is a key. For a table file, when it is False every row is
+    data (list reading); when it is True the first row names the column
+    and is skipped (dict reading). A table must have exactly one column.
+
+    Args:
+        file_name: The file to read the key list from.
+        skip_column_names: Whether the file starts with a column name to
+            skip.
+        stderr_file: The stream to report errors to.
+
+    Returns:
+        The keys in the order they appear in the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        IsADirectoryError: If the file is a directory.
+        PermissionError: If the file is not readable.
+        UnicodeDecodeError: If a text file is not valid UTF-8.
+        ValueError: If a column text line holds more than one word, if a
+            table has more than one column, or if the extension is not a
+            supported table format.
+    """
+    if _is_text(file_name):
+        return _read_text(file_name, skip_column_names, stderr_file)
+    return _read_table(file_name, skip_column_names, stderr_file)
+
+
+def _ensure_absent(file_name: PathOrStr, stderr_file: TextIO) -> None:
+    """Raise ``FileExistsError`` when the target file already exists."""
+    if Path(file_name).exists():
+        message = f'File already exists: {file_name}'
+        print(message, file=stderr_file)
+        raise FileExistsError(message)
+
+
+def _write_text(key_list: Sequence[str], file_name: PathOrStr,
+                add_column_name: bool) -> None:
+    """Write a key list as plain text, one key per line."""
+    lines = [KEY_COLUMN_NAME, *key_list] if add_column_name else list(key_list)
+    text = ''.join(f'{line}\n' for line in lines)
+    Path(file_name).write_text(text, encoding='utf-8')
+
+
+def _write_table(key_list: Sequence[str], file_name: PathOrStr,
+                 add_column_name: bool, stderr_file: TextIO) -> None:
+    """Write a key list as a one column TableIO table."""
+    with create_output_table(file_name, stderr_file) as tableio:
+        if add_column_name:
+            dict_rows: DictData[Value] = [{KEY_COLUMN_NAME: key}
+                                          for key in key_list]
+            tableio.write_table_dictdata(dict_rows,
+                                         column_order=[KEY_COLUMN_NAME])
+        else:
+            tableio.write_table_listdata([[key] for key in key_list])
+
+
+def write_key_list(key_list: Sequence[str], file_name: PathOrStr, *,
+                   add_column_name: bool = False,
+                   stderr_file: TextIO = sys.stderr) -> None:
+    """Write a key list to a file.
+
+    The file type is chosen from the file name extension. A ``.txt`` or
+    ``.dat`` file is written as UTF-8 text with one key per line; any
+    other extension is written as a TableIO table with a single column.
+
+    ``add_column_name`` decides whether the column name ``Keys`` is
+    written before the keys: as a heading line for a text file, and as a
+    header row for a table file. When it is False a text file holds only
+    the keys and a table file holds only data rows (list writing).
+
+    Args:
+        key_list: The keys to write, in order.
+        file_name: The file to create.
+        add_column_name: Whether to write the column name ``Keys`` first.
+        stderr_file: The stream to report errors to.
+
+    Raises:
+        FileExistsError: If the file already exists.
+        IsADirectoryError: If the file is a directory.
+        PermissionError: If the file is not writable.
+        ValueError: If the extension is not a supported table format.
+    """
+    _ensure_absent(file_name, stderr_file)
+    if _is_text(file_name):
+        _write_text(key_list, file_name, add_column_name)
+    else:
+        _write_table(key_list, file_name, add_column_name, stderr_file)

backlogops/levels.py

@@ -0,0 +1,165 @@
+#! /usr/local/bin/python3
+"""Levels of a backlog item."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass, field
+import sys
+from typing import NoReturn, TextIO
+from backlogops.backlog_helpers import check_key_syntax, report_bad_value
+from backlogops.backlog_helpers import report_wrong_type
+
+
+@dataclass
+class Level:
+    """A level of a backlog item.
+
+    Fields:
+        level: The level of the backlog item. Required. Must be an integer.
+               Usually a positive integer, but can be negative for special
+               cases. A higher level means a bigger backlog item.
+               A lower level means a smaller, more detailed backlog item.
+        name: The name of the level. Required. Must be a string.
+              Must not be empty, must not contain whitespace and must
+              not contain any of the characters , . ; : ( ) [ ] { }.
+              Must be unique within the Levels.
+        aliases: The aliases of the level. Optional. Must be a list of strings.
+                 For instance if level 1 is called "Story", it may have the
+                 aliases "Task" and "Bug".
+                 The aliases are used if a backlog item is converted from a
+                 tool that have different names for the same level.
+                 Each alias must not be empty, must not contain whitespace and
+                 must not contain any of the characters , . ; : ( ) [ ] { }.
+                 Must be unique within the Levels and must not be the same
+                 as any name used in the Levels.
+    """
+
+    level: int
+    name: str
+    aliases: list[str] = field(default_factory=list)
+
+    def _check_level_type(self, stderr_file: TextIO) -> None:
+        """Check that the level number is an integer (not a bool)."""
+        if not isinstance(self.level, int) or isinstance(self.level, bool):
+            report_wrong_type('level', self.level, int, stderr_file, 'Level')
+
+    def _check_labels(self, stderr_file: TextIO) -> None:
+        """Check the name and each alias for valid label syntax."""
+        check_key_syntax('name', self.name, stderr_file, 'Level')
+        if not isinstance(self.aliases, list):
+            report_wrong_type('aliases', self.aliases, list, stderr_file,
+                              'Level')
+        for index, alias in enumerate(self.aliases):
+            check_key_syntax(f'aliases[{index}]', alias, stderr_file, 'Level')
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the level.
+
+        The documented constraints are checked on all member variables.
+        The name and aliases follow the same character rules as a backlog
+        item key. Uniqueness across levels is checked by
+        :func:`check_levels_consistency`, not here.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If a field value violates a constraint.
+        """
+        self._check_level_type(stderr_file)
+        self._check_labels(stderr_file)
+
+
+type Levels = dict[int, Level]
+"""A dictionary of levels by level number."""
+
+DEFAULT_LEVELS: Levels = {
+    0: Level(level=0, name='Sub-Task', aliases=[]),
+    1: Level(level=1, name='Story', aliases=['Task', 'Bug']),
+    2: Level(level=2, name='Epic', aliases=[]),
+    3: Level(level=3, name='Initiative', aliases=[]),
+}
+"""The default levels for backlog items."""
+
+
+def report_duplicate_label(label: str, existing: str,
+                           stderr_file: TextIO = sys.stderr) -> NoReturn:
+    """Report a duplicate level name or alias and raise ``KeyError``.
+
+    Args:
+        label: The label that duplicates an earlier one.
+        existing: The earlier label it collides with.
+        stderr_file: The file to report the error to.
+
+    Raises:
+        KeyError: Always, after reporting the message.
+    """
+    message = (f'Level name or alias {label!r} duplicates {existing!r} '
+               f'(case-insensitive)')
+    print(message, file=stderr_file)
+    raise KeyError(message)
+
+
+def check_levels_consistency(levels: Levels,
+                             stderr_file: TextIO = sys.stderr) -> None:
+    """Check the consistency of the levels.
+
+    The documented constraints are checked on all levels. Each dict key
+    must match the ``level`` field of its value. Names and aliases are
+    checked for uniqueness across all levels using case-insensitive
+    comparison, so that a name and an alias may not differ only in case.
+
+    Args:
+        levels: The levels to check.
+        stderr_file: The file to report errors to.
+
+    Raises:
+        TypeError: If a field has the wrong type.
+        ValueError: If a field value violates a constraint, or a dict key
+            does not match its level number.
+        KeyError: If a name or alias is not unique (case-insensitive).
+    """
+    seen_labels: dict[str, str] = {}
+    for number, level in levels.items():
+        level.check_consistency(stderr_file)
+        if level.level != number:
+            report_bad_value('level', level.level,
+                             f'does not match dict key {number}', stderr_file,
+                             'Level')
+        for label in [level.name, *level.aliases]:
+            lowered = label.lower()
+            if lowered in seen_labels:
+                report_duplicate_label(label, seen_labels[lowered],
+                                       stderr_file)
+            seen_labels[lowered] = label
+
+
+def level_number_from_name(name: str, levels: Levels,
+                           stderr_file: TextIO = sys.stderr) -> int:
+    """Return the level number whose name or alias matches ``name``.
+
+    Matching is case-insensitive but otherwise exact (no prefix or
+    fuzzy matching). The level name and all of its aliases are
+    considered. The levels are assumed to be consistent, as checked by
+    :func:`check_levels_consistency`.
+
+    Args:
+        name: The level name or alias to look up.
+        levels: The levels to search.
+        stderr_file: The file to report errors to.
+
+    Returns:
+        The level number of the matching level.
+
+    Raises:
+        ValueError: If no level name or alias matches ``name``.
+    """
+    lowered = name.lower()
+    for level in levels.values():
+        if any(label.lower() == lowered
+               for label in [level.name, *level.aliases]):
+            return level.level
+    report_bad_value('level', name, 'unknown level name or alias', stderr_file,
+                     'Level')