bell-schedule 0.7.0__py3-none-any.whl

bell_schedule-0.7.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: bell-schedule
+Version: 0.7.0
+Summary: A framework-agnostic library for querying school bell schedules (Python port)
+Author: Peter Seibel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gigamonkey/bells
+Project-URL: Repository, https://github.com/gigamonkey/bells
+Project-URL: Bug Tracker, https://github.com/gigamonkey/bells/issues
+Keywords: bell schedule,school,calendar,timetable,bells,education
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# bells (Python)
+
+A framework-agnostic Python library for querying school bell schedules. This is
+a port of the [`@peterseibel/bells`](https://github.com/gigamonkey/bells/tree/main/libs/ts) JavaScript library, kept
+behaviorally identical to it.
+
+Where the JS library is built on the [Temporal API](https://tc39.es/proposal-temporal/),
+this port uses only the Python standard library:
+
+| Temporal                | Python                                     |
+| ----------------------- | ------------------------------------------ |
+| `Temporal.PlainDate`    | `datetime.date`                            |
+| `Temporal.PlainTime`    | `datetime.time`                            |
+| `Temporal.Instant`      | timezone-aware `datetime.datetime` in UTC  |
+| `Temporal.Duration`     | `datetime.timedelta`                       |
+| `Temporal.PlainDateTime`| naive `datetime.datetime`                  |
+
+An "instant" throughout the package is an aware `datetime` normalized to UTC.
+
+Requires Python 3.9+ (uses `zoneinfo`). No third-party dependencies.
+
+## Calendar data format
+
+The calendar data format is identical to the JS library — see [`libs/ts/README.md`](https://github.com/gigamonkey/bells/blob/main/libs/ts/README.md)
+for the full field reference. Briefly, calendar data is a list of year objects:
+
+```json
+[
+  {
+    "year": "2025-2026",
+    "id": "bhs",
+    "name": "Berkeley High School",
+    "timezone": "America/Los_Angeles",
+    "firstDay": "2025-08-13",
+    "firstDayTeachers": "2025-08-11",
+    "lastDay": "2026-06-04",
+    "schedules": {
+      "NORMAL": [
+        { "name": "Period 1", "start": "8:30", "end": "9:28" },
+        { "name": "Period 2", "start": "9:34", "end": "10:37" }
+      ]
+    },
+    "weekdaySchedules": { "monday": "LATE_START" },
+    "holidays": ["2025-09-01"]
+  }
+]
+```
+
+## API
+
+The public API mirrors the JS one, with method names converted to
+`snake_case` and options passed as a dict with snake_case keys (`role`,
+`include_tags`).
+
+```python
+import json
+from bells import BellSchedule
+
+with open("my-calendars.json") as f:
+    data = json.load(f)
+
+bells = BellSchedule(data, {
+    "role": "student",          # "student" | "teacher"  (default: "student")
+    "include_tags": {
+        1: ["seventh"],         # Monday: include Period 7
+        2: ["zero", "seventh"],
+    },
+    # Or a flat list for the same tags every weekday:
+    # "include_tags": ["seventh"],
+
+    # Which periods are "numbered" and what number they carry, for the
+    # abstract-time API. Default: match r"^Period (\d+)\b" in the name.
+    # "period_number": lambda period: ...int or None...,
+})
+
+# What's happening right now?
+interval = bells.current_interval()
+print(interval.name)        # e.g. "Period 3"
+print(interval.type)        # 'period' | 'passing' | 'before-school' | 'after-school' | 'break'
+print(interval.left())      # timedelta until end of interval
+
+# Other queries (all accept an optional aware datetime instant):
+bells.period_at()                 # Interval | None (None unless a period)
+bells.is_school_day()             # bool (accepts an optional date)
+bells.current_day_bounds()        # {"start": ..., "end": ...} | None
+bells.next_school_day_start()     # datetime
+bells.previous_school_day_end()   # datetime
+bells.school_time_left()          # timedelta
+bells.school_time_done()          # timedelta
+bells.total_school_time()         # timedelta
+bells.school_days_left()          # int
+bells.calendar_days_left()        # int
+bells.next_year_start()           # datetime (raises if not loaded)
+bells.school_time_between(a, b)   # timedelta
+bells.summer_bounds()             # {"start": ..., "end": ...} | None
+```
+
+### Abstract times
+
+An *abstract time* describes a moment relative to the schedule — "five minutes
+before the end of the period", "start of school next Monday" — rather than as a
+wall-clock time. It has three independent parts: a *day spec* (which date,
+possibly relative to a base date), a *time anchor* (a schedule-defined point in
+that day: `start_of_period`, `end_of_period`, `start_of_day`, `end_of_day`, or
+`midnight`), and a signed `HH:MM` offset.
+
+Resolution happens in two phases, so the period can stay unbound until query
+time (a stored "start of period" resolves differently for a period-2 class than
+a period-5 class). The types are plain dicts; `parse_time`/`format_time` need no
+calendar.
+
+```python
+from bells import parse_time, format_time
+
+# Standalone — no calendar needed:
+t = parse_time("end_of_period -00:05 +1 day")
+format_time(t)                     # canonical round-trip
+
+# Phase 1 (load time): bind the day spec against a base date. Warnings for
+# specs that don't make sense against the calendar (e.g. a school anchor on a
+# holiday) are reported via the callback (default: print to stderr).
+bound = bells.bind_time(base_date, t, lambda warning: print(warning))
+# → {"date": "2026-01-06", "anchor": "end_of_period", "offset": "-00:05"}
+
+# Phase 2 (query time): resolve to a concrete moment (an aware datetime in the
+# schedule's timezone), supplying the period if the anchor needs one. None when
+# the date has no schedule or no such period.
+bells.resolve_time(bound, 3)       # datetime | None
+
+# Pieces of the above, usable directly:
+bells.resolve_day(base_date, t.get("day"))   # date
+bells.time_warnings(bound)                    # list[str] (empty = OK)
+bells.add_school_days(d, 3)                    # n school days out (n may be negative)
+bells.period_on_date(d, 3)                     # period dict | None
+bells.current_or_next_period_number()          # int | None
+```
+
+The string syntax is `anchor [time-offset] [day-part]`, whitespace-separated
+and case-insensitive (e.g. `end_of_period -00:05`, `start_of_day next week`,
+`end_of_day +1 day`, `midnight +1 week`, `start_of_day 2026-01-05`). Day-part
+semantics: `±N day(s)` counts *school* days; `±N week(s)` is literal calendar
+arithmetic (no snapping); a weekday name means the first such day strictly after
+the base date, taken literally even if it's a holiday; the week boundaries
+(`start of [next] week`, `end of [next] week`) snap to the first/last school day
+of the ISO week. `start of week` on a week with no school days advances to the
+first day back (with a warning); `end of week` on such a week raises. Resolution
+that runs past the loaded calendars raises an `IndexError`.
+
+### `Calendars`
+
+For loading per-year JSON files from a directory or URL:
+
+```python
+from bells import Calendars
+
+calendars = Calendars("./calendars/")        # or "https://example.com/calendars/"
+
+bells = calendars.for_year("2025-2026", options)
+bells = calendars.current(options)            # handles summer automatically
+```
+
+Files must be named `{year}.json` (e.g. `2025-2026.json`). Local paths are read
+from disk; URL bases are fetched with `urllib`.
+
+### `bhs-calendars` (bundled BHS data)
+
+As an alternative to supplying your own `{year}.json` files, the companion
+`bhs-calendars` package ships ready-to-use calendar data for Berkeley High and
+nearby middle schools. `by_id()` groups the bundled years by school (each
+group's years sorted chronologically); hand one group straight to
+`BellSchedule`:
+
+```python
+from bhs_calendars import by_id, load_all
+from bells import BellSchedule
+
+years = by_id()["bhs"]                 # one school's years, oldest first
+bells = BellSchedule(years, options)
+
+all_years = load_all()                 # or the flat list of every school-year
+```
+
+Install it alongside the library (`pip install bhs-calendars`). Unlike
+`Calendars`, the data is bundled with the package — no filesystem layout or
+network access — but it only covers the BHS-area schools. Equivalent data
+packages exist for the [TypeScript](https://github.com/gigamonkey/bells/tree/main/libs/ts) (`@peterseibel/bhs-calendars` on npm)
+and [Java](https://github.com/gigamonkey/bells/tree/main/libs/java) (`com.gigamonkeys:bhs-calendars`) ports.
+
+### Validation
+
+```python
+from bells import validate_calendar_data
+
+result = validate_calendar_data(data)
+if not result["valid"]:
+    print(result["errors"])
+```
+
+CLI:
+
+```sh
+bells-validate calendars.json          # after `pip install .`
+python -m bells.cli calendars.json     # without installing
+```
+
+## Tests
+
+```sh
+cd libs/python
+python -m pytest
+```
+
+The test suite is a port of the JS test suite. A behavioral cross-check against
+the JS library on the real BHS calendars produces identical results.

bell_schedule-0.7.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+bell_schedule-0.7.0.dist-info/licenses/LICENSE,sha256=SYzcv7abfLjQvCJUokP_qhSM3iCV0tHd6mXx3UlrtZA,1074
+bells/__init__.py,sha256=wwbkgA9LDtq93OSXsAoWM4tWV8WXJq6VhLSmIg-uDgs,721
+bells/abstract_time.py,sha256=bGpzUTYi2Hq8u8Z1MmSBiDmzWjk25BfryjY9hPhtSbY,6567
+bells/bell_schedule.py,sha256=HVwRZPPXcWJmuH3RShiJgoPbjRfwRAcbphNcwaWhQvI,19425
+bells/calendar.py,sha256=8ngDw7O3fljNtXwCcZhObp8-dUrQXgYc1GlqCRjDXlY,17961
+bells/calendars.py,sha256=AIFt3wwegeUIwmwCWGnIAMXC0w4QdtTVVyIQ2oAZ_P8,3927
+bells/cli.py,sha256=6fDCwha7F9FfZUuj0UJapJsm3Hx5-sLqBbEGKYDI7Ks,1666
+bells/datetimeutil.py,sha256=XQUOYRJsnk7Xzq3xnkUybJoq9QZvxPpsVlZOVhZ5cWw,6135
+bells/validate.py,sha256=pO0VUCIX7u2c3WOwHDnbpeEMy85rvbX4faNn93DnxXc,12726
+bell_schedule-0.7.0.dist-info/METADATA,sha256=mqoMc1UE9K1tFNBzldmAnPWpGp6wsbaQJDWhbHrMEiE,9498
+bell_schedule-0.7.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bell_schedule-0.7.0.dist-info/entry_points.txt,sha256=T96xLhgrFtAzoVSfKcS62ea5ebJ5Nq-xrY70XmJ81UE,50
+bell_schedule-0.7.0.dist-info/top_level.txt,sha256=0efalOUwO-jvfeJ3c844fmuUgV1rPELoayjda1orGf8,6
+bell_schedule-0.7.0.dist-info/RECORD,,

bell_schedule-0.7.0.dist-info/WHEEL

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

bell_schedule-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bells-validate = bells.cli:main

bell_schedule-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Peter Seibel
+
+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.

bell_schedule-0.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bells

bells/__init__.py

@@ -0,0 +1,26 @@
+"""bells — a framework-agnostic library for querying school bell schedules.
+
+Python port of the ``@peterseibel/bells`` JavaScript library. Built on the
+standard library ``datetime`` and ``zoneinfo`` modules instead of Temporal.
+"""
+
+from .abstract_time import format_time, parse_time
+from .bell_schedule import BellSchedule
+from .calendar import Calendar, Interval, Period, Schedule, normalize_include_tags
+from .calendars import Calendars
+from .validate import validate_calendar_data
+
+__all__ = [
+    "BellSchedule",
+    "Calendars",
+    "Calendar",
+    "Schedule",
+    "Period",
+    "Interval",
+    "normalize_include_tags",
+    "validate_calendar_data",
+    "parse_time",
+    "format_time",
+]
+
+__version__ = "0.5.0"

bells/abstract_time.py

@@ -0,0 +1,198 @@
+"""Abstract times: moments described relative to the school schedule ("five
+minutes before the end of the period", "start of school next Monday") rather
+than as wall-clock times.
+
+Python counterpart of the JavaScript ``abstract-time.js`` module. An abstract
+time has three independent parts: a day spec (which date, possibly relative to
+a base date), a time anchor (a schedule-defined point in that day), and a
+signed HH:MM offset. Resolution happens in two phases: day binding
+(:meth:`BellSchedule.bind_time`, producing a bound time) and time resolution
+(:meth:`BellSchedule.resolve_time`, supplying the period if the anchor needs
+one).
+
+This module holds the types and the string syntax (:func:`parse_time` /
+:func:`format_time`); everything that needs a calendar lives on BellSchedule.
+
+The types are plain dicts, mirroring the rest of the Python port:
+
+- ``AbstractTime``: ``{"anchor": str, "offset"?: str, "day"?: DaySpec}``
+- ``BoundTime``: ``{"date": str, "anchor": str, "offset": str}``
+- ``DaySpec``: ``{"type": "date", "date": str}`` |
+  ``{"type": "schoolDays"|"weeks", "n": int}`` |
+  ``{"type": "weekday", "weekday": int}`` |
+  ``{"type": "week", "edge": "start"|"end", "n": int}``
+
+Anchors: ``start_of_period``, ``end_of_period``, ``start_of_day``,
+``end_of_day``, ``midnight``.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+
+ANCHORS = (
+    "start_of_period",
+    "end_of_period",
+    "start_of_day",
+    "end_of_day",
+    "midnight",
+)
+
+WEEKDAY_NUMBERS = {
+    "monday": 1, "mon": 1,
+    "tuesday": 2, "tue": 2,
+    "wednesday": 3, "wed": 3,
+    "thursday": 4, "thu": 4,
+    "friday": 5, "fri": 5,
+    "saturday": 6, "sat": 6,
+    "sunday": 7, "sun": 7,
+}
+
+WEEKDAY_NAMES = {
+    1: "monday",
+    2: "tuesday",
+    3: "wednesday",
+    4: "thursday",
+    5: "friday",
+    6: "saturday",
+    7: "sunday",
+}
+
+_OFFSET_RE = re.compile(r"^([+-]?)(\d{1,2}):(\d{2})$")
+
+# A signed time-offset token: the string syntax requires the sign.
+_OFFSET_TOKEN_RE = re.compile(r"^[+-]\d{1,2}:\d{2}$")
+
+_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+_SIGNED_INT_RE = re.compile(r"^([+-])(\d+)$")
+
+
+def parse_offset_minutes(offset: str) -> int:
+    """Parse an ``'[-+]HH:MM'`` offset into signed minutes.
+
+    The sign is optional here (stored offsets may be unsigned, e.g. ``'00:00'``);
+    the string syntax requires it so an offset token is unambiguous.
+    """
+    m = _OFFSET_RE.match(offset)
+    if m:
+        minutes = int(m.group(3))
+        if minutes <= 59:
+            total = int(m.group(2)) * 60 + minutes
+            return -total if m.group(1) == "-" else total
+    raise ValueError(f'Invalid time offset "{offset}"')
+
+
+def _format_offset(minutes: int) -> str:
+    sign = "-" if minutes < 0 else "+"
+    abs_minutes = abs(minutes)
+    return f"{sign}{abs_minutes // 60:02d}:{abs_minutes % 60:02d}"
+
+
+def _parse_day_part(tokens: list[str]) -> dict:
+    def bad() -> ValueError:
+        return ValueError(f'Unrecognized day part "{" ".join(tokens)}"')
+
+    if len(tokens) == 1:
+        tok = tokens[0]
+        if _ISO_DATE_RE.match(tok):
+            try:
+                date.fromisoformat(tok)
+            except ValueError:
+                raise ValueError(f'Invalid date "{tok}"')
+            return {"type": "date", "date": tok}
+        if tok in WEEKDAY_NUMBERS:
+            return {"type": "weekday", "weekday": WEEKDAY_NUMBERS[tok]}
+        raise bad()
+
+    if len(tokens) == 2:
+        if tokens[0] == "next" and tokens[1] == "week":
+            return {"type": "week", "edge": "start", "n": 1}
+        if _SIGNED_INT_RE.match(tokens[0]):
+            n = int(tokens[0])
+            if tokens[1] in ("day", "days"):
+                return {"type": "schoolDays", "n": n}
+            if tokens[1] in ("week", "weeks"):
+                return {"type": "weeks", "n": n}
+        raise bad()
+
+    if tokens[0] in ("start", "end") and tokens[1] == "of":
+        if len(tokens) == 3 and tokens[2] == "week":
+            return {"type": "week", "edge": tokens[0], "n": 0}
+        if len(tokens) == 4 and tokens[2] == "next" and tokens[3] == "week":
+            return {"type": "week", "edge": tokens[0], "n": 1}
+
+    raise bad()
+
+
+def parse_time(spec: str) -> dict:
+    """Parse the compact one-line syntax: ``anchor [time-offset] [day-part]``,
+    whitespace-separated, case-insensitive. E.g. ``'end_of_period -00:05'``,
+    ``'start_of_day next week'``, ``'end_of_day +1 day'``. Raises on unknown
+    anchors, malformed offsets, and unrecognized day parts.
+    """
+    tokens = spec.strip().lower().split()
+    if not tokens:
+        raise ValueError("Empty abstract-time spec")
+
+    anchor = tokens.pop(0)
+    if anchor not in ANCHORS:
+        raise ValueError(f'Unknown anchor "{anchor}"')
+
+    t: dict = {"anchor": anchor}
+
+    if tokens and _OFFSET_TOKEN_RE.match(tokens[0]):
+        offset = tokens.pop(0)
+        parse_offset_minutes(offset)  # validate (e.g. minutes <= 59)
+        t["offset"] = offset
+
+    if tokens:
+        t["day"] = _parse_day_part(tokens)
+
+    return t
+
+
+def _format_day_part(day: dict) -> str:
+    kind = day["type"]
+    if kind == "date":
+        return day["date"]
+    if kind in ("schoolDays", "weeks"):
+        n = day["n"]
+        if not isinstance(n, int):
+            raise ValueError(f"Cannot format non-integer day spec {n}")
+        abs_n = abs(n)
+        unit = "day" if kind == "schoolDays" else "week"
+        plural = "" if abs_n == 1 else "s"
+        return f"{'-' if n < 0 else '+'}{abs_n} {unit}{plural}"
+    if kind == "weekday":
+        name = WEEKDAY_NAMES.get(day["weekday"])
+        if not name:
+            raise ValueError(
+                f"Invalid weekday {day['weekday']} (must be 1=Monday..7=Sunday)"
+            )
+        return name
+    if kind == "week":
+        n = day["n"]
+        if n == 0:
+            return f"{day['edge']} of week"
+        if n == 1:
+            return f"{day['edge']} of next week"
+        raise ValueError(
+            f"Cannot format week spec with n={n} (string syntax covers n=0 and n=1)"
+        )
+    raise ValueError(f'Unknown day spec type "{kind}"')
+
+
+def format_time(t: dict) -> str:
+    """Canonical string form of an abstract time; round-trips through
+    :func:`parse_time`."""
+    if t["anchor"] not in ANCHORS:
+        raise ValueError(f'Unknown anchor "{t["anchor"]}"')
+    parts = [t["anchor"]]
+    offset = parse_offset_minutes(t.get("offset") or "+00:00")
+    if offset != 0:
+        parts.append(_format_offset(offset))
+    if t.get("day"):
+        parts.append(_format_day_part(t["day"]))
+    return " ".join(parts)