apyefa 0.0.1__tar.gz

apyefa-0.0.1/.github/workflows/python-package.yml

@@ -0,0 +1,58 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "master", "dev" ]
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  checks: write
+  pull-requests: write
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Display Python version
+      run: python -c "import sys; print(sys.version)"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools wheel
+        python -m pip install .[tests]
+    - name: Install the code linting and formatting tool Ruff
+      run: pipx install ruff
+    - name: Lint code with Ruff
+      run: ruff check --output-format=github --target-version=py39
+    - name: Check code formatting with Ruff
+      run: ruff format --diff --target-version=py39
+      continue-on-error: true
+    - name: Test with pytest
+      run: |
+        pytest --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
+    - name: Upload pytest test results
+      uses: actions/upload-artifact@v4
+      with:
+        name: pytest-results-${{ matrix.python-version }}
+        path: junit/test-results-${{ matrix.python-version }}.xml
+      if: ${{ always() }}
+    - name: Publish Test Results
+      uses: EnricoMi/publish-unit-test-result-action@v2
+      if: always()
+      with:
+        files: |
+          junit/**/*.xml

apyefa-0.0.1/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

apyefa-0.0.1/.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "editor.codeActionsOnSave": 
+    {
+        "source.organizeImports": "always",
+    },
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "notebook.defaultFormatter": "ms-python.black-formatter",
+    "editor.formatOnSave": true,
+    "[json]": {
+        "editor.defaultFormatter": "vscode.json-language-features"
+    }
+}

apyefa-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+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.

apyefa-0.0.1/PKG-INFO

@@ -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"
+```