frist 0.6.0__py3-none-any.whl

frist/__init__.py

@@ -0,0 +1,26 @@
+"""
+Frist: Standalone datetime utility package
+
+Provides robust tools for:
+    - Age and duration calculations across multiple time units
+    - Calendar window filtering (days, weeks, months, quarters, years)
+    - Fiscal year/quarter logic and holiday detection
+    - Flexible datetime parsing and normalization
+
+Designed for use in any Python project requiring advanced datetime analysis, not limited to file operations.
+
+Exports:
+    Frist   -- Main datetime utility class
+    Age       -- Duration and age calculations
+    Cal       -- Calendar window and filtering logic
+    TimeSpan  -- Time span representation for advanced calculations
+"""
+
+from ._age import Age
+from ._cal import Cal, TimeSpan
+from ._frist import Frist
+
+__version__ = "0.6.0"
+__author__ = "Chuck Bass"
+
+__all__ = ["Frist", "Age", "Cal", "TimeSpan"]

frist/_age.py

@@ -0,0 +1,132 @@
+"""
+Age property implementation for Frist package.
+
+Handles age calculations in various time units, supporting both file-based and standalone usage.
+"""
+
+import datetime as dt
+import re
+from pathlib import Path
+
+from ._constants import (
+    DAYS_PER_MONTH,
+    DAYS_PER_YEAR,
+    SECONDS_PER_DAY,
+    SECONDS_PER_HOUR,
+    SECONDS_PER_MINUTE,
+    SECONDS_PER_MONTH,
+    SECONDS_PER_WEEK,
+    SECONDS_PER_YEAR,
+)
+
+
+class Age:
+    """Property class for handling age calculations in various time units."""
+
+    def __init__(self, path: Path | None, timestamp: float, base_time: dt.datetime):
+        self.path = path
+        self.timestamp = timestamp
+        self.base_time = base_time
+
+    @property
+    def seconds(self) -> float:
+        """Get age in seconds."""
+        # Only check file existence if we have a path
+        if self.path is not None and not self.path.exists():
+            return 0
+        file_time = dt.datetime.fromtimestamp(self.timestamp)
+        return (self.base_time - file_time).total_seconds()
+
+    @property
+    def minutes(self) -> float:
+        """Get age in minutes."""
+        return self.seconds / SECONDS_PER_MINUTE
+
+    @property
+    def hours(self) -> float:
+        """Get age in hours."""
+        return self.seconds / SECONDS_PER_HOUR
+
+    @property
+    def days(self) -> float:
+        """Get age in days."""
+        return self.seconds / SECONDS_PER_DAY
+
+    @property
+    def weeks(self) -> float:
+        """Get age in weeks."""
+        return self.days / 7
+
+    @property
+    def months(self) -> float:
+        """Get age in months (approximate - 30.44 days)."""
+        return self.days / DAYS_PER_MONTH
+
+    @property
+    def years(self) -> float:
+        """Get age in years (approximate - 365.25 days, can be negative)."""
+        # Allow negative ages if base_time is before timestamp
+        return self.days / DAYS_PER_YEAR
+
+    @staticmethod
+    def parse(age_str: str) -> float:
+        """
+        Parse an age string and return the age in seconds.
+
+        Examples:
+            "30" -> 30 seconds
+            "5m" -> 300 seconds (5 minutes)
+            "2h" -> 7200 seconds (2 hours)
+            "3d" -> 259200 seconds (3 days)
+            "1w" -> 604800 seconds (1 week)
+            "2months" -> 5260032 seconds (2 months)
+            "1y" -> 31557600 seconds (1 year)
+        """
+        age_str = age_str.strip().lower()
+
+        # Handle plain numbers (seconds)
+        if age_str.isdigit():
+            return float(age_str)
+
+        # Regular expression to parse age with unit
+        match = re.match(r"^(\d+(?:\.\d+)?)\s*([a-zA-Z]+)$", age_str)
+        if not match:
+            raise ValueError(f"Invalid age format: {age_str}")
+
+        value: float = float(match.group(1))
+        unit: str = match.group(2).lower()
+
+        # Define multipliers (convert to seconds)
+        unit_multipliers = {
+            "s": 1,
+            "sec": 1,
+            "second": 1,
+            "seconds": 1,
+            "m": SECONDS_PER_MINUTE,
+            "min": SECONDS_PER_MINUTE,
+            "minute": SECONDS_PER_MINUTE,
+            "minutes": SECONDS_PER_MINUTE,
+            "h": SECONDS_PER_HOUR,
+            "hr": SECONDS_PER_HOUR,
+            "hour": SECONDS_PER_HOUR,
+            "hours": SECONDS_PER_HOUR,
+            "d": SECONDS_PER_DAY,
+            "day": SECONDS_PER_DAY,
+            "days": SECONDS_PER_DAY,
+            "w": SECONDS_PER_WEEK,
+            "week": SECONDS_PER_WEEK,
+            "weeks": SECONDS_PER_WEEK,
+            "month": SECONDS_PER_MONTH,
+            "months": SECONDS_PER_MONTH,
+            "y": SECONDS_PER_YEAR,
+            "year": SECONDS_PER_YEAR,
+            "years": SECONDS_PER_YEAR,
+        }
+
+        if unit not in unit_multipliers:
+            raise ValueError(f"Unknown unit: {unit}")
+
+        return value * unit_multipliers[unit]
+
+
+__all__ = ["Age"]

frist/_cal.py

@@ -0,0 +1,480 @@
+
+"""
+Calendar-based time window filtering for Frist package.
+
+Provides calendar window filtering functionality that works with any object
+having datetime and base_time properties (Time or Frist objects).
+"""
+
+import datetime as dt
+from typing import TYPE_CHECKING, Protocol
+
+from ._constants import WEEKDAY_INDEX
+
+if TYPE_CHECKING:  # pragma: no cover
+    pass
+
+
+class TimeSpan(Protocol):
+    """Protocol for objects that represent a time span between two datetime points."""
+
+    @property
+    def target_dt(self) -> dt.datetime:
+        """The target datetime being analyzed."""
+        raise NotImplementedError
+
+    @property
+    def ref_dt(self) -> dt.datetime:
+        """The reference datetime for span calculations."""
+        raise NotImplementedError
+
+
+
+def normalize_weekday(day_spec: str) -> int:
+    """Normalize various day-of-week specifications to Python weekday numbers.
+
+    Args:
+        day_spec: Day specification as a string
+
+    Returns:
+        int: Python weekday number (0=Monday, 1=Tuesday, ..., 6=Sunday)
+
+    Accepts:
+        - Full names: 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'
+        - 3-letter abbrev: 'mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'
+        - 2-letter abbrev: 'mo', 'tu', 'we', 'th', 'fr', 'sa', 'su'
+        - Pandas style: 'w-mon', 'w-tue', etc.
+        - All case insensitive
+
+    Examples:
+        normalize_weekday('monday') -> 0
+        normalize_weekday('MON') -> 0
+        normalize_weekday('w-sun') -> 6
+        normalize_weekday('thu') -> 3
+    """
+    day_spec = str(day_spec).lower().strip()
+
+    # Remove pandas-style prefix
+    if day_spec.startswith("w-"):
+        day_spec = day_spec[2:]
+
+    if day_spec in WEEKDAY_INDEX:
+        return WEEKDAY_INDEX[day_spec]
+
+    # Generate helpful error message
+    valid_examples = [
+        "Full: 'monday', 'sunday'",
+        "3-letter: 'mon', 'sun', 'tue', 'wed', 'thu', 'fri', 'sat'",
+        "2-letter: 'mo', 'su', 'tu', 'we', 'th', 'fr', 'sa'",
+        "Pandas: 'w-mon', 'w-sun'",
+    ]
+    raise ValueError(
+        f"Invalid day specification: '{day_spec}'. Valid formats:\n"
+        + "\n".join(f"  • {ex}" for ex in valid_examples)
+    )
+
+
+class Cal:
+    """Calendar window filtering functionality for TimeSpan objects."""
+
+    def __init__(self, time_span: TimeSpan, fy_start_month: int = 1, holidays: set[str] | None = None) -> None:
+        """Initialize with a TimeSpan object to provide calendar filtering methods."""
+        self.time_span: TimeSpan = time_span
+        self.fy_start_month: int = fy_start_month
+        self.holidays: set[str] = holidays if holidays is not None else set()
+
+
+
+
+
+    @property
+    def holiday(self) -> bool:
+        """Return True if dt_val is a holiday (in holidays set)."""
+        date_str = self.dt_val.strftime('%Y-%m-%d')
+        return date_str in self.holidays
+    @property
+    def fiscal_year(self) -> int:
+        """Return the fiscal year for dt_val based on fy_start_month."""
+        month = self.dt_val.month
+        year = self.dt_val.year
+        if month >= self.fy_start_month:
+            return year
+        else:
+            return year - 1
+
+    @property
+    def fiscal_quarter(self) -> int:
+        """Return the fiscal quarter for dt_val based on fy_start_month."""
+        month = self.dt_val.month
+        offset = (month - self.fy_start_month) % 12
+        return (offset // 3) + 1
+
+    @property
+    def dt_val(self) -> dt.datetime:
+        """Get target datetime from the time span."""
+        return self.time_span.target_dt
+
+    @property
+    def base_time(self) -> dt.datetime:
+        """Get reference datetime from the time span."""
+        return self.time_span.ref_dt
+
+    def in_minutes(self, start: int = 0, end: int | None = None) -> bool:
+        """
+        True if timestamp falls within the minute window(s) from start to end.
+
+        Uses a half-open interval: start_minute <= target_time < end_minute.
+
+        Args:
+            start: Minutes from now to start range (negative = past, 0 = current minute, positive = future)
+            end: Minutes from now to end range (defaults to start for single minute)
+
+        Examples:
+            zeit.cal.in_minutes(0)          # This minute (now)
+            zeit.cal.in_minutes(-5)         # 5 minutes ago only
+            zeit.cal.in_minutes(-10, -5)    # From 10 minutes ago through 5 minutes ago
+            zeit.cal.in_minutes(-30, 0)     # Last 30 minutes through now
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        target_time = self.dt_val
+
+        # Calculate the time window boundaries
+        start_time = self.base_time + dt.timedelta(minutes=start)
+        start_minute = start_time.replace(second=0, microsecond=0)
+
+        end_time = self.base_time + dt.timedelta(minutes=end)
+        end_minute = end_time.replace(second=0, microsecond=0) + dt.timedelta(minutes=1)
+
+        return start_minute <= target_time < end_minute
+
+    def in_hours(self, start: int = 0, end: int | None = None) -> bool:
+        """
+        True if timestamp falls within the hour window(s) from start to end.
+
+        Uses a half-open interval: start_hour <= target_time < end_hour.
+
+        Args:
+            start: Hours from now to start range (negative = past, 0 = current hour, positive = future)
+            end: Hours from now to end range (defaults to start for single hour)
+
+        Examples:
+            zeit.cal.in_hours(0)          # This hour (now)
+            zeit.cal.in_hours(-2)         # 2 hours ago only
+            zeit.cal.in_hours(-6, -1)     # From 6 hours ago through 1 hour ago
+            zeit.cal.in_hours(-24, 0)     # Last 24 hours through now
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        target_time = self.dt_val
+
+        # Calculate the time window boundaries
+        start_time = self.base_time + dt.timedelta(hours=start)
+        start_hour = start_time.replace(minute=0, second=0, microsecond=0)
+
+        end_time = self.base_time + dt.timedelta(hours=end)
+        end_hour = end_time.replace(minute=0, second=0, microsecond=0) + dt.timedelta(
+            hours=1
+        )
+
+        return start_hour <= target_time < end_hour
+
+    def in_days(self, start: int = 0, end: int | None = None) -> bool:
+        """True if timestamp falls within the day window(s) from start to end.
+
+        Args:
+            start: Days from now to start range (negative = past, 0 = today, positive = future)
+            end: Days from now to end range (defaults to start for single day)
+
+        Examples:
+            zeit.cal.in_days(0)          # Today only
+            zeit.cal.in_days(-1)         # Yesterday only
+            zeit.cal.in_days(-7, -1)     # From 7 days ago through yesterday
+            zeit.cal.in_days(-30, 0)     # Last 30 days through today
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            msg = f"start ({start}) must not be greater than end ({end})"
+            raise ValueError(msg)
+
+        target_date = self.dt_val.date()
+
+        # Calculate the date range boundaries
+        start_date = (self.base_time + dt.timedelta(days=start)).date()
+        end_date = (self.base_time + dt.timedelta(days=end)).date()
+
+        return start_date <= target_date <= end_date
+
+    def in_months(self, start: int = 0, end: int | None = None) -> bool:
+        """True if timestamp falls within the month window(s) from start to end.
+
+        Args:
+            start: Months from now to start range (negative = past, 0 = this month, positive = future)
+            end: Months from now to end range (defaults to start for single month)
+
+        Examples:
+            zeit.cal.in_months(0)          # This month
+            zeit.cal.in_months(-1)         # Last month only
+            zeit.cal.in_months(-6, -1)     # From 6 months ago through last month
+            zeit.cal.in_months(-12, 0)     # Last 12 months through this month
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        target_time = self.dt_val
+        base_year = self.base_time.year
+        base_month = self.base_time.month
+
+        # Calculate the start month (earliest)
+        start_month = base_month + start
+        start_year = base_year
+        while start_month <= 0:
+            start_month += 12
+            start_year -= 1
+        while start_month > 12:
+            start_month -= 12
+            start_year += 1
+
+        # Calculate the end month (latest)
+        end_month = base_month + end
+        end_year = base_year
+        while end_month <= 0:
+            end_month += 12
+            end_year -= 1
+        while end_month > 12:
+            end_month -= 12
+            end_year += 1
+
+        # Convert months to a comparable format (year * 12 + month)
+        file_month_index = target_time.year * 12 + target_time.month
+        start_month_index = start_year * 12 + start_month
+        end_month_index = end_year * 12 + end_month
+
+        return start_month_index <= file_month_index <= end_month_index
+
+    def in_quarters(self, start: int = 0, end: int | None = None) -> bool:
+        """
+        True if timestamp falls within the quarter window(s) from start to end.
+
+        Uses a half-open interval: start_tuple <= target_tuple < (end_tuple[0], end_tuple[1] + 1).
+
+        Args:
+            start: Quarters from now to start range (negative = past, 0 = this quarter, positive = future)
+            end: Quarters from now to end range (defaults to start for single quarter)
+
+        Examples:
+            zeit.cal.in_quarters(0)          # This quarter (Q1: Jan-Mar, Q2: Apr-Jun, Q3: Jul-Sep, Q4: Oct-Dec)
+            zeit.cal.in_quarters(-1)         # Last quarter
+            zeit.cal.in_quarters(-4, -1)     # From 4 quarters ago through last quarter
+            zeit.cal.in_quarters(-8, 0)      # Last 8 quarters through this quarter
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        target_time = self.dt_val
+        base_time = self.base_time
+
+        # Get current quarter (1-4) and year
+        current_quarter = ((base_time.month - 1) // 3) + 1
+        current_year = base_time.year
+
+        def normalize_quarter_year(offset: int) -> tuple[int, int]:
+            total_quarters = (current_year * 4 + current_quarter + offset - 1)
+            year = total_quarters // 4
+            quarter = (total_quarters % 4) + 1
+            return year, quarter
+
+        start_year, start_quarter = normalize_quarter_year(start)
+        end_year, end_quarter = normalize_quarter_year(end)
+
+        # Get target's quarter
+        target_quarter = ((target_time.month - 1) // 3) + 1
+        target_year = target_time.year
+
+        # Use tuple comparison for (year, quarter)
+        target_tuple = (target_year, target_quarter)
+        start_tuple = (start_year, start_quarter)
+        end_tuple = (end_year, end_quarter)
+
+        # Check if target falls within the quarter range: start <= target < end
+        return start_tuple <= target_tuple < (end_tuple[0], end_tuple[1] + 1)
+
+    def in_years(self, start: int = 0, end: int | None = None) -> bool:
+        """True if timestamp falls within the year window(s) from start to end.
+
+        Args:
+            start: Years from now to start range (negative = past, 0 = this year, positive = future)
+            end: Years from now to end range (defaults to start for single year)
+
+        Examples:
+            zeit.cal.in_years(0)          # This year
+            zeit.cal.in_years(-1)         # Last year only
+            zeit.cal.in_years(-5, -1)     # From 5 years ago through last year
+            zeit.cal.in_years(-10, 0)     # Last 10 years through this year
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        target_year = self.dt_val.year
+        base_year = self.base_time.year
+
+        # Calculate year range boundaries
+        start_year = base_year + start
+        end_year = base_year + end
+
+        return start_year <= target_year <= end_year
+
+    def in_weeks(
+        self, start: int = 0, end: int | None = None, week_start: str = "monday"
+    ) -> bool:
+        """True if timestamp falls within the week window(s) from start to end.
+
+        Args:
+            start: Weeks from now to start range (negative = past, 0 = current week, positive = future)
+            end: Weeks from now to end range (defaults to start for single week)
+            week_start: Week start day (default: 'monday' for ISO weeks)
+                - 'monday'/'mon'/'mo' (ISO 8601 default)
+                - 'sunday'/'sun'/'su' (US convention)
+                - Supports full names, abbreviations, pandas style ('w-mon')
+                - Case insensitive
+
+        Examples:
+            zeit.cal.in_weeks(0)                     # This week (Monday start)
+            zeit.cal.in_weeks(-1, week_start='sun')  # Last week (Sunday start)
+            zeit.cal.in_weeks(-4, 0)                 # Last 4 weeks through this week
+            zeit.cal.in_weeks(-2, -1, 'sunday')      # 2-1 weeks ago (Sunday weeks)
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        # Normalize the week start day
+        week_start_day = normalize_weekday(week_start)
+
+        target_date = self.dt_val.date()
+        base_date = self.base_time.date()
+
+        # Calculate the start of the current week based on week_start_day
+        days_since_week_start = (base_date.weekday() - week_start_day) % 7
+        current_week_start = base_date - dt.timedelta(days=days_since_week_start)
+
+        # Calculate week boundaries
+        start_week_start = current_week_start + dt.timedelta(weeks=start)
+        end_week_start = current_week_start + dt.timedelta(weeks=end)
+        end_week_end = end_week_start + dt.timedelta(
+            days=6
+        )  # End of week (6 days after start)
+
+        return start_week_start <= target_date <= end_week_end
+
+
+    def in_fiscal_quarters(self, start: int = 0, end: int | None = None) -> bool:
+        """
+        True if timestamp falls within the fiscal quarter window(s) from start to end.
+
+        Uses a half-open interval: start_tuple <= target_tuple < (end_tuple[0], end_tuple[1] + 1).
+
+        Args:
+            start: Fiscal quarters from now to start range (negative = past, 0 = this fiscal quarter, positive = future)
+            end: Fiscal quarters from now to end range (defaults to start for single fiscal quarter)
+
+        Examples:
+            zeit.cal.in_fiscal_quarters(0)          # This fiscal quarter
+            zeit.cal.in_fiscal_quarters(-1)         # Last fiscal quarter
+            zeit.cal.in_fiscal_quarters(-4, -1)     # From 4 fiscal quarters ago through last fiscal quarter
+            zeit.cal.in_fiscal_quarters(-8, 0)      # Last 8 fiscal quarters through this fiscal quarter
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        base_time = self.base_time
+        fy_start_month = self.fy_start_month
+
+        fy = Cal.get_fiscal_year(base_time, fy_start_month)
+        fq = Cal.get_fiscal_quarter(base_time, fy_start_month)
+
+        def normalize_fiscal_quarter_year(offset: int) -> tuple[int, int]:
+            total_quarters = (fy * 4 + fq + offset - 1)
+            year = total_quarters // 4
+            quarter = (total_quarters % 4) + 1
+            return year, quarter
+
+        start_year, start_quarter = normalize_fiscal_quarter_year(start)
+        end_year, end_quarter = normalize_fiscal_quarter_year(end)
+
+        target_fy = Cal.get_fiscal_year(self.dt_val, fy_start_month)
+        target_fq = Cal.get_fiscal_quarter(self.dt_val, fy_start_month)
+
+        target_tuple = (target_fy, target_fq)
+        start_tuple = (start_year, start_quarter)
+        end_tuple = (end_year, end_quarter)
+
+        return start_tuple <= target_tuple < (end_tuple[0], end_tuple[1] + 1)
+
+
+    def in_fiscal_years(self, start: int = 0, end: int | None = None) -> bool:
+        """
+        True if timestamp falls within the fiscal year window(s) from start to end.
+
+        Uses a half-open interval: start_year <= target_year < end_year + 1.
+
+        Args:
+            start: Fiscal years from now to start range (negative = past, 0 = this fiscal year, positive = future)
+            end: Fiscal years from now to end range (defaults to start for single fiscal year)
+
+        Examples:
+            zeit.cal.in_fiscal_years(0)          # This fiscal year
+            zeit.cal.in_fiscal_years(-1)         # Last fiscal year
+            zeit.cal.in_fiscal_years(-5, -1)     # From 5 fiscal years ago through last fiscal year
+            zeit.cal.in_fiscal_years(-10, 0)     # Last 10 fiscal years through this fiscal year
+        """
+        if end is None:
+            end = start
+
+        if start > end:
+            raise ValueError(f"start ({start}) must not be greater than end ({end})")
+
+        base_time = self.base_time
+        fy_start_month = self.fy_start_month
+
+        fy = Cal.get_fiscal_year(base_time, fy_start_month)
+        start_year = fy + start
+        end_year = fy + end
+
+        target_fy = Cal.get_fiscal_year(self.dt_val, fy_start_month)
+
+        return start_year <= target_fy < end_year + 1
+    @staticmethod
+    def get_fiscal_year(dt: dt.datetime, fy_start_month: int) -> int:
+        """Return the fiscal year for a given datetime and fiscal year start month."""
+        return dt.year if dt.month >= fy_start_month else dt.year - 1
+
+    @staticmethod
+    def get_fiscal_quarter(dt: dt.datetime, fy_start_month: int) -> int:
+        """Return the fiscal quarter for a given datetime and fiscal year start month."""
+        offset = (dt.month - fy_start_month) % 12 if dt.month >= fy_start_month else (dt.month + 12 - fy_start_month) % 12
+        return (offset // 3) + 1

frist/_constants.py

@@ -0,0 +1,50 @@
+
+"""
+Constants used throughout the Frist package.
+"""
+
+from typing import Dict, Final
+
+# Time conversion constants
+SECONDS_PER_MINUTE: Final[int] = 60
+SECONDS_PER_HOUR: Final[int] = 3600
+SECONDS_PER_DAY: Final[int] = 86400
+SECONDS_PER_WEEK: Final[int] = 604800  # 7 * 24 * 60 * 60
+
+# Advanced time constants for age calculations
+DAYS_PER_MONTH: Final[float] = 30.44  # Average days per month
+DAYS_PER_YEAR: Final[float] = 365.25  # Average days per year (accounting for leap years)
+SECONDS_PER_MONTH: Final[int] = int(DAYS_PER_MONTH * SECONDS_PER_DAY)  # 2630016
+SECONDS_PER_YEAR: Final[int] = int(DAYS_PER_YEAR * SECONDS_PER_DAY)  # 31557600
+
+# Default fallback timestamp (1 day after Unix epoch to avoid timezone issues)
+DEFAULT_FALLBACK_TIMESTAMP: Final[int] = SECONDS_PER_DAY
+
+# Calendar constants
+DAYS_PER_WEEK: Final[int] = 7
+MONTHS_PER_YEAR: Final[int] = 12
+
+# Unified weekday mapping: all supported names/abbreviations to weekday index
+WEEKDAY_INDEX: Final[Dict[str, int]] = {
+    "monday": 0, "mon": 0, "mo": 0,
+    "tuesday": 1, "tue": 1, "tu": 1,
+    "wednesday": 2, "wed": 2, "we": 2,
+    "thursday": 3, "thu": 3, "th": 3,
+    "friday": 4, "fri": 4, "fr": 4,
+    "saturday": 5, "sat": 5, "sa": 5,
+    "sunday": 6, "sun": 6, "su": 6,
+}
+__all__ = [
+    "SECONDS_PER_MINUTE",
+    "SECONDS_PER_HOUR",
+    "SECONDS_PER_DAY",
+    "SECONDS_PER_WEEK",
+    "DAYS_PER_MONTH",
+    "DAYS_PER_YEAR",
+    "SECONDS_PER_MONTH",
+    "SECONDS_PER_YEAR",
+    "DEFAULT_FALLBACK_TIMESTAMP",
+    "DAYS_PER_WEEK",
+    "MONTHS_PER_YEAR",
+    "WEEKDAY_INDEX",
+]

frist/_frist.py

@@ -0,0 +1,176 @@
+"""
+Frist - Comprehensive datetime utility class.
+
+Handles age calculations, calendar windows, and datetime parsing for any datetime operations.
+Designed to be reusable beyond file operations.
+"""
+
+import datetime as dt
+
+from ._age import Age
+from ._cal import Cal
+
+
+class Frist:
+    """
+    Comprehensive datetime utility with age and window calculations.
+
+    Provides age calculations, calendar windows, and datetime parsing that can be used
+    for any datetime operations, not just file timestamps.
+
+    Examples:
+        # Standalone datetime operations
+        meeting = Frist(datetime(2024, 12, 1, 14, 0))
+        if meeting.age.hours < 2:
+            print("Meeting was recent")
+
+        # Custom reference time
+        project = Frist(start_date, reference_time=deadline)
+        if project.age.days > 30:
+            print("Project overdue")
+
+        # Calendar windows
+    if meeting.cal.in_days(0):
+            print("Meeting was today")
+    """
+
+    def __init__(
+        self,
+        *,
+        target_time: dt.datetime,
+        reference_time: dt.datetime | None = None,
+        fy_start_month: int = 1,
+        holidays: set[str] | None = None,
+    ):
+        """
+        Initialize Frist with target and reference times.
+
+        Args:
+            target_time: The datetime to analyze (e.g., file timestamp, meeting time)
+            reference_time: Reference time for calculations (defaults to now)
+            fy_start_month: Fiscal year start month (1=Jan, 2=Feb, ... 12=Dec)
+            holidays: Set of date strings (YYYY-MM-DD) that are holidays
+
+        Raises:
+            ValueError: If fy_start_month is not between 1 and 12
+        """
+        if not (1 <= fy_start_month <= 12):
+            raise ValueError(f"fy_start_month must be between 1 and 12, got {fy_start_month}")
+        if not isinstance(target_time, dt.datetime):
+            raise ValueError(f"target_time must be a datetime instance, got {type(target_time)}")
+        self.target_time:dt.datetime = target_time
+        self.reference_time :dt.datetime= reference_time or dt.datetime.now()
+        self.fy_start_month:int = fy_start_month
+        self.holidays :set[str]= holidays if holidays is not None else set()
+
+
+    @property
+    def age(self) -> Age:
+        """
+        Get age of target_time relative to reference_time.
+
+        Returns Age object with properties like .seconds, .minutes, .hours, .days, etc.
+        """
+        # Convert datetime objects to timestamps for Age class
+        target_timestamp = self.target_time.timestamp()
+
+        # Age expects (path, timestamp, base_time) - we pass None for path since standalone
+        return Age(None, target_timestamp, self.reference_time)  # type: ignore
+
+    @property
+    def cal(self):
+
+        """
+        Get calendar window functionality for target_time.
+
+        Returns Cal object for checking if target_time falls within calendar windows.
+        """
+        # Cal can work directly with Frist since we have .target_dt and .ref_dt properties
+        return Cal(self, fy_start_month=self.fy_start_month, holidays=self.holidays)
+
+    @property
+    def timestamp(self) -> float:
+        """Get the raw timestamp for target_time."""
+        return self.target_time.timestamp()
+
+    @property
+    def target_dt(self) -> dt.datetime:
+        """Get the target datetime for TimeSpan compatibility."""
+        return self.target_time
+
+    @property
+    def ref_dt(self) -> dt.datetime:
+        """Get the reference datetime for TimeSpan compatibility."""
+        return self.reference_time
+
+
+    @staticmethod
+    def parse(time_str: str, reference_time: dt.datetime | None = None):
+        """
+        Parse a time string and return a Frist object.
+
+        Args:
+            time_str: Time string to parse
+            reference_time: Optional reference time for age calculations
+
+        Returns:
+            Frist object for the parsed time
+
+        Examples:
+            "2023-12-25" -> Frist for Dec 25, 2023
+            "2023-12-25 14:30" -> Frist for Dec 25, 2023 2:30 PM
+            "2023-12-25T14:30:00" -> ISO format datetime
+            "1640995200" -> Frist from Unix timestamp
+        """
+        time_str = time_str.strip()
+
+        # Handle Unix timestamp (all digits)
+        if time_str.isdigit():
+            target_time = dt.datetime.fromtimestamp(float(time_str))
+            return Frist(target_time=target_time, reference_time=reference_time)
+
+        # Try common datetime formats
+        formats = [
+            "%Y-%m-%d",  # 2023-12-25
+            "%Y-%m-%d %H:%M",  # 2023-12-25 14:30
+            "%Y-%m-%d %H:%M:%S",  # 2023-12-25 14:30:00
+            "%Y-%m-%dT%H:%M:%S",  # 2023-12-25T14:30:00 (ISO)
+            "%Y-%m-%dT%H:%M:%SZ",  # 2023-12-25T14:30:00Z (ISO with Z)
+            "%Y/%m/%d",  # 2023/12/25
+            "%Y/%m/%d %H:%M",  # 2023/12/25 14:30
+            "%m/%d/%Y",  # 12/25/2023
+            "%m/%d/%Y %H:%M",  # 12/25/2023 14:30
+        ]
+
+        for fmt in formats:
+            try:
+                target_time = dt.datetime.strptime(time_str, fmt)
+                return Frist(target_time=target_time, reference_time=reference_time)
+            except ValueError:
+                continue
+
+        raise ValueError(f"Unable to parse time string: {time_str}")
+
+    def with_reference_time(self, reference_time: dt.datetime):
+        """
+        Create a new Frist object with a different reference time.
+
+        Args:
+            reference_time: New reference time for calculations
+
+        Returns:
+            New Frist object with same target_time but different reference_time
+        """
+        return Frist(target_time=self.target_time, reference_time=reference_time)
+
+
+    def __repr__(self) -> str:
+        """String representation of Frist object."""
+        return f"Frist(target={self.target_time.isoformat()}, reference={self.reference_time.isoformat()})"
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        return f"Frist for {self.target_time.strftime('%Y-%m-%d %H:%M:%S')}"
+
+
+__all__ = ["Frist"]

frist-0.6.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: frist
+Version: 0.6.0
+Summary: Test Package
+Author: Chuck Bass

frist-0.6.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+frist/__init__.py,sha256=SwjHUWZ3fijtn2ccXhRn13fL8x7AHIZ4Jn-aT_cNhek,851
+frist/_age.py,sha256=2ek2fQqrdQRJJ2Fe_-we7glzCYrqheDBeGGhRX6LfTM,3986
+frist/_cal.py,sha256=V5JWxz4SuYZId7PDPF63Z5ChHkkSp_80dS9o4pN89k0,18918
+frist/_constants.py,sha256=tfzI3STohpXsG58h-9He2ezUmSILauu_yBm7Gd3o3sE,1599
+frist/_frist.py,sha256=GT03d1I9fZEyTlVLVuWWC8cYoFONi_ZpWfPptqHLj6Q,6240
+frist-0.6.0.dist-info/METADATA,sha256=Enqfx3pSK6pYU-Bg2NXvaGPbq8G44n9_Jx7feH5T1qI,95
+frist-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+frist-0.6.0.dist-info/top_level.txt,sha256=o1-mQrds1xg1-gralev0pv2G8GnD_Wwq4QPi6u2XfOA,6
+frist-0.6.0.dist-info/RECORD,,

frist-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frist-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+frist