frist 0.7.0__tar.gz

frist-0.7.0/PKG-INFO

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

frist-0.7.0/README.md

@@ -0,0 +1,213 @@
+
+
+# Frist
+
+Frist is a property-based date and time utility for Python, designed to make relative date calculations and calendar logic simple and intuitive—without manual math. You create a Frist object with a target time (when something happened) and a reference time (usually "now").
+
+Frist lets you answer questions like "Did this event happen today, this month, or this year?" using properties such as `in_day`, `in_month`, and `in_year`. These properties check if the target time lands anywhere in the current time unit window—even exactly at the start or end. You can also use ranges, like `in_days(-7, 0)` for "in the last 7 days" or `in_months(-1, 1)` for "from last month to next month." This is different from `.age.days`, which gives you the precise floating-point age in days between the target and reference times.
+
+With Frist, you get instant answers to time-based questions with a single property, instead of writing complex date math. This makes it easy to work with calendar windows, fiscal periods, and custom time ranges.
+
+---
+
+**Note:** In German, "Frist" means "deadline" or "time limit." This reflects the package's focus on time windows, periods, and calendar logic.
+
+## Key Concepts
+
+- **Property-based API:** Most calculations are exposed as properties (e.g., `.age.days`, `.fiscal_year`, `.holiday`), not methods, so you rarely need to call functions or do arithmetic.
+- **Minimal math required:** You can answer most date and calendar questions by accessing properties, not by writing formulas.
+- **Flexible reference time:** Zeit lets you compare any target date/time to any reference date/time, not just "now".
+- **Calendar and fiscal logic:** Built-in support for calendar windows (days, weeks, months, quarters, years) and fiscal year/quarter calculations.
+- **Holiday detection:** Pass a set of holiday dates and instantly check if a date is a holiday.
+
+
+## Quick Start
+
+```python
+import datetime as dt
+from frist import Frist
+
+# Create a Frist object for a target date
+meeting = Frist(target_time=dt.datetime(2025, 12, 25))
+
+# Check age properties
+print(meeting.age.days)      # Days since meeting
+print(meeting.age.hours)     # Hours since meeting
+
+# Calendar windows
+if meeting.cal.in_days(0):
+  print("Meeting is today!")
+if meeting.cal.in_weeks(-1):
+  print("Meeting was last week.")
+
+# Fiscal year and quarter
+print(meeting.fiscal_year)      # Fiscal year for the meeting
+print(meeting.fiscal_quarter)   # Fiscal quarter for the meeting
+
+# Holiday detection
+holidays = {'2025-12-25', '2025-01-01'}
+meeting = Frist(target_time=dt.datetime(2025, 12, 25), holidays=holidays)
+if meeting.holiday:
+  print("This date is a holiday!")
+
+# Compare to a custom reference time
+project = Frist(target_time=dt.datetime(2025, 1, 1), reference_time=dt.datetime(2025, 2, 1))
+print(project.age.days)  # Days between Jan 1 and Feb 1, 2025
+```
+
+## Features
+
+## Time Scale Properties Table
+
+| Time Scale    | Age Property         | Window Function(s)                    |
+|-------------- |----------------------|---------------------------------------|
+| Seconds       | `.age.seconds`       | `.cal.in_seconds(start, end)`         |
+| Minutes       | `.age.minutes`       | `.cal.in_minutes(start, end)`         |
+| Hours         | `.age.hours`         | `.cal.in_hours(start, end)`           |
+| Days          | `.age.days`          | `.cal.in_days(start, end)`            |
+| Weeks         | `.age.weeks`         | `.cal.in_weeks(start, end)`           |
+| Months        | `.age.months`        | `.cal.in_months(start, end)`          |
+| Quarters      | `.age.quarters`      | `.cal.in_quarters(start, end)`        |
+| Years         | `.age.years`         | `.cal.in_years(start, end)`           |
+| Fiscal Years  | `.age.fiscal_year`   | `.cal.in_fiscal_years(start, end)`    |
+| Fiscal Qtrs   | `.age.fiscal_quarter`| `.cal.in_fiscal_quarters(start, end)` |
+
+Each age property gives the precise floating-point difference in that unit. Each window function generates a boolean if the target time falls within the specified range of time units relative to the reference time.
+Age properties (like `.age.days`) are designed for direct comparisons—use them to ask questions like `>`, `<`, `==`, or `!=` between the target and reference times. In contrast, the `in_*` window functions (like `.cal.in_days()`) return `True` or `False` depending on whether the target time falls within the specified range.
+Note: The `end` parameter is optional. If omitted, the function checks for a single time unit (e.g., `.cal.in_days(0)` means "today").
+
+
+## Fiscal Year & Quarter Example
+
+Frist supports fiscal year and quarter calculations with customizable fiscal year start months. For example:
+
+```python
+# Fiscal year starts in April (fy_start_month=4)
+meeting = Frist(target_time=dt.datetime(2025, 7, 15), fy_start_month=4)
+print(meeting.fiscal_year)      # 2025 (fiscal year for July 15, 2025)
+print(meeting.fiscal_quarter)   # 2 (Q2: July–September for April start)
+
+# Check if a date is in a fiscal quarter or year window
+if meeting.cal.in_fiscal_quarters(0):
+  print("Meeting is in the current fiscal quarter.")
+if meeting.cal.in_fiscal_years(0):
+  print("Meeting is in the current fiscal year.")
+```
+
+
+## Holiday Detection Example
+
+Frist can instantly check if a date is a holiday using a set of holiday dates:
+
+```python
+holidays = {
+  '2025-12-25',  # Christmas
+  '2025-01-01',  # New Year's Day
+  '2025-07-04',  # Independence Day
+}
+
+# Check a specific date
+meeting = Frist(target_time=dt.datetime(2025, 12, 25), holidays=holidays)
+if meeting.holiday:
+  print("Meeting date is a holiday!")
+
+# Check multiple dates
+for date_str in holidays:
+  date = dt.datetime.strptime(date_str, '%Y-%m-%d')
+  c = Frist(target_time=date, holidays=holidays)
+  print(f"{date.date()}: Holiday? {c.holiday}")
+
+# Use with custom reference time
+project = Frist(target_time=dt.datetime(2025, 7, 4), reference_time=dt.datetime(2025, 7, 5), holidays=holidays)
+if project.holiday:
+  print("Project start date is a holiday!")
+```
+
+## Short Examples
+
+
+### Age Calculation
+
+```python
+person = Frist(target_time=dt.datetime(1990, 5, 1), reference_time=dt.datetime(2025, 5, 1))
+print(f"Age in days: {person.age.days}, Age in years: {person.age.years:.2f}")
+```
+
+
+### Calendar Windows
+
+```python
+meeting = Frist(target_time=dt.datetime(2025, 12, 25))
+if meeting.cal.in_days(0):
+  print("Meeting is today!")
+if meeting.cal.in_weeks(-1):
+  print("Meeting was last week.")
+```
+
+## API Reference
+
+
+### Frist
+
+`Frist(target_time: datetime, reference_time: datetime = None, fy_start_month: int = 1, holidays: set[str] = None)`
+
+- **Properties:**
+  - `age`: Age object with properties for `.days`, `.hours`, `.minutes`, `.seconds`, `.weeks`, `.months`, `.quarters`, `.years`, `.fiscal_year`, `.fiscal_quarter`.
+  - `cal`: Cal object for calendar window logic.
+  - `fiscal_year`: Fiscal year for the target time.
+  - `fiscal_quarter`: Fiscal quarter for the target time.
+  - `holiday`: True if target time is a holiday (if holidays set provided).
+
+### Cal
+
+`Cal(time_span: TimeSpan, fy_start_month: int = 1, holidays: set[str] = None)`
+
+- **Properties:**
+  - `dt_val`: Target datetime.
+  - `base_time`: Reference datetime.
+  - `fiscal_year`: Fiscal year for `dt_val`.
+  - `fiscal_quarter`: Fiscal quarter for `dt_val`.
+  - `holiday`: True if `dt_val` is a holiday.
+  - `time_span`: The TimeSpan object.
+
+- **Interval Methods:**
+  - `in_minutes(start: int = 0, end: int | None = None) -> bool`
+  - `in_hours(start: int = 0, end: int | None = None) -> bool`
+  - `in_days(start: int = 0, end: int | None = None) -> bool`
+  - `in_weeks(start: int = 0, end: int | None = None, week_start: str = "monday") -> bool`
+  - `in_months(start: int = 0, end: int | None = None) -> bool`
+  - `in_quarters(start: int = 0, end: int | None = None) -> bool`
+  - `in_years(start: int = 0, end: int | None = None) -> bool`
+  - `in_fiscal_quarters(start: int = 0, end: int | None = None) -> bool`
+  - `in_fiscal_years(start: int = 0, end: int | None = None) -> bool`
+
+- **Static Methods:**
+  - `get_fiscal_year(dt: datetime, fy_start_month: int) -> int`
+  - `get_fiscal_quarter(dt: datetime, fy_start_month: int) -> int`
+
+- **Exceptions:**
+  - All interval methods raise `ValueError` if `start > end`.
+  - `normalize_weekday(day_spec: str) -> int` raises `ValueError` for invalid day specifications, with detailed error messages.
+
+### Age
+
+`Age(target_time: datetime, reference_time: datetime)`
+
+- **Properties:**
+  - `days`, `hours`, `minutes`, `seconds`, `weeks`, `months`, `quarters`, `years`, `fiscal_year`, `fiscal_quarter`
+
+### TimeSpan (Protocol)
+
+`TimeSpan`
+
+- **Properties:**
+  - `target_dt`: Target datetime.
+  - `ref_dt`: Reference datetime.
+
+---
+
+## Testing and Support
+
+[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/hucker/zeit/actions)
+[![Ruff](https://img.shields.io/badge/ruff-100%25%20clean-brightgreen?logo=ruff&logoColor=white)](https://github.com/charliermarsh/ruff)

frist-0.7.0/pyproject.toml

@@ -0,0 +1,14 @@
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frist"
+version = "0.7.0"
+description = "Test Package"
+authors = [{name = "Chuck Bass"}]
+
+[tool.setuptools]
+packages = ["frist"]
+package-dir = {"" = "src"}

frist-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frist-0.7.0/src/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.7.0"
+__author__ = "Chuck Bass"
+
+__all__ = ["Frist", "Age", "Cal", "TimeSpan"]

frist-0.7.0/src/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"]