scriptplan 0.9.0__py3-none-any.whl

scriptplan/core/timesheet.py

@@ -0,0 +1,457 @@
+"""TimeSheets module for tracking work reports.
+
+Contains TimeSheetRecord, TimeSheet, and TimeSheets classes for
+managing time tracking and work reporting.
+"""
+
+from typing import List, Optional, Union, Any
+from scriptplan.utils.message_handler import MessageHandler
+
+
+class TimeSheetRecord(MessageHandler):
+    """Holds work-related bits of a time sheet specific to a single Task.
+
+    For effort-based tasks, stores the remaining effort.
+    For other tasks, stores the expected end date.
+    For all tasks, stores the completed work during the reporting time frame.
+    """
+
+    def __init__(self, time_sheet: 'TimeSheet', task):
+        """Create a new TimeSheetRecord.
+
+        Args:
+            time_sheet: The TimeSheet this record belongs to.
+            task: Task object for existing tasks or ID string for new tasks.
+        """
+        self._task = task
+        self._time_sheet = time_sheet
+        time_sheet.add_record(self)
+
+        self._work: Optional[int] = None  # Measured in time slots
+        self._remaining: Optional[int] = None  # Measured in time slots
+        self._expected_end = None
+        self._name: Optional[str] = None  # For new tasks
+        self._status = None  # JournalEntry reference
+        self._priority: int = 0
+        self.sourceFileInfo = None
+
+    @property
+    def task(self):
+        return self._task
+
+    @property
+    def work(self) -> Optional[int]:
+        return self._work
+
+    @work.setter
+    def work(self, value):
+        """Set work value. Integer is slots, Float is percentage (0.0-1.0)."""
+        if isinstance(value, int):
+            self._work = value
+        else:
+            # Percentage value
+            self._work = self._time_sheet.percentToSlots(value)
+
+    @property
+    def remaining(self) -> Optional[int]:
+        return self._remaining
+
+    @remaining.setter
+    def remaining(self, value):
+        self._remaining = value
+
+    @property
+    def expectedEnd(self):
+        return self._expected_end
+
+    @expectedEnd.setter
+    def expectedEnd(self, value):
+        self._expected_end = value
+
+    @property
+    def status(self):
+        return self._status
+
+    @status.setter
+    def status(self, value):
+        self._status = value
+
+    @property
+    def priority(self) -> int:
+        return self._priority
+
+    @priority.setter
+    def priority(self, value):
+        self._priority = value
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._name
+
+    @name.setter
+    def name(self, value):
+        self._name = value
+
+    def check(self):
+        """Perform consistency checks on the record."""
+        scIdx = self._time_sheet.scenarioIdx
+        taskId = self.taskId
+
+        # All records must have a 'work' attribute
+        if self._work is None:
+            self.error('ts_no_work',
+                       f"The time sheet record for task {taskId} must "
+                       "have a 'work' attribute to specify how much was done "
+                       "for this task during the reported period.")
+
+        # Check if task is an existing Task object or a string ID
+        if hasattr(self._task, 'fullId'):
+            # Existing task
+            effort = self._task.get('effort', scIdx) if hasattr(self._task, 'get') else 0
+            if effort and effort > 0:
+                if not self._remaining:
+                    self.error('ts_no_remaining',
+                               f"The time sheet record for task {taskId} must "
+                               "have a 'remaining' attribute to specify how much "
+                               "effort is left for this task.")
+            else:
+                if not self._expected_end:
+                    self.error('ts_no_expected_end',
+                               f"The time sheet record for task {taskId} must "
+                               "have an 'end' attribute to specify the expected end "
+                               "of this task.")
+        else:
+            # New task
+            if self._remaining is None and self._expected_end is None:
+                self.error('ts_no_rem_or_end',
+                           f"New task {taskId} requires either a 'remaining' or a "
+                           "'end' attribute.")
+
+        if self._work and self._work >= self._time_sheet.daysToSlots(1) and self._status is None:
+            self.error('ts_no_status_work',
+                       f"You must specify a status for task {taskId}. It was worked "
+                       "on for a day or more.")
+
+        if self._status:
+            if hasattr(self._status, 'headline') and not self._status.headline:
+                self.error('ts_no_headline',
+                           f"You must provide a headline for the status of "
+                           f"task {taskId}")
+
+    def warnOnDelta(self, startIdx: int, endIdx: int):
+        """Warn about differences between planned and actual work."""
+        if self._task is None:
+            return
+
+        resource = self._time_sheet.resource
+        project = resource.project if hasattr(resource, 'project') else None
+        if not project:
+            return
+
+        if isinstance(self._task, str):
+            # New task request
+            remaining_str = (f"Remaining: {self._time_sheet.slotsToDays(self._remaining)}d"
+                            if self._remaining else f"End: {self._expected_end}")
+            self.warning('ts_res_new_task',
+                        f"{resource.name} is requesting a new task:\n"
+                        f"  ID: {self._task}\n"
+                        f"  Name: {self._name}\n"
+                        f"  Work: {self._time_sheet.slotsToDays(self._work)}d  "
+                        f"{remaining_str}")
+            return
+
+        # Compare actual vs planned work
+        scenarioIdx = self._time_sheet.scenarioIdx
+        if hasattr(self._task, 'getEffectiveWork'):
+            plannedWork = self._task.getEffectiveWork(scenarioIdx, startIdx, endIdx, resource)
+            scheduleGranularity = project.get('scheduleGranularity', 3600)
+            work = project.convertToDailyLoad(self._work * scheduleGranularity) if hasattr(project, 'convertToDailyLoad') else self._work
+
+            if work != plannedWork:
+                direction = 'less' if work < plannedWork else 'more'
+                self.warning('ts_res_work_delta',
+                            f"{resource.name} worked {direction} on {self._task.fullId}\n"
+                            f"{work}d instead of {plannedWork}d")
+
+    @property
+    def taskId(self) -> str:
+        """Return the task ID."""
+        if hasattr(self._task, 'fullId'):
+            return self._task.fullId
+        return str(self._task)
+
+    def actualWorkPercent(self) -> float:
+        """Return reported work as percentage (0.0 - 100.0) of average working time."""
+        if self._work is None:
+            return 0.0
+        total = self._time_sheet.totalGrossWorkingSlots
+        if total == 0:
+            return 0.0
+        return (float(self._work) / total) * 100.0
+
+    def planWorkPercent(self) -> float:
+        """Return planned work as percentage (0.0 - 100.0) of average working time."""
+        resource = self._time_sheet.resource
+        if not hasattr(resource, 'project'):
+            return 0.0
+
+        project = resource.project
+        scenarioIdx = self._time_sheet.scenarioIdx
+        interval = self._time_sheet.interval
+
+        if hasattr(project, 'dateToIdx'):
+            startIdx = project.dateToIdx(interval.start)
+            endIdx = project.dateToIdx(interval.end)
+        else:
+            return 0.0
+
+        if hasattr(resource, 'getAllocatedSlots'):
+            allocated = resource.getAllocatedSlots(scenarioIdx, startIdx, endIdx, self._task)
+            total = self._time_sheet.totalGrossWorkingSlots
+            if total == 0:
+                return 0.0
+            return (float(allocated) / total) * 100.0
+        return 0.0
+
+    def actualRemaining(self) -> float:
+        """Return reported remaining effort in days."""
+        if self._remaining is None:
+            return 0.0
+        resource = self._time_sheet.resource
+        if not hasattr(resource, 'project'):
+            return float(self._remaining)
+
+        project = resource.project
+        scheduleGranularity = project.get('scheduleGranularity', 3600) if hasattr(project, 'get') else 3600
+        if hasattr(project, 'convertToDailyLoad'):
+            return project.convertToDailyLoad(self._remaining * scheduleGranularity)
+        return float(self._remaining)
+
+    def planRemaining(self) -> float:
+        """Return remaining effort according to plan."""
+        resource = self._time_sheet.resource
+        if not hasattr(resource, 'project') or not hasattr(self._task, 'getEffectiveWork'):
+            return 0.0
+
+        project = resource.project
+        scenarioIdx = self._time_sheet.scenarioIdx
+
+        if hasattr(project, 'dateToIdx'):
+            startIdx = project.dateToIdx(project.get('now'))
+            endIdx = project.dateToIdx(self._task.get('end', scenarioIdx))
+            return self._task.getEffectiveWork(scenarioIdx, startIdx, endIdx, resource)
+        return 0.0
+
+    def actualEnd(self):
+        """Return reported expected end of task."""
+        return self._expected_end
+
+    def planEnd(self):
+        """Return planned end of task."""
+        if hasattr(self._task, 'get'):
+            return self._task.get('end', self._time_sheet.scenarioIdx)
+        return None
+
+
+class TimeSheet(MessageHandler):
+    """Stores work-related bits of a time sheet.
+
+    Holds TimeSheetRecord objects for each task.
+    Always bound to an existing Resource.
+    """
+
+    def __init__(self, resource, interval, scenarioIdx: int):
+        """Create a new TimeSheet.
+
+        Args:
+            resource: The Resource this time sheet belongs to.
+            interval: The time interval covered by this time sheet.
+            scenarioIdx: The scenario index.
+        """
+        if not resource:
+            raise ValueError("Illegal resource")
+        self._resource = resource
+
+        if interval is None:
+            raise ValueError("Interval undefined")
+        self._interval = interval
+
+        if scenarioIdx is None:
+            raise ValueError("Scenario index undefined")
+        self._scenarioIdx = scenarioIdx
+
+        self.sourceFileInfo = None
+        self._percentageUsed = False
+        self._records: List[TimeSheetRecord] = []
+
+    @property
+    def resource(self):
+        return self._resource
+
+    @property
+    def interval(self):
+        return self._interval
+
+    @property
+    def scenarioIdx(self) -> int:
+        return self._scenarioIdx
+
+    @property
+    def records(self) -> List[TimeSheetRecord]:
+        return self._records
+
+    def add_record(self, record: TimeSheetRecord):
+        """Add a TimeSheetRecord to this time sheet."""
+        for r in self._records:
+            if r.task == record.task:
+                self.error('ts_duplicate_task',
+                          f"Duplicate records for task {r.taskId}")
+        self._records.append(record)
+
+    def __lshift__(self, record: TimeSheetRecord):
+        """Add a record using << operator."""
+        self.add_record(record)
+        return self
+
+    def check(self):
+        """Perform consistency checks on all records."""
+        totalSlots = 0
+        for record in self._records:
+            record.check()
+            if record.work:
+                totalSlots += record.work
+
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project:
+            return
+
+        trackingScenarioIdx = project.get('trackingScenarioIdx') if hasattr(project, 'get') else None
+        if not trackingScenarioIdx:
+            self.error('ts_no_tracking_scenario',
+                      'No trackingscenario has been defined.')
+            return
+
+        efficiency = self._resource.get('efficiency', self._scenarioIdx) if hasattr(self._resource, 'get') else 1.0
+        if efficiency and efficiency > 0.0:
+            targetSlots = self.totalNetWorkingSlots
+            delta = 1  # Acceptable rounding error
+
+            if totalSlots < (targetSlots - delta):
+                self.error('ts_work_too_low',
+                          f"The total work to be reported for this time sheet "
+                          f"is {self._workWithUnit(targetSlots)} but only "
+                          f"{self._workWithUnit(totalSlots)} were reported.")
+
+            if totalSlots > (targetSlots + delta):
+                self.error('ts_work_too_high',
+                          f"The total work to be reported for this time sheet "
+                          f"is {self._workWithUnit(targetSlots)} but "
+                          f"{self._workWithUnit(totalSlots)} were reported.")
+        else:
+            if totalSlots > 0:
+                self.error('ts_work_not_null',
+                          "The reported work for non-working resources must be 0.")
+
+    def warnOnDelta(self):
+        """Warn about all delta differences in records."""
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project or not hasattr(project, 'dateToIdx'):
+            return
+
+        startIdx = project.dateToIdx(self._interval.start)
+        endIdx = project.dateToIdx(self._interval.end)
+
+        for record in self._records:
+            record.warnOnDelta(startIdx, endIdx)
+
+    @property
+    def totalGrossWorkingSlots(self) -> int:
+        """Compute total potential working time slots during report period."""
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project:
+            return 0
+
+        # Calculate weeks in report
+        duration = self._interval.end - self._interval.start
+        if hasattr(duration, 'total_seconds'):
+            weeksToReport = duration.total_seconds() / (60 * 60 * 24 * 7)
+        else:
+            weeksToReport = float(duration) / (60 * 60 * 24 * 7)
+
+        weeklyWorkingDays = getattr(project, 'weeklyWorkingDays', 5)
+        return self.daysToSlots(int(weeklyWorkingDays * weeksToReport))
+
+    @property
+    def totalNetWorkingSlots(self) -> int:
+        """Compute total actual working time slots of the Resource."""
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project or not hasattr(project, 'dateToIdx'):
+            return 0
+
+        startIdx = project.dateToIdx(self._interval.start)
+        endIdx = project.dateToIdx(self._interval.end)
+
+        allocated = 0
+        free = 0
+        if hasattr(self._resource, 'getAllocatedSlots'):
+            allocated = self._resource.getAllocatedSlots(self._scenarioIdx, startIdx, endIdx, None)
+        if hasattr(self._resource, 'getFreeSlots'):
+            free = self._resource.getFreeSlots(self._scenarioIdx, startIdx, endIdx)
+
+        return allocated + free
+
+    def percentToSlots(self, value: float) -> int:
+        """Convert allocation percentage to time slots."""
+        self._percentageUsed = True
+        return int(self.totalGrossWorkingSlots * value)
+
+    def slotsToPercent(self, slots: int) -> float:
+        """Compute what percent the slots are of total working slots."""
+        total = self.totalGrossWorkingSlots
+        if total == 0:
+            return 0.0
+        return float(slots) / total
+
+    def slotsToDays(self, slots: int) -> float:
+        """Convert slots to days."""
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project:
+            return float(slots)
+
+        scheduleGranularity = project.get('scheduleGranularity', 3600) if hasattr(project, 'get') else 3600
+        dailyWorkingHours = getattr(project, 'dailyWorkingHours', 8)
+        return slots * scheduleGranularity / (60 * 60 * dailyWorkingHours)
+
+    def daysToSlots(self, days: int) -> int:
+        """Convert days to slots."""
+        project = self._resource.project if hasattr(self._resource, 'project') else None
+        if not project:
+            return days
+
+        dailyWorkingHours = getattr(project, 'dailyWorkingHours', 8)
+        scheduleGranularity = project.get('scheduleGranularity', 3600) if hasattr(project, 'get') else 3600
+        return int((days * 60 * 60 * dailyWorkingHours) / scheduleGranularity)
+
+    def _workWithUnit(self, slots: int) -> str:
+        """Format work with appropriate unit."""
+        if self._percentageUsed:
+            return f"{int(self.slotsToPercent(slots) * 100.0)}%"
+        else:
+            return f"{self.slotsToDays(slots)} days"
+
+
+class TimeSheets(list):
+    """Collection of all time sheets for a project."""
+
+    def __init__(self):
+        super().__init__()
+
+    def check(self):
+        """Check all time sheets."""
+        for sheet in self:
+            sheet.check()
+
+    def warnOnDelta(self):
+        """Warn about deltas in all time sheets."""
+        for sheet in self:
+            sheet.warnOnDelta()

scriptplan/core/working_hours.py

@@ -0,0 +1,231 @@
+"""
+WorkingHours class for managing per-resource working hour schedules.
+
+This class handles irregular working hours like "08:15 - 11:45, 13:15 - 16:30"
+for specific days of the week.
+"""
+
+from datetime import datetime, time, timedelta
+
+try:
+    import zoneinfo
+    HAS_ZONEINFO = True
+except ImportError:
+    HAS_ZONEINFO = False
+    try:
+        import pytz
+        HAS_PYTZ = True
+    except ImportError:
+        HAS_PYTZ = False
+
+
+class WorkingHours:
+    """
+    Manages working hours for a resource.
+
+    Working hours are defined as time intervals for each day of the week.
+    For example:
+        Mon, Wed, Fri: 08:15 - 11:45, 13:15 - 16:30
+        Tue, Thu: 09:00 - 10:30, 14:45 - 16:00
+    """
+
+    # Map day names to weekday numbers (0=Monday, 6=Sunday)
+    DAY_MAP = {
+        'mon': 0, 'tue': 1, 'wed': 2, 'thu': 3, 'fri': 4, 'sat': 5, 'sun': 6
+    }
+
+    def __init__(self, project):
+        """
+        Initialize working hours.
+
+        Args:
+            project: Project reference for time conversion
+        """
+        self.project = project
+        # Dict mapping weekday (0-6) to list of (start_time, end_time) tuples
+        # Times are stored as (hour, minute) tuples
+        self._hours = {}
+        # Start with empty hours - will be populated by set_hours()
+        # If no hours are set, onShift will fall back to project default
+        self._custom_hours_set = False
+
+    def set_hours(self, days, ranges):
+        """
+        Set working hours for specific days.
+
+        Args:
+            days: List of day names like ['mon', 'wed', 'fri']
+            ranges: List of (start_time, end_time) tuples like [('08:15', '11:45')]
+        """
+        self._custom_hours_set = True
+
+        # Convert day names to weekday numbers
+        day_nums = []
+        for day in days:
+            day_lower = day.lower()
+            if day_lower in self.DAY_MAP:
+                day_nums.append(self.DAY_MAP[day_lower])
+
+        # Handle day ranges like "mon - fri"
+        if len(day_nums) == 0:
+            return
+
+        # Parse time ranges to (hour, minute) tuples
+        time_intervals = []
+        for start_str, end_str in ranges:
+            start_h, start_m = self._parse_time(start_str)
+            end_h, end_m = self._parse_time(end_str)
+            time_intervals.append(((start_h, start_m), (end_h, end_m)))
+
+        # Set hours for each day
+        # NOTE: Multiple workinghours directives for the same resource will
+        # result in multiple calls. The behavior depends on whether days overlap:
+        # - Different days: each gets its own time intervals
+        # - Same day called multiple times: extends (adds more intervals)
+        for day_num in day_nums:
+            if day_num not in self._hours:
+                self._hours[day_num] = []
+            # Extend with new intervals (allows multiple non-contiguous ranges per day)
+            self._hours[day_num].extend(time_intervals)
+
+    def _parse_time(self, time_str):
+        """Parse a time string like '08:15' to (hour, minute) tuple."""
+        parts = str(time_str).split(':')
+        hour = int(parts[0])
+        minute = int(parts[1]) if len(parts) > 1 else 0
+        return (hour, minute)
+
+    def onShift(self, slot_idx, timezone=None):
+        """
+        Check if a slot index is within working hours.
+
+        Args:
+            slot_idx: Scoreboard slot index
+            timezone: Optional timezone string (e.g., "Asia/Tokyo"). If provided,
+                     the UTC slot time is converted to local time before checking
+                     working hours. This enables resources in different timezones
+                     to have their shifts defined in local time.
+
+        Returns:
+            True if the slot is within working hours
+        """
+        # If no custom hours set, fall back to project default
+        if not self._custom_hours_set:
+            return self.project.isWorkingTime(slot_idx)
+
+        # Get datetime for this slot (in UTC)
+        dt = self.project.idxToDate(slot_idx)
+        if dt is None:
+            return False
+
+        # Convert UTC time to resource's local timezone if specified
+        if timezone:
+            dt = self._convert_to_timezone(dt, timezone)
+            if dt is None:
+                return False
+
+        weekday = dt.weekday()
+
+        # Check if this day has working hours defined
+        if weekday not in self._hours or not self._hours[weekday]:
+            # No working hours defined for this day = not working
+            return False
+
+        slot_time = (dt.hour, dt.minute)
+        slot_minutes = slot_time[0] * 60 + slot_time[1]
+
+        # Check if slot falls within any working interval
+        for (start_h, start_m), (end_h, end_m) in self._hours[weekday]:
+            start_minutes = start_h * 60 + start_m
+            end_minutes = end_h * 60 + end_m
+
+            # Check for cross-midnight shift (e.g., 22:00 - 06:00)
+            if end_minutes <= start_minutes:
+                # This interval crosses midnight
+                # Working time is: start_minutes <= slot < 1440 OR 0 <= slot < end_minutes
+                if slot_minutes >= start_minutes or slot_minutes < end_minutes:
+                    return True
+            else:
+                # Normal interval within same day
+                if start_minutes <= slot_minutes < end_minutes:
+                    return True
+
+        # Also check if we're in the early morning part of a cross-midnight shift from previous day
+        prev_weekday = (weekday - 1) % 7
+        if prev_weekday in self._hours and self._hours[prev_weekday]:
+            for (start_h, start_m), (end_h, end_m) in self._hours[prev_weekday]:
+                start_minutes = start_h * 60 + start_m
+                end_minutes = end_h * 60 + end_m
+
+                # If previous day had a cross-midnight shift
+                if end_minutes <= start_minutes:
+                    # Check if current slot is in the morning part (0 <= slot < end)
+                    if slot_minutes < end_minutes:
+                        return True
+
+        return False
+
+    def get_daily_hours(self, weekday):
+        """
+        Get total working hours for a specific weekday.
+
+        Args:
+            weekday: Day of week (0=Monday, 6=Sunday)
+
+        Returns:
+            Total working hours as float
+        """
+        if weekday not in self._hours:
+            return 0.0
+
+        total_minutes = 0
+        for (start_h, start_m), (end_h, end_m) in self._hours[weekday]:
+            start_minutes = start_h * 60 + start_m
+            end_minutes = end_h * 60 + end_m
+            total_minutes += (end_minutes - start_minutes)
+
+        return total_minutes / 60.0
+
+    def clear_day(self, weekday):
+        """Clear working hours for a specific day."""
+        if weekday in self._hours:
+            self._hours[weekday] = []
+
+    def clear_all(self):
+        """Clear all working hours."""
+        self._hours = {}
+
+    def _convert_to_timezone(self, dt, timezone_str):
+        """
+        Convert a naive UTC datetime to the specified timezone.
+
+        Args:
+            dt: Naive datetime (assumed to be UTC)
+            timezone_str: Timezone string like "Asia/Tokyo" or "America/New_York"
+
+        Returns:
+            Datetime in the local timezone, or None if conversion fails
+        """
+        if not timezone_str:
+            return dt
+
+        try:
+            if HAS_ZONEINFO:
+                # Python 3.9+ with zoneinfo
+                from datetime import timezone as dt_timezone
+                utc_dt = dt.replace(tzinfo=dt_timezone.utc)
+                tz = zoneinfo.ZoneInfo(timezone_str)
+                return utc_dt.astimezone(tz)
+            elif HAS_PYTZ:
+                # Fallback to pytz
+                import pytz
+                utc = pytz.UTC
+                utc_dt = utc.localize(dt)
+                tz = pytz.timezone(timezone_str)
+                return utc_dt.astimezone(tz)
+            else:
+                # No timezone support - return as-is with a warning
+                return dt
+        except Exception:
+            # Invalid timezone - return original datetime
+            return dt