mihrab-methods 1.3.2__tar.gz

mihrab_methods-1.3.2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: mihrab-methods
+Version: 1.3.2
+Summary: The prayer-time authorities' own calculation methods, each reproducing its published timetable to the minute: a port of the mihrab-methods library.
+Author: Hassan El Ghamri
+License: MPL-2.0
+Project-URL: Homepage, https://github.com/MihrabHQ/mihrab-methods
+Project-URL: Documentation, https://github.com/MihrabHQ/mihrab-methods/tree/main/ports/python
+Project-URL: Changelog, https://github.com/MihrabHQ/mihrab-methods/blob/main/CHANGELOG.md
+Keywords: prayer-times,salah,adhan,islam,diyanet,mihrab
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Religion
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tzdata; platform_system == "Windows"
+
+# mihrab-methods in Python
+
+The methods of [mihrab-methods](../../README.md) — Sweden, Diyanet,
+Morocco, Algeria, Indonesia and Türkiye Takvimi — in plain Python, with no dependencies
+beyond the standard library (Python 3.9 or later, for `zoneinfo`).
+
+The TypeScript library is the reference. This port follows it line for
+line, is held to `test/vectors.json`, and names the method revisions it
+reproduces in `mihrab_methods.REVISIONS`. A correction list belongs to one
+revision: when a method's revision is raised in the library, this port is
+behind until it is raised here too.
+
+```sh
+pip install mihrab-methods
+```
+
+The package carries the correction lists of its release; a version has the
+same number as the npm package it was built with.
+
+```python
+from mihrab_methods import load_corrections, times_for
+
+lists = load_corrections()          # the package's own; or a directory laid out as data/corrections
+stockholm = {'authority': 'sweden', 'lat': 59.33, 'lon': 18.034, 'tz': 'Europe/Stockholm'}
+day = times_for(stockholm, '2026-11-12', lists['sweden'])
+print(day['printed'])     # the six times as 'HH:MM' on the clock the table prints
+print(day['instants'])    # the same six times as timezone-aware datetimes
+```
+
+A place is a dict shaped like the library's `Place`: `authority`, `lat`,
+`lon`, `tz`, and the fields a list gives some of its places (`ishaDeg`,
+`clock`, `prayerPoints`, `dipDeg`, `dipMaghribDeg`, `highland`,
+`twilightDip`, `afternoon`, `temkin`). The places themselves are in `data/places/`;
+use the coordinates exactly as the list has them, since the correction
+lists are looked up by them.
+
+Without a correction list `times_for` gives the bare method: within a
+minute of the full answer on the days a list has an entry for, the same on
+every other day.
+
+## Check
+
+From the repository root:
+
+```sh
+python3 ports/python/test_vectors.py
+```
+
+The zone offsets come from the machine's time-zone database, as they do in
+the library; two machines with different editions of it can differ on a
+zone whose rules changed between them.
+
+## What is where
+
+| File | What |
+| --- | --- |
+| `mihrab_methods/sun.py` | The three positions of the sun the methods use |
+| `mihrab_methods/methods.py` | The methods: the Congress method (Sweden, Diyanet), Morocco, Algeria, Indonesia, Türkiye Takvimi |
+| `mihrab_methods/api.py` | Place and date in, the day out: clock, correction list, printing |
+| `test_vectors.py` | Holds the port to `test/vectors.json` |

mihrab_methods-1.3.2/README.md

@@ -0,0 +1,60 @@
+# mihrab-methods in Python
+
+The methods of [mihrab-methods](../../README.md) — Sweden, Diyanet,
+Morocco, Algeria, Indonesia and Türkiye Takvimi — in plain Python, with no dependencies
+beyond the standard library (Python 3.9 or later, for `zoneinfo`).
+
+The TypeScript library is the reference. This port follows it line for
+line, is held to `test/vectors.json`, and names the method revisions it
+reproduces in `mihrab_methods.REVISIONS`. A correction list belongs to one
+revision: when a method's revision is raised in the library, this port is
+behind until it is raised here too.
+
+```sh
+pip install mihrab-methods
+```
+
+The package carries the correction lists of its release; a version has the
+same number as the npm package it was built with.
+
+```python
+from mihrab_methods import load_corrections, times_for
+
+lists = load_corrections()          # the package's own; or a directory laid out as data/corrections
+stockholm = {'authority': 'sweden', 'lat': 59.33, 'lon': 18.034, 'tz': 'Europe/Stockholm'}
+day = times_for(stockholm, '2026-11-12', lists['sweden'])
+print(day['printed'])     # the six times as 'HH:MM' on the clock the table prints
+print(day['instants'])    # the same six times as timezone-aware datetimes
+```
+
+A place is a dict shaped like the library's `Place`: `authority`, `lat`,
+`lon`, `tz`, and the fields a list gives some of its places (`ishaDeg`,
+`clock`, `prayerPoints`, `dipDeg`, `dipMaghribDeg`, `highland`,
+`twilightDip`, `afternoon`, `temkin`). The places themselves are in `data/places/`;
+use the coordinates exactly as the list has them, since the correction
+lists are looked up by them.
+
+Without a correction list `times_for` gives the bare method: within a
+minute of the full answer on the days a list has an entry for, the same on
+every other day.
+
+## Check
+
+From the repository root:
+
+```sh
+python3 ports/python/test_vectors.py
+```
+
+The zone offsets come from the machine's time-zone database, as they do in
+the library; two machines with different editions of it can differ on a
+zone whose rules changed between them.
+
+## What is where
+
+| File | What |
+| --- | --- |
+| `mihrab_methods/sun.py` | The three positions of the sun the methods use |
+| `mihrab_methods/methods.py` | The methods: the Congress method (Sweden, Diyanet), Morocco, Algeria, Indonesia, Türkiye Takvimi |
+| `mihrab_methods/api.py` | Place and date in, the day out: clock, correction list, printing |
+| `test_vectors.py` | Holds the port to `test/vectors.json` |

mihrab_methods-1.3.2/mihrab_methods/__init__.py

@@ -0,0 +1,7 @@
+"""mihrab-methods in Python: the prayer-time methods of five authorities,
+ported from the TypeScript library and held to its test vectors."""
+from .api import (PRAYERS, REVISIONS, CorrectionList, clock_offset_at, load_corrections, minutes_for, place_clock_at,
+                  point_key, printed, times_for)
+
+__all__ = ['PRAYERS', 'REVISIONS', 'CorrectionList', 'clock_offset_at', 'load_corrections', 'minutes_for',
+           'place_clock_at', 'point_key', 'printed', 'times_for']

mihrab_methods-1.3.2/mihrab_methods/api.py

@@ -0,0 +1,162 @@
+"""A place and a date in, the day's six times out: the authority's method,
+then its correction list — what `timesFor` does in the TypeScript library.
+
+A place is a dict shaped like the library's `Place` (see docs/api.md):
+`authority`, `lat`, `lon`, `tz`, and where the list has them `ishaDeg`,
+`clock`, `prayerPoints`, `dipDeg`, `dipMaghribDeg`, `highland`,
+`twilightDip`, `afternoon`, `temkin`.
+"""
+import datetime
+import json
+import math
+import os
+from decimal import ROUND_HALF_UP, Decimal
+from zoneinfo import ZoneInfo
+
+from . import methods
+
+PRAYERS = ('fajr', 'sunrise', 'dhuhr', 'asr', 'maghrib', 'isha')
+#: The method revisions this port reproduces. A correction list belongs to one revision.
+REVISIONS = {'sweden': 1, 'diyanet': 1, 'morocco': 2, 'algeria': 1, 'indonesia': 2, 'turkiyetakvimi': 1}
+
+_UTC = datetime.timezone.utc
+
+
+def _to_fixed(x):
+    """A coordinate to three decimals, as JavaScript's toFixed(3) writes it:
+    the binary value's exact decimal expansion, ties away from zero."""
+    return str(Decimal(float(x) + 0.0).quantize(Decimal('0.001'), rounding=ROUND_HALF_UP))  # + 0.0: -0 is written 0.000
+
+
+def point_key(lat, lon):
+    return '%s,%s' % (_to_fixed(lat), _to_fixed(lon))
+
+
+class CorrectionList:
+    """data/corrections/<authority>.json, indexed: point -> date -> {prayer: minutes}."""
+
+    def __init__(self, source):
+        self.source = source
+        self._index = {}
+        for point, entries in source.get('points', {}).items():
+            by_date = self._index.setdefault(point, {})
+            for e in entries:
+                date, key, step = e.split(' ')
+                by_date.setdefault(date, {})[key] = int(step)
+
+    @classmethod
+    def load(cls, path):
+        with open(path, encoding='utf-8') as f:
+            return cls(json.load(f))
+
+    def correction(self, lat, lon, date):
+        return self._index.get(point_key(lat, lon), {}).get(date)
+
+
+def clock_offset_at(tz, year, month0, day):
+    """Minutes east of UTC that a zone keeps at noon UTC of a date."""
+    at = datetime.datetime(year, month0 + 1, 1, 12, tzinfo=_UTC) + datetime.timedelta(days=day - 1)
+    return round(at.astimezone(ZoneInfo(tz)).utcoffset().total_seconds() / 60)
+
+
+def place_clock_at(place, year, month0, day):
+    """The clock a place's table prints a date in: its own where it has one, else its zone's."""
+    clock = place.get('clock')
+    if clock:
+        date = '%04d-%02d-%02d' % (year, month0 + 1, day)
+        off = clock[0][1]
+        for start, o in clock:
+            if start <= date:
+                off = o
+        return off
+    return clock_offset_at(place['tz'], year, month0, day)
+
+
+def _congress(place, year, month0, day, asr_shadow):
+    clock = place_clock_at(place, year, month0, day)
+    isha_deg = place.get('ishaDeg', methods.CONGRESS_ISHA_DEG)
+    pts_by_year = place.get('prayerPoints')
+    if pts_by_year:
+        years = sorted(int(y) for y in pts_by_year)
+        best = years[0]
+        for y in years:
+            if abs(y - year) < abs(best - year):
+                best = y
+        pts = pts_by_year[str(best)]
+        raw = {k: methods.congress_minutes(pts[i][0], pts[i][1], year, month0, day, asr_shadow, isha_deg, clock)[k]
+               for i, k in enumerate(PRAYERS)}
+    else:
+        raw = methods.congress_minutes(place['lat'], place['lon'], year, month0, day, asr_shadow, isha_deg, clock)
+    # the library carries an instant in whole milliseconds, then rounds it to the minute
+    return {k: math.floor(math.trunc(v * 60000) / 60000 + 0.5) for k, v in raw.items()}
+
+
+def minutes_for(place, date, corrections=None, asr_shadow=1):
+    """Minutes past 00:00 UT of `date` ('YYYY-MM-DD') for the six times, or None where the method gives none."""
+    year, month, day = (int(p) for p in date.split('-'))
+    month0 = month - 1
+    a = place['authority']
+    if a in ('sweden', 'diyanet'):
+        t = _congress(place, year, month0, day, asr_shadow)
+    elif a == 'morocco':
+        t = methods.morocco_minutes(place['lat'], place['lon'], year, month0, day, place.get('dipDeg'), asr_shadow,
+                                    place.get('dipMaghribDeg'))
+    elif a == 'algeria':
+        t = methods.algeria_minutes(place['lat'], place['lon'], year, month0, day, asr_shadow)
+    elif a == 'indonesia':
+        t = methods.kemenag_minutes(place['lat'], place['lon'], year, month0, day, bool(place.get('highland')),
+                                    bool(place.get('twilightDip')), asr_shadow, place.get('afternoon'))
+    elif a == 'turkiyetakvimi':
+        t = methods.takvim_minutes(place['lat'], place['lon'], year, month0, day, place.get('temkin'), asr_shadow)
+    else:
+        raise ValueError('unknown authority: %r' % (a,))
+    if t is None:
+        return None
+    c = corrections.correction(place['lat'], place['lon'], date) if corrections else None
+    if c:
+        for k, step in c.items():
+            if not (k == 'asr' and asr_shadow != 1):  # the lists are of the standard Asr only
+                t[k] += step
+    return t
+
+
+def printed(minutes, offset_minutes):
+    """'HH:MM' of a time on a clock, as a table prints it."""
+    m = (minutes + offset_minutes) % 1440
+    return '%02d:%02d' % (m // 60, m % 60)
+
+
+def times_for(place, date, corrections=None, asr_shadow=1):
+    """The day as a table prints it: {'clock': minutes east of UTC, 'printed': {...}, 'instants': {...}} or None.
+
+    `corrections` is the authority's CorrectionList; without it the times are the bare method's,
+    which is the published table to within the list's few minutes, not on every one.
+    """
+    t = minutes_for(place, date, corrections, asr_shadow)
+    if t is None:
+        return None
+    year, month, day = (int(p) for p in date.split('-'))
+    off = place_clock_at(place, year, month - 1, day)
+    start = datetime.datetime(year, month, day, tzinfo=_UTC)
+    return {
+        'clock': off,
+        'printed': {k: printed(t[k], off) for k in PRAYERS},
+        'instants': {k: start + datetime.timedelta(minutes=t[k]) for k in PRAYERS},
+    }
+
+
+#: The lists the installed package carries (those of its release); absent in a source checkout.
+BUNDLED_CORRECTIONS = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data', 'corrections')
+
+
+def load_corrections(directory=None):
+    """Every list in a directory laid out as the repository's data/corrections;
+    with no directory, the lists the installed package carries."""
+    if directory is None:
+        directory = BUNDLED_CORRECTIONS
+    out = {}
+    for a in REVISIONS:
+        p = os.path.join(directory, a + '.json')
+        if os.path.exists(p):
+            out[a] = CorrectionList.load(p)
+    return out

mihrab_methods-1.3.2/mihrab_methods/data/certification.json

@@ -0,0 +1,154 @@
+{
+  "sweden": {
+    "certified": true,
+    "checkedAt": "2026-11-09",
+    "places": 108,
+    "checks": [
+      {
+        "tables": "Sweden — Islamiska Förbundet’s tables",
+        "places": 107,
+        "times": 63114,
+        "off": 0,
+        "offWithoutCorrections": 20,
+        "from": "2026-10-11",
+        "to": "2027-12-14",
+        "setAside": {
+          "misplaced": [],
+          "sourceFaults": 35491,
+          "copiedRows": 696
+        }
+      },
+      {
+        "tables": "Sweden — Diyanet’s own tables",
+        "places": 159,
+        "times": 1393794,
+        "off": 0,
+        "offWithoutCorrections": 259,
+        "from": "2024-01-01",
+        "to": "2027-12-31"
+      }
+    ],
+    "corrections": {
+      "from": "2024-01-01",
+      "to": "2027-12-31",
+      "entries": 270,
+      "sha256": "173d7145b5ec917882f8ac9890dd1fa5f3143bd714eb540482861bf8a6bac660"
+    },
+    "revision": 1
+  },
+  "diyanet": {
+    "certified": true,
+    "checkedAt": "2026-11-11",
+    "places": 8318,
+    "checks": [
+      {
+        "tables": "Diyanet — its tables worldwide",
+        "places": 8318,
+        "times": 71630078,
+        "off": 0,
+        "offWithoutCorrections": 9368,
+        "from": "2024-01-01",
+        "to": "2027-12-31"
+      }
+    ],
+    "corrections": {
+      "from": "2024-01-01",
+      "to": "2027-12-31",
+      "entries": 9357,
+      "sha256": "a8c6a7305611f8dcedc04a64efb8dd150d9a588c2b3ac3391bfb776d70a2ec83"
+    },
+    "revision": 1
+  },
+  "morocco": {
+    "certified": true,
+    "checkedAt": "2026-11-11",
+    "places": 164,
+    "checks": [
+      {
+        "tables": "Morocco — Habous",
+        "places": 164,
+        "times": 94350,
+        "off": 0,
+        "offWithoutCorrections": 114,
+        "from": "2026-08-27",
+        "to": "2026-11-30"
+      }
+    ],
+    "corrections": {
+      "from": "2026-08-27",
+      "to": "2026-11-30",
+      "entries": 114,
+      "sha256": "2ae7161a7164f7ccebf1aa9f81628a810ce8fdd337e0645907e6c58d0be6aae9"
+    },
+    "revision": 2
+  },
+  "algeria": {
+    "certified": true,
+    "checkedAt": "2026-11-09",
+    "places": 68,
+    "checks": [
+      {
+        "tables": "Algeria — Ministry of Religious Affairs",
+        "places": 68,
+        "times": 101184,
+        "off": 0,
+        "offWithoutCorrections": 642,
+        "from": "2026-10-01",
+        "to": "2027-06-05"
+      }
+    ],
+    "corrections": {
+      "from": "2026-10-01",
+      "to": "2027-06-05",
+      "entries": 642,
+      "sha256": "f8d227cdd88aabe5bcd1775ec0324abfdae07a8a3986fdd19816337c2d4ab3ca"
+    },
+    "revision": 1
+  },
+  "indonesia": {
+    "certified": true,
+    "checkedAt": "2026-11-11",
+    "places": 517,
+    "checks": [
+      {
+        "tables": "Indonesia — Kemenag",
+        "places": 517,
+        "times": 362934,
+        "off": 0,
+        "offWithoutCorrections": 234,
+        "from": "2026-10-07",
+        "to": "2027-01-31"
+      }
+    ],
+    "corrections": {
+      "from": "2026-10-07",
+      "to": "2027-01-31",
+      "entries": 234,
+      "sha256": "a3f1c30576ddddbfda6cadabe442e1bcf3fb476b018b269d7d4783edd4e39d03"
+    },
+    "revision": 2
+  },
+  "turkiyetakvimi": {
+    "certified": true,
+    "checkedAt": "2026-11-11",
+    "places": 821,
+    "checks": [
+      {
+        "tables": "Türkiye Takvimi — its cities’ years",
+        "places": 821,
+        "times": 1812768,
+        "off": 0,
+        "offWithoutCorrections": 860,
+        "from": "2025-12-31",
+        "to": "2027-01-02"
+      }
+    ],
+    "corrections": {
+      "from": "2025-12-31",
+      "to": "2027-01-02",
+      "entries": 860,
+      "sha256": "edf5bd37ccd06dbcb87300a6c943353adb624a545ff6ea416a8f89715713d7bd"
+    },
+    "revision": 1
+  }
+}