crashbytes-dateutils 1.0.0__py3-none-any.whl

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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+crashbytes_dateutils/__init__.py,sha256=EC6xrDIY4xU9AGgqYOktEYSXDFb9XVeTdaW2KPz1qJg,795
+crashbytes_dateutils/_core.py,sha256=1ZLSr5_IrTpCprSEzwAKWCyU63BoSVAx1Dwt1lAwU7Q,4505
+crashbytes_dateutils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crashbytes_dateutils-1.0.0.dist-info/METADATA,sha256=-IYvgqBP-xmRIjBw90BubIlfCAnjg41C8zxgvS9Ncig,1986
+crashbytes_dateutils-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+crashbytes_dateutils-1.0.0.dist-info/licenses/LICENSE,sha256=Ic61HOO4EsyXXAGNY-D-1nG62feh_IBbipY1v_QcYcY,1067
+crashbytes_dateutils-1.0.0.dist-info/RECORD,,

crashbytes_dateutils-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

crashbytes_dateutils-1.0.0.dist-info/licenses/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.