apyefa 0.0.1__py3-none-any.whl

apyefa/__init__.py

@@ -0,0 +1,21 @@
+from apyefa.client import EfaClient
+from apyefa.data_classes import (
+    Departure,
+    Line,
+    Location,
+    LocationFilter,
+    LocationType,
+    SystemInfo,
+    TransportType,
+)
+
+__all__ = [
+    "LocationFilter",
+    "Location",
+    "LocationType",
+    "Departure",
+    "SystemInfo",
+    "Line",
+    "TransportType",
+    "EfaClient",
+]

apyefa/client.py

@@ -0,0 +1,215 @@
+import logging
+
+import aiohttp
+
+from apyefa.commands import (
+    Command,
+    CommandDepartures,
+    CommandServingLines,
+    CommandStopFinder,
+    CommandSystemInfo,
+)
+from apyefa.data_classes import (
+    CoordFormat,
+    Departure,
+    Line,
+    Location,
+    LocationFilter,
+    LocationType,
+    SystemInfo,
+)
+from apyefa.exceptions import EfaConnectionError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EfaClient:
+    async def __aenter__(self):
+        self._client_session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, *args, **kwargs):
+        await self._client_session.__aexit__(*args, **kwargs)
+
+    def __init__(self, url: str, debug: bool = False):
+        """Create a new instance of client.
+
+        Args:
+            url (str): url string to EFA endpoint
+
+        Raises:
+            ValueError: No url provided
+        """
+        if not url:
+            raise ValueError("No EFA endpoint url provided")
+
+        self._debug: bool = debug
+        self._base_url: str = url if url.endswith("/") else f"{url}/"
+
+    async def info(self) -> SystemInfo:
+        """Get system info used by EFA endpoint.
+
+        Returns:
+            SystemInfo: info object
+        """
+        _LOGGER.info("Request system info")
+
+        command = CommandSystemInfo()
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def locations_by_name(
+        self, name: str, *, filters: list[LocationFilter] = [], limit: int = 30
+    ) -> list[Location]:
+        """Find location(s) by provided `name`.
+
+        Args:
+            name (str): Name or ID of location to search (case insensitive)
+            e.g. "Plärrer", "Nordostbanhof" or "de:09564:704"
+            filters (list[LocationFilter], optional): List of filters to apply for search. Defaults to empty.
+            limit (int, optional): Max size of returned list. Defaults to 30.
+
+        Returns:
+            list[Location]: List of location(s) returned by endpoint. List is sorted by match quality.
+        """
+        _LOGGER.info(f"Request location search by name/id: {name}")
+        _LOGGER.debug(f"filters: {filters}")
+        _LOGGER.debug(f"limit: {limit}")
+
+        command = CommandStopFinder("any", name)
+        command.add_param("anyMaxSizeHitList", limit)
+
+        if filters:
+            command.add_param("anyObjFilter_sf", sum(filters))
+
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def location_by_coord(
+        self,
+        coord_x: float,
+        coord_y: float,
+        format: CoordFormat = CoordFormat.WGS84,
+        limit: int = 10,
+    ) -> Location:
+        """Find location(s) by provided `coordinates`.
+
+        Args:
+            coord_x (float): X coordinate
+            coord_y (float): Y coordinate
+            format (CoordFormat, optional): Coordinate format. Defaults to CoordFormat.WGS84.
+            limit (int, optional): Max size of returned list. Defaults to 10.
+
+        Returns:
+            Location: List of location(s) returned by endpoint. List is sorted by match quality.
+        """
+        _LOGGER.info("Request location search by coordinates")
+        _LOGGER.debug(f"coord_x: {coord_x}")
+        _LOGGER.debug(f"coord_y: {coord_y}")
+        _LOGGER.debug(f"format: {format}")
+        _LOGGER.debug(f"limit: {limit}")
+
+        command = CommandStopFinder("coord", f"{coord_x}:{coord_y}:{format}")
+        command.add_param("anyMaxSizeHitList", limit)
+
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def trip(self):
+        raise NotImplementedError
+
+    async def departures_by_location(
+        self,
+        stop: Location | str,
+        limit=40,
+        date: str | None = None,
+    ) -> list[Departure]:
+        _LOGGER.info(f"Request departures for stop {stop}")
+        _LOGGER.debug(f"limit: {limit}")
+        _LOGGER.debug(f"date: {date}")
+
+        if isinstance(stop, Location):
+            stop = stop.id
+
+        command = CommandDepartures(stop)
+
+        # add parameters
+        command.add_param("limit", limit)
+        command.add_param_datetime(date)
+
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def lines_by_name(self, line: str) -> list[Line]:
+        """Search lines by name. e.g. subway `U3` or bus `65`
+
+        Args:
+            line (str): Line name to search
+
+        Returns:
+            list[Transport]: List of lines
+        """
+        _LOGGER.info("Request lines by name")
+        _LOGGER.debug(f"line:{line}")
+
+        command = CommandServingLines("line", line)
+
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def lines_by_location(self, location: str | Location) -> list[Line]:
+        """Search for lines that pass `location`. Location can be location ID like `de:08111:6221` or a Location object
+
+        Args:
+            location (str | Location): Location
+
+        Raises:
+            ValueError: If not a stop location provided but e.g. POI or Address
+
+        Returns:
+            list[Transport]: List of lines
+        """
+        _LOGGER.info("Request lines by location")
+        _LOGGER.debug(f"location:{location}")
+
+        if isinstance(location, Location):
+            if location.loc_type != LocationType.STOP:
+                raise ValueError(
+                    f"Only locations with type Stop are supported, provided {location.loc_type}"
+                )
+            location = location.id
+
+        command = CommandServingLines("odv", location)
+
+        response = await self._run_query(self._build_url(command))
+
+        return command.parse(response)
+
+    async def locations_by_line(self, line: str | Line) -> list[Location]:
+        raise NotImplementedError
+
+    async def _run_query(self, query: str) -> str:
+        _LOGGER.info(f"Run query {query}")
+
+        async with self._client_session.get(query, ssl=False) as response:
+            _LOGGER.debug(f"Response status: {response.status}")
+
+            if response.status == 200:
+                text = await response.text()
+
+                if self._debug:
+                    _LOGGER.debug(text)
+
+                return text
+            else:
+                raise EfaConnectionError(
+                    f"Failed to fetch data from endpoint. Returned status: {response.status}"
+                )
+
+    def _build_url(self, cmd: Command):
+        return self._base_url + str(cmd)

apyefa/commands/__init__.py

@@ -0,0 +1,15 @@
+from .command import Command
+from .command_departures import CommandDepartures
+from .command_serving_lines import CommandServingLines
+from .command_stop_finder import CommandStopFinder
+from .command_system_info import CommandSystemInfo
+from .command_trip import CommandTrip
+
+__all__ = [
+    "Command",
+    "CommandDepartures",
+    "CommandStopFinder",
+    "CommandSystemInfo",
+    "CommandTrip",
+    "CommandServingLines",
+]

apyefa/commands/command.py

@@ -0,0 +1,115 @@
+import logging
+from abc import abstractmethod
+
+from voluptuous import MultipleInvalid, Schema
+
+from apyefa.commands.parsers.rapid_json_parser import RapidJsonParser
+from apyefa.exceptions import EfaFormatNotSupported, EfaParameterError
+from apyefa.helpers import is_date, is_datetime, is_time
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class Command:
+    def __init__(self, name: str, macro: str, output_format: str = "rapidJSON") -> None:
+        self._name: str = name
+        self._macro: str = macro
+        self._parameters: dict[str, str] = {}
+        self._format: str = output_format
+
+        self.add_param("outputFormat", output_format)
+        self.add_param("coordOutputFormat", "WGS84")
+
+    def add_param(self, param: str, value: str):
+        if not param or not value:
+            return
+
+        if param not in self._get_params_schema().schema.keys():
+            raise EfaParameterError(
+                f"Parameter {param} is now allowed for this command"
+            )
+
+        _LOGGER.debug(f'Add parameter "{param}" with value "{value}"')
+
+        self._parameters.update({param: value})
+
+        _LOGGER.debug("Updated parameters:")
+        _LOGGER.debug(self._parameters)
+
+    def add_param_datetime(self, date: str):
+        if not date:
+            return
+
+        if is_datetime(date):
+            self.add_param("itdDate", date.split(" ")[0])
+            self.add_param("itdTime", date.split(" ")[1].replace(":", ""))
+        elif is_date(date):
+            self.add_param("itdDate", date)
+        elif is_time(date):
+            self.add_param("itdTime", date.replace(":", ""))
+        else:
+            raise ValueError("Date(time) provided in invalid format")
+
+    def to_str(self) -> str:
+        self._parameters = self.extend_with_defaults()
+        self.validate()
+
+        return f"{self._name}?commonMacro={self._macro}" + self._get_params_as_str()
+
+    def __str__(self) -> str:
+        return self.to_str()
+
+    def validate(self):
+        """Validate self._parameters
+
+        Raises:
+            EfaParameterError: some of parameters are missing or have invalid values
+        """
+        params_schema = self._get_params_schema()
+
+        try:
+            params = self.extend_with_defaults()
+            params_schema(params)
+        except MultipleInvalid as exc:
+            _LOGGER.error("Parameters validation failed", exc_info=exc)
+            raise EfaParameterError(str(exc)) from exc
+
+    def extend_with_defaults(self) -> dict:
+        """Extend self._parameters with default values
+
+        Returns:
+            dict: parameters extended with default values
+        """
+
+        params_schema = self._get_params_schema()
+
+        return params_schema(self._parameters)
+
+    def _get_params_as_str(self) -> str:
+        """Return parameters concatenated with &
+
+        Returns:
+            str: parameters as string
+        """
+        if not self._parameters:
+            return ""
+
+        return "&" + "&".join([f"{k}={str(v)}" for k, v in self._parameters.items()])
+
+    @abstractmethod
+    def parse(self, data: str):
+        raise NotImplementedError("Abstract method not implemented")
+
+    @abstractmethod
+    def _get_params_schema(self) -> Schema:
+        raise NotImplementedError("Abstract method not implemented")
+
+    @abstractmethod
+    def _get_parser(self):
+        match self._format:
+            case "rapidJSON":
+                return RapidJsonParser()
+            case _:
+                raise EfaFormatNotSupported(
+                    f"Output format {self._format} is not supported"
+                )

apyefa/commands/command_departures.py

@@ -0,0 +1,49 @@
+import logging
+
+from voluptuous import Any, Date, Datetime, Optional, Required, Schema
+
+from apyefa.commands.command import Command
+from apyefa.data_classes import Departure
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CommandDepartures(Command):
+    def __init__(self, stop: str) -> None:
+        super().__init__("XML_DM_REQUEST", "dm")
+
+        self.add_param("name_dm", stop)
+
+    def parse(self, data: dict):
+        data = self._get_parser().parse(data)
+
+        departures = data.get("stopEvents", [])
+
+        _LOGGER.info(f"{len(departures)} departure(s) found")
+
+        result = []
+
+        for departure in departures:
+            result.append(Departure.from_dict(departure))
+
+        return result
+
+    def _get_params_schema(self) -> Schema:
+        return Schema(
+            {
+                Required("outputFormat", default="rapidJSON"): Any("rapidJSON"),
+                Required("coordOutputFormat", default="WGS84"): Any("WGS84"),
+                Required("name_dm"): str,
+                Required("type_dm", default="stop"): Any("any", "stop"),
+                Required("mode", default="direct"): Any("any", "direct"),
+                Optional("itdTime"): Datetime("%M%S"),
+                Optional("itdDate"): Date("%Y%m%d"),
+                Optional("useAllStops"): Any("0", "1", 0, 1),
+                Optional("useRealtime", default=1): Any("0", "1", 0, 1),
+                Optional("lsShowTrainsExplicit"): Any("0", "1", 0, 1),
+                Optional("useProxFootSearch"): Any("0", "1", 0, 1),
+                Optional("deleteAssigendStops_dm"): Any("0", "1", 0, 1),
+                Optional("doNotSearchForStops_dm"): Any("0", "1", 0, 1),
+                Optional("limit"): int,
+            }
+        )

apyefa/commands/command_serving_lines.py

@@ -0,0 +1,60 @@
+import logging
+
+from voluptuous import Any, Optional, Required, Schema
+
+from apyefa.commands.command import Command
+from apyefa.data_classes import Line
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CommandServingLines(Command):
+    def __init__(self, mode: str, value: str) -> None:
+        super().__init__("XML_SERVINGLINES_REQUEST", "servingLines")
+
+        match mode:
+            case "odv":
+                self.add_param("type_sl", "stopID")
+                self.add_param("name_sl", value)
+            case "line":
+                self.add_param("lineName", value)
+            case _:
+                raise ValueError(f"Mode {mode} not supported for serving lines")
+
+        self.add_param("mode", mode)
+
+    def parse(self, data: dict) -> list[Line]:
+        data = self._get_parser().parse(data)
+
+        transportations = data.get("lines", [])
+
+        _LOGGER.info(f"{len(transportations)} transportation(s) found")
+
+        result = []
+
+        for t in transportations:
+            result.append(Line.from_dict(t))
+
+        return result
+
+    def _get_params_schema(self) -> Schema:
+        return Schema(
+            {
+                Required("outputFormat", default="rapidJSON"): Any("rapidJSON"),
+                Required("coordOutputFormat", default="WGS84"): Any("WGS84"),
+                Required("mode", default="line"): Any("odv", "line"),
+                # mode 'odv'
+                Optional("type_sl"): Any("stopID"),
+                Optional("name_sl"): str,
+                # mode 'line'
+                Optional("lineName"): str,
+                Optional("lineReqType"): int,
+                Optional("mergeDir"): Any("0", "1", 0, 1),
+                Optional("lsShowTrainsExplicit"): Any("0", "1", 0, 1),
+                Optional("line"): str,
+                # Optional("doNotSearchForStops_sf"): Any("0", "1", 0, 1),
+                # Optional("anyObjFilter_origin"): Range(
+                #    min=0, max=sum([x.value for x in StopFilter])
+                # ),
+            }
+        )

apyefa/commands/command_stop_finder.py

@@ -0,0 +1,48 @@
+import logging
+
+from voluptuous import Any, Optional, Range, Required, Schema
+
+from apyefa.commands.command import Command
+from apyefa.data_classes import Location, LocationFilter
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CommandStopFinder(Command):
+    def __init__(self, req_type: str, name: str) -> None:
+        super().__init__("XML_STOPFINDER_REQUEST", "stopfinder")
+
+        self.add_param("type_sf", req_type)
+        self.add_param("name_sf", name)
+
+    def parse(self, data: dict) -> list[Location]:
+        data = self._get_parser().parse(data)
+
+        locations = data.get("locations", [])
+
+        _LOGGER.info(f"{len(locations)} location(s) found")
+
+        result = []
+
+        for location in locations:
+            result.append(Location.from_dict(location))
+
+        return sorted(result, key=lambda x: x.match_quality, reverse=True)
+
+    def _get_params_schema(self) -> Schema:
+        return Schema(
+            {
+                Required("outputFormat", default="rapidJSON"): Any("rapidJSON"),
+                Required("coordOutputFormat", default="WGS84"): Any("WGS84"),
+                Required("type_sf", default="any"): Any("any", "coord"),
+                Required("name_sf"): str,
+                Optional("anyMaxSizeHitList"): int,
+                Optional("anySigWhenPerfectNoOtherMatches"): Any("0", "1", 0, 1),
+                Optional("anyResSort_sf"): str,
+                Optional("anyObjFilter_sf"): int,
+                Optional("doNotSearchForStops_sf"): Any("0", "1", 0, 1),
+                Optional("anyObjFilter_origin"): Range(
+                    min=0, max=sum([x.value for x in LocationFilter])
+                ),
+            }
+        )

apyefa/commands/command_system_info.py

@@ -0,0 +1,28 @@
+import logging
+
+from voluptuous import Any, Optional, Required, Schema
+
+from apyefa.commands.command import Command
+from apyefa.data_classes import SystemInfo
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CommandSystemInfo(Command):
+    def __init__(self) -> None:
+        super().__init__("XML_SYSTEMINFO_REQUEST", "system")
+
+    def parse(self, data: dict) -> SystemInfo:
+        _LOGGER.info("Parsing system info response")
+
+        data = self._get_parser().parse(data)
+
+        return SystemInfo.from_dict(data)
+
+    def _get_params_schema(self) -> Schema:
+        return Schema(
+            {
+                Required("outputFormat", default="rapidJSON"): Any("rapidJSON"),
+                Optional("coordOutputFormat", default="WGS84"): Any("WGS84"),
+            }
+        )

apyefa/commands/command_trip.py

@@ -0,0 +1,31 @@
+import logging
+
+from voluptuous import Any, Optional, Required, Schema
+
+from apyefa.commands.command import Command
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CommandTrip(Command):
+    def __init__(self) -> None:
+        super().__init__("XML_TRIP_REQUEST2", "trip")
+
+    def parse(self, data: dict):
+        raise NotImplementedError
+
+    def _get_params_schema(self) -> Schema:
+        return Schema(
+            {
+                Required("outputFormat", default="rapidJSON"): Any("rapidJSON"),
+                Required("coordOutputFormat", default="WGS84"): Any("WGS84"),
+                Required("type_origin", default="any"): Any("any", "coord"),
+                Required("name_origin"): str,
+                Required("type_destination", default="any"): Any("any", "coord"),
+                Required("name_destination"): str,
+                Optional("type_via", default="any"): Any("any", "coord"),
+                Optional("name_via"): str,
+                Optional("useUT"): Any("0", "1", 0, 1),
+                Optional("useRealtime"): Any("0", "1", 0, 1),
+            }
+        )

apyefa/commands/parsers/parser.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+
+
+class Parser(ABC):
+    @abstractmethod
+    def parse(data) -> dict:
+        raise NotImplementedError

apyefa/commands/parsers/rapid_json_parser.py

@@ -0,0 +1,11 @@
+import json
+
+from apyefa.commands.parsers.parser import Parser
+
+
+class RapidJsonParser(Parser):
+    def parse(self, data: str) -> dict:
+        if not data:
+            return {}
+
+        return json.loads(data)

apyefa/commands/parsers/xml_parser.py

@@ -0,0 +1,6 @@
+from apyefa.commands.parsers.parser import Parser
+
+
+class XmlParser(Parser):
+    def parse(self, data: str) -> dict:
+        raise NotImplementedError