py-nymta 0.1.0__tar.gz

py_nymta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 py-nymta Contributors
+
+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.

py_nymta-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include pymta/py.typed

py_nymta-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: py-nymta
+Version: 0.1.0
+Summary: Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC
+Author: py-nymta Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/OnFreund/py-nymta
+Project-URL: Issues, https://github.com/OnFreund/py-nymta/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gtfs-realtime-bindings>=1.0.0
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# py-nymta
+
+Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC.
+
+## Features
+
+- Simple, clean API for accessing MTA subway real-time arrival data
+- Support for all MTA subway lines
+- Compatible with protobuf 6.x
+- Type hints for better IDE support
+- Extensible design for future bus API support
+
+## Installation
+
+```bash
+pip install py-nymta
+```
+
+## Usage
+
+### Basic Example
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed for the N/Q/R/W lines
+feed = SubwayFeed(feed_id="N")
+
+# Get the next 3 arrivals for the Q line at station B08S (southbound)
+arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+for arrival in arrivals:
+    print(f"Route {arrival.route_id} to {arrival.destination}")
+    print(f"  Arrives at: {arrival.arrival_time}")
+    print(f"  Stop ID: {arrival.stop_id}")
+```
+
+### Finding the Feed ID for a Route
+
+```python
+from pymta import SubwayFeed
+
+# Get the feed ID for a specific route
+feed_id = SubwayFeed.get_feed_id_for_route("Q")
+print(f"The Q line is in feed: {feed_id}")  # Output: N
+
+# Create a feed using the discovered feed_id
+feed = SubwayFeed(feed_id=feed_id)
+```
+
+### Custom Timeout and Max Arrivals
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed with custom timeout
+feed = SubwayFeed(feed_id="1", timeout=60)
+
+# Get up to 5 arrivals instead of the default 3
+arrivals = feed.get_arrivals(
+    route_id="1",
+    stop_id="127N",  # Times Square - 42 St (northbound)
+    max_arrivals=5
+)
+```
+
+### Error Handling
+
+```python
+from pymta import SubwayFeed, MTAFeedError
+
+feed = SubwayFeed(feed_id="A")
+
+try:
+    arrivals = feed.get_arrivals(route_id="A", stop_id="A42N")
+except MTAFeedError as e:
+    print(f"Error fetching arrivals: {e}")
+```
+
+## Station IDs and Directions
+
+MTA station IDs include a direction suffix:
+- `N` suffix: Northbound/Uptown direction
+- `S` suffix: Southbound/Downtown direction
+
+For example:
+- `127N`: Times Square - 42 St (northbound)
+- `127S`: Times Square - 42 St (southbound)
+- `B08N`: DeKalb Av (northbound)
+- `B08S`: DeKalb Av (southbound)
+
+**Note**: These are MTA designations and don't always correspond to geographic north/south.
+
+## Feed IDs
+
+The MTA groups subway lines into feeds:
+
+| Feed ID | Lines |
+|---------|-------|
+| `1` | 1, 2, 3, 4, 5, 6, GS |
+| `A` | A, C, E, H, FS |
+| `N` | N, Q, R, W |
+| `B` | B, D, F, M |
+| `L` | L |
+| `SI` | SIR (Staten Island Railway) |
+| `G` | G |
+| `J` | J, Z |
+| `7` | 7, 7X |
+
+## API Reference
+
+### `SubwayFeed`
+
+Main class for accessing subway GTFS-RT feeds.
+
+#### `__init__(feed_id: str, timeout: int = 30)`
+
+Initialize the subway feed.
+
+**Parameters:**
+- `feed_id`: The feed ID (e.g., '1', 'A', 'N', 'B', 'L', 'SI', 'G', 'J', '7')
+- `timeout`: Request timeout in seconds (default: 30)
+
+**Raises:**
+- `ValueError`: If feed_id is not valid
+
+#### `get_arrivals(route_id: str, stop_id: str, max_arrivals: int = 3) -> list[Arrival]`
+
+Get upcoming train arrivals for a specific route and stop.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id`: The stop ID including direction (e.g., '127N', 'B08S')
+- `max_arrivals`: Maximum number of arrivals to return (default: 3)
+
+**Returns:**
+- List of `Arrival` objects sorted by arrival time
+
+**Raises:**
+- `MTAFeedError`: If feed cannot be fetched or parsed
+
+#### `get_feed_id_for_route(route_id: str) -> str` (static method)
+
+Get the feed ID for a given route.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+
+**Returns:**
+- The feed ID for the route
+
+**Raises:**
+- `ValueError`: If route_id is not valid
+
+### `Arrival`
+
+Dataclass representing a single train arrival.
+
+**Attributes:**
+- `arrival_time` (datetime): The datetime when the train will arrive (UTC)
+- `route_id` (str): The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id` (str): The stop ID including direction (e.g., '127N', 'B08S')
+- `destination` (str): The trip headsign/destination
+
+### Exceptions
+
+- `MTAError`: Base exception for the library
+- `MTAFeedError`: Raised when feed cannot be fetched or parsed
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/OnFreund/py-nymta.git
+cd py-nymta
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+This library uses the official GTFS-RT protocol buffers from Google's [gtfs-realtime-bindings](https://github.com/MobilityData/gtfs-realtime-bindings) package.
+
+MTA data is provided by the [Metropolitan Transportation Authority](https://www.mta.info/).

py_nymta-0.1.0/README.md

@@ -0,0 +1,194 @@
+# py-nymta
+
+Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC.
+
+## Features
+
+- Simple, clean API for accessing MTA subway real-time arrival data
+- Support for all MTA subway lines
+- Compatible with protobuf 6.x
+- Type hints for better IDE support
+- Extensible design for future bus API support
+
+## Installation
+
+```bash
+pip install py-nymta
+```
+
+## Usage
+
+### Basic Example
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed for the N/Q/R/W lines
+feed = SubwayFeed(feed_id="N")
+
+# Get the next 3 arrivals for the Q line at station B08S (southbound)
+arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+for arrival in arrivals:
+    print(f"Route {arrival.route_id} to {arrival.destination}")
+    print(f"  Arrives at: {arrival.arrival_time}")
+    print(f"  Stop ID: {arrival.stop_id}")
+```
+
+### Finding the Feed ID for a Route
+
+```python
+from pymta import SubwayFeed
+
+# Get the feed ID for a specific route
+feed_id = SubwayFeed.get_feed_id_for_route("Q")
+print(f"The Q line is in feed: {feed_id}")  # Output: N
+
+# Create a feed using the discovered feed_id
+feed = SubwayFeed(feed_id=feed_id)
+```
+
+### Custom Timeout and Max Arrivals
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed with custom timeout
+feed = SubwayFeed(feed_id="1", timeout=60)
+
+# Get up to 5 arrivals instead of the default 3
+arrivals = feed.get_arrivals(
+    route_id="1",
+    stop_id="127N",  # Times Square - 42 St (northbound)
+    max_arrivals=5
+)
+```
+
+### Error Handling
+
+```python
+from pymta import SubwayFeed, MTAFeedError
+
+feed = SubwayFeed(feed_id="A")
+
+try:
+    arrivals = feed.get_arrivals(route_id="A", stop_id="A42N")
+except MTAFeedError as e:
+    print(f"Error fetching arrivals: {e}")
+```
+
+## Station IDs and Directions
+
+MTA station IDs include a direction suffix:
+- `N` suffix: Northbound/Uptown direction
+- `S` suffix: Southbound/Downtown direction
+
+For example:
+- `127N`: Times Square - 42 St (northbound)
+- `127S`: Times Square - 42 St (southbound)
+- `B08N`: DeKalb Av (northbound)
+- `B08S`: DeKalb Av (southbound)
+
+**Note**: These are MTA designations and don't always correspond to geographic north/south.
+
+## Feed IDs
+
+The MTA groups subway lines into feeds:
+
+| Feed ID | Lines |
+|---------|-------|
+| `1` | 1, 2, 3, 4, 5, 6, GS |
+| `A` | A, C, E, H, FS |
+| `N` | N, Q, R, W |
+| `B` | B, D, F, M |
+| `L` | L |
+| `SI` | SIR (Staten Island Railway) |
+| `G` | G |
+| `J` | J, Z |
+| `7` | 7, 7X |
+
+## API Reference
+
+### `SubwayFeed`
+
+Main class for accessing subway GTFS-RT feeds.
+
+#### `__init__(feed_id: str, timeout: int = 30)`
+
+Initialize the subway feed.
+
+**Parameters:**
+- `feed_id`: The feed ID (e.g., '1', 'A', 'N', 'B', 'L', 'SI', 'G', 'J', '7')
+- `timeout`: Request timeout in seconds (default: 30)
+
+**Raises:**
+- `ValueError`: If feed_id is not valid
+
+#### `get_arrivals(route_id: str, stop_id: str, max_arrivals: int = 3) -> list[Arrival]`
+
+Get upcoming train arrivals for a specific route and stop.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id`: The stop ID including direction (e.g., '127N', 'B08S')
+- `max_arrivals`: Maximum number of arrivals to return (default: 3)
+
+**Returns:**
+- List of `Arrival` objects sorted by arrival time
+
+**Raises:**
+- `MTAFeedError`: If feed cannot be fetched or parsed
+
+#### `get_feed_id_for_route(route_id: str) -> str` (static method)
+
+Get the feed ID for a given route.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+
+**Returns:**
+- The feed ID for the route
+
+**Raises:**
+- `ValueError`: If route_id is not valid
+
+### `Arrival`
+
+Dataclass representing a single train arrival.
+
+**Attributes:**
+- `arrival_time` (datetime): The datetime when the train will arrive (UTC)
+- `route_id` (str): The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id` (str): The stop ID including direction (e.g., '127N', 'B08S')
+- `destination` (str): The trip headsign/destination
+
+### Exceptions
+
+- `MTAError`: Base exception for the library
+- `MTAFeedError`: Raised when feed cannot be fetched or parsed
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/OnFreund/py-nymta.git
+cd py-nymta
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+This library uses the official GTFS-RT protocol buffers from Google's [gtfs-realtime-bindings](https://github.com/MobilityData/gtfs-realtime-bindings) package.
+
+MTA data is provided by the [Metropolitan Transportation Authority](https://www.mta.info/).

py_nymta-0.1.0/py_nymta.egg-info/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: py-nymta
+Version: 0.1.0
+Summary: Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC
+Author: py-nymta Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/OnFreund/py-nymta
+Project-URL: Issues, https://github.com/OnFreund/py-nymta/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gtfs-realtime-bindings>=1.0.0
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# py-nymta
+
+Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC.
+
+## Features
+
+- Simple, clean API for accessing MTA subway real-time arrival data
+- Support for all MTA subway lines
+- Compatible with protobuf 6.x
+- Type hints for better IDE support
+- Extensible design for future bus API support
+
+## Installation
+
+```bash
+pip install py-nymta
+```
+
+## Usage
+
+### Basic Example
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed for the N/Q/R/W lines
+feed = SubwayFeed(feed_id="N")
+
+# Get the next 3 arrivals for the Q line at station B08S (southbound)
+arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+for arrival in arrivals:
+    print(f"Route {arrival.route_id} to {arrival.destination}")
+    print(f"  Arrives at: {arrival.arrival_time}")
+    print(f"  Stop ID: {arrival.stop_id}")
+```
+
+### Finding the Feed ID for a Route
+
+```python
+from pymta import SubwayFeed
+
+# Get the feed ID for a specific route
+feed_id = SubwayFeed.get_feed_id_for_route("Q")
+print(f"The Q line is in feed: {feed_id}")  # Output: N
+
+# Create a feed using the discovered feed_id
+feed = SubwayFeed(feed_id=feed_id)
+```
+
+### Custom Timeout and Max Arrivals
+
+```python
+from pymta import SubwayFeed
+
+# Create a feed with custom timeout
+feed = SubwayFeed(feed_id="1", timeout=60)
+
+# Get up to 5 arrivals instead of the default 3
+arrivals = feed.get_arrivals(
+    route_id="1",
+    stop_id="127N",  # Times Square - 42 St (northbound)
+    max_arrivals=5
+)
+```
+
+### Error Handling
+
+```python
+from pymta import SubwayFeed, MTAFeedError
+
+feed = SubwayFeed(feed_id="A")
+
+try:
+    arrivals = feed.get_arrivals(route_id="A", stop_id="A42N")
+except MTAFeedError as e:
+    print(f"Error fetching arrivals: {e}")
+```
+
+## Station IDs and Directions
+
+MTA station IDs include a direction suffix:
+- `N` suffix: Northbound/Uptown direction
+- `S` suffix: Southbound/Downtown direction
+
+For example:
+- `127N`: Times Square - 42 St (northbound)
+- `127S`: Times Square - 42 St (southbound)
+- `B08N`: DeKalb Av (northbound)
+- `B08S`: DeKalb Av (southbound)
+
+**Note**: These are MTA designations and don't always correspond to geographic north/south.
+
+## Feed IDs
+
+The MTA groups subway lines into feeds:
+
+| Feed ID | Lines |
+|---------|-------|
+| `1` | 1, 2, 3, 4, 5, 6, GS |
+| `A` | A, C, E, H, FS |
+| `N` | N, Q, R, W |
+| `B` | B, D, F, M |
+| `L` | L |
+| `SI` | SIR (Staten Island Railway) |
+| `G` | G |
+| `J` | J, Z |
+| `7` | 7, 7X |
+
+## API Reference
+
+### `SubwayFeed`
+
+Main class for accessing subway GTFS-RT feeds.
+
+#### `__init__(feed_id: str, timeout: int = 30)`
+
+Initialize the subway feed.
+
+**Parameters:**
+- `feed_id`: The feed ID (e.g., '1', 'A', 'N', 'B', 'L', 'SI', 'G', 'J', '7')
+- `timeout`: Request timeout in seconds (default: 30)
+
+**Raises:**
+- `ValueError`: If feed_id is not valid
+
+#### `get_arrivals(route_id: str, stop_id: str, max_arrivals: int = 3) -> list[Arrival]`
+
+Get upcoming train arrivals for a specific route and stop.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id`: The stop ID including direction (e.g., '127N', 'B08S')
+- `max_arrivals`: Maximum number of arrivals to return (default: 3)
+
+**Returns:**
+- List of `Arrival` objects sorted by arrival time
+
+**Raises:**
+- `MTAFeedError`: If feed cannot be fetched or parsed
+
+#### `get_feed_id_for_route(route_id: str) -> str` (static method)
+
+Get the feed ID for a given route.
+
+**Parameters:**
+- `route_id`: The route/line ID (e.g., '1', 'A', 'Q')
+
+**Returns:**
+- The feed ID for the route
+
+**Raises:**
+- `ValueError`: If route_id is not valid
+
+### `Arrival`
+
+Dataclass representing a single train arrival.
+
+**Attributes:**
+- `arrival_time` (datetime): The datetime when the train will arrive (UTC)
+- `route_id` (str): The route/line ID (e.g., '1', 'A', 'Q')
+- `stop_id` (str): The stop ID including direction (e.g., '127N', 'B08S')
+- `destination` (str): The trip headsign/destination
+
+### Exceptions
+
+- `MTAError`: Base exception for the library
+- `MTAFeedError`: Raised when feed cannot be fetched or parsed
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/OnFreund/py-nymta.git
+cd py-nymta
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Credits
+
+This library uses the official GTFS-RT protocol buffers from Google's [gtfs-realtime-bindings](https://github.com/MobilityData/gtfs-realtime-bindings) package.
+
+MTA data is provided by the [Metropolitan Transportation Authority](https://www.mta.info/).

py_nymta-0.1.0/py_nymta.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+py_nymta.egg-info/PKG-INFO
+py_nymta.egg-info/SOURCES.txt
+py_nymta.egg-info/dependency_links.txt
+py_nymta.egg-info/requires.txt
+py_nymta.egg-info/top_level.txt
+pymta/__init__.py
+pymta/constants.py
+pymta/models.py
+pymta/py.typed
+tests/test_subway_feed.py

py_nymta-0.1.0/py_nymta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_nymta-0.1.0/py_nymta.egg-info/requires.txt

@@ -0,0 +1,2 @@
+gtfs-realtime-bindings>=1.0.0
+requests>=2.31.0

py_nymta-0.1.0/py_nymta.egg-info/top_level.txt

@@ -0,0 +1 @@
+pymta

py_nymta-0.1.0/pymta/__init__.py

@@ -0,0 +1,156 @@
+"""py-nymta library for accessing NYC transit real-time data."""
+
+from datetime import datetime, timezone
+
+from google.protobuf.message import DecodeError
+from google.transit import gtfs_realtime_pb2
+import requests
+
+from .constants import FEED_URLS, LINE_TO_FEED
+from .models import Arrival
+
+__version__ = "0.1.0"
+__all__ = ["SubwayFeed", "Arrival", "MTAError", "MTAFeedError"]
+
+
+class MTAError(Exception):
+    """Base exception for py-nymta library."""
+
+
+class MTAFeedError(MTAError):
+    """Exception raised when feed cannot be fetched or parsed."""
+
+
+class SubwayFeed:
+    """Interface for MTA subway real-time feeds."""
+
+    def __init__(self, feed_id: str, timeout: int = 30) -> None:
+        """Initialize the subway feed.
+
+        Args:
+            feed_id: The feed ID (e.g., '1', 'A', 'N', 'B', 'L', 'SI', 'G', 'J', '7').
+            timeout: Request timeout in seconds (default: 30).
+
+        Raises:
+            ValueError: If feed_id is not valid.
+        """
+        if feed_id not in FEED_URLS:
+            raise ValueError(
+                f"Invalid feed_id '{feed_id}'. "
+                f"Must be one of: {', '.join(FEED_URLS.keys())}"
+            )
+
+        self.feed_id = feed_id
+        self.feed_url = FEED_URLS[feed_id]
+        self.timeout = timeout
+
+    def get_arrivals(
+        self,
+        route_id: str,
+        stop_id: str,
+        max_arrivals: int = 3,
+    ) -> list[Arrival]:
+        """Get upcoming train arrivals for a specific route and stop.
+
+        Args:
+            route_id: The route/line ID (e.g., '1', 'A', 'Q').
+            stop_id: The stop ID including direction (e.g., '127N', 'B08S').
+            max_arrivals: Maximum number of arrivals to return (default: 3).
+
+        Returns:
+            List of Arrival objects sorted by arrival time.
+
+        Raises:
+            MTAFeedError: If feed cannot be fetched or parsed.
+        """
+        # Fetch the GTFS-RT feed
+        try:
+            response = requests.get(self.feed_url, timeout=self.timeout)
+            response.raise_for_status()
+        except requests.exceptions.RequestException as err:
+            raise MTAFeedError(f"Error fetching GTFS-RT feed: {err}") from err
+
+        # Parse the protobuf
+        feed = gtfs_realtime_pb2.FeedMessage()
+        try:
+            feed.ParseFromString(response.content)
+        except DecodeError as err:
+            raise MTAFeedError(f"Error parsing GTFS-RT feed: {err}") from err
+
+        arrivals: list[Arrival] = []
+        now = datetime.now(timezone.utc)
+
+        # Get base station ID (without direction suffix) for flexible matching
+        base_station_id = stop_id.rstrip("NS")
+        direction_suffix = stop_id[-1] if stop_id and stop_id[-1] in ("N", "S") else ""
+
+        # Process each entity in the feed
+        for entity in feed.entity:
+            if not entity.HasField("trip_update"):
+                continue
+
+            trip_update = entity.trip_update
+            trip = trip_update.trip
+
+            # Filter by route/line
+            if trip.route_id != route_id:
+                continue
+
+            # Process stop time updates
+            for stop_time_update in trip_update.stop_time_update:
+                current_stop_id = stop_time_update.stop_id
+
+                # Match on base station ID and direction suffix
+                if (
+                    current_stop_id
+                    and current_stop_id.startswith(base_station_id)
+                    and current_stop_id.endswith(direction_suffix)
+                    and stop_time_update.HasField("arrival")
+                ):
+                    # Get the arrival time
+                    arrival_timestamp = stop_time_update.arrival.time
+                    arrival_time = datetime.fromtimestamp(
+                        arrival_timestamp, tz=timezone.utc
+                    )
+
+                    # Only include future arrivals
+                    if arrival_time > now:
+                        # Get trip headsign if available
+                        destination = "Unknown"
+                        if trip.HasField("trip_headsign"):
+                            destination = trip.trip_headsign
+                        elif stop_time_update.HasField("stop_headsign"):
+                            destination = stop_time_update.stop_headsign
+
+                        arrivals.append(
+                            Arrival(
+                                arrival_time=arrival_time,
+                                route_id=trip.route_id,
+                                stop_id=current_stop_id,
+                                destination=destination,
+                            )
+                        )
+
+        # Sort by arrival time and limit to max_arrivals
+        arrivals.sort()
+        return arrivals[:max_arrivals]
+
+    @staticmethod
+    def get_feed_id_for_route(route_id: str) -> str:
+        """Get the feed ID for a given route.
+
+        Args:
+            route_id: The route/line ID (e.g., '1', 'A', 'Q').
+
+        Returns:
+            The feed ID for the route.
+
+        Raises:
+            ValueError: If route_id is not valid.
+        """
+        if route_id not in LINE_TO_FEED:
+            raise ValueError(
+                f"Invalid route_id '{route_id}'. "
+                f"Must be one of: {', '.join(LINE_TO_FEED.keys())}"
+            )
+        return LINE_TO_FEED[route_id]

py_nymta-0.1.0/pymta/constants.py

@@ -0,0 +1,53 @@
+"""Constants for MTA GTFS-RT library."""
+
+# MTA GTFS-RT feed URLs
+FEED_URLS = {
+    "1": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs",
+    "A": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-ace",
+    "N": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw",
+    "B": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-bdfm",
+    "L": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-l",
+    "SI": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-si",
+    "G": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-g",
+    "J": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-jz",
+    "7": "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-7",
+}
+
+# Mapping of subway lines to feed IDs
+LINE_TO_FEED = {
+    # Feed 1: 1, 2, 3, 4, 5, 6, GS (Grand Central Shuttle)
+    "1": "1",
+    "2": "1",
+    "3": "1",
+    "4": "1",
+    "5": "1",
+    "6": "1",
+    "GS": "1",
+    # Feed A: A, C, E, H (Rockaway Shuttle), FS (Franklin Av Shuttle)
+    "A": "A",
+    "C": "A",
+    "E": "A",
+    "H": "A",
+    "FS": "A",
+    # Feed N: N, Q, R, W
+    "N": "N",
+    "Q": "N",
+    "R": "N",
+    "W": "N",
+    # Feed B: B, D, F, M
+    "B": "B",
+    "D": "B",
+    "F": "B",
+    "M": "B",
+    # Feed L: L
+    "L": "L",
+    # Feed SI: SIR (Staten Island Railway)
+    "SI": "SI",
+    # Feed G: G
+    "G": "G",
+    # Feed J: J, Z
+    "J": "J",
+    "Z": "J",
+    # Feed 7: 7, 7X (7 Express)
+    "7": "7",
+}

py_nymta-0.1.0/pymta/models.py

@@ -0,0 +1,25 @@
+"""Data models for MTA GTFS-RT library."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Arrival:
+    """Represents a single train arrival."""
+
+    arrival_time: datetime
+    """The datetime when the train will arrive."""
+
+    route_id: str
+    """The route/line ID (e.g., '1', 'A', 'Q')."""
+
+    stop_id: str
+    """The stop ID including direction (e.g., '127N', 'B08S')."""
+
+    destination: str
+    """The trip headsign/destination (e.g., 'Van Cortlandt Park - 242 St')."""
+
+    def __lt__(self, other: "Arrival") -> bool:
+        """Allow sorting by arrival time."""
+        return self.arrival_time < other.arrival_time

py_nymta-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-nymta"
+version = "0.1.0"
+description = "Python library for accessing MTA (Metropolitan Transportation Authority) real-time transit data for NYC"
+readme = "README.md"
+authors = [
+    {name = "py-nymta Contributors"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "gtfs-realtime-bindings>=1.0.0",
+    "requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/OnFreund/py-nymta"
+Issues = "https://github.com/OnFreund/py-nymta/issues"
+
+[tool.setuptools.packages.find]
+include = ["pymta*"]
+exclude = ["tests*"]

py_nymta-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

py_nymta-0.1.0/tests/test_subway_feed.py

@@ -0,0 +1,167 @@
+"""Tests for SubwayFeed class."""
+
+from datetime import datetime, timezone
+from unittest.mock import Mock, patch
+
+from google.transit import gtfs_realtime_pb2
+import pytest
+
+from pymta import Arrival, MTAFeedError, SubwayFeed
+
+
+def test_init_valid_feed_id():
+    """Test initialization with valid feed ID."""
+    feed = SubwayFeed(feed_id="N")
+    assert feed.feed_id == "N"
+    assert feed.timeout == 30
+
+
+def test_init_invalid_feed_id():
+    """Test initialization with invalid feed ID."""
+    with pytest.raises(ValueError, match="Invalid feed_id"):
+        SubwayFeed(feed_id="INVALID")
+
+
+def test_get_feed_id_for_route():
+    """Test getting feed ID for a route."""
+    assert SubwayFeed.get_feed_id_for_route("Q") == "N"
+    assert SubwayFeed.get_feed_id_for_route("1") == "1"
+    assert SubwayFeed.get_feed_id_for_route("F") == "B"
+
+
+def test_get_feed_id_for_invalid_route():
+    """Test getting feed ID for invalid route."""
+    with pytest.raises(ValueError, match="Invalid route_id"):
+        SubwayFeed.get_feed_id_for_route("INVALID")
+
+
+@patch("pymta.requests.get")
+def test_get_arrivals_success(mock_get):
+    """Test getting arrivals successfully."""
+    # Create a GTFS-RT FeedMessage
+    feed_message = gtfs_realtime_pb2.FeedMessage()
+
+    # Create a trip update entity
+    entity = feed_message.entity.add()
+    entity.id = "trip1"
+
+    trip_update = entity.trip_update
+    trip_update.trip.route_id = "Q"
+    trip_update.trip.trip_headsign = "Coney Island - Stillwell Av"
+
+    # Add stop time update for the future
+    stop_time = trip_update.stop_time_update.add()
+    stop_time.stop_id = "B08S"
+    future_time = datetime.now(timezone.utc).timestamp() + 300  # 5 minutes from now
+    stop_time.arrival.time = int(future_time)
+
+    # Mock response
+    mock_response = Mock()
+    mock_response.content = feed_message.SerializeToString()
+    mock_response.raise_for_status = Mock()
+    mock_get.return_value = mock_response
+
+    # Test
+    feed = SubwayFeed(feed_id="N")
+    arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+    assert len(arrivals) == 1
+    assert arrivals[0].route_id == "Q"
+    assert arrivals[0].stop_id == "B08S"
+    assert arrivals[0].destination == "Coney Island - Stillwell Av"
+    assert isinstance(arrivals[0].arrival_time, datetime)
+
+
+@patch("pymta.requests.get")
+def test_get_arrivals_filters_past_arrivals(mock_get):
+    """Test that past arrivals are filtered out."""
+    # Create a GTFS-RT FeedMessage
+    feed_message = gtfs_realtime_pb2.FeedMessage()
+
+    # Create trip with past arrival
+    entity = feed_message.entity.add()
+    entity.id = "trip1"
+    trip_update = entity.trip_update
+    trip_update.trip.route_id = "Q"
+    trip_update.trip.trip_headsign = "Coney Island"
+
+    stop_time = trip_update.stop_time_update.add()
+    stop_time.stop_id = "B08S"
+    past_time = datetime.now(timezone.utc).timestamp() - 300  # 5 minutes ago
+    stop_time.arrival.time = int(past_time)
+
+    # Mock response
+    mock_response = Mock()
+    mock_response.content = feed_message.SerializeToString()
+    mock_response.raise_for_status = Mock()
+    mock_get.return_value = mock_response
+
+    # Test
+    feed = SubwayFeed(feed_id="N")
+    arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+    assert len(arrivals) == 0
+
+
+@patch("pymta.requests.get")
+def test_get_arrivals_max_arrivals(mock_get):
+    """Test max_arrivals parameter."""
+    # Create a GTFS-RT FeedMessage with 5 arrivals
+    feed_message = gtfs_realtime_pb2.FeedMessage()
+
+    for i in range(5):
+        entity = feed_message.entity.add()
+        entity.id = f"trip{i}"
+        trip_update = entity.trip_update
+        trip_update.trip.route_id = "Q"
+        trip_update.trip.trip_headsign = "Coney Island"
+
+        stop_time = trip_update.stop_time_update.add()
+        stop_time.stop_id = "B08S"
+        future_time = datetime.now(timezone.utc).timestamp() + (i + 1) * 60
+        stop_time.arrival.time = int(future_time)
+
+    # Mock response
+    mock_response = Mock()
+    mock_response.content = feed_message.SerializeToString()
+    mock_response.raise_for_status = Mock()
+    mock_get.return_value = mock_response
+
+    # Test
+    feed = SubwayFeed(feed_id="N")
+    arrivals = feed.get_arrivals(route_id="Q", stop_id="B08S", max_arrivals=3)
+
+    assert len(arrivals) == 3
+
+
+@patch("pymta.requests.get")
+def test_get_arrivals_network_error(mock_get):
+    """Test handling of network errors."""
+    mock_get.side_effect = Exception("Network error")
+
+    feed = SubwayFeed(feed_id="N")
+    with pytest.raises(MTAFeedError, match="Error fetching GTFS-RT feed"):
+        feed.get_arrivals(route_id="Q", stop_id="B08S")
+
+
+def test_arrival_sorting():
+    """Test that Arrival objects can be sorted by time."""
+    now = datetime.now(timezone.utc)
+    arrival1 = Arrival(
+        arrival_time=now,
+        route_id="Q",
+        stop_id="B08S",
+        destination="Coney Island",
+    )
+    arrival2 = Arrival(
+        arrival_time=now.replace(minute=now.minute + 5),
+        route_id="Q",
+        stop_id="B08S",
+        destination="Coney Island",
+    )
+
+    arrivals = [arrival2, arrival1]
+    arrivals.sort()
+
+    assert arrivals[0] == arrival1
+    assert arrivals[1] == arrival2