backlogops 0.1__py3-none-any.whl

backlogops/release_backlog_updates.py

@@ -0,0 +1,239 @@
+#! /usr/local/bin/python3
+"""Interaction between releases and backlogs."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass, replace
+from datetime import date, timedelta
+from typing import NamedTuple, Optional
+from backlogops.backlog import Backlog, BacklogItem
+from backlogops.releases import Releases
+
+
+@dataclass
+class ReleaseChange:
+    """A change of the release a backlog item is delivered in.
+
+    Both releases are optional, because a backlog item may carry no
+    release before the change and may end up with no release after it.
+    """
+
+    backlog_key: str
+    old_release: Optional[str]
+    new_release: Optional[str]
+
+
+type ReleaseChanges = list[ReleaseChange]
+"""Changes of releases for a backlog items."""
+
+
+class BacklogReleaseChange(NamedTuple):
+    """A change of a backlog with changes to releases."""
+
+    backlog: Backlog
+    release_changes: ReleaseChanges
+
+
+@dataclass
+class ReleaseDateChange:
+    """A change of a release date.
+
+    Both dates are optional, because a release may have had no date
+    before the change and may have no date after it.
+    """
+
+    release: str
+    old_date: Optional[date]
+    new_date: Optional[date]
+
+
+type ReleaseDateChanges = list[ReleaseDateChange]
+"""Changes of release dates for a release."""
+
+
+class ReleasesAndDateChanges(NamedTuple):
+    """Releases and their date changes."""
+
+    releases: Releases
+    date_changes: ReleaseDateChanges
+
+
+def _check_buffer(buffer: timedelta) -> None:
+    """Raise ``ValueError`` when the buffer is negative.
+
+    A buffer is a slack added to a date, so a negative buffer would mean
+    negative slack and is rejected.
+    """
+    if buffer < timedelta(0):
+        raise ValueError('buffer must not be negative')
+
+
+def _latest_per_release(backlog: Backlog) -> dict[str, date]:
+    """Return the latest estimated ready date assigned to each release.
+
+    A backlog item adds to the result only when it names a release and
+    carries an estimated ready date. A release named by no such item is
+    absent from the result.
+    """
+    latest: dict[str, date] = {}
+    for item in backlog:
+        ready = item.estimated_ready_date
+        if item.release is None or ready is None:
+            continue
+        current = latest.get(item.release)
+        if current is None or ready > current:
+            latest[item.release] = ready
+    return latest
+
+
+def estimate_release_dates(releases: Releases, backlog: Backlog) \
+        -> ReleasesAndDateChanges:
+    """Find estimated release dates from backlog item estimates.
+
+    For each release, the estimated date is set to the latest estimated
+    ready date of the backlog items assigned to the release. A release
+    with no assigned item that carries an estimated ready date gets no
+    estimated date (``None``). A change is recorded only for a release
+    whose estimated date actually changes.
+
+    Args:
+        releases: The releases to find the estimated dates for.
+                  The argument is not modified.
+        backlog: The already estimated backlog to find the estimated dates
+                 from. The argument is not modified.
+
+    Returns:
+        The releases with updated estimated dates and a record of how
+        the estimated release dates were changed.
+    """
+    latest = _latest_per_release(backlog)
+    new_releases: Releases = []
+    changes: ReleaseDateChanges = []
+    for release in releases:
+        new_date = latest.get(release.name)
+        if new_date != release.estimated_date:
+            changes.append(ReleaseDateChange(release.name,
+                                             release.estimated_date, new_date))
+        new_releases.append(replace(release, estimated_date=new_date))
+    return ReleasesAndDateChanges(new_releases, changes)
+
+
+def release_plan_on_estimate(releases: Releases, buffer: timedelta) \
+        -> ReleasesAndDateChanges:
+    """Set the planned release dates from the estimated release dates.
+
+    For each release the planned date is set to the estimated date plus
+    the buffer. A release with no estimated date gets no planned date
+    (``None``), as there is nothing to base the plan on. A change is
+    recorded only for a release whose planned date actually changes.
+
+    Args:
+        releases: The releases to set the planned release dates for.
+                  The argument is not modified.
+        buffer: The buffer or slack to add to the estimated release dates
+                to get the planned release dates. Must not be negative.
+
+    Returns:
+        The releases with updated planned release dates and a record of
+        how the planned release dates were changed.
+
+    Raises:
+        ValueError: If the buffer is negative.
+    """
+    _check_buffer(buffer)
+    new_releases: Releases = []
+    changes: ReleaseDateChanges = []
+    for release in releases:
+        estimated = release.estimated_date
+        new_date = None if estimated is None else estimated + buffer
+        if new_date != release.planned_date:
+            changes.append(ReleaseDateChange(release.name,
+                                             release.planned_date, new_date))
+        new_releases.append(replace(release, planned_date=new_date))
+    return ReleasesAndDateChanges(new_releases, changes)
+
+
+def _dated_releases(releases: Releases) -> list[tuple[date, int, str]]:
+    """Return the planned releases as ``(date, order, name)``, sorted.
+
+    Only releases that carry a planned date take part, because a release
+    with no planned date offers no deadline to fit an item into. The
+    order index keeps the sort stable for releases that share a date.
+    """
+    dated = [(release.planned_date, index, release.name)
+             for index, release in enumerate(releases)
+             if release.planned_date is not None]
+    return sorted(dated)
+
+
+def _fitting_release(dated: list[tuple[date, int, str]],
+                     fit_date: date) -> Optional[str]:
+    """Return the earliest planned release that the fit date reaches.
+
+    The earliest release whose planned date is on or after ``fit_date``
+    is returned, or ``None`` when no planned release is late enough.
+    """
+    for planned, _order, name in dated:
+        if planned >= fit_date:
+            return name
+    return None
+
+
+def _new_release_for(item: BacklogItem, dated: list[tuple[date, int, str]],
+                     buffer: timedelta) -> Optional[str]:
+    """Return the release the item belongs in for its current estimate.
+
+    An item with no estimated ready date keeps its current release, as
+    there is no basis to place it. Otherwise the item is placed in the
+    earliest planned release that its estimated ready date plus the buffer
+    reaches, regardless of its current release, so an item with no release
+    yet is assigned to the release it is ready in time for. The item is
+    placed in no release when no planned release is late enough.
+    """
+    if item.estimated_ready_date is None:
+        return item.release
+    return _fitting_release(dated, item.estimated_ready_date + buffer)
+
+
+def adjust_release_content(releases: Releases, backlog: Backlog,
+                           buffer: timedelta) -> BacklogReleaseChange:
+    """Adjust the release content to fit the planned release dates.
+
+    Each backlog item that carries an estimated ready date is placed in
+    the earliest release whose planned date is on or after the item's
+    estimated ready date plus the buffer. This pushes an item to a later
+    release when it no longer fits its current one, pulls it to an earlier
+    release when it now fits sooner, and assigns an item that has no
+    release yet to the release it is ready in time for. An item that no
+    planned release is late enough for is left out of every release (its
+    release becomes ``None``). An item with no estimated ready date keeps
+    its current release, as there is no basis to place it. A change is
+    recorded only for an item whose release actually changes.
+
+    Args:
+        releases: The releases to fit the items into. The argument is not
+                  modified.
+        backlog: The already estimated backlog to adjust. The argument is
+                 not modified.
+        buffer: The buffer or slack added to the estimated ready dates to
+                gain confidence that an item fits a release. Must not be
+                negative.
+
+    Returns:
+        The backlog with updated release content and a record of how the
+        release content was changed.
+
+    Raises:
+        ValueError: If the buffer is negative.
+    """
+    _check_buffer(buffer)
+    dated = _dated_releases(releases)
+    new_backlog: Backlog = []
+    changes: ReleaseChanges = []
+    for item in backlog:
+        new_release = _new_release_for(item, dated, buffer)
+        if new_release != item.release:
+            changes.append(ReleaseChange(item.key, item.release, new_release))
+        new_backlog.append(replace(item, release=new_release))
+    return BacklogReleaseChange(new_backlog, changes)

backlogops/release_change_io.py

@@ -0,0 +1,134 @@
+#! /usr/local/bin/python3
+"""Print and write release-change records as text or table files.
+
+A release-change record is the small log produced by the release update
+operations: which backlog item moved between releases
+(:class:`ReleaseChange`) and how a release date moved
+(:class:`ReleaseDateChange`). These functions render such a log as text
+for the console and write it to a one-table file with TableIO, choosing
+the file format from the file name extension.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Optional, Sequence, TextIO
+from config_as_json import PathOrStr
+from tableio import Value
+from backlogops.table_create import create_output_table
+from backlogops.release_backlog_updates import ReleaseChanges, \
+    ReleaseDateChanges
+
+CONTENT_HEADER = ['backlog_key', 'old_release', 'new_release']
+"""Column names of a release content change table."""
+
+DATE_HEADER = ['release', 'old_date', 'new_date']
+"""Column names of a release date change table."""
+
+
+def _text(value: Optional[str]) -> str:
+    """Return a release name for display, or ``(none)`` when absent."""
+    return value if value is not None else '(none)'
+
+
+def _date_text(value: Optional[date]) -> str:
+    """Return a date for display, or ``(none)`` when absent."""
+    return value.isoformat() if value is not None else '(none)'
+
+
+def _listing(title: str, empty: str, rows: Sequence[str]) -> str:
+    """Return a titled multi line listing, or the empty message."""
+    if not rows:
+        return empty
+    return '\n'.join([title, *rows])
+
+
+def format_content_changes(changes: ReleaseChanges) -> str:
+    """Return release content changes as text for the console."""
+    rows = [f'  {change.backlog_key}: {_text(change.old_release)} -> '
+            f'{_text(change.new_release)}' for change in changes]
+    return _listing('Release content changes:', 'No release content changes.',
+                    rows)
+
+
+def format_date_changes(changes: ReleaseDateChanges) -> str:
+    """Return release date changes as text for the console."""
+    rows = [f'  {change.release}: {_date_text(change.old_date)} -> '
+            f'{_date_text(change.new_date)}' for change in changes]
+    return _listing('Release date changes:', 'No release date changes.', rows)
+
+
+def _date_cell(value: Optional[date]) -> Value:
+    """Return a date as an ISO string cell, or None when absent."""
+    return value.isoformat() if value is not None else None
+
+
+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_table(header: list[str], rows: list[list[Value]],
+                 file_name: PathOrStr, stderr_file: TextIO) -> None:
+    """Write a header row and the change rows as a one table file.
+
+    The rows are written with list writing, so the header is the first
+    data row. An empty change list still writes the header row, recording
+    that there were no changes.
+    """
+    _ensure_absent(file_name, stderr_file)
+    with create_output_table(file_name, stderr_file) as tableio:
+        tableio.write_table_listdata([header, *rows])
+
+
+def write_content_changes(changes: ReleaseChanges, file_name: PathOrStr,
+                          stderr_file: TextIO = sys.stderr) -> None:
+    """Write release content changes to a one table file.
+
+    The file format is chosen from the file name extension, as for any
+    TableIO table. The single table has the columns ``backlog_key``,
+    ``old_release`` and ``new_release``; an absent release is an empty
+    cell.
+
+    Args:
+        changes: The release content changes to write, in order.
+        file_name: The file to create.
+        stderr_file: The stream to report errors to.
+
+    Raises:
+        FileExistsError: If the file already exists.
+        ValueError: If the extension is not a supported table format.
+    """
+    rows: list[list[Value]] = \
+        [[change.backlog_key, change.old_release, change.new_release]
+         for change in changes]
+    _write_table(CONTENT_HEADER, rows, file_name, stderr_file)
+
+
+def write_date_changes(changes: ReleaseDateChanges, file_name: PathOrStr,
+                       stderr_file: TextIO = sys.stderr) -> None:
+    """Write release date changes to a one table file.
+
+    The file format is chosen from the file name extension, as for any
+    TableIO table. The single table has the columns ``release``,
+    ``old_date`` and ``new_date``; an absent date is an empty cell.
+
+    Args:
+        changes: The release date changes to write, in order.
+        file_name: The file to create.
+        stderr_file: The stream to report errors to.
+
+    Raises:
+        FileExistsError: If the file already exists.
+        ValueError: If the extension is not a supported table format.
+    """
+    rows: list[list[Value]] = \
+        [[change.release, _date_cell(change.old_date),
+          _date_cell(change.new_date)] for change in changes]
+    _write_table(DATE_HEADER, rows, file_name, stderr_file)

backlogops/releases.py

@@ -0,0 +1,170 @@
+#! /usr/local/bin/python3
+"""Releases related to a backlog."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass, fields
+from datetime import date
+from typing import NoReturn, Optional, TextIO
+import sys
+from backlogops.backlog_helpers import build_item_kwargs, check_field_types
+from backlogops.backlog_helpers import check_key_syntax, construct
+from backlogops.backlog_helpers import field_type_hints, report_bad_value
+
+
+@dataclass
+class Release:
+    """A release of some BacklogItems.
+
+    A release groups backlog items that are delivered together. A
+    backlog item refers to its release by name through its ``release``
+    field, so the release name must follow the same syntax rules as a
+    backlog item key.
+
+    Fields:
+        name: The name of the release. Required. Must be unique among
+              the releases. Must not be empty, must not contain
+              whitespace and must not contain any of the characters
+              , . ; : ( ) [ ] { }.
+        planned_date: The planned date of the release. Optional.
+                      The date that is communicated to the customer.
+        estimated_date: The estimated date of the release. Optional.
+                        The date that the content of the release is
+                        estimated to be ready. The estimated date and
+                        the planned date are independent of each other;
+                        no ordering between them is required.
+    """
+
+    name: str
+    planned_date: Optional[date] = None
+    estimated_date: Optional[date] = None
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the internal consistency of the release.
+
+        The field types are verified and the name is checked to be a
+        well formed key (a non-empty string with no whitespace and none
+        of the forbidden separator characters). Uniqueness of the name
+        among several releases is not checked here; that is done by
+        :func:`check_releases`.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If the name violates the key syntax constraint.
+        """
+        check_field_types(self, stderr_file, subject='Release')
+        check_key_syntax('name', self.name, stderr_file, subject='Release')
+
+
+type Releases = list[Release]
+"""A list of releases related to a Backlog."""
+
+
+def report_unknown_keys(unknown: set[str],
+                        stderr_file: TextIO = sys.stderr) -> NoReturn:
+    """Report unknown release input keys and raise ``KeyError``.
+
+    Args:
+        unknown: The input keys that match no field of :class:`Release`.
+        stderr_file: The file to report the error to.
+
+    Raises:
+        KeyError: Always, after reporting the message.
+    """
+    names = ', '.join(sorted(unknown))
+    message = f'Release has unknown field(s): {names}'
+    print(message, file=stderr_file)
+    raise KeyError(message)
+
+
+def get_release(data: dict[str, object], stderr_file: TextIO = sys.stderr,
+                strict: bool = True) -> Release:
+    """Get a release from a dictionary.
+
+    The dictionary is expected to hold the mandatory ``name`` field and
+    may hold the optional ``planned_date`` and ``estimated_date``
+    fields. Date fields given as ISO 8601 strings (such as
+    ``'2026-06-12'``) are converted to ``date`` objects.
+
+    Args:
+        data: The dictionary to get the release from.
+        stderr_file: The file to report errors to.
+        strict: When True (the default), any input key that matches no
+                field of :class:`Release` is an error. When False such
+                keys are silently ignored.
+
+    Returns:
+        The release.
+
+    Raises:
+        KeyError: If the mandatory ``name`` field is missing, or if
+            ``strict`` is True and the data has a key that is not a
+            release field.
+        TypeError: If a field has a type that cannot be converted.
+    """
+    field_types = field_type_hints(Release)
+    if strict:
+        unknown = set(data) - set(field_types)
+        if unknown:
+            report_unknown_keys(unknown, stderr_file)
+    item_kwargs = build_item_kwargs(fields(Release), field_types, data,
+                                    stderr_file)
+    return construct(Release, item_kwargs)
+
+
+def get_releases(datalist: list[dict[str, object]],
+                 stderr_file: TextIO = sys.stderr,
+                 strict: bool = True) -> Releases:
+    """Get a list of releases from a list of dictionaries.
+
+    Each dictionary is converted to a release as documented for
+    :func:`get_release`, with the same ``strict`` handling of keys that
+    do not match a release field.
+
+    Args:
+        datalist: The list of dictionaries to get the releases from.
+        stderr_file: The file to report errors to.
+        strict: Passed to :func:`get_release` for each dictionary. When
+                True (the default), unknown keys are an error; when
+                False they are ignored.
+
+    Returns:
+        The list of releases.
+
+    Raises:
+        KeyError: If a mandatory ``name`` field is missing, or if
+            ``strict`` is True and a dictionary has a key that is not a
+            release field.
+        TypeError: If a field has a type that cannot be converted.
+    """
+    return [get_release(data, stderr_file, strict) for data in datalist]
+
+
+def check_releases(releases: Releases,
+                   stderr_file: TextIO = sys.stderr) -> None:
+    """Check the internal consistency of a list of releases.
+
+    Every release is checked for internal consistency as documented for
+    :meth:`Release.check_consistency`, and the release names are checked
+    to be unique.
+
+    Args:
+        releases: The list of releases to check.
+        stderr_file: The file to report errors to.
+
+    Raises:
+        TypeError: If a field has the wrong type.
+        ValueError: If a name violates the key syntax constraint, or if
+            two releases share the same name.
+    """
+    seen: set[str] = set()
+    for release in releases:
+        release.check_consistency(stderr_file)
+        if release.name in seen:
+            report_bad_value('name', release.name, 'duplicate release name',
+                             stderr_file, subject='Release')
+        seen.add(release.name)

backlogops/table_create.py

@@ -0,0 +1,47 @@
+#! /usr/local/bin/python3
+"""Open a TableIO file for creating a single table output.
+
+Several writers create a file that holds one table whose format follows
+the file name extension (a key list, a list of changes, and so on). They
+all resolve the output configuration from the file name, request CREATE
+capabilities, and open a TableIO context. This helper holds that shared
+setup so each writer only describes the rows it writes.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TextIO
+from config_as_json import PathOrStr
+from tableio import FileAccess, TableIO, access_capabilities, \
+    tio_config_create
+from backlogops.io_config import resolve_output_config
+
+
+@contextmanager
+def create_output_table(file_name: PathOrStr,
+                        stderr_file: TextIO = sys.stderr) -> Iterator[TableIO]:
+    """Yield a TableIO opened to create a one table file.
+
+    The output format is resolved from the file name extension and the
+    file is opened with CREATE access. The yielded TableIO is used to
+    write the table inside the ``with`` block.
+
+    Args:
+        file_name: The file to create.
+        stderr_file: The stream to report errors to.
+
+    Yields:
+        The TableIO ready to write one table to the file.
+    """
+    config = resolve_output_config(None, data_file=file_name,
+                                   stderr_file=stderr_file).tableio
+    capabilities = access_capabilities(FileAccess.CREATE,
+                                       error_file=stderr_file)
+    with tio_config_create(config=config, file_name=file_name,
+                           file_access=FileAccess.CREATE,
+                           capabilities=capabilities) as tableio:
+        yield tableio