0xMH/mawaqit-py

# mawaqit-py **mawaqit-py** 是一个用于 [mawaqit.net](https://mawaqit.net) 的轻量级 Python 客户端，该平台为全球 8000 多座清真寺提供礼拜时间服务。它封装了公共搜索 API 和每个清真寺的 `confData` blob，让你无需手动解析 HTML，即可获得包含清真寺信息、今日礼拜时间、入拜间隔时间、全年日历和通知的整洁类型对象。 搜索 endpoint 无需身份验证，并且已经在每个结果中嵌入了今天的礼拜时间。单个清真寺的年度日历和通知并未由公共 API 暴露，因此它们是从每个清真寺网页上的 `confData` blob 中读取的。 ## 安装 ``` pip install mawaqit-py ``` 本地开发： ``` uv sync uv run python -m unittest discover -s tests ``` ## 快速开始 ``` from mawaqit_py import Mawaqit with Mawaqit() as client: # Search by name or city for mosque in client.search("amsterdam"): print(mosque.name, mosque.times.prayers, "| Jumua:", mosque.jumua) # Nearest mosques to a coordinate nearest = client.nearby(48.8566, 2.3522) print(nearest[0].name, nearest[0].coordinates) # Full-year calendar for a specific mosque (by slug or Mosque object) calendar = client.calendar("grande-mosquee-de-paris") print("Jul 1:", calendar.day(7, 1).prayers) # Announcements for notice in client.announcements("grande-mosquee-de-paris"): print(notice.title, notice.start_date, "->", notice.end_date) ``` ## 礼拜时间 每座清真寺在 `times` 中包含今天的六个时间值。索引 1 是日出/shuruq，不属于礼拜，因此 `PrayerTimes` 将其单独保留： ``` times = mosque.times times.fajr, times.sunrise, times.dhuhr, times.asr, times.maghrib, times.isha times.prayers # {'fajr': ..., 'dhuhr': ..., 'asr': ..., 'maghrib': ..., 'isha': ...} mosque.iqama_offsets # {'fajr': '+10', 'dhuhr': '+10', ...} minutes after the adhan ``` ## API `Mawaqit` 是你唯一需要构造的对象。其公共方法如下： | 方法 | 返回值 | 描述 | |--------|---------|-------------| | `search(word=None, *, lat=None, lon=None, page=1)` | `list[Mosque]` | 按文本或坐标（最近优先）搜索。 | | `nearby(lat, lon, *, page=1)` | `list[Mosque]` | 坐标搜索的便捷封装。 | | `iter_search(word=None, *, lat=None, lon=None, start_page=1, max_pages=None)` | `Iterator[Mosque]` | 翻页遍历结果，直到返回空结果为止。 | | `conf_data(mosque, *, lang="en")` | `ConfData` | 完整的 confData blob：日历、通知、事件。 | | `calendar(mosque, *, lang="en")` | `Calendar` | 全年礼拜时间日历。 | | `announcements(mosque, *, lang="en")` | `list[Announcement]` | 某座清真寺的当前通知。 | `mosque` 参数接受 `Mosque` 对象、slug 字符串或完整的 `mawaqit.net/{lang}/{slug}` URL。 每个值对象都有 `.to_dict()`（传入 `include_raw=True` 可保留原始 payload），未经处理的响应始终存储在 `.raw` 中。 ## 工作原理 本库使用 mawaqit.net 的两个公共接口： | Endpoint | 方法 | 用途 | |----------|--------|---------| | `mawaqit.net/api/2.0/mosque/search?word=` | GET | 按名称/城市搜索清真寺，并嵌入今日时间。 | | `mawaqit.net/api/2.0/mosque/search?lat=&lon=` | GET | 距离坐标最近的清真寺。 | | `mawaqit.net/{lang}/{slug}` | GET | 清真寺网页；嵌入了包含全年日历和通知的 `confData` JSON blob。 | 针对单个清真寺的移动端 endpoint（`mosque/{uuid}/times`、`mosque/{uuid}/calendar`、`favorite`、`statistic/mosque`）受到 `Api-Access-Token` 的保护，此处未使用。 请求传输、浏览器指纹模拟以及重试处理均属于内部细节。普通用户只需构造 `Mawaqit()` 并调用上述公共方法即可。 ## 免责声明 这是一个非官方库，不隶属于 MAWAQIT 或其任何附属机构，也未获得其授权、维护、赞助或认可。使用风险由您自行承担。 本库仅通过 mawaqit.net 的 Web API 和网页访问公开可用的清真寺数据。这些 API 未公开文档，可能随时更改或失效。请负责任地使用，并避免发送可能对 MAWAQIT 基础设施造成负担的过多请求。 ## 许可证 AGPL-3.0

标签：API客户端, API封装, Python, URL抓取, 宗教生活, 数据抓取, 无后门, 日历, 逆向工具