backlogops 0.1__py3-none-any.whl

backlogops/move_keys_first.py

@@ -0,0 +1,166 @@
+#! /usr/bin/env python3
+"""Reorder a backlog from a key list and extract keys by level."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from typing import Optional, TextIO
+from collections.abc import Sequence
+import sys
+from backlogops.backlog import Backlog, BacklogItem
+from backlogops.backlog_helpers import report_bad_value
+from backlogops.levels import DEFAULT_LEVELS, Levels, level_number_from_name
+
+
+def _by_key(backlog: Backlog) -> dict[str, BacklogItem]:
+    """Return a mapping from each key to its backlog item."""
+    return {item.key: item for item in backlog}
+
+
+def _validate_keys(keys: Sequence[str], by_key: dict[str, BacklogItem],
+                   stderr_file: TextIO) -> None:
+    """Check that the keys are unique and present in the backlog."""
+    seen: set[str] = set()
+    for key in keys:
+        if key in seen:
+            report_bad_value('keys', key, 'duplicate key', stderr_file)
+        seen.add(key)
+        if key not in by_key:
+            message = f'Key not found in backlog: {key!r}'
+            print(message, file=stderr_file)
+            raise KeyError(message)
+
+
+def _children_map(backlog: Backlog) -> dict[str, list[BacklogItem]]:
+    """Return the children of each key, in original backlog order."""
+    children: dict[str, list[BacklogItem]] = {}
+    for item in backlog:
+        if item.parent_key is not None:
+            children.setdefault(item.parent_key, []).append(item)
+    return children
+
+
+def _front_order(backlog: Backlog, keys: Sequence[str]) -> list[str]:
+    """Return the leading keys: each named key after its descendant subtree.
+
+    Each named key is preceded by its descendants in post order, so that a
+    child comes right before its own parent and a parent right before the
+    grandparent. Siblings keep their original backlog order. A named
+    descendant is not pulled in, as it is placed by its own key. A
+    descendant is pulled in 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.
+    """
+    named = set(keys)
+    index = {item.key: position for position, item in enumerate(backlog)}
+    children = _children_map(backlog)
+    visited: set[str] = set()
+    front: list[str] = []
+
+    def emit_descendants(node_key: str, root_index: int) -> None:
+        visited.add(node_key)
+        for child in children.get(node_key, []):
+            if child.key in named or child.key in visited:
+                continue
+            emit_descendants(child.key, root_index)
+            if index[child.key] > root_index:
+                front.append(child.key)
+
+    for key in keys:
+        emit_descendants(key, index[key])
+        front.append(key)
+    return front
+
+
+def move_keys_first(backlog: Backlog, keys: Sequence[str],
+                    stderr_file: TextIO = sys.stderr) -> Backlog:
+    """Move the items named by ``keys`` to the front of the backlog.
+
+    A new backlog is returned; the argument is not modified. 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, all the
+    way up to the named item. For example, if ``E`` is a parent of ``S1``
+    and ``S2`` and ``S2`` is a parent of ``T``, moving ``E`` first yields
+    ``S1, T, S2, E``. Siblings keep their original backlog order. A named
+    descendant is not pulled in this way; it is placed by its own key, 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. All items that are neither named nor pulled to the front keep
+    their original order after the front block.
+
+    Args:
+        backlog: The backlog to reorder. The argument is not modified.
+        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 stream to report errors to.
+
+    Returns:
+        A new backlog with the named items moved to the front.
+
+    Raises:
+        KeyError: If a key is not found in the backlog.
+        ValueError: If a key is not unique.
+    """
+    by_key = _by_key(backlog)
+    _validate_keys(keys, by_key, stderr_file)
+    front = _front_order(backlog, keys)
+    front_set = set(front)
+    moved = [by_key[key] for key in front]
+    rest = [item for item in backlog if item.key not in front_set]
+    return moved + rest
+
+
+def _level_sequence(only_levels: int | str | Sequence[int | str]
+                    ) -> Sequence[int | str]:
+    """Return the requested levels as a sequence of single level values."""
+    if isinstance(only_levels, (int, str)):
+        return [only_levels]
+    if isinstance(only_levels, Sequence):
+        return only_levels
+    raise TypeError('only_levels must be an int, a str, or a sequence of '
+                    'ints or strs')
+
+
+def _level_number(value: int | str, levels: Levels) -> int:
+    """Return the level number for one int or str level value."""
+    if isinstance(value, bool):
+        raise TypeError('a level must be an int or a str, not a bool')
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        return level_number_from_name(value, levels)
+    raise TypeError('a level must be an int or a str')
+
+
+def get_keys_in_order(backlog: Backlog,
+                      only_levels: int | str | Sequence[int | str],
+                      levels: Optional[Levels] = None) -> list[str]:
+    """Return the keys of the backlog items at the given levels, in order.
+
+    The keys are returned in the order they appear in the backlog, keeping
+    only the items whose level is among ``only_levels``. A level may be
+    given as a level number or as a level name or alias. A name or alias
+    is resolved through ``levels`` (the default levels when ``levels`` is
+    None). A level number is used as is and need not be one of ``levels``.
+
+    Args:
+        backlog: The backlog to take the keys from.
+        only_levels: The levels to keep, as a single int or str or as a
+            sequence of ints and strs.
+        levels: The levels used to resolve a level name or alias, or None
+            to use :data:`DEFAULT_LEVELS`.
+
+    Returns:
+        The keys of the matching items, in backlog order.
+
+    Raises:
+        TypeError: If ``only_levels`` is not an int, a str, or a sequence
+            of ints and strs.
+        ValueError: If a level name or alias matches no level.
+    """
+    chosen = DEFAULT_LEVELS if levels is None else levels
+    numbers = {_level_number(value, chosen)
+               for value in _level_sequence(only_levels)}
+    return [item.key for item in backlog if item.level in numbers]

backlogops/no_text_io.py

@@ -0,0 +1,100 @@
+#! /usr/local/bin/python3
+"""NoTextIO can be used as a TextIO object that does nothing."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from typing import override
+from collections.abc import Iterable
+from types import TracebackType
+import io
+
+
+class NoTextIO(io.StringIO):
+    """NoTextIO can be used as a TextIO object that does nothing.
+
+    When a function expects a TextIO object for output, you can pass in
+    a NoTextIO object and no output will be produced.
+    The differrence compared to using StringIO to suppress output is that
+    the NoTextIO does not store any data, so no matter how much is
+    written to it, you do not risk running out of memory.
+    """
+
+    @override
+    def write(self, s: str) -> int:
+        """Write a string to the NoTextIO object.
+
+        This method does nothing and returns 0.
+        """
+        _ = s
+        return 0
+
+    @override
+    def writelines(self,  # type: ignore[override]
+                   lines: Iterable[str]) -> None:
+        """Write a list of strings to the NoTextIO object.
+
+        This method does nothing and returns None.
+        """
+        _ = lines
+
+    @override
+    def flush(self) -> None:
+        """Flush the NoTextIO object.
+
+        This method does nothing and returns None.
+        """
+
+    @override
+    def close(self) -> None:
+        """Close the NoTextIO object.
+
+        This method does nothing and returns None.
+        """
+
+    @override
+    def seek(self, offset: int, whence: int = io.SEEK_SET, /) -> int:
+        """Seek to a position in the NoTextIO object.
+
+        This method does nothing and returns 0.
+        """
+        _ = offset
+        _ = whence
+        return 0
+
+    @override
+    def tell(self) -> int:
+        """Get the current position in the NoTextIO object.
+
+        This method does nothing and returns 0.
+        """
+        return 0
+
+    @override
+    def truncate(self, size: int | None = None, /) -> int:
+        """Truncate the NoTextIO object.
+
+        This method does nothing and returns 0.
+        """
+        _ = size
+        return 0
+
+    @override
+    def __enter__(self) -> 'NoTextIO':
+        """Enter the NoTextIO object.
+
+        This method does nothing and returns the NoTextIO object.
+        """
+        return self
+
+    @override
+    def __exit__(self, exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> None:
+        """Exit the NoTextIO object.
+
+        This method does nothing.
+        """
+        _ = exc_type
+        _ = exc_value
+        _ = traceback

backlogops/order_by_dependencies.py

@@ -0,0 +1,381 @@
+#! /usr/local/bin/python3
+"""Order a backlog by dependencies."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+import heapq
+from enum import Enum, auto
+from typing import Optional, TextIO
+from collections.abc import Sequence
+from backlogops.backlog import Backlog, BacklogItem, DEPENDENCY_FIELDS
+from backlogops.backlog import build_dependency_graph, event_start
+
+
+class DependencyMode(Enum):
+    """Mode to determine backlog position of items with dependencies.
+
+    EARLY: All items that take part in a dependency are placed as early
+           as possible, before the items that take part in no
+           dependency. This packs the dependency chains at the front and
+           leaves a buffer of independent items after the last dependent
+           item, to reduce the risk of delays in a chain of dependencies.
+    EVEN:  Items that take part in a dependency are spread out so that
+           the dependency chains are as evenly distributed as possible
+           over the complete backlog. The independent items fill the gaps
+           between them. This may create a small time buffer between each
+           item in a dependency chain.
+    KEEP:  Items that take part in no dependency keep their original
+           relative order, and only the items that take part in a
+           dependency are moved, and only as far as a dependency forces
+           them to move. The idea is that someone has already put work
+           into the order of the backlog, and we should not change it
+           without a good reason. This is the default behavior.
+    """
+
+    EARLY = auto()
+    EVEN = auto()
+    KEEP = auto()
+
+
+def _normalize_space_around(space_around: Optional[str | Sequence[str]],
+                            stderr_file: TextIO) -> list[str]:
+    """Return the space_around argument as a list of key strings.
+
+    A single key is wrapped in a one element list and a sequence of keys
+    is copied into a new list. ``None`` becomes an empty list.
+
+    Raises:
+        TypeError: If the argument is neither None, a string, nor a
+            sequence of strings.
+    """
+    if space_around is None:
+        return []
+    if isinstance(space_around, str):
+        return [space_around]
+    if isinstance(space_around, Sequence) and \
+            all(isinstance(key, str) for key in space_around):
+        return list(space_around)
+    message = 'space_around must be a string or a sequence of strings'
+    print(message, file=stderr_file)
+    raise TypeError(message)
+
+
+def _space_around_limit(item_count: int) -> int:
+    """Return the largest allowed number of space_around items.
+
+    The limit is five items for a backlog of at least fifty items, and
+    ten percent of the backlog (but at least one) for a smaller backlog.
+    """
+    if item_count >= 50:
+        return 5
+    return max(1, item_count // 10)
+
+
+def _check_space_around(keys: Sequence[str], backlog: Backlog,
+                        stderr_file: TextIO) -> None:
+    """Check that the space_around keys exist and are not too many.
+
+    Raises:
+        KeyError: If a key is not the key of a backlog item.
+        RuntimeError: If there are more keys than the allowed limit.
+    """
+    present = {item.key for item in backlog}
+    for key in keys:
+        if key not in present:
+            message = f'space_around key not found in backlog: {key!r}'
+            print(message, file=stderr_file)
+            raise KeyError(message)
+    limit = _space_around_limit(len(backlog))
+    if len(keys) > limit:
+        message = (f'space_around has {len(keys)} keys, more than the '
+                   f'allowed {limit}')
+        print(message, file=stderr_file)
+        raise RuntimeError(message)
+
+
+def _item_dependencies(item: BacklogItem) -> list[str]:
+    """Return the keys that one item depends on (explicit and parent)."""
+    keys: list[str] = []
+    for dep_field in DEPENDENCY_FIELDS:
+        keys.extend(getattr(item, dep_field))
+    if item.parent_key is not None:
+        keys.append(item.parent_key)
+    return keys
+
+
+def _has_dependencies(backlog: Backlog) -> bool:
+    """Tell whether any backlog item takes part in a dependency."""
+    return any(_item_dependencies(item) for item in backlog)
+
+
+def _linked_items(backlog: Backlog) -> set[str]:
+    """Return the keys of items that take part in any dependency.
+
+    An item is linked when it depends on another item or is depended on
+    by another item, counting both the explicit dependency lists and the
+    parent relations.
+    """
+    linked: set[str] = set()
+    for item in backlog:
+        dependencies = _item_dependencies(item)
+        if dependencies:
+            linked.add(item.key)
+            linked.update(dependencies)
+    return linked
+
+
+def _seed_events(backlog: Backlog) -> list[str]:
+    """Return all start and finish events in original backlog order."""
+    events: list[str] = []
+    for item in backlog:
+        events.append(event_start(item.key))
+        events.append(f'{item.key}:finish')
+    return events
+
+
+def _forward_events(graph: dict[str, list[str]],
+                    seed: Sequence[str]) -> list[str]:
+    """Order events with each prerequisite emitted just before its user.
+
+    A depth first search visits the events in original order and emits
+    every event after all the events it depends on. This pulls a
+    prerequisite to a position just before the dependent item, while the
+    dependent item keeps its original position as much as possible.
+    """
+    visited: set[str] = set()
+    order: list[str] = []
+
+    def visit(event: str) -> None:
+        if event in visited:
+            return
+        visited.add(event)
+        for dependency in graph.get(event, []):
+            visit(dependency)
+        order.append(event)
+    for event in seed:
+        visit(event)
+    return order
+
+
+def _back_events(graph: dict[str, list[str]],
+                 seed: Sequence[str]) -> list[str]:
+    """Order events delaying each dependent event as long as possible.
+
+    A stable topological sort always emits the ready event with the
+    smallest original position. This keeps the independent events early
+    and pushes a dependent event as late as its prerequisites allow.
+    """
+    rank = {event: index for index, event in enumerate(seed)}
+    pending = {event: set(graph.get(event, [])) for event in seed}
+    dependents: dict[str, list[str]] = {}
+    for event, dependencies in pending.items():
+        for dependency in dependencies:
+            dependents.setdefault(dependency, []).append(event)
+    ready = [(rank[event], event)
+             for event, deps in pending.items() if not deps]
+    heapq.heapify(ready)
+    order: list[str] = []
+    while ready:
+        _, event = heapq.heappop(ready)
+        order.append(event)
+        for dependent in dependents.get(event, []):
+            pending[dependent].discard(event)
+            if not pending[dependent]:
+                heapq.heappush(ready, (rank[dependent], dependent))
+    return order
+
+
+def _topo_item_order(backlog: Backlog, later: bool) -> list[str]:
+    """Return the item keys in dependency order, projected from events.
+
+    The events of the backlog are topologically sorted, honoring the
+    direction given by ``later``, and the item order is read off from the
+    order of the start events. The backlog position of an item is the
+    order in which a team starts to work on it.
+    """
+    graph = build_dependency_graph(backlog)
+    seed = _seed_events(backlog)
+    events = _back_events(graph, seed) if later \
+        else _forward_events(graph, seed)
+    start_to_key = {event_start(item.key): item.key for item in backlog}
+    return [start_to_key[event] for event in events if event in start_to_key]
+
+
+def _merge_even(linked: Sequence[str], unlinked: Sequence[str]) -> list[str]:
+    """Merge linked and unlinked keys, spreading linked keys evenly.
+
+    The linked keys keep their given order and the unlinked keys keep
+    their given order. The linked keys are placed at evenly spaced
+    positions over the whole result, and the unlinked keys fill the gaps.
+    """
+    total = len(linked) + len(unlinked)
+    if not linked:
+        return list(unlinked)
+    targets = [(index + 0.5) * total / len(linked)
+               for index in range(len(linked))]
+    result: list[str] = []
+    next_linked = 0
+    next_unlinked = 0
+    for position in range(total):
+        due = next_linked < len(linked) and \
+            targets[next_linked] <= position + 0.5
+        if (due or next_unlinked >= len(unlinked)) and \
+                next_linked < len(linked):
+            result.append(linked[next_linked])
+            next_linked += 1
+        else:
+            result.append(unlinked[next_unlinked])
+            next_unlinked += 1
+    return result
+
+
+def _arrange_by_mode(topo: Sequence[str], backlog: Backlog,
+                     mode: DependencyMode) -> list[str]:
+    """Place the dependency-ordered keys according to the chosen mode."""
+    if mode is DependencyMode.KEEP:
+        return list(topo)
+    linked = _linked_items(backlog)
+    linked_order = [key for key in topo if key in linked]
+    unlinked_order = [item.key for item in backlog
+                      if item.key not in linked]
+    if mode is DependencyMode.EARLY:
+        return linked_order + unlinked_order
+    return _merge_even(linked_order, unlinked_order)
+
+
+def _start_reachable(graph: dict[str, list[str]], item: BacklogItem,
+                     backlog: Backlog) -> set[str]:
+    """Return the keys of items that must start before the given item.
+
+    The search follows the dependency edges from the start event of the
+    item. Reaching either the start or the finish event of another item
+    means that other item must start before this item.
+    """
+    start_to_key = {event_start(other.key): other.key for other in backlog}
+    finish_to_key = {f'{other.key}:finish': other.key for other in backlog}
+    seen: set[str] = set()
+    stack = [event_start(item.key)]
+    while stack:
+        event = stack.pop()
+        for dependency in graph.get(event, []):
+            if dependency not in seen:
+                seen.add(dependency)
+                stack.append(dependency)
+    keys: set[str] = set()
+    for event in seen:
+        key = start_to_key.get(event) or finish_to_key.get(event)
+        if key is not None and key != item.key:
+            keys.add(key)
+    return keys
+
+
+def _precedence(backlog: Backlog) -> tuple[dict[str, set[str]],
+                                           dict[str, set[str]]]:
+    """Return the must-start-before and must-start-after item relations."""
+    graph = build_dependency_graph(backlog)
+    before = {item.key: _start_reachable(graph, item, backlog)
+              for item in backlog}
+    after: dict[str, set[str]] = {item.key: set() for item in backlog}
+    for key, prerequisites in before.items():
+        for prerequisite in prerequisites:
+            after[prerequisite].add(key)
+    return before, after
+
+
+def _space_one(order: Sequence[str], key: str, prereqs: set[str],
+               dependents: set[str]) -> list[str]:
+    """Reposition one key to maximize the space to its dependencies.
+
+    The prerequisites of the key are moved as early as possible and the
+    items that depend on the key are moved as late as possible, keeping
+    their relative order. The key is then placed among the remaining
+    items: at the front when it has no prerequisite, at the back when it
+    has no dependent, and in the middle otherwise. This places as many
+    other items as possible between the key and its dependencies.
+    """
+    front = [item for item in order if item in prereqs]
+    back = [item for item in order if item in dependents]
+    middle = [item for item in order if item != key
+              and item not in prereqs and item not in dependents]
+    if not prereqs:
+        insert = 0
+    elif not dependents:
+        insert = len(middle)
+    else:
+        insert = len(middle) // 2
+    return front + middle[:insert] + [key] + middle[insert:] + back
+
+
+def _apply_space_around(order: list[str], keys: Sequence[str],
+                        backlog: Backlog) -> list[str]:
+    """Reposition each space_around key to the middle of its slack."""
+    before, after = _precedence(backlog)
+    for key in keys:
+        order = _space_one(order, key, before[key], after[key])
+    return order
+
+
+def order_by_dependencies(backlog: Backlog, *, later: bool = False,
+                          mode: DependencyMode = DependencyMode.KEEP,
+                          space_around: Optional[str | Sequence[str]] = None,
+                          stderr_file: TextIO = sys.stderr) -> Backlog:
+    """Order a backlog by dependencies.
+
+    A new backlog is returned; the argument is not modified. If no item
+    takes part in any dependency the argument backlog is returned
+    unchanged (the same object). The backlog is ordered so that a team
+    can start the items in backlog order without starting an item before
+    the items it depends on. The dependencies are taken from the start
+    and finish event graph of the backlog, which combines the explicit
+    dependency lists with the implicit parent relations. The backlog
+    position of an item is the order in which the team starts it, so only
+    a dependency that constrains the start of an item moves that item;
+    a finish-to-finish dependency, which only constrains completion, does
+    not move an item by itself.
+
+    Args:
+        backlog: The backlog to order. The argument is not modified.
+        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, and the dependent
+            item keeps its position. If True the dependent item is pushed
+            to a position just after its prerequisites, and the
+            prerequisite items keep their position.
+        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.
+            For each named item the prerequisites are pulled as early as
+            possible and the items that depend on it are pushed as late as
+            possible, and the named item is centered among the remaining
+            items. This is useful when there is a big risk of delays in a
+            chain of dependencies. 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.
+
+    Returns:
+        A new backlog with the items ordered by dependencies, or the
+        argument backlog unchanged when no item takes part in a
+        dependency.
+
+    Raises:
+        TypeError: If space_around is neither None, a string, nor a
+            sequence of strings.
+        KeyError: If a space_around key is not the key of a backlog item.
+        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.
+    """
+    space_keys = _normalize_space_around(space_around, stderr_file)
+    _check_space_around(space_keys, backlog, stderr_file)
+    if not _has_dependencies(backlog):
+        return backlog
+    topo = _topo_item_order(backlog, later)
+    order = _arrange_by_mode(topo, backlog, mode)
+    order = _apply_space_around(order, space_keys, backlog)
+    by_key = {item.key: item for item in backlog}
+    return [by_key[key] for key in order]

backlogops/person.py

@@ -0,0 +1,25 @@
+#! /usr/local/bin/python3
+"""Define a person including any exceptions in work hours."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from dataclasses import dataclass, field
+from backlogops.work_hours import ExceptionWorkHours
+
+
+@dataclass
+class Person:
+    """Define a person including any exceptions in work hours."""
+
+    name: str
+    """The name of the person."""
+
+    exceptions: list[ExceptionWorkHours] = field(default_factory=list)
+    """Any exceptions in work hours for the person.
+
+    These exceptions are used to mark personal vacation days,
+    and other planned days off. They can also mark any period
+    of time the person has other work hours, for instance periods
+    of part-time work or ordered over-time work.
+    """