praytime 0.1.0__py3-none-any.whl

praytime/__init__.py

@@ -0,0 +1,21 @@
+"""praytime — zero-dependency Islamic prayer times calculator.
+
+Python port of ``zarrabi/praytime``. Public surface: :class:`PrayTime`,
+:data:`METHODS`, and :data:`__version__`.
+
+.. warning::
+   This package was ported from the original ``zarrabi/praytime`` library using
+   AI-agent code-generation tooling. Despite extensive testing against the
+   upstream implementation, it may contain bugs in prayer-time calculations.
+   Verify the times before relying on them, and use it at your own
+   responsibility (provided "as is", without warranty of any kind).
+"""
+
+from __future__ import annotations
+
+from .constants import METHODS
+from .praytime import PrayTime
+
+__version__ = "0.1.0"
+
+__all__ = ["PrayTime", "METHODS", "__version__"]

praytime/__main__.py

@@ -0,0 +1,122 @@
+"""Command-line interface for :mod:`praytime` (plan.md Phase 6).
+
+Runnable as ``python -m praytime`` (or as the ``praytime`` console script once
+installed). Computes the eight daily prayer times for a location, date, and
+calculation method and prints them with aligned labels.
+
+Standard library only; no third-party runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+from typing import List, Optional, Sequence, Tuple
+
+from .constants import METHODS
+from .praytime import PrayTime
+
+#: Selectable method names, excluding the internal ``defaults`` entry
+#: (specs.md §4).
+METHOD_NAMES: List[str] = [name for name in METHODS if name != "defaults"]
+
+#: Allowed ``--format`` values (specs.md §9.1).
+FORMATS: List[str] = ["24h", "12h", "12H", "x", "X"]
+
+#: Allowed ``--asr`` values (specs.md §5).
+ASR_CHOICES: List[str] = ["Standard", "Hanafi"]
+
+#: Allowed ``--high-lats`` values (specs.md §6).
+HIGH_LATS_CHOICES: List[str] = ["None", "NightMiddle", "OneSeventh", "AngleBased"]
+
+
+def _parse_date(value: str) -> Tuple[int, int, int]:
+    """Parse an ISO ``YYYY-MM-DD`` date into a 1-based ``(year, month, day)`` tuple."""
+    try:
+        parsed = _dt.date.fromisoformat(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            f"invalid date {value!r}; expected YYYY-MM-DD"
+        ) from exc
+    return parsed.year, parsed.month, parsed.day
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the :mod:`argparse` argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="praytime",
+        description=(
+            "Compute the eight daily Islamic prayer times for a location and "
+            "date (Python port of zarrabi/praytime)."
+        ),
+    )
+    parser.add_argument(
+        "--method",
+        default="MWL",
+        choices=METHOD_NAMES,
+        help="calculation method (default: MWL)",
+    )
+    parser.add_argument("--lat", type=float, required=True, help="latitude in degrees")
+    parser.add_argument("--lng", type=float, required=True, help="longitude in degrees")
+    parser.add_argument(
+        "--timezone",
+        default="UTC",
+        help="IANA timezone name used for display (default: UTC)",
+    )
+    parser.add_argument(
+        "--date",
+        type=_parse_date,
+        default=None,
+        help="date as YYYY-MM-DD (default: today)",
+    )
+    parser.add_argument(
+        "--format",
+        default="24h",
+        choices=FORMATS,
+        help="output format (default: 24h)",
+    )
+    parser.add_argument(
+        "--asr",
+        default="Standard",
+        choices=ASR_CHOICES,
+        help="Asr madhab (default: Standard)",
+    )
+    parser.add_argument(
+        "--high-lats",
+        dest="high_lats",
+        default="NightMiddle",
+        choices=HIGH_LATS_CHOICES,
+        help="high-latitude adjustment rule (default: NightMiddle)",
+    )
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Run the ``praytime`` command line and print the eight prayer times."""
+    args = build_parser().parse_args(argv)
+
+    date = args.date if args.date is not None else _today()
+
+    praytime = (
+        PrayTime(args.method)
+        .location([args.lat, args.lng])
+        .timezone(args.timezone)
+        .adjust({"asr": args.asr, "highLats": args.high_lats})
+        .format(args.format)
+    )
+    times = praytime.times(date)
+
+    width = max(len(label) for label in praytime.labels)
+    for label, key in zip(praytime.labels, times):
+        print(f"{label:<{width}}  {times[key]}")
+    return 0
+
+
+def _today() -> Tuple[int, int, int]:
+    """Return today's host-local date as a ``(year, month, day)`` tuple."""
+    today = _dt.date.today()
+    return today.year, today.month, today.day
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

praytime/astro.py

@@ -0,0 +1,114 @@
+"""Pure astronomical core (specs.md §8.2–§8.6).
+
+Implements the approximate solar-coordinate algorithm and the hour-angle
+trigonometry used by the prayer-time pipeline:
+
+* :func:`julian_offset` — the Julian-day offset term ``D`` (specs.md §8.2);
+* :func:`sun_position` — solar declination and equation of time (specs.md §8.2);
+* :func:`mid_day` — local solar noon / Dhuhr (specs.md §8.3);
+* :func:`angle_time` — time the sun reaches a given altitude (specs.md §8.4);
+* :func:`asr_angle` — Asr shadow-angle (specs.md §8.6, §5).
+
+Every function is **pure**: it takes the inputs it needs explicitly (the UTC
+midnight timestamp ``utc_ms`` and the longitude ``lng`` are threaded through
+rather than read from instance state) and holds no global state. All angles are
+in degrees and all times are local solar hours. Operation order mirrors the JS
+source exactly so the double-precision results agree to the last ULP.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, NamedTuple, Union
+
+from . import constants as C
+from .formatting import parse_value
+from .trig import acos, acot, asin, atan2, cos, mod, sin, tan
+
+#: Type accepted for the ``time`` seed: a number or a JS-style string such as
+#: ``'90 min'``. Non-numeric strings coerce to ``nan`` (specs.md §8.1).
+TimeValue = Union[int, float, str]
+
+
+class SunPosition(NamedTuple):
+    """Solar declination (degrees) and equation of time (hours)."""
+
+    declination: float
+    equation: float
+
+
+#: Asr shadow-length factors for the named madhabs (specs.md §5).
+_SHADOW_FACTORS: Dict[str, int] = {
+    "Standard": C.SHADOW_STANDARD,
+    "Hanafi": C.SHADOW_HANAFI,
+}
+
+
+def julian_offset(utc_ms: float, time: TimeValue, lng: float) -> float:
+    """Return the Julian-day offset ``D`` from the J2000.0 epoch (specs.md §8.2).
+
+    Mirrors ``utcTime / 864e5 - 10957.5 + value(time) / 24 - lng / 360``.
+    """
+    return (
+        utc_ms / C.MS_PER_DAY
+        - C.J2000_OFFSET_DAYS
+        + parse_value(time) / C.HOURS_PER_DAY
+        - lng / 360
+    )
+
+
+def sun_position(time: TimeValue, utc_ms: float, lng: float) -> SunPosition:
+    """Return the sun's declination and equation of time (specs.md §8.2).
+
+    Uses the USNO approximate solar-coordinate algorithm; the Earth-Sun
+    distance term is not used. ``time`` seeds the fractional solar day.
+    """
+    d = julian_offset(utc_ms, time, lng)
+
+    g = mod(C.MEAN_ANOMALY_BASE + C.MEAN_ANOMALY_RATE * d, 360)
+    q = mod(C.MEAN_LONGITUDE_BASE + C.MEAN_LONGITUDE_RATE * d, 360)
+    L = mod(q + C.EQ_CENTER_1 * sin(g) + C.EQ_CENTER_2 * sin(2 * g), 360)
+    e = C.OBLIQUITY_J2000 - C.OBLIQUITY_RATE * d
+    ra = mod(atan2(cos(e) * sin(L), cos(L)) / C.DEG_PER_HOUR, 24)
+
+    declination = asin(sin(e) * sin(L))
+    equation = q / 15 - ra
+    return SunPosition(declination, equation)
+
+
+def mid_day(time: TimeValue, utc_ms: float, lng: float) -> float:
+    """Return local solar noon as ``mod(12 - EqT, 24)`` hours (specs.md §8.3)."""
+    eqt = sun_position(time, utc_ms, lng).equation
+    return mod(C.NOON_OFFSET - eqt, C.HOURS_PER_DAY)
+
+
+def angle_time(
+    angle: Any,
+    time: TimeValue,
+    lat: float,
+    utc_ms: float,
+    lng: float,
+    direction: int = 1,
+) -> float:
+    """Return the hour the sun reaches ``angle`` below the horizon (specs.md §8.4).
+
+    ``direction`` is ``-1`` for morning prayers and ``+1`` (default) for
+    afternoon. When ``cos(H)`` leaves ``[-1, 1]`` the ``acos`` helper returns
+    ``nan`` (never clamped), and a non-numeric ``angle`` string coerces to
+    ``nan`` via the trig helpers.
+    """
+    decl = sun_position(time, utc_ms, lng).declination
+    numerator = -sin(angle) - sin(lat) * sin(decl)
+    diff = acos(numerator / (cos(lat) * cos(decl))) / C.DEG_PER_HOUR
+    return mid_day(time, utc_ms, lng) + diff * direction
+
+
+def asr_angle(asr_param: Any, time: TimeValue, lat: float, utc_ms: float, lng: float) -> float:
+    """Return the Asr shadow angle ``-acot(t + tan|lat - decl|)`` (specs.md §8.6).
+
+    The shadow factor ``t`` is ``1`` for ``'Standard'``, ``2`` for ``'Hanafi'``,
+    otherwise ``parse_value(asr_param)`` (a custom factor). The ``or`` mirrors
+    the JS ``||`` short-circuit (specs.md §5).
+    """
+    shadow_factor = _SHADOW_FACTORS.get(asr_param) or parse_value(asr_param)
+    decl = sun_position(time, utc_ms, lng).declination
+    return -acot(shadow_factor + tan(abs(lat - decl)))

praytime/constants.py

@@ -0,0 +1,168 @@
+"""Static data tables and numeric constants for :mod:`praytime`.
+
+This module is a leaf: it imports nothing from the rest of the package. It holds
+
+* :data:`METHODS` — the calculation-method table (specs.md §4);
+* :data:`LABELS` — the prayer labels (specs.md §11);
+* :data:`DEFAULTS` — the static settings template (specs.md §7);
+* :func:`default_settings` — a fresh settings mapping with host timezone/location
+  resolved (specs.md §7.1);
+* every numeric constant and seed hour used by the astronomy pipeline
+  (specs.md §11).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any, Dict, List, Tuple, Union
+
+Number = Union[int, float]
+
+# ---------------------------------------------------------------------------
+# Calculation methods (specs.md §4)
+# ---------------------------------------------------------------------------
+
+#: Calculation-method table, transcribed verbatim from the JS source.
+#:
+#: ``defaults`` is applied first by ``PrayTime.method`` and then overridden by
+#: the named method, so methods such as ``Tehran``/``Jafari`` inherit
+#: ``isha: 14`` and ``maghrib: '1 min'``.
+METHODS: Dict[str, Dict[str, Any]] = {
+    "MWL": {"fajr": 18, "isha": 17},
+    "ISNA": {"fajr": 15, "isha": 15},
+    "Egypt": {"fajr": 19.5, "isha": 17.5},
+    "Makkah": {"fajr": 18.5, "isha": "90 min"},
+    "Karachi": {"fajr": 18, "isha": 18},
+    "Tehran": {"fajr": 17.7, "maghrib": 4.5, "midnight": "Jafari"},
+    "Jafari": {"fajr": 16, "maghrib": 4, "midnight": "Jafari"},
+    "France": {"fajr": 12, "isha": 12},
+    "Russia": {"fajr": 16, "isha": 15},
+    "Malaysia": {"fajr": 20, "isha": 18},  # JAKIM
+    "Singapore": {"fajr": 20, "isha": 18},
+    "defaults": {"isha": 14, "maghrib": "1 min", "midnight": "Standard"},
+}
+
+#: Human-readable prayer labels, in returned-dict order (specs.md §11).
+LABELS: List[str] = [
+    "Fajr",
+    "Sunrise",
+    "Dhuhr",
+    "Asr",
+    "Sunset",
+    "Maghrib",
+    "Isha",
+    "Midnight",
+]
+
+# ---------------------------------------------------------------------------
+# Numeric constants (specs.md §11)
+# ---------------------------------------------------------------------------
+
+#: Sunrise/Sunset horizon angle in degrees (refraction + solar radius).
+HORIZON = 0.833
+
+#: Days from the Unix epoch to J2000.0 (JD 2451545.0). Computed, not hardcoded,
+#: per the research recommendation: ``2451545.0 - 2440587.5 == 10957.5``.
+J2000_OFFSET_DAYS = 2451545.0 - 2440587.5
+
+MS_PER_DAY = 86_400_000
+MS_PER_HOUR = 3_600_000
+MS_PER_MINUTE = 60_000
+
+# Sun-position coefficients (USNO approximate solar coordinates).
+MEAN_ANOMALY_BASE = 357.529
+MEAN_ANOMALY_RATE = 0.98560028
+MEAN_LONGITUDE_BASE = 280.459
+MEAN_LONGITUDE_RATE = 0.98564736
+EQ_CENTER_1 = 1.915
+EQ_CENTER_2 = 0.020
+OBLIQUITY_J2000 = 23.439
+OBLIQUITY_RATE = 0.00000036
+
+# Asr shadow factors.
+SHADOW_STANDARD = 1
+SHADOW_HANAFI = 2
+
+# High-latitude portion factors.
+HL_NIGHT_MIDDLE = 1 / 2
+HL_ONE_SEVENTH = 1 / 7
+#: Divisor for the AngleBased factor ``(1 / HL_ANGLE_DIVISOR) * parse_value(angle)``.
+HL_ANGLE_DIVISOR = 60
+
+#: Fixed local-solar-time seed (hours) used to estimate next-day Jafari Fajr.
+JAFARI_SEED_HOUR = 29
+
+NOON_OFFSET = 12
+HOURS_PER_DAY = 24
+DEG_PER_HOUR = 15
+
+#: Placeholder returned for an invalid (NaN) timestamp.
+INVALID_TIME = "-----"
+
+#: Initial local-solar-time seed hours for ``compute_times`` (specs.md §8.9).
+SEED_TIMES: Dict[str, Number] = {
+    "fajr": 5,
+    "sunrise": 6,
+    "dhuhr": 12,
+    "asr": 13,
+    "sunset": 18,
+    "maghrib": 18,
+    "isha": 18,
+    "midnight": 24,
+}
+
+# ---------------------------------------------------------------------------
+# Settings defaults (specs.md §7)
+# ---------------------------------------------------------------------------
+
+#: Static settings template. ``timezone`` and ``location`` are host-dependent
+#: and filled in by :func:`default_settings` at runtime.
+DEFAULTS: Dict[str, Any] = {
+    "dhuhr": "0 min",
+    "asr": "Standard",
+    "highLats": "NightMiddle",
+    "tune": {},
+    "format": "24h",
+    "rounding": "nearest",
+    "utcOffset": "auto",
+    "iterations": 1,
+}
+
+
+def _host_timezone_and_longitude() -> Tuple[str, float]:
+    """Return the host IANA zone (or ``"UTC"``) and its default longitude.
+
+    Mirrors ``Intl.DateTimeFormat().resolvedOptions().timeZone`` and
+    ``-(new Date()).getTimezoneOffset() / 4`` (specs.md §7.1). Fixed-offset
+    tzinfos that lack a ``.key`` fall back to ``"UTC"``.
+    """
+    now = _dt.datetime.now().astimezone()
+    tzinfo = now.tzinfo
+    default_tz = getattr(tzinfo, "key", "UTC")
+    offset = now.utcoffset()
+    offset_min = 0.0 if offset is None else offset.total_seconds() / 60
+    default_lng = -offset_min / 4
+    return default_tz, default_lng
+
+
+def default_settings() -> Dict[str, Any]:
+    """Build a fresh settings mapping with host timezone/location resolved.
+
+    Returns a new ``dict`` each call (including a new ``tune`` mapping) so
+    callers can freely mutate it without affecting :data:`DEFAULTS` or other
+    instances.
+    """
+    settings: Dict[str, Any] = {
+        "dhuhr": DEFAULTS["dhuhr"],
+        "asr": DEFAULTS["asr"],
+        "highLats": DEFAULTS["highLats"],
+        "tune": dict(DEFAULTS["tune"]),
+        "format": DEFAULTS["format"],
+        "rounding": DEFAULTS["rounding"],
+        "utcOffset": DEFAULTS["utcOffset"],
+        "iterations": DEFAULTS["iterations"],
+    }
+    timezone, longitude = _host_timezone_and_longitude()
+    settings["timezone"] = timezone
+    settings["location"] = [0, longitude]
+    return settings

praytime/formatting.py

@@ -0,0 +1,141 @@
+"""Output formatting, rounding, and interval parsing (specs.md §8.13, §9).
+
+This module holds the pure helpers used to turn computed timestamps into
+strings (and interval strings into numbers):
+
+* :func:`parse_value` — the JS ``value`` leading-number parse (specs.md §9.4);
+* :func:`is_min` — the JS ``isMin`` ``'min'`` substring test (specs.md §9.4);
+* :func:`js_round` — half-up rounding matching JS ``Math.round`` (specs.md §8.13);
+* :func:`round_time` — minute rounding on the millisecond scale (specs.md §8.13);
+* :func:`time_to_string` — ``24h``/``12h``/``12H`` rendering (specs.md §9.1, §9.3);
+* :func:`format_time` — ``x``/``X``/callable/``'-----'`` dispatch (specs.md §9.1).
+
+Standard library only (``math``, ``re``, ``datetime``, ``zoneinfo``).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import math
+import re
+from typing import Any, Mapping
+
+from zoneinfo import ZoneInfo
+
+from .constants import INVALID_TIME, MS_PER_MINUTE
+
+#: Split pattern matching JS ``/[^0-9.+-]/``: everything that is not a digit,
+#: dot, plus, or minus.
+_NUM_RE = re.compile(r"[^0-9.+-]")
+
+#: Pattern stripping the ``" AM"``/``" PM"`` suffix for the ``'12H'`` format,
+#: matching JS ``/ ?[AP]M/`` (specs.md §8.13/§9.1).
+_AMPM_RE = re.compile(r" ?[AP]M")
+
+
+def parse_value(x: Any) -> float:
+    """Parse the leading number of ``x`` like the JS ``value`` helper.
+
+    Numbers pass straight through as ``float(x)``. For any other value the
+    string form is split on the first non-numeric character and the head is
+    converted; an empty or unparseable head yields ``0.0`` (mirroring
+    ``+'' === 0`` / the JS fallback). See specs.md §9.4.
+    """
+    if isinstance(x, (int, float)):
+        return float(x)
+    head = _NUM_RE.split(str(x), maxsplit=1)[0]
+    try:
+        return float(head)
+    except ValueError:
+        return 0.0
+
+
+def is_min(x: Any) -> bool:
+    """Return whether the string form of ``x`` contains ``'min'`` (specs.md §9.4)."""
+    return "min" in str(x)
+
+
+def js_round(x: float) -> int:
+    """Round half-up, matching JS ``Math.round`` (specs.md §8.13).
+
+    JS ``Math.round`` rounds ``.5`` toward ``+`` infinity; Python's built-in
+    :func:`round` uses banker's rounding and must not be used. For the positive
+    timestamps handled here ``floor(x + 0.5)`` reproduces JS exactly.
+    """
+    return math.floor(x + 0.5)
+
+
+def round_time(timestamp: float, rounding: str) -> float:
+    """Round ``timestamp`` (ms) to the nearest minute per ``rounding`` (specs.md §8.13).
+
+    ``'up'`` uses :func:`math.ceil`, ``'down'`` uses :func:`math.floor`,
+    ``'nearest'`` uses :func:`js_round` (half-up). Any other value (including
+    ``'none'``) leaves the timestamp unchanged, mirroring the JS lookup miss.
+    """
+    fn = {"up": math.ceil, "down": math.floor, "nearest": js_round}.get(rounding)
+    if fn is None:
+        return timestamp
+    if isinstance(timestamp, float) and not math.isfinite(timestamp):
+        return timestamp
+    return fn(timestamp / MS_PER_MINUTE) * MS_PER_MINUTE
+
+
+def _zone(name: str) -> _dt.tzinfo:
+    """Return the IANA zone ``name``, falling back to UTC if data is missing.
+
+    ``ZoneInfo`` raises when the tz database has no matching key (e.g. minimal
+    images without ``tzdata``); the port degrades gracefully to UTC rather than
+    failing (specs.md §7.1, §9.2).
+    """
+    try:
+        return ZoneInfo(name)
+    except Exception:
+        return _dt.timezone.utc
+
+
+def time_to_string(timestamp: float, fmt: str, settings: Mapping[str, Any]) -> str:
+    """Render ``timestamp`` (ms) as a clock string in the configured zone.
+
+    The instant is shifted by a numeric ``settings['utcOffset']`` (minutes)
+    before rendering; ``'auto'`` leaves it untouched. JS **always** renders with
+    ``settings['timezone']`` (specs.md §9.2, §9.3):
+
+    * ``'24h'`` → ``HH:MM`` (zero-padded);
+    * otherwise ``H:MM AM/PM`` (no leading zero), with the suffix stripped for
+      ``'12H'`` and kept for ``'12h'``.
+    """
+    utc_offset = settings["utcOffset"]
+    zone = _zone(settings["timezone"])
+    if utc_offset == "auto":
+        dt = _dt.datetime.fromtimestamp(timestamp / 1000, tz=zone)
+    else:
+        dt = _dt.datetime.fromtimestamp((timestamp + utc_offset * 60000) / 1000, tz=zone)
+
+    if fmt == "24h":
+        return f"{dt.hour:02d}:{dt.minute:02d}"
+
+    hour = dt.hour % 12 or 12
+    ampm = "AM" if dt.hour < 12 else "PM"
+    rendered = f"{hour}:{dt.minute:02d} {ampm}"
+    if fmt == "12H":
+        return _AMPM_RE.sub("", rendered)
+    return rendered
+
+
+def format_time(timestamp: float, settings: Mapping[str, Any]) -> Any:
+    """Dispatch ``timestamp`` (ms) through ``settings['format']`` (specs.md §9.1).
+
+    A ``float('nan')`` timestamp renders as :data:`INVALID_TIME` (``'-----'``).
+    A callable format receives the (already rounded) millisecond number. A
+    ``'x'``/``'X'`` format returns ``floor`` of milliseconds/seconds (the
+    seconds branch is case-sensitive on ``'X'``). Anything else is rendered via
+    :func:`time_to_string`.
+    """
+    fmt = settings["format"]
+    if isinstance(timestamp, float) and math.isnan(timestamp):
+        return INVALID_TIME
+    if callable(fmt):
+        return fmt(timestamp)
+    if isinstance(fmt, str) and fmt.lower() == "x":
+        return math.floor(timestamp / (1000 if fmt == "X" else 1))
+    return time_to_string(timestamp, fmt, settings)

praytime/highlat.py

@@ -0,0 +1,86 @@
+"""High-latitude adjustment rules (specs.md §6, §10.5).
+
+Implements the JS ``adjustHighLats`` / ``adjustTime`` logic for the ``None`` /
+``NightMiddle`` / ``OneSeventh`` / ``AngleBased`` rules:
+
+* :func:`adjust_high_lats` — clamp Fajr/Isha/Maghrib for abnormal night lengths,
+  returning the ``adjusted`` flag;
+* :func:`adjust_time` — clamp one time against ``base ± portion × night``.
+
+The stateful quirk is preserved: the ``'None'`` rule returns ``prior_adjusted``
+untouched and mutates nothing (specs.md §10.5). ``NaN`` is **never** clamped
+away silently — it is replaced by the clamp value and flips ``adjusted``.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, Dict, Mapping, MutableMapping, Optional, Tuple
+
+from . import constants as C
+
+
+def adjust_high_lats(
+    times: MutableMapping[str, float],
+    settings: Mapping[str, Any],
+    value_fn: Callable[[Any], float],
+    prior_adjusted: Optional[bool] = None,
+) -> Optional[bool]:
+    """Adjust Fajr/Isha/Maghrib for high latitudes (specs.md §6).
+
+    Returns the ``adjusted`` flag: ``prior_adjusted`` unchanged when
+    ``settings['highLats'] == 'None'`` (and touches nothing — specs.md §10.5),
+    otherwise ``True`` if any of the three prayers was clamped. ``times`` is
+    mutated in place.
+    """
+    if settings["highLats"] == "None":
+        return prior_adjusted
+
+    adjusted = False
+    night = 24 + times["sunrise"] - times["sunset"]
+
+    times["fajr"], adjusted = adjust_time(
+        times["fajr"], times["sunrise"], settings["fajr"], night, -1,
+        settings, value_fn, adjusted,
+    )
+    times["isha"], adjusted = adjust_time(
+        times["isha"], times["sunset"], settings["isha"], night, 1,
+        settings, value_fn, adjusted,
+    )
+    times["maghrib"], adjusted = adjust_time(
+        times["maghrib"], times["sunset"], settings["maghrib"], night, 1,
+        settings, value_fn, adjusted,
+    )
+    return adjusted
+
+
+def adjust_time(
+    time: float,
+    base: float,
+    angle: Any,
+    night: float,
+    direction: int,
+    settings: Mapping[str, Any],
+    value_fn: Callable[[Any], float],
+    adjusted: bool,
+) -> Tuple[float, bool]:
+    """Clamp a single ``time`` against ``base ± portion × night`` (specs.md §6.1).
+
+    ``portion`` depends on the rule in ``settings['highLats']``:
+    ``NightMiddle`` → ``1/2``, ``OneSeventh`` → ``1/7``, ``AngleBased`` →
+    ``(1/60) × value_fn(angle)`` (the **raw** setting value, e.g. ``'90 min'``
+    → ``1.5``). A ``NaN`` time or one whose ``(time − base) × direction``
+    exceeds ``portion`` is clamped to ``base + portion × direction`` and sets
+    ``adjusted`` to ``True`` (strict ``>`` — an exact boundary is not clamped).
+    """
+    factors: Dict[str, float] = {
+        "NightMiddle": C.HL_NIGHT_MIDDLE,
+        "OneSeventh": C.HL_ONE_SEVENTH,
+        "AngleBased": (1 / C.HL_ANGLE_DIVISOR) * value_fn(angle),
+    }
+    portion = factors[settings["highLats"]] * night
+    time_diff = (time - base) * direction
+    if math.isnan(time) or time_diff > portion:
+        time = base + portion * direction
+        adjusted = True
+    return time, adjusted