backlogops 0.1__py3-none-any.whl

backlogops/table_rows.py

@@ -0,0 +1,125 @@
+#! /usr/local/bin/python3
+"""Convert backlog items and releases to and from table rows.
+
+A backlog item or a release is represented in a table as one row keyed by
+its internal field name. These conversions are shared by the file IO and
+by the formatting of table data, so they live in their own module to keep
+the dependency order between those parts simple.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from collections.abc import Mapping
+from dataclasses import fields
+from datetime import date
+from typing import Optional, TextIO
+from tableio import Value
+from backlogops.backlog import BacklogItem, DEPENDENCY_FIELDS, Status, \
+    get_backlog_item
+from backlogops.levels import Levels
+from backlogops.releases import Release, get_release
+
+BACKLOG_FIELDS = [item_field.name for item_field in fields(BacklogItem)
+                  if item_field.name != 'extra_fields']
+"""Internal backlog column names, in a stable write order."""
+
+RELEASE_FIELDS = [item_field.name for item_field in fields(Release)]
+"""Internal release column names, in a stable write order."""
+
+
+def _is_empty(value: object) -> bool:
+    """Return whether a cell value should be treated as absent."""
+    return value is None or value == ''
+
+
+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 _cell_from_field(name: str, value: object) -> Value:
+    """Return the cell value for one named backlog item field."""
+    if name == 'status':
+        assert isinstance(value, Status)
+        return value.name
+    if name in DEPENDENCY_FIELDS:
+        assert isinstance(value, list)
+        return ' '.join(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    assert value is None or isinstance(value, (str, int, float, bool))
+    return value
+
+
+def _extra_cell(value: object) -> Value:
+    """Return an extra field value as a cell value."""
+    if isinstance(value, date):
+        return value.isoformat()
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    return str(value)
+
+
+def item_to_row(item: BacklogItem) -> dict[str, Value]:
+    """Return one backlog item as a row keyed by internal field name."""
+    row: dict[str, Value] = {}
+    for name in BACKLOG_FIELDS:
+        row[name] = _cell_from_field(name, getattr(item, name))
+    for key, value in item.extra_fields.items():
+        row[key] = _extra_cell(value)
+    return row
+
+
+def release_to_row(release: Release) -> dict[str, Value]:
+    """Return one release as a row keyed by internal field name."""
+    return {'name': release.name,
+            'planned_date': _date_cell(release.planned_date),
+            'estimated_date': _date_cell(release.estimated_date)}
+
+
+def _split_deps(value: object) -> list[str]:
+    """Return the dependency keys parsed from one space separated cell."""
+    if value is None:
+        return []
+    text = str(value).strip()
+    return text.split() if text else []
+
+
+def _maybe_int(value: object) -> object:
+    """Return an integer when a numeric cell should be one, else the value."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            return value
+    return value
+
+
+def _present_cells(row: Mapping[str, object]) -> dict[str, object]:
+    """Return the row without cells that are absent (None or empty)."""
+    return {key: value for key, value in row.items() if not _is_empty(value)}
+
+
+def row_to_item(row: Mapping[str, object], levels: Optional[Levels] = None,
+                stderr_file: TextIO = sys.stderr) -> BacklogItem:
+    """Return a backlog item from a row keyed by internal field name."""
+    prepared = _present_cells(row)
+    for name in DEPENDENCY_FIELDS:
+        if name in prepared:
+            prepared[name] = _split_deps(row[name])
+    for name in ('story_points', 'level'):
+        if name in prepared:
+            prepared[name] = _maybe_int(row[name])
+    return get_backlog_item(prepared, levels, stderr_file)
+
+
+def row_to_release(row: Mapping[str, object],
+                   stderr_file: TextIO = sys.stderr) -> Release:
+    """Return a release from a row keyed by internal field name."""
+    return get_release(_present_cells(row), stderr_file, strict=False)

backlogops/team.py

@@ -0,0 +1,190 @@
+#! /usr/local/bin/python3
+"""Define a team, its memberships and their availability over time."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Optional, TextIO
+from backlogops.backlog_helpers import check_field_types, report_bad_value
+from backlogops.date_ranges import check_date_range, check_no_overlap
+
+
+@dataclass
+class FteException:
+    """Define a full-time equivalent exception.
+
+    The full-time equivalent exception is used to override the default
+    full-time equivalent for a specific period. This can be used to mark
+    a learning period for a new team member, or a period of time when the
+    team member works part-time outside of this team.
+
+    Fields:
+        start_date: The first day of the exception (inclusive).
+        end_date: The last day of the exception (inclusive). Must not be
+                  before start_date.
+        fte: The full-time equivalent during the exception. Must not be
+             negative.
+    """
+
+    start_date: date
+    end_date: date
+    fte: float
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the full-time equivalent exception.
+
+        Field types are verified, the date range must be non-empty, and
+        the full-time equivalent must not be negative.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If the range is empty or the fte is negative.
+        """
+        check_field_types(self, stderr_file, 'FTE exception')
+        check_date_range('fte exception', self.start_date, self.end_date,
+                         stderr_file, 'FTE exception')
+        if self.fte < 0.0:
+            report_bad_value('fte', self.fte, 'must not be negative',
+                             stderr_file, 'FTE exception')
+
+
+@dataclass
+class Membership:
+    """Define how a person belongs to a team over a period of time.
+
+    A membership links a person, by name, to the team that holds it. The
+    person name is looked up in the central person registry of
+    :class:`~backlogops.available_teams.AvailableTeams`. A person may have
+    several memberships, in the same or in different teams, which models a
+    person moving between teams or splitting time across teams over time.
+
+    Fields:
+        person_name: The name of the person, used as a key into the
+                     person registry. Compared case-insensitively. Must
+                     not be empty.
+        fte: The full-time equivalent the person gives to this team
+             outside of any fte_exceptions. 1.0 means full time. Must not
+             be negative.
+        start_date: The first day of the membership (inclusive), or None
+                    for a membership that is open at the start.
+        end_date: The last day of the membership (inclusive), or None for
+                  a membership that is open at the end.
+        fte_exceptions: Periods with a full-time equivalent that differs
+                        from fte, for example a learning period or a period
+                        of part-time work in another team. The periods must
+                        not overlap.
+    """
+
+    person_name: str
+    fte: float = 1.0
+    start_date: Optional[date] = None
+    end_date: Optional[date] = None
+    fte_exceptions: list[FteException] = field(default_factory=list)
+
+    def _check_values(self, stderr_file: TextIO) -> None:
+        """Check the person name, full-time equivalent and date range."""
+        if self.person_name == '':
+            report_bad_value('person_name', self.person_name,
+                             'must not be empty', stderr_file, 'Membership')
+        if self.fte < 0.0:
+            report_bad_value('fte', self.fte, 'must not be negative',
+                             stderr_file, 'Membership')
+        if self.start_date is not None and self.end_date is not None:
+            check_date_range('membership', self.start_date, self.end_date,
+                             stderr_file, 'Membership')
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the membership.
+
+        Field types are verified, the person name must not be empty, the
+        full-time equivalent must not be negative, the membership date
+        range (when both ends are given) must be non-empty, every
+        fte_exception must be consistent, and the fte_exceptions must not
+        overlap.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If a value is invalid or two fte_exceptions
+                overlap.
+        """
+        check_field_types(self, stderr_file, 'Membership')
+        self._check_values(stderr_file)
+        for exception in self.fte_exceptions:
+            exception.check_consistency(stderr_file)
+        check_no_overlap('fte_exceptions',
+                         [(e.start_date, e.end_date)
+                          for e in self.fte_exceptions], stderr_file,
+                         'Membership')
+
+
+@dataclass
+class Team:
+    """Define a team.
+
+    Fields:
+        name: The name of the team. Compared case-insensitively. Must be
+              unique across all teams and must not be empty.
+        velocity: The velocity of the team. Must not be negative.
+        sum_fte_at_velocity: The sum of the full-time equivalents of the
+                             team members when velocity was measured. Used
+                             to rescale the velocity when the team capacity
+                             changes. Must be positive.
+        sprint_length: The length of the sprint in working days. Must be
+                       positive.
+        aliases: The aliases for the team. A backlog might refer to the
+                 team using the team name or an alias. Compared
+                 case-insensitively. Each alias must be unique and not
+                 empty.
+        members: The list of memberships of the team.
+    """
+
+    name: str
+    velocity: float
+    sum_fte_at_velocity: float
+    sprint_length: int
+    aliases: list[str] = field(default_factory=list)
+    members: list[Membership] = field(default_factory=list)
+
+    def _check_values(self, stderr_file: TextIO) -> None:
+        """Check the name, velocity, capacity and sprint length."""
+        if self.name == '':
+            report_bad_value('name', self.name, 'must not be empty',
+                             stderr_file, 'Team')
+        if self.velocity < 0.0:
+            report_bad_value('velocity', self.velocity, 'must not be negative',
+                             stderr_file, 'Team')
+        if self.sum_fte_at_velocity <= 0.0:
+            report_bad_value('sum_fte_at_velocity', self.sum_fte_at_velocity,
+                             'must be positive', stderr_file, 'Team')
+        if self.sprint_length <= 0:
+            report_bad_value('sprint_length', self.sprint_length,
+                             'must be positive', stderr_file, 'Team')
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the team.
+
+        Field types are verified, the numeric fields must be within their
+        documented ranges, and every membership must be consistent.
+        Uniqueness of the name and aliases across teams is checked by
+        :meth:`AvailableTeams.check_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.
+        """
+        check_field_types(self, stderr_file, 'Team')
+        self._check_values(stderr_file)
+        for member in self.members:
+            member.check_consistency(stderr_file)

backlogops/work_hours.py

@@ -0,0 +1,155 @@
+#! /usr/local/bin/python3
+"""Work hours schedule and exceptions."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from dataclasses import dataclass, field
+from enum import IntEnum, auto
+from datetime import date
+from typing import TextIO
+from backlogops.backlog_helpers import check_field_types, report_bad_value
+from backlogops.date_ranges import check_date_range, check_no_overlap
+
+
+class WeekDay(IntEnum):
+    """Week day."""
+
+    MONDAY = auto()
+    TUESDAY = auto()
+    WEDNESDAY = auto()
+    THURSDAY = auto()
+    FRIDAY = auto()
+    SATURDAY = auto()
+    SUNDAY = auto()
+
+
+type ScheduleWorkHours = dict[WeekDay, float]
+"""Work hours schedule by week day."""
+
+DEFAULT_WORK_WEEK: ScheduleWorkHours = {
+    WeekDay.MONDAY: 8.0,
+    WeekDay.TUESDAY: 8.0,
+    WeekDay.WEDNESDAY: 8.0,
+    WeekDay.THURSDAY: 8.0,
+    WeekDay.FRIDAY: 8.0,
+    WeekDay.SATURDAY: 0.0,
+    WeekDay.SUNDAY: 0.0,
+}
+"""The default work week."""
+
+
+@dataclass
+class ExceptionWorkHours:
+    """Exception work hours for a specific period.
+
+    The exception work hours are used to override the default work hours
+    for a specific period. This can be used to mark holidays or other days
+    with different work hours. It can also be used to mark a period with
+    ordered over-time work.
+    When used for an individual employee, the company exceptions are seen
+    as part of the schedule.
+
+    Fields:
+        start_date: The first day of the exception (inclusive).
+        end_date: The last day of the exception (inclusive). Must not be
+                  before start_date.
+        hours_per_day: The work hours per day during the exception. Must
+                       not be negative.
+        new_work_days: If True, the exception adds new work days compared
+                       to the schedule. That is the hours per day also
+                       applies to days with no work hours in the schedule.
+                       If False, the exception does not add new work days.
+                       That is the hours per day only applies to days with
+                       work hours in the schedule.
+                       If an individual employee has an exception to work
+                       during days the company is closed, the new_work_days
+                       flag must be True.
+
+    Exceptions in one list (a company or a person) must not overlap, so
+    that the work hours of any day are defined by at most one exception.
+    """
+
+    start_date: date
+    end_date: date
+    hours_per_day: float
+    new_work_days: bool = False
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the exception work hours.
+
+        Field types are verified, the date range must be non-empty, and
+        the work hours per day must not be negative.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If the range is empty or the hours are negative.
+        """
+        check_field_types(self, stderr_file, 'Work hours exception')
+        check_date_range('exception', self.start_date, self.end_date,
+                         stderr_file, 'Work hours exception')
+        if self.hours_per_day < 0.0:
+            report_bad_value('hours_per_day', self.hours_per_day,
+                             'must not be negative', stderr_file,
+                             'Work hours exception')
+
+
+@dataclass
+class CompanyWorkHours:
+    """Company work hours.
+
+    The company work hours are used to define the work hours for a company.
+
+    Fields:
+        work_hours: The work hours schedule for the company. Every week
+                    day must have non-negative work hours.
+        exceptions: The list of exception work hours for the company.
+                    This should list national holidays and other days with
+                    different work hours. This should also include any days
+                    the company is closed for any reason (such as company
+                    wide vacations). The exceptions must not overlap.
+    """
+
+    work_hours: ScheduleWorkHours = field(
+        default_factory=lambda: dict(DEFAULT_WORK_WEEK))
+    exceptions: list[ExceptionWorkHours] = field(default_factory=list)
+
+    def _check_schedule(self, stderr_file: TextIO) -> None:
+        """Check every week day has non-negative work hours defined."""
+        for week_day in WeekDay:
+            if week_day not in self.work_hours:
+                report_bad_value('work_hours', week_day,
+                                 'missing work hours for week day',
+                                 stderr_file, 'Company work hours')
+            elif self.work_hours[week_day] < 0.0:
+                report_bad_value('work_hours', self.work_hours[week_day],
+                                 'must not be negative', stderr_file,
+                                 'Company work hours')
+
+    def check_consistency(self, stderr_file: TextIO = sys.stderr) -> None:
+        """Check the consistency of the company work hours.
+
+        Field types are verified, the schedule must define non-negative
+        work hours for every week day, every exception must be consistent,
+        and the exceptions must not overlap.
+
+        Args:
+            stderr_file: The file to report errors to.
+
+        Raises:
+            TypeError: If a field has the wrong type.
+            ValueError: If the schedule or an exception is invalid, or if
+                two exceptions overlap.
+        """
+        check_field_types(self, stderr_file, 'Company work hours')
+        self._check_schedule(stderr_file)
+        for exception in self.exceptions:
+            exception.check_consistency(stderr_file)
+        check_no_overlap('exceptions',
+                         [(e.start_date, e.end_date)
+                          for e in self.exceptions], stderr_file,
+                         'Company work hours')