backlogops 0.1__py3-none-any.whl

backlogops/backlog_releases.py

@@ -0,0 +1,299 @@
+#! /usr/local/bin/python3
+"""Backlog and and its related releases."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+from typing import Optional, TextIO, Sequence
+import sys
+from backlogops.backlog import Backlog, check_backlog_consistency
+from backlogops.backlog_helpers import report_unknown_reference
+from backlogops.releases import Release, Releases, check_releases
+from backlogops.move_keys_first import move_keys_first
+from backlogops.order_by_dependencies import order_by_dependencies, \
+    DependencyMode
+from backlogops.estimate_ready_date import estimate_ready_date, \
+    set_plan_from_estimate
+from backlogops.available_teams import AvailableTeams
+from backlogops.release_backlog_updates import estimate_release_dates, \
+    release_plan_on_estimate, adjust_release_content, ReleaseChanges, \
+    ReleaseDateChanges
+
+
+@dataclass
+class BacklogReleases:
+    """A backlog and its related releases.
+
+    The releases list describes the releases that the backlog items are
+    delivered in. A backlog item refers to its release by name through
+    its ``release`` field. The releases list may hold releases that no
+    backlog item refers to yet, but every release named by a backlog
+    item is expected to be present in the releases list.
+
+    Fields:
+        backlog: The backlog of items.
+        releases: The releases the backlog items are delivered in.
+    """
+
+    backlog: Backlog
+    releases: Releases
+
+    @staticmethod
+    def add_to_releases(backlog: Backlog, releases: Releases) -> Releases:
+        """Add all releases mentioned in the backlog to the releases list.
+
+        For each backlog item that names a release, a release with that
+        name is added to the releases list when no release of that name
+        is present yet. A release added this way has no planned or
+        estimated date, because a backlog item only carries the release
+        name. The order of the existing releases is kept and any new
+        releases are appended in the order they are first met in the
+        backlog.
+
+        Args:
+            backlog: The backlog to take the release names from.
+            releases: The releases to add the missing releases to.
+                      The argument is not modified.
+
+        Returns:
+            The releases list with the added releases. If all releases
+            named by the backlog are already present, the argument
+            object is returned unchanged. If any new releases are added,
+            a new list is returned.
+        """
+        known = {release.name for release in releases}
+        added: Releases = []
+        for item in backlog:
+            if item.release is not None and item.release not in known:
+                known.add(item.release)
+                added.append(Release(name=item.release))
+        return releases + added if added else releases
+
+    @staticmethod
+    def check_in_releases(backlog: Backlog, releases: Releases,
+                          stderr_file: TextIO = sys.stderr) -> None:
+        """Check that all releases in the backlog are in the releases list.
+
+        For each backlog item that names a release, the release is
+        checked to be present by name in the releases list.
+
+        Args:
+            backlog: The backlog to check.
+            releases: The releases to check the backlog against.
+            stderr_file: The file to report errors to.
+
+        Raises:
+            KeyError: If a release named by the backlog is not present in
+                the releases list.
+        """
+        known = {release.name for release in releases}
+        for item in backlog:
+            if item.release is not None and item.release not in known:
+                report_unknown_reference('release', item.key, item.release,
+                                         stderr_file)
+
+    def update_releases(self) -> None:
+        """Update the releases list to include all releases in the backlog.
+
+        For each backlog item that names a release, the release is added
+        to the releases list when it is not already present, as
+        documented for :meth:`add_to_releases`.
+        """
+        self.releases = self.add_to_releases(self.backlog, self.releases)
+
+    def check_release_xref(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check that all releases in the backlog are in the releases list.
+
+        This is the cross reference check documented for
+        :meth:`check_in_releases`, applied to the member backlog and
+        releases.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            KeyError: If a release named by the backlog is not present in
+                the releases list.
+        """
+        self.check_in_releases(self.backlog, self.releases, stderr_file)
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the internal consistency of the backlog and releases.
+
+        The backlog is checked for full consistency as documented for
+        :func:`check_backlog_consistency`, the releases are checked for
+        internal consistency and unique names as documented for
+        :func:`check_releases`, and every release named by the backlog
+        is checked to be present in the releases list.
+
+        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, or if
+                release names are not unique.
+            KeyError: If a key reference is invalid, or if a release
+                named by the backlog is not in the releases list.
+        """
+        check_backlog_consistency(self.backlog, stderr_file)
+        check_releases(self.releases, stderr_file)
+        self.check_in_releases(self.backlog, self.releases, stderr_file)
+
+    def move_keys_first(self, keys: Sequence[str],
+                        stderr_file: TextIO = sys.stderr) -> None:
+        """Move the items named by ``keys`` to the front of the backlog.
+
+        The named items lead the backlog in the order of ``keys``. Each
+        named item is preceded by its descendants in post order: a child
+        comes right before its own parent, and that parent right before
+        the grandparent, up to the named item. Siblings keep their
+        original backlog order. A named descendant is placed by its own
+        key instead, so it may end up after its named parent. A descendant
+        is pulled to the front only when it appears after its named
+        ancestor in the backlog, so that no item is moved to a later
+        position because of an ancestor's key. The remaining items keep
+        their original order after the front block. The behavior is the
+        one documented for :func:`backlogops.move_keys_first`.
+
+        Args:
+            keys: The keys to move to the front, in the wanted order. The
+                keys must be unique and must exist in the backlog.
+            stderr_file: The file to report errors to.
+
+        Raises:
+            KeyError: If a key is not found in the backlog.
+            ValueError: If a key is not unique.
+        """
+        self.backlog = move_keys_first(self.backlog, keys, stderr_file)
+
+    def order_by_dependencies(self, *, later: bool = False,
+                              mode: DependencyMode = DependencyMode.KEEP,
+                              space_around: Optional[str | Sequence[str]]
+                              = None,
+                              stderr_file: TextIO = sys.stderr) -> None:
+        """Order the member backlog by dependencies.
+
+        The member backlog is replaced by a backlog ordered so that a
+        team can start the items in backlog order without starting an
+        item before the items it depends on. The behavior is the one
+        documented for :func:`backlogops.order_by_dependencies`.
+
+        Args:
+            later: How a dependency that is not yet satisfied is resolved.
+                If False (the default) the prerequisite item is pulled to
+                a position just before the dependent item. If True the
+                dependent item is pushed to a position just after its
+                prerequisites.
+            mode: How items that take part in a dependency are placed in
+                relation to items that take part in no dependency, as
+                documented for :class:`DependencyMode`. The default is
+                KEEP.
+            space_around: Key or keys of items that should have as many
+                other items as possible placed between them and the items
+                they depend on, and between them and the items that
+                depend on them. It only works well for one or very few
+                items. None means no item is treated this way.
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If space_around is neither None, a string, nor a
+                sequence of strings.
+            KeyError: If a space_around key is not found in the backlog.
+            RuntimeError: If space_around names more keys than allowed:
+                more than five, or more than ten percent of a backlog of
+                fewer than fifty items.
+        """
+        self.backlog = order_by_dependencies(self.backlog, later=later,
+                                             mode=mode,
+                                             space_around=space_around,
+                                             stderr_file=stderr_file)
+
+    def estimate_ready_date(self, available_teams: AvailableTeams,
+                            start_date: Optional[date] = None,
+                            stderr_file: TextIO = sys.stderr) \
+            -> ReleaseDateChanges:
+        """Estimate the ready date of the member backlog items.
+
+        The member backlog is replaced by a backlog whose items carry the
+        estimated ready date. The teams start working on the start date,
+        which defaults to today when None is given. The behavior is the
+        one documented for :func:`backlogops.estimate_ready_date`.
+
+        Args:
+            available_teams: The available teams used to estimate the
+                         ready date, including absence, velocity and work
+                         hours.
+            start_date: The day the teams start working, or None for today.
+            stderr_file: The file to report warnings to.
+        """
+        self.backlog = estimate_ready_date(self.backlog, available_teams,
+                                           start_date, stderr_file)
+        self.releases, changes = estimate_release_dates(self.releases,
+                                                        self.backlog)
+        return changes
+
+    def set_plan_from_estimate(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Set the planned ready dates from the estimated ready dates.
+
+        The member backlog is replaced by a backlog whose items carry the
+        planned ready date taken from the estimated ready date, as
+        documented for :func:`backlogops.set_plan_from_estimate`.
+
+        Args:
+            stderr_file: The file to report errors to.
+        """
+        self.backlog = set_plan_from_estimate(self.backlog, stderr_file)
+
+    def adjust_release_content(self, buffer: timedelta,
+                               stderr_file: TextIO = sys.stderr) \
+            -> ReleaseChanges:
+        """Adjust the release content to fit the planned release dates.
+
+        The member backlog is replaced by a backlog whose items carry the
+        adjusted release content. The behavior is the one documented for
+        :func:`backlogops.adjust_release_content`.
+
+        Args:
+            buffer: The buffer or slack added to the estimated ready dates
+                    to gain confidence that an item fits a release. Must
+                    not be negative.
+            stderr_file: The file to report errors to.
+
+        Returns:
+            A record of how the release content was changed.
+
+        Raises:
+            ValueError: If the buffer is negative.
+        """
+        _ = stderr_file
+        self.backlog, changes = adjust_release_content(self.releases,
+                                                       self.backlog, buffer)
+        return changes
+
+    def release_plan_on_estimate(self, buffer: timedelta,
+                                 stderr_file: TextIO = sys.stderr) \
+            -> ReleaseDateChanges:
+        """Set the planned release dates from the estimated release dates.
+
+        The member releases is replaced by releases whose items carry the
+        planned release dates taken from the estimated release dates, as
+        documented for :func:`backlogops.release_plan_on_estimate`.
+
+        Args:
+            buffer: The buffer or slack to add to the estimated release dates
+                    to get the planned release dates. Must not be negative.
+            stderr_file: The file to report errors to.
+
+        Returns:
+            A record of how the release dates were changed.
+
+        Raises:
+            ValueError: If the buffer is negative.
+        """
+        _ = stderr_file
+        self.releases, changes = release_plan_on_estimate(self.releases,
+                                                          buffer)
+        return changes

backlogops/backlog_releases_io.py

@@ -0,0 +1,200 @@
+#! /usr/local/bin/python3
+"""Read and write a backlog and its releases as tables with TableIO.
+
+A backlog and its releases form two tables. They are written to one file
+(and read back) using TableIO, which supports several tables in one sheet
+separated by headings. Reading walks the tables in the file and tells a
+backlog table from a releases table by their columns: a table with a
+``key`` column is the backlog, a table with a ``name`` column is the
+releases.
+
+The internal field names of the data model can differ from the column
+names in the file. An :class:`InputFormatConfig` carries a map from
+external column name to internal field name, and an
+:class:`OutputFormatConfig` carries a map from internal field name to
+external column name. The dependency lists of a backlog item are stored
+as one space separated string per dependency kind, and the extra fields
+of a backlog item become extra columns.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from typing import Optional, TextIO, TypeVar
+from config_as_json import PathOrStr
+from tableio import CAP_IGNORABLE, Capabilities, DictData, FileAccess, \
+    TableIO, Value, ValueFmt, access_capabilities, tio_config_create
+from backlogops.backlog import Backlog
+from backlogops.backlog_releases import BacklogReleases
+from backlogops.io_config import InputFormatConfig, OutputFormatConfig
+from backlogops.levels import Levels
+from backlogops.releases import Releases
+from backlogops.format_rules import FormatRules
+from backlogops.apply_format_rules import format_backlog, format_releases
+from backlogops.table_rows import BACKLOG_FIELDS, RELEASE_FIELDS, \
+    row_to_item, row_to_release
+
+BACKLOG_HEADING = 'Backlog'
+"""Heading written before the backlog table."""
+
+RELEASE_HEADING = 'Releases'
+"""Heading written before the releases table."""
+
+_RenameCell = TypeVar('_RenameCell', Value, ValueFmt)
+
+
+def _rename(row: dict[str, _RenameCell],
+            names: dict[str, str]) -> dict[str, _RenameCell]:
+    """Return the row with its keys translated through a name map."""
+    return {names.get(key, key): value for key, value in row.items()}
+
+
+def _is_backlog_table(rows: DictData[Value]) -> bool:
+    """Return whether a table of internal-named rows is the backlog."""
+    return 'key' in rows[0]
+
+
+def _is_release_table(rows: DictData[Value]) -> bool:
+    """Return whether a table of internal-named rows is the releases."""
+    return 'name' in rows[0]
+
+
+def _collect_tables(config: InputFormatConfig, data_file: PathOrStr,
+                    stderr_file: TextIO
+                    ) -> tuple[DictData[Value], DictData[Value]]:
+    """Read every table and split it into backlog and release rows."""
+    capabilities = access_capabilities(FileAccess.READ, error_file=stderr_file)
+    backlog_rows: DictData[Value] = []
+    release_rows: DictData[Value] = []
+    with tio_config_create(config=config.tableio, file_name=data_file,
+                           file_access=FileAccess.READ,
+                           capabilities=capabilities) as tableio:
+        while True:
+            result = tableio.read_table_dictdata()
+            if not result.data:
+                break
+            rows = [_rename(row, config.to_internal) for row in result.data]
+            if _is_backlog_table(rows):
+                backlog_rows.extend(rows)
+            elif _is_release_table(rows):
+                release_rows.extend(rows)
+            else:
+                raise ValueError('A table has neither a key column (backlog) '
+                                 'nor a name column (releases).')
+    return backlog_rows, release_rows
+
+
+def read_backlog_releases(data_file: PathOrStr, config: InputFormatConfig,
+                          levels: Optional[Levels] = None,
+                          stderr_file: TextIO = sys.stderr) -> BacklogReleases:
+    """Read a backlog, releases, or both from one file.
+
+    Each table in the file is read and classified by its columns. The
+    column names are translated to internal field names through the input
+    configuration before classification and conversion. Field values are
+    converted to their internal types; consistency across items is not
+    checked here.
+
+    Args:
+        data_file: The data file to read.
+        config: The input configuration (format and column-name map).
+        levels: The levels used to resolve a string level, or None for
+                the default levels.
+        stderr_file: Stream used for user-facing diagnostics.
+
+    Returns:
+        The backlog and releases found in the file. Either may be empty.
+
+    Raises:
+        KeyError: A mandatory field is missing in a row.
+        TypeError: A field value has a type that cannot be converted.
+        ValueError: A table cannot be classified as backlog or releases.
+    """
+    backlog_rows, release_rows = _collect_tables(config, data_file,
+                                                 stderr_file)
+    backlog: Backlog = [row_to_item(row, levels, stderr_file)
+                        for row in backlog_rows]
+    releases: Releases = [row_to_release(row, stderr_file)
+                          for row in release_rows]
+    return BacklogReleases(backlog=backlog, releases=releases)
+
+
+def _write_capabilities(stderr_file: TextIO) -> Capabilities:
+    """Return CREATE capabilities that prefer borders, format and filter.
+
+    The border, cell formatting, highlight and filter features are
+    requested as ignorable, so a backend that supports them (such as an
+    Excel backend like XlsxWriter or OpenPyXL) is preferred, while
+    formats without them (such as CSV) and backends without them
+    (such as pylightxl for Excel) are still allowed.
+    """
+    base = access_capabilities(FileAccess.CREATE, error_file=stderr_file)
+    return base._replace(filtered_data_range=CAP_IGNORABLE,
+                         can_write_borders=CAP_IGNORABLE,
+                         can_fmt_row=CAP_IGNORABLE,
+                         can_fmt_value=CAP_IGNORABLE,
+                         can_write_highlight=CAP_IGNORABLE)
+
+
+def _backlog_order(backlog: Backlog) -> list[str]:
+    """Return the backlog column order, with extra fields appended."""
+    extra = sorted({name for item in backlog for name in item.extra_fields})
+    return BACKLOG_FIELDS + extra
+
+
+def _write_table(tableio: TableIO,
+                 section: tuple[str, DictData[ValueFmt], list[str]],
+                 names: dict[str, str], rules: FormatRules) -> None:
+    """Write one heading and one formatted, bordered table."""
+    heading, rows, column_order = section
+    tableio.write_heading(heading)
+    external_rows = [_rename(row, names) for row in rows]
+    external_order = [names.get(name, name) for name in column_order]
+    tableio.write_table_dictdata(external_rows, column_order=external_order,
+                                 missing_ok=True,
+                                 first_row_format=rules.first_row_format,
+                                 filtered_data_range=rules.filtered_data_range,
+                                 border_style=rules.border_style)
+
+
+def _ordered_sections(data: BacklogReleases, rules: FormatRules
+                      ) -> list[tuple[str, DictData[ValueFmt], list[str]]]:
+    """Return the non-empty tables to write, in the requested order."""
+    backlog_rows = format_backlog(data.backlog, rules)
+    release_rows = format_releases(data.releases, rules)
+    backlog = (BACKLOG_HEADING, backlog_rows, _backlog_order(data.backlog))
+    releases = (RELEASE_HEADING, release_rows, RELEASE_FIELDS)
+    sections = [backlog, releases] if rules.backlog_first else \
+        [releases, backlog]
+    return [section for section in sections if section[1]]
+
+
+def write_backlog_releases(data: BacklogReleases, data_file: PathOrStr,
+                           config: OutputFormatConfig,
+                           format_rules: Optional[FormatRules] = None,
+                           stderr_file: TextIO = sys.stderr) -> None:
+    """Write a backlog, releases, or both to one file.
+
+    Each non-empty table is written with a heading before it, so several
+    tables can share one file. Internal field names are translated to
+    external column names through the output configuration. The format
+    rules decide the table order, the borders, the filter range and the
+    cell formatting; when omitted the default :class:`FormatRules` apply.
+
+    Args:
+        data: The backlog and releases to write.
+        data_file: The data file to create.
+        config: The output configuration (format and column-name map).
+        format_rules: How to format the written data, or None for the
+                      default format rules.
+        stderr_file: Stream used for user-facing diagnostics.
+    """
+    rules = FormatRules() if format_rules is None else format_rules
+    capabilities = _write_capabilities(stderr_file)
+    sections = _ordered_sections(data, rules)
+    with tio_config_create(config=config.tableio, file_name=data_file,
+                           file_access=FileAccess.CREATE,
+                           capabilities=capabilities) as tableio:
+        for section in sections:
+            _write_table(tableio, section, config.to_external, rules)

backlogops/console_yes_no_bridge.py

@@ -0,0 +1,45 @@
+#! /usr/local/bin/python3
+"""Console wizard bridge that adds yes/no questions.
+
+The workforce wizard asks yes/no questions through a
+:class:`YesNoUiBridge`. This module provides the console implementation of
+that bridge, built on the text-based ``WizardUiBridgeConsole`` of
+``tableio_cfg_json``, so a command-line program can drive the wizard. A yes
+or no answer is read as free text such as ``y`` or ``no``, and an empty
+answer chooses the default.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from typing import Optional
+from tableio_cfg_json import WizardUiBridgeConsole
+from backlogops.available_teams_wizard import YesNoUiBridge
+
+
+class ConsoleYesNoUiBridge(WizardUiBridgeConsole, YesNoUiBridge):
+    """Console wizard bridge that asks yes/no questions as free text."""
+
+    def ask_yes_no(self, question: str, default: bool) -> bool:
+        """Ask a yes/no question, returning ``default`` for an empty answer.
+
+        Args:
+            question: The yes/no question to ask.
+            default: The value to use when the user gives an empty answer.
+
+        Returns:
+            The user's choice as a boolean.
+        """
+        hint = 'Y/n' if default else 'y/N'
+        re_ask: Optional[str] = None
+        while True:
+            answer = self.ask(f'{question} ({hint})', re_ask)
+            text = answer if isinstance(answer, str) else str(answer)
+            if text == '':
+                return default
+            lowered = text.strip().lower()
+            if lowered in ('y', 'yes'):
+                return True
+            if lowered in ('n', 'no'):
+                return False
+            re_ask = "Please answer 'yes' or 'no'."

backlogops/date_ranges.py

@@ -0,0 +1,59 @@
+#! /usr/local/bin/python3
+"""Helpers for validating inclusive date ranges."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from datetime import date
+from typing import TextIO
+from backlogops.backlog_helpers import report_bad_value
+
+
+def check_date_range(field_name: str, start: date, end: date,
+                     stderr_file: TextIO = sys.stderr,
+                     subject: str = 'Backlog item') -> None:
+    """Check that an inclusive date range is not empty.
+
+    The range covers every day from ``start`` to ``end`` inclusive, so
+    ``start`` must not be after ``end``.
+
+    Args:
+        field_name: The name of the field that holds the range.
+        start: The first day of the range.
+        end: The last day of the range.
+        stderr_file: The file to report errors to.
+        subject: What owns the field, used to start error messages.
+
+    Raises:
+        ValueError: If ``start`` is after ``end``.
+    """
+    if start > end:
+        report_bad_value(field_name, (start, end),
+                         'start_date is after end_date', stderr_file, subject)
+
+
+def check_no_overlap(field_name: str, ranges: list[tuple[date, date]],
+                     stderr_file: TextIO = sys.stderr,
+                     subject: str = 'Backlog item') -> None:
+    """Check that inclusive date ranges do not share a day.
+
+    Each range must already be valid (start not after end). The ranges
+    are sorted by start day and each is compared with the next, so an
+    overlap is found in a single pass.
+
+    Args:
+        field_name: The name of the field that holds the ranges.
+        ranges: The inclusive ``(start, end)`` ranges to check.
+        stderr_file: The file to report errors to.
+        subject: What owns the field, used to start error messages.
+
+    Raises:
+        ValueError: If two ranges share a day.
+    """
+    ordered = sorted(ranges)
+    for earlier, later in zip(ordered, ordered[1:]):
+        if later[0] <= earlier[1]:
+            report_bad_value(field_name, later,
+                             'overlaps an earlier date range', stderr_file,
+                             subject)