Merge pull request #35 from eggplants/area_maintenance

`get_maintenance` を追加する

README.md

@@ -8,6 +8,7 @@
 JR西日本列車走行位置 非公式API Pythonライブラリ
 
 * 列車走行位置取得 (`/api/v3/{LINE}.json`)
+* メンテナンス予定取得 (`/api/v3/area_{AREA}_maintenance.json`)
 * 路線名取得 (`/api/v3/area_{AREA}_master.json`)
 * 駅一覧取得 (`/api/v3/{LINE}_st.json`)
 * 運行情報取得 (`/api/v3/area_{AREA}_trafficinfo.json`)
@@ -42,14 +43,14 @@ jr = westjr.WestJR(line="kobesanyo", area="kinki")
 
 ```python
 print(jr.get_trains())
-# {'update': '2021-03-31T08:14:34.313Z', 'trains': [{'no': '798T', 'pos': '0414_0415', ...```
+# {'update': '2021-03-31T08:14:34.313Z', 'trains': [{'no': '798T', 'pos': '0414_0415', ...
 ```
 
-#### 駅一覧取得
+#### メンテナンス予定取得
 
 ```python
-print(jr.get_stations())
-# {'stations': [{'info': {'name': '新大阪', 'code': '0415', 'stopTrains': [1, 2, 5], 'typeNotice': None, ...
+print(jr.get_maintenance())
+# {'status': 1, 'notification': {'groupId': 2023012802, 'text': '1月24日から1月31日を, ...
 ```
 
 #### 路線一覧取得
@@ -59,6 +60,13 @@ print(jr.get_lines())
 # {'lines': {'ako': {'name': '赤穂線', 'range': '相生〜播州赤穂', 'st': ...
 ```
 
+#### 駅一覧取得
+
+```python
+print(jr.get_stations())
+# {'stations': [{'info': {'name': '新大阪', 'code': '0415', 'stopTrains': [1, 2, 5], 'typeNotice': None, ...
+```
+
 #### 運行情報取得
 
 ```Python

example.py

@@ -8,6 +8,8 @@
 # {'stations': [{'info': {'name': '新大阪', 'code': '0415', 'stopTrains': [1, 2, 5], 'typeNotice': None, ...
 print(jr.get_lines())
 # {'lines': {'ako': {'name': '赤穂線', 'range': '相生〜播州赤穂', 'st': ...
+print(jr.get_maintenance())
+# {'status': 1, 'notification': {'groupId': 2023012802, 'text': '1月24日から1月31日...
 print(jr.get_traffic_info())
 # {'lines': {}, 'express': {}}
 

westjr/api.py

@@ -7,6 +7,7 @@
 
 from .const import AREAS, LINES, STATIONS, STOP_TRAINS
 from .response_types import (
+    AreaMaintenance,
     AreaMaster,
     ResponseDict,
     Stations,
@@ -91,6 +92,32 @@ def get_trains(self, line: str | None = None) -> TrainPos:
 
         return cast(TrainPos, res)
 
+    def get_maintenance(self, area: str | None = None) -> AreaMaintenance:
+        """
+        メンテナンス予定を取得して返す．大雪などで運休が予定されているときのみ情報が載る．
+        :param area: [必須] 広域エリア名(ex. kinki)
+        :return: dict
+        """
+        _area = area if area else self.area
+        if _area is None:
+            raise ValueError("Need to set the area name.")
+        endpoint = f"area_{_area}_maintenance"
+        res = self._request(endpoint=endpoint)
+        if res is None:
+            raise ValueError("Response is empty")
+        return cast(AreaMaintenance, res)
+
+    def get_train_monitor_info(self) -> TrainMonitorInfo:
+        """
+        列車の環境を取得して返す．
+        :return: dict
+        """
+        endpoint = "trainmonitorinfo"
+        res = self._request(endpoint=endpoint)
+        if res is None:
+            raise ValueError("Response is empty")
+        return cast(TrainMonitorInfo, res)
+
     def get_traffic_info(self, area: str | None = None) -> TrainInfo:
         """
         路線の交通情報を取得して返す．問題が発生しているときのみ情報が載る．
@@ -157,10 +184,3 @@ def convert_pos(
         else:
             raise ValueError(f"invalid direction: {_direction}")
         return prev_st_name, next_st_name
-
-    def get_train_monitor_info(self) -> TrainMonitorInfo:
-        endpoint = "trainmonitorinfo"
-        res = self._request(endpoint=endpoint)
-        if res is None:
-            raise ValueError("Response is empty")
-        return cast(TrainMonitorInfo, res)

westjr/response_types/__init__.py

@@ -2,21 +2,26 @@
 
 from typing import Union
 
-from . import area_master, stations, train_info, train_pos
+from . import area_maintenance, area_master, stations, train_info, train_pos
+from .area_maintenance import AreaMaintenance
 from .area_master import AreaMaster
 from .stations import Stations
 from .train_info import TrainInfo
 from .train_monitor_info import TrainMonitorInfo
 from .train_pos import TrainPos, TrainsItem
 
-ResponseDict = Union[AreaMaster, Stations, TrainInfo, TrainPos, TrainMonitorInfo]
+ResponseDict = Union[
+    AreaMaintenance, AreaMaster, Stations, TrainInfo, TrainPos, TrainMonitorInfo
+]
 
 __all__ = [
+    "area_maintenance",
     "area_master",
     "stations",
     "train_info",
     "train_pos",
     "train_monitor_info",
+    "AreaMaintenance",
     "AreaMaster",
     "Stations",
     "TrainInfo",

westjr/response_types/area_maintenance.py

@@ -0,0 +1,24 @@
+# [/api/v3/area_{AREA}_maintenance.json]
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+
+class Notification(TypedDict):
+    groupId: int
+    text: str
+    duration: str
+
+
+class Maintenance(TypedDict):
+    title: str
+    text: str
+    duration: str
+    linkTitle: str
+    linkUrl: str
+
+
+class AreaMaintenance(TypedDict):
+    status: int
+    notification: Notification
+    maintenance: Maintenance