Metadata-Version: 2.4
Name: vvspy
Version: 2.4.0
Summary: API Wrapper for VVS (Verkehrsverbund Stuttgart)
Author-email: zaanposni <vvspy@zaanposni.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zaanposni/vvspy
Project-URL: Source, https://github.com/zaanposni/vvspy
Project-URL: Issues, https://github.com/zaanposni/vvspy/issues
Project-URL: Changelog, https://github.com/zaanposni/vvspy/releases
Keywords: vvs,api,stuttgart,wrapper,json,rest,efa,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.4
Dynamic: license-file

# 🚂 VVS API Wrapper

[![PackageVersion][package_version_img]][pypi_url]
[![PythonVersions][python_versions_img]][pypi_url]
[![License][repo_license_img]][repo_license_url]

**Fully object-oriented library** to integrate the **VVS API** into your project.
vvspy ships with type hints, so editors and type checkers understand its API.

## Installation

```bash
pip install vvspy
```

## Examples

> [!TIP]
> For optimal performance on low-spec hardware such as Raspberry Pi, it is advisable to use the string values of the enum directly to avoid the overhead associated with loading the full enum.

- Detect delay in upcoming departures:

```python
from vvspy import get_departures
from vvspy.enums import Station

deps = get_departures(Station.HAUPTBAHNHOF__TIEF, limit=3)
for dep in deps:
    if dep.delay > 0:
        print("Alarm! Delay detected.")
        print(dep)  # [Delayed] [11:47] [RB17]: Stuttgart Hauptbahnhof (oben) - Pforzheim Hauptbahnhof

    else:
        print("Train on time")
        print(dep)  # [11:47] [RB17]: Stuttgart Hauptbahnhof (oben) - Pforzheim Hauptbahnhof
```

- Detect cancellations in upcoming departures/arrivals:

```python
from vvspy import get_departures
from vvspy.enums import Station

deps = get_departures(Station.VAIHINGEN, limit=5)

for dep in deps:
    if dep.cancelled:
        print(f"Alarm! The train at {dep.real_datetime} has been cancelled!")
        # Check dep.stop_infos and dep.line_infos for more information
```

- Get complete trip info between two stations (including interchanges):

```python
from vvspy import get_trip  # also usable: get_trips
from vvspy.enums import Station

trip = get_trip(Station.HAUPTBAHNHOF__TIEF, Station.HARDTLINDE)

print(f"Duration: {trip.duration / 60} minutes")
for connection in trip.connections:
    print(f"From: {connection.origin.name} - To: {connection.destination.name}")
```

```text
# Output:
Duration: 58 minutes
From: Hauptbf (Arnulf-Klett-Platz) - To: Stuttgart Hauptbahnhof (tief)
From: Stuttgart Hauptbahnhof (tief) - To: Marbach (N)
From: Marbach (N) Bf - To: Murr Hardtlinde
```

- Filter for specific lines:

```python
from vvspy import get_departures
from vvspy.enums import Station

deps = get_departures(Station.HAUPTBAHNHOF__TIEF)
for dep in deps:
    if dep.serving_line.symbol == "S4":
        print(f"Departure of S4 at {dep.real_datetime}")
```

- Filter for specific platforms:

```python
from vvspy import get_departures
from vvspy.enums import Station

deps = get_departures(Station.HAUPTBAHNHOF__TIEF)
for dep in deps:
    if dep.platform == "101":
        print(f"Departure of {dep.serving_line.number} to {dep.serving_line.direction} on {dep.platform_name} at {dep.real_datetime}")
```

- Get trips arriving by a specific time:

```python
from datetime import datetime, timedelta
from vvspy import get_trip
from vvspy.enums import Station

tomorrow_8am = (datetime.now() + timedelta(days=1)).replace(hour=8, minute=0)

trip = get_trip(
    Station.HAUPTBAHNHOF__TIEF,
    Station.HARDTLINDE,
    check_time=tomorrow_8am,
    itdDateTimeDepArr="arr",
    itdTripDateTimeDepArr="arr",
)
```

### Get your station id

Use `get_stops` to search for a stop by name. Both `stop.stop_id` and `stop.global_id` can be used as station id in all other functions. `global_id` uses the same format as the `Station` enum:

```python
from vvspy import get_stops

stops = get_stops("Hauptbahnhof Stuttgart")
print(stops[0])
print(stops[0].global_id)
```

```text
# Output:
Stuttgart, Hauptbahnhof (de:08111:6118)
de:08111:6118
```

See also: [#64][station_id_issue_url]

### Logging

vvspy uses the python logging module. If you want to change the log level of vvspy, use the following:

```python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("vvspy")
logger.setLevel(logging.DEBUG)
```

## ⭐️ Project assistance

If you want to say **thank you** or/and support active development of `vvspy`:

- Add a [GitHub Star][repo_url] to the project.
- Report bugs and suggest features in the [issues][repo_issues_url].
- Open a [pull request][repo_pull_request_url]. See [CONTRIBUTING.md][contributing_url] for the development setup.

Please report security vulnerabilities privately as described in [SECURITY.md][security_url].

## 👀 Projects using vvspy

- [vvs_direct_connect][vvs_direct_connect_url] is a dockerized REST service providing departure data by aschuma.

## ⚠️ License

[vvspy][repo_url] is free and open-source software licensed under
the [MIT][repo_license_url].

The `Station` enum is generated from the "Haltestellen VVS" dataset by VVS, published on
[opendata-oepnv.de][vvs_opendata_url] under a Creative Commons Attribution (CC BY) license.

<!-- Repository -->

[repo_url]: https://github.com/zaanposni/vvspy
[repo_issues_url]: https://github.com/zaanposni/vvspy/issues
[repo_pull_request_url]: https://github.com/zaanposni/vvspy/pulls
[repo_license_url]: https://github.com/zaanposni/vvspy/blob/master/LICENSE
[repo_license_img]: https://img.shields.io/badge/license-MIT-red?style=for-the-badge&logo=none
[contributing_url]: https://github.com/zaanposni/vvspy/blob/master/CONTRIBUTING.md
[security_url]: https://github.com/zaanposni/vvspy/blob/master/SECURITY.md

[pypi_url]: https://pypi.org/project/vvspy/
[python_versions_img]: https://img.shields.io/pypi/pyversions/vvspy?style=for-the-badge
[package_version_img]: https://img.shields.io/pypi/v/vvspy?style=for-the-badge

[station_id_issue_url]: https://github.com/zaanposni/vvspy/issues/64
[vvs_opendata_url]: https://www.opendata-oepnv.de/ht/de/organisation/verkehrsverbuende/vvs/startseite

<!-- Projects -->

[vvs_direct_connect_url]: https://github.com/aschuma/vvs_direct_connect
