crashbytes-dateutils 1.0.0__tar.gz

crashbytes_dateutils-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CrashBytes

crashbytes_dateutils-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: mypy --strict src/
+      - run: pytest --cov=crashbytes_dateutils --cov-branch --cov-fail-under=90

crashbytes_dateutils-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

crashbytes_dateutils-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+

crashbytes_dateutils-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrashBytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crashbytes_dateutils-1.0.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: crashbytes-dateutils
+Version: 1.0.0
+Summary: Zero-dependency datetime business helpers — business days, fiscal quarters, relative strings.
+Project-URL: Homepage, https://github.com/CrashBytes/crashbytes-dateutils
+Project-URL: Repository, https://github.com/CrashBytes/crashbytes-dateutils
+Project-URL: Issues, https://github.com/CrashBytes/crashbytes-dateutils/issues
+Author-email: CrashBytes <crashbytes@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: business-days,date-utilities,datetime,fiscal-quarter
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crashbytes-dateutils
+
+Zero-dependency datetime business helpers — business days, fiscal quarters, relative strings.
+
+## Install
+
+```bash
+pip install crashbytes-dateutils
+```
+
+## Usage
+
+```python
+from datetime import date
+from crashbytes_dateutils import (
+    add_business_days, business_days_between, to_relative_string,
+    fiscal_quarter, age, start_of_month, end_of_month,
+)
+
+add_business_days(date(2024, 6, 14), 1)           # date(2024, 6, 17) — skips weekend
+business_days_between(date(2024, 6, 17), date(2024, 6, 21))  # 4
+to_relative_string(date(2024, 6, 12), today=date(2024, 6, 15))  # "3 days ago"
+fiscal_quarter(date(2024, 7, 15), start_month=7)   # 1
+age(date(1990, 6, 15), today=date(2024, 6, 15))    # 34
+```
+
+## License
+
+MIT

crashbytes_dateutils-1.0.0/README.md

@@ -0,0 +1,29 @@
+# crashbytes-dateutils
+
+Zero-dependency datetime business helpers — business days, fiscal quarters, relative strings.
+
+## Install
+
+```bash
+pip install crashbytes-dateutils
+```
+
+## Usage
+
+```python
+from datetime import date
+from crashbytes_dateutils import (
+    add_business_days, business_days_between, to_relative_string,
+    fiscal_quarter, age, start_of_month, end_of_month,
+)
+
+add_business_days(date(2024, 6, 14), 1)           # date(2024, 6, 17) — skips weekend
+business_days_between(date(2024, 6, 17), date(2024, 6, 21))  # 4
+to_relative_string(date(2024, 6, 12), today=date(2024, 6, 15))  # "3 days ago"
+fiscal_quarter(date(2024, 7, 15), start_month=7)   # 1
+age(date(1990, 6, 15), today=date(2024, 6, 15))    # 34
+```
+
+## License
+
+MIT

crashbytes_dateutils-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crashbytes-dateutils"
+version = "1.0.0"
+description = "Zero-dependency datetime business helpers — business days, fiscal quarters, relative strings."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "CrashBytes", email = "crashbytes@users.noreply.github.com" }]
+keywords = ["datetime", "business-days", "fiscal-quarter", "date-utilities"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "mypy", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/CrashBytes/crashbytes-dateutils"
+Repository = "https://github.com/CrashBytes/crashbytes-dateutils"
+Issues = "https://github.com/CrashBytes/crashbytes-dateutils/issues"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["crashbytes_dateutils"]
+
+[tool.coverage.report]
+fail_under = 90

crashbytes_dateutils-1.0.0/src/crashbytes_dateutils/__init__.py

@@ -0,0 +1,39 @@
+"""crashbytes-dateutils — Zero-dependency datetime business helpers."""
+
+from crashbytes_dateutils._core import (
+    add_business_days,
+    age,
+    business_days_between,
+    end_of_day,
+    end_of_month,
+    end_of_year,
+    fiscal_quarter,
+    fiscal_year,
+    is_business_day,
+    is_weekend,
+    next_business_day,
+    previous_business_day,
+    start_of_day,
+    start_of_month,
+    start_of_year,
+    to_relative_string,
+)
+
+__all__ = [
+    "add_business_days",
+    "age",
+    "business_days_between",
+    "end_of_day",
+    "end_of_month",
+    "end_of_year",
+    "fiscal_quarter",
+    "fiscal_year",
+    "is_business_day",
+    "is_weekend",
+    "next_business_day",
+    "previous_business_day",
+    "start_of_day",
+    "start_of_month",
+    "start_of_year",
+    "to_relative_string",
+]

crashbytes_dateutils-1.0.0/src/crashbytes_dateutils/_core.py

@@ -0,0 +1,155 @@
+"""DateTime business helpers — business days, fiscal quarters, relative strings."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+# Monday=0 ... Sunday=6
+_SATURDAY = 5
+_SUNDAY = 6
+
+
+def start_of_day(dt: datetime) -> datetime:
+    """Return *dt* with time set to 00:00:00."""
+    return dt.replace(hour=0, minute=0, second=0, microsecond=0)
+
+
+def end_of_day(dt: datetime) -> datetime:
+    """Return *dt* with time set to 23:59:59.999999."""
+    return dt.replace(hour=23, minute=59, second=59, microsecond=999999)
+
+
+def start_of_month(d: date) -> date:
+    """Return the first day of the month for *d*."""
+    return d.replace(day=1)
+
+
+def end_of_month(d: date) -> date:
+    """Return the last day of the month for *d*."""
+    if d.month == 12:
+        return d.replace(day=31)
+    return d.replace(month=d.month + 1, day=1) - timedelta(days=1)
+
+
+def start_of_year(d: date) -> date:
+    """Return January 1 of the year for *d*."""
+    return d.replace(month=1, day=1)
+
+
+def end_of_year(d: date) -> date:
+    """Return December 31 of the year for *d*."""
+    return d.replace(month=12, day=31)
+
+
+def is_weekend(d: date) -> bool:
+    """Check if *d* is a Saturday or Sunday."""
+    return d.weekday() >= _SATURDAY
+
+
+def is_business_day(d: date, holidays: Sequence[date] = ()) -> bool:
+    """Check if *d* is a business day (not weekend, not in *holidays*)."""
+    return not is_weekend(d) and d not in holidays
+
+
+def add_business_days(
+    d: date, days: int, holidays: Sequence[date] = ()
+) -> date:
+    """Add *days* business days to *d*, skipping weekends and *holidays*."""
+    if days == 0:
+        return d
+    step = 1 if days > 0 else -1
+    remaining = abs(days)
+    current = d
+    while remaining > 0:
+        current += timedelta(days=step)
+        if is_business_day(current, holidays):
+            remaining -= 1
+    return current
+
+
+def business_days_between(
+    start: date, end: date, holidays: Sequence[date] = ()
+) -> int:
+    """Count business days between *start* (exclusive) and *end* (inclusive)."""
+    if start >= end:
+        return 0
+    count = 0
+    current = start + timedelta(days=1)
+    while current <= end:
+        if is_business_day(current, holidays):
+            count += 1
+        current += timedelta(days=1)
+    return count
+
+
+def to_relative_string(d: date, today: date | None = None) -> str:
+    """Return a human-readable relative string like "3 days ago" or "in 2 weeks"."""
+    if today is None:
+        today = date.today()
+    delta = (d - today).days
+    if delta == 0:
+        return "today"
+    if delta == 1:
+        return "tomorrow"
+    if delta == -1:
+        return "yesterday"
+    abs_days = abs(delta)
+    if abs_days < 7:
+        unit = "day" if abs_days == 1 else "days"
+        label = f"{abs_days} {unit}"
+    elif abs_days < 30:
+        weeks = abs_days // 7
+        unit = "week" if weeks == 1 else "weeks"
+        label = f"{weeks} {unit}"
+    elif abs_days < 365:
+        months = abs_days // 30
+        unit = "month" if months == 1 else "months"
+        label = f"{months} {unit}"
+    else:
+        years = abs_days // 365
+        unit = "year" if years == 1 else "years"
+        label = f"{years} {unit}"
+    return f"in {label}" if delta > 0 else f"{label} ago"
+
+
+def age(birth: date, today: date | None = None) -> int:
+    """Calculate age in years from *birth* to *today*."""
+    if today is None:
+        today = date.today()
+    years = today.year - birth.year
+    if (today.month, today.day) < (birth.month, birth.day):
+        years -= 1
+    return years
+
+
+def fiscal_quarter(d: date, start_month: int = 1) -> int:
+    """Return fiscal quarter (1–4) for *d*.
+
+    *start_month* is the first month of the fiscal year (default: January).
+    """
+    adjusted = (d.month - start_month) % 12
+    return adjusted // 3 + 1
+
+
+def fiscal_year(d: date, start_month: int = 1) -> int:
+    """Return fiscal year for *d*.
+
+    *start_month* is the first month of the fiscal year.
+    """
+    if d.month >= start_month:
+        return d.year
+    return d.year - 1
+
+
+def next_business_day(d: date, holidays: Sequence[date] = ()) -> date:
+    """Return the next business day after *d*."""
+    return add_business_days(d, 1, holidays)
+
+
+def previous_business_day(d: date, holidays: Sequence[date] = ()) -> date:
+    """Return the previous business day before *d*."""
+    return add_business_days(d, -1, holidays)

crashbytes_dateutils-1.0.0/tests/test_dateutils.py

@@ -0,0 +1,209 @@
+"""Tests for crashbytes-dateutils."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from crashbytes_dateutils import (
+    add_business_days,
+    age,
+    business_days_between,
+    end_of_day,
+    end_of_month,
+    end_of_year,
+    fiscal_quarter,
+    fiscal_year,
+    is_business_day,
+    is_weekend,
+    next_business_day,
+    previous_business_day,
+    start_of_day,
+    start_of_month,
+    start_of_year,
+    to_relative_string,
+)
+
+
+class TestStartEndOfDay:
+    def test_start_of_day(self) -> None:
+        dt = datetime(2024, 6, 15, 14, 30, 45, 123456)
+        result = start_of_day(dt)
+        assert result == datetime(2024, 6, 15, 0, 0, 0, 0)
+
+    def test_end_of_day(self) -> None:
+        dt = datetime(2024, 6, 15, 14, 30, 45)
+        result = end_of_day(dt)
+        assert result == datetime(2024, 6, 15, 23, 59, 59, 999999)
+
+
+class TestStartEndOfMonth:
+    def test_start_of_month(self) -> None:
+        assert start_of_month(date(2024, 6, 15)) == date(2024, 6, 1)
+
+    def test_end_of_month_june(self) -> None:
+        assert end_of_month(date(2024, 6, 15)) == date(2024, 6, 30)
+
+    def test_end_of_month_february_leap(self) -> None:
+        assert end_of_month(date(2024, 2, 1)) == date(2024, 2, 29)
+
+    def test_end_of_month_february_non_leap(self) -> None:
+        assert end_of_month(date(2023, 2, 1)) == date(2023, 2, 28)
+
+    def test_end_of_month_december(self) -> None:
+        assert end_of_month(date(2024, 12, 1)) == date(2024, 12, 31)
+
+
+class TestStartEndOfYear:
+    def test_start_of_year(self) -> None:
+        assert start_of_year(date(2024, 6, 15)) == date(2024, 1, 1)
+
+    def test_end_of_year(self) -> None:
+        assert end_of_year(date(2024, 6, 15)) == date(2024, 12, 31)
+
+
+class TestWeekend:
+    def test_saturday(self) -> None:
+        assert is_weekend(date(2024, 6, 15)) is True  # Saturday
+
+    def test_sunday(self) -> None:
+        assert is_weekend(date(2024, 6, 16)) is True  # Sunday
+
+    def test_monday(self) -> None:
+        assert is_weekend(date(2024, 6, 17)) is False  # Monday
+
+    def test_friday(self) -> None:
+        assert is_weekend(date(2024, 6, 14)) is False  # Friday
+
+
+class TestBusinessDay:
+    def test_weekday(self) -> None:
+        assert is_business_day(date(2024, 6, 17)) is True  # Monday
+
+    def test_weekend(self) -> None:
+        assert is_business_day(date(2024, 6, 15)) is False  # Saturday
+
+    def test_holiday(self) -> None:
+        holidays = [date(2024, 6, 17)]
+        assert is_business_day(date(2024, 6, 17), holidays) is False
+
+
+class TestAddBusinessDays:
+    def test_add_one(self) -> None:
+        # Friday + 1 = Monday
+        assert add_business_days(date(2024, 6, 14), 1) == date(2024, 6, 17)
+
+    def test_add_five(self) -> None:
+        # Monday + 5 = next Monday
+        assert add_business_days(date(2024, 6, 17), 5) == date(2024, 6, 24)
+
+    def test_add_zero(self) -> None:
+        d = date(2024, 6, 17)
+        assert add_business_days(d, 0) is d
+
+    def test_subtract_one(self) -> None:
+        # Monday - 1 = previous Friday
+        assert add_business_days(date(2024, 6, 17), -1) == date(2024, 6, 14)
+
+    def test_with_holidays(self) -> None:
+        holidays = [date(2024, 6, 17)]  # Monday is holiday
+        # Friday + 1, skip Monday holiday = Tuesday
+        assert add_business_days(date(2024, 6, 14), 1, holidays) == date(2024, 6, 18)
+
+
+class TestBusinessDaysBetween:
+    def test_same_week(self) -> None:
+        # Mon to Fri = 4 business days
+        assert business_days_between(date(2024, 6, 17), date(2024, 6, 21)) == 4
+
+    def test_across_weekend(self) -> None:
+        # Fri to next Mon = 1 business day
+        assert business_days_between(date(2024, 6, 14), date(2024, 6, 17)) == 1
+
+    def test_same_day(self) -> None:
+        assert business_days_between(date(2024, 6, 17), date(2024, 6, 17)) == 0
+
+    def test_start_after_end(self) -> None:
+        assert business_days_between(date(2024, 6, 20), date(2024, 6, 17)) == 0
+
+    def test_with_holidays(self) -> None:
+        holidays = [date(2024, 6, 18)]
+        # Mon to Fri, minus Tuesday holiday = 3
+        assert business_days_between(date(2024, 6, 17), date(2024, 6, 21), holidays) == 3
+
+
+class TestRelativeString:
+    def test_today(self) -> None:
+        d = date(2024, 6, 15)
+        assert to_relative_string(d, today=d) == "today"
+
+    def test_tomorrow(self) -> None:
+        assert to_relative_string(date(2024, 6, 16), today=date(2024, 6, 15)) == "tomorrow"
+
+    def test_yesterday(self) -> None:
+        assert to_relative_string(date(2024, 6, 14), today=date(2024, 6, 15)) == "yesterday"
+
+    def test_days_ago(self) -> None:
+        assert to_relative_string(date(2024, 6, 12), today=date(2024, 6, 15)) == "3 days ago"
+
+    def test_days_future(self) -> None:
+        assert to_relative_string(date(2024, 6, 18), today=date(2024, 6, 15)) == "in 3 days"
+
+    def test_weeks(self) -> None:
+        assert to_relative_string(date(2024, 5, 25), today=date(2024, 6, 15)) == "3 weeks ago"
+
+    def test_months(self) -> None:
+        assert to_relative_string(date(2024, 3, 15), today=date(2024, 6, 15)) == "3 months ago"
+
+    def test_years(self) -> None:
+        assert to_relative_string(date(2022, 6, 15), today=date(2024, 6, 15)) == "2 years ago"
+
+    def test_1_week(self) -> None:
+        assert to_relative_string(date(2024, 6, 22), today=date(2024, 6, 15)) == "in 1 week"
+
+    def test_1_month(self) -> None:
+        assert to_relative_string(date(2024, 7, 15), today=date(2024, 6, 15)) == "in 1 month"
+
+    def test_1_year(self) -> None:
+        assert to_relative_string(date(2025, 6, 15), today=date(2024, 6, 15)) == "in 1 year"
+
+
+class TestAge:
+    def test_basic(self) -> None:
+        assert age(date(1990, 6, 15), today=date(2024, 6, 15)) == 34
+
+    def test_before_birthday(self) -> None:
+        assert age(date(1990, 6, 15), today=date(2024, 6, 14)) == 33
+
+    def test_after_birthday(self) -> None:
+        assert age(date(1990, 6, 15), today=date(2024, 6, 16)) == 34
+
+
+class TestFiscalQuarter:
+    def test_calendar_year(self) -> None:
+        assert fiscal_quarter(date(2024, 1, 15)) == 1
+        assert fiscal_quarter(date(2024, 4, 15)) == 2
+        assert fiscal_quarter(date(2024, 7, 15)) == 3
+        assert fiscal_quarter(date(2024, 10, 15)) == 4
+
+    def test_fiscal_year_july(self) -> None:
+        assert fiscal_quarter(date(2024, 7, 15), start_month=7) == 1
+        assert fiscal_quarter(date(2024, 10, 15), start_month=7) == 2
+        assert fiscal_quarter(date(2025, 1, 15), start_month=7) == 3
+        assert fiscal_quarter(date(2025, 4, 15), start_month=7) == 4
+
+
+class TestFiscalYear:
+    def test_calendar_year(self) -> None:
+        assert fiscal_year(date(2024, 6, 15)) == 2024
+
+    def test_fiscal_year_july(self) -> None:
+        assert fiscal_year(date(2024, 7, 15), start_month=7) == 2024
+        assert fiscal_year(date(2024, 6, 15), start_month=7) == 2023
+
+
+class TestNextPrevBusinessDay:
+    def test_next_from_friday(self) -> None:
+        assert next_business_day(date(2024, 6, 14)) == date(2024, 6, 17)
+
+    def test_previous_from_monday(self) -> None:
+        assert previous_business_day(date(2024, 6, 17)) == date(2024, 6, 14)