apyefa 0.0.1__py3-none-any.whl

apyefa-0.0.1.dist-info/METADATA

@@ -0,0 +1,413 @@
+Metadata-Version: 2.1
+Name: apyefa
+Version: 0.0.1
+Summary: Python API for EFA(Elektronische Fahrplanauskunft) async requests
+Author-email: Alex Jung <jungdevelop@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Alex Jung 
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/alex-jung/apyefa
+Project-URL: Documentation, https://github.com/alex-jung/apyefa
+Project-URL: Repository, https://github.com/alex-jung/apyefa
+Project-URL: Issues, https://github.com/alex-jung/apyefa/issues
+Keywords: efa,vgn,gtfs,public transport,traffic
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp==3.11.7
+Requires-Dist: voluptuous==0.15.2
+Requires-Dist: tzdata==2024.2
+Provides-Extra: tests
+Requires-Dist: coverage>=5.0.3; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-asyncio==0.24.0; extra == "tests"
+Requires-Dist: pytest-benchmark[histogram]>=3.2.1; extra == "tests"
+Requires-Dist: requests==2.32.3; extra == "tests"
+
+# apyefa
+[![Python package](https://github.com/alex-jung/apyefa/actions/workflows/python-package.yml/badge.svg)](https://github.com/alex-jung/apyefa/actions/workflows/python-package.yml)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+# Intro
+**apyefa** is a python package used to asynchronously fetch public transit routing data via EFA  interfaces like [efa.vgn](https://efa.vgn.de/vgnExt_oeffi/"). It can request itineraries for Bus/Trams/Subways etc. connections and return data in a human and machine readable format.
+# Installation
+You only need to install the **apyefa** package, for example using pip:
+``` bash
+pip install apyefa
+```
+
+# Restrictions
+Currently the package supports only endpoints using [RapidJSON](https://rapidjson.org/) format. To check whether the endpoint supports this format, please call:
+``` bash
+To describe(!)
+```
+
+# Development setup
+Create and activate virtual environment. Then install dependencies required by `apefa` package.
+``` bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+```
+
+# EfaClient functions
+|Function name                                       |Implementation    |Documentation     |
+|----------------------------------------------------|------------------|------------------|
+|[info()](#info)                                     |:white_check_mark:|:white_check_mark:|
+|[locations_by_name()](#locations_by_name)           |:white_check_mark:|:white_check_mark:|
+|[location_by_coord()](#locations_by_coord)          |:white_check_mark:|:white_check_mark:|
+|[trip()](#trip)                                     |:x:               |:x:               |
+|[departures_by_location()](#departures_by_location) |:white_check_mark:|:white_check_mark:|
+|[lines_by_name()](#lines_by_name)                   |:white_check_mark:|:white_check_mark:|
+|[lines_by_location()](#lines_by_location)           |:white_check_mark:|:white_check_mark:|
+|[locations_by_line()](#locations_by_line) |:x:               |:x:               |
+|[coords()](#coords)                                 |:x:               |:x:               |
+|[geo_object()](#geo_object)                         |:x:               |:x:               |
+|[trip_stop_time()](#trip_stop_time)                 |:x:               |:x:               |
+|[stop_seq_coord()](#stop_seq_coord)                 |:x:               |:x:               |
+|[map_route()](#map_route)                           |:x:               |:x:               |
+|[add_info()](#add_info)                             |:x:               |:x:               |
+|[stop_list()](#stop_list)                           |:x:               |:x:               |
+|[line_list()](#line_list)                           |:x:               |:x:               |
+
+## info()
+Provides end API system information.
+
+### Arguments
+None
+
+### Return value
+|Type|Description|
+|----|-----------|
+|[SystemInfo](#systeminfo)|System information object|
+
+### Example request
+``` python
+from apyefa import EfaClient, SystemInfo
+from pprint import pprint
+
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    info: SystemInfo = await client.info()
+
+    pprint(info)
+
+    # OUTPUT:
+    # SystemInfo(version='10.6.14.22',
+    #            app_version='10.4.30.6 build 16.09.2024 01:30:57',
+    #            data_format='EFA10_04_00',
+    #            data_build='2024-12-02T16:53:02Z',
+    #            valid_from=datetime.date(2024, 11, 1),
+    #            valid_to=datetime.date(2025, 12, 13))
+```
+
+## locations_by_name()
+Find localities by name or unique id.
+
+### Arguments
+|Name     |Type                |Required|Description|
+|---------|--------------------|--------|-----------|
+|name     |str                 |required|Name or id ID of locality to search for|
+|filters  |list[[LocationFilter](#locationfilter)]|optional|The localition search may be limited by certain types of objects using this parameter. Default value is `[]`|
+|limit    |int                 |optional|Max size of returned list. Default value is `30`|
+
+### Return value
+|Type|Description|
+|----|-----------|
+|list[[Location](#location)]|List of locations found py provided name sorted by match quality|
+
+
+### Examples
+1. Search for all localities contain name `Plärrer`
+``` python
+from apyefa import EfaClient, Location, LocationFilter
+
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    locations: list[Location] = await client.locations_by_name("Plärrer")
+
+    print(f"Found {len(locations)} location(s)")
+    print(location[0].id)
+    print(location[0].name)
+    print(location[0].loc_type)
+    # OUTPUT:
+    # Found 20 location(s)
+    # de:09574:7132
+    # Hersbruck, Plärrer
+    # <LocationType.STOP: 'stop'>
+```
+2. Search for POIs and Addresses with name `Plärrer`
+``` python
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    locations: list[Location] = await client.locations_by_name("Plärrer", filters=[LocationFilter.ADDRESSES, LocationFilter.POIS])
+    
+    print(f"Found {len(locations)} location(s)")
+    print(location[0].id)
+    print(location[0].name)
+    print(location[0].loc_type)
+
+    # OUTPUT:
+    # Found 4 location(s)
+    # poiID:1000029001:9564000:-1:N-PLärrer:Nürnberg:N-PLärrer:ANY:POI:4431934:680416:NAV4:vgn
+    # Nürnberg, N-PLärrer
+    # <LocationType.POI: 'poi'>
+```
+3. Search by `stop id`
+``` python
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    locations: list[Location] = await client.locations_by_name("de:09564:704")
+
+    print(f"Found {len(locations)} location(s)")
+    print(location[0].id)
+    print(location[0].name)
+    print(location[0].loc_type)
+    # OUTPUT:
+    # Found 1 location(s)
+    # de:09564:704
+    # Nürnberg, N-PLärrer
+    # <LocationType.STOP: 'stop'>
+```
+
+## locations_by_coord()
+Find localities by coordinates.
+
+> :x: Currently test endpoint does not sent any answers for this request
+
+### Arguments
+|Arguments|Type                |Required|Description|
+|---------|--------------------|--------|-----------|
+|coord_x  |float               |required|X-coordinate|
+|coord_y  |float               |required|Y-coordinate|
+|format   |[CoordFormat](#coordformat)|optional|Coordinates format used for request|
+|limit    |int                 |optional|Max size of returned list. Default value is `10`|
+
+### Return value
+|Type|Description|
+|----|-----------|
+|list[[Location](#location)]|List of locations found py provided name sorted by match quality|
+
+## trip()
+
+## departures_by_location()
+Find all departures for a specific location
+
+### Arguments
+|Arguments|Type                |Required|Description|
+|---------|--------------------|--------|-----------|
+|stop     |[Location](#location) \| str |required|Location for which the departures are being sought|
+|limit    |int                 |optional|Max size of returned list. Default value is `40`|
+|date     |str                 |optional|Date/time for which the departures are sought in format "YYYYMMDD hh:mm", "YYYYMMDD" or "mm:hh". Default value is `empty`|
+
+### Return value
+|Type|Description|
+|----|-----------|
+|list[[Departure](#departure)]|List of departures sorted by departure time|
+
+### Examples
+``` python
+from apyefa import EfaClient, Departure
+
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    departures: list[Departure] = await client.departures_by_location("de:09564:704", limit=3, date="22:13")
+
+    print(f"Found {len(departures)} departure(s)")
+    print(location[0].line_name)
+    print(location[0].route)
+    print(location[0].transport)
+    print(location[0].planned_time)
+    # OUTPUT:
+    # Found 3 departure(s)
+    # U3
+    # Nordwestring - Hauptbahnhof - Plärrer - Großreuth bei Schweinau
+    # <TransportType.SUBWAY: 2>
+    # datetime.datetime(2024, 12, 7, 22, 16, tzinfo=zoneinfo.ZoneInfo(key='Europe/Berlin'))
+```
+
+## lines_by_name()
+Find lines by name.
+
+### Arguments
+|Arguments|Type                |Required|Description|
+|---------|--------------------|--------|-----------|
+|name  |str               |required|Name of the line to search. e.g. `U1` or `67`|
+
+### Return value
+|Type|Description|
+|----|-----------|
+|list[[Line](#line)]|List of lines found for provided name|
+
+> NOTE: The attribute `origin` of returned `line` objects is None
+
+### Examples
+``` python
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    lines: list[Line] = await client.lines_by_name("U1")
+
+    print(f"Found {len(lines)} line(s)")
+    print(f"id         : {lines[0].id}")
+    print(f"name       : {lines[0].name}")
+    print(f"description: {lines[0].description}")
+    print(f"product    : {lines[0].product}")
+
+    # OUTPUT:
+    # Found 4 line(s)
+    # id         : vgn:11001: :H:j24
+    # name       : U1
+    # description: Fürth Hardhöhe - Nürnberg Plärrer - Hauptbahnhof - Langwasser Süd
+    # product    : <TransportType.SUBWAY: 2> 
+```
+
+## lines_by_location()
+Find lines pass provided location.
+
+### Arguments
+|Arguments|Type                |Required|Description|
+|---------|--------------------|--------|-----------|
+|location |str \| [Location](#location) |required|The location passed by searched line(s)|
+
+### Return value
+|Type|Description|
+|----|-----------|
+|list[[Line](#line)]|List of lines found for provided location|
+
+> The attribute `origin` of returned `line` objects is None
+
+### Examples
+``` python
+async with EfaClient("https://efa.vgn.de/vgnExt_oeffi/") as client:
+    lines: list[Line] = await client.lines_by_location("de:09564:704")
+
+    print(f"Found {len(lines)} line(s)")
+    print(f"id         : {lines[0].id}")
+    print(f"name       : {lines[0].name}")
+    print(f"description: {lines[0].description}")
+    print(f"product    : {lines[0].product}")
+
+    # OUTPUT:
+    # Found 10 line(s)
+    # id         : vgn:33283: :H:j24
+    # name       : 283
+    # description: Hugenottenplatz - St. Johann - Dechsendorfer Weiher
+    # product    : <TransportType.BUS: 5> 
+```
+
+## coords()
+## geo_object()
+## trip_stop_time()
+## stop_seq_coord()
+## map_route()
+## add_info()
+## stop_list()
+## line_list()
+
+# Data Classes
+## SystemInfo
+|Attribute   |Type|Description  |
+|------------|----|------------------------ |
+|version     |str |API internal information|
+|app_version |str |API internal information |
+|data_format |str |API internal information |
+|data_build  |str |API internal information |
+|valid_from  |date|Start validity date      |
+|valid_to    |date|End validity date        |
+
+## Location
+|Attribute        |Type               |Description  |
+|-----------------|-------------------|-------------|
+|name             |str                |Name of location e.g. `Nürnberg, Nordostbahnhof`|
+|loc_type         |[LocationType](#locationtype)|Type of location e.g. `STOP` or `POI`|
+|id               |str                |Location unique id|
+|coord            |list[int]          |Location coordinates|
+|transports       |list[[TransportType](#transporttype)]|Transport type(s) this location pass|
+|parent           |[Location](#location) \| None|Parent location|
+|stops            |list[[Location](#location)]|Location with type `STOP` assigned to this location|
+|properties       |dict               |API internal information|
+
+## Departure
+|Attribute      |Type|Description              |
+|---------------|----|------------------------|
+|location       |[Location](#location) |Location of departure|
+|line_name      |str |Line name e.g. `U3`|
+|route          |str |The complete route name from origin to destination stops e.g. `Nordwestring - Hauptbahnhof - Plärrer - Großreuth bei Schweinau`|
+|origin         |[Location](#location)|Origin location|
+|destination    |[Location](#location)|Destination location|
+|transport      |[TransportType](#transporttype)|Transport type e.g. `Bus` or `Subway`|
+|planned_time   |datetime|Planned departure time|
+|estimated_time |datetime \| None|Estimated departure time(will be provided by endpoits supporting real time mode)|
+|infos          |list[dict] \| None|List of ICS messages|
+
+## Line
+|Attribute   |Type|Description              |
+|------------|----|------------------------ |
+|id          |str |Line id                  |
+|name        |str |Line name                |
+|description |str |Route name               |
+|product     |[TransportType](#transporttype) |Type of transportation. Bus, Subway etc.|
+|destination |[Location](#location)|Line destination location|
+|origin      |[Location](#location) \| None|Line start location|
+|properties  |dict|Additional properties    |
+
+# Enums
+## TransportType
+```python
+class TransportType(IntEnum):
+    RAIL        = 0 
+    SUBURBAN    = 1
+    SUBWAY      = 2 
+    CITY_RAIL   = 3 
+    TRAM        = 4
+    BUS         = 5 
+    RBUS        = 6 
+    EXPRESS_BUS = 7
+    CABLE_TRAM  = 8
+    FERRY       = 9 
+    AST         = 10  # Anruf-Sammel-Taxi
+```
+
+## CoordFormat
+```python
+class CoordFormat(StrEnum):
+    WGS84 = "WGS84 [dd.ddddd]"
+```
+
+## LocationFilter
+```python
+class LocationFilter(IntEnum):
+    NO_FILTER     = 0
+    LOCATIONS     = 1
+    STOPS         = 2
+    STREETS       = 4
+    ADDRESSES     = 8
+    INTERSACTIONS = 16
+    POIS          = 32
+    POST_CODES    = 64
+```
+
+## LocationType
+```python
+class LocationType(StrEnum):
+    STOP     = "stop"
+    POI      = "poi"
+    ADDRESS  = "address"
+    STREET   = "street"
+    LOCALITY = "locality"
+    SUBURB   = "suburb"
+    PLATFORM = "platform"
+    UNKNOWN  = "unknown"
+```

apyefa-0.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+apyefa/__init__.py,sha256=kohSwa1VlugPyxKa0QZqQFwRi4hIGrKFd74W7NDgunA,342
+apyefa/client.py,sha256=mxlxxBMEBRkklWhhbujvN5HpL8QWllSRFwIhkICcmQI,6591
+apyefa/data_classes.py,sha256=ZZfP3CAATiSYCt2AJy3Hw6vPr4Rc9TmH8UU0r0-bzwI,10195
+apyefa/exceptions.py,sha256=Vhc8FEtI1xSxbVRLFXd3BlNTekY2w3byEvd3Jhhg8h4,240
+apyefa/helpers.py,sha256=EJyj-Pw3xDrn8WKGbpfqbnaUZjHtVrE2A2LYpTkACps,1695
+apyefa/commands/__init__.py,sha256=kC7Zr8IcahAN8xEOytDUS6WCADQ5oe_nqDIPAjlzxy4,425
+apyefa/commands/command.py,sha256=wq3rEaYd3NUpkNqo2sX3Yw9-lcRerp8scAy2SVpx1hs,3577
+apyefa/commands/command_departures.py,sha256=kHOyxxSHn7F7ClAV1fQdl1O4cOVRs6a60pkqc8-r_9o,1736
+apyefa/commands/command_serving_lines.py,sha256=C8PrMVWCp71fyPzvsTYMmSaYORs60yUNdEShXEawrK0,2021
+apyefa/commands/command_stop_finder.py,sha256=oDCbjVoQVK_ARDEdmHXuaUJ-IJA0P6f99cVDRS2hqT8,1688
+apyefa/commands/command_system_info.py,sha256=0bQ0oYbp7FFqPA1b5RgaxANm9-BYlN5KiwRILCCuDVY,783
+apyefa/commands/command_trip.py,sha256=kOlchWyBRlvWBqwjqpx130VXEh5kly6KMSv_pgCBljs,1095
+apyefa/commands/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+apyefa/commands/parsers/parser.py,sha256=1PSlLpfYrNeKRTpvCcYsCzAKlNrs0oHvSN7zpF4Xcs8,140
+apyefa/commands/parsers/rapid_json_parser.py,sha256=UMexRiMKkJLcK5EEj80B6RYkWBuR8ZWD3YpeGa0J3lQ,212
+apyefa/commands/parsers/xml_parser.py,sha256=ru52QtBP68KoTZ8OgjFWrLy-PD4_j1miY8Zv5umNSE8,151
+apyefa-0.0.1.dist-info/LICENSE,sha256=C2Gdvb1B39BeEP-RGqVd7w6j94GnJo4gnYyiC_l3SFQ,1066
+apyefa-0.0.1.dist-info/METADATA,sha256=Dnau_LJIBxJKkVcZoMSx-0R3iuXtDKOXemmYDQQT72Y,15624
+apyefa-0.0.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+apyefa-0.0.1.dist-info/top_level.txt,sha256=b9VSv2S7lxdaypCumxO92IEQFpJdFuB8vQs03j5gZxY,7
+apyefa-0.0.1.dist-info/RECORD,,

apyefa-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

apyefa-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+apyefa