MBTAclient 0.1.0__tar.gz

mbtaclient-0.1.0/LICENSE

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

mbtaclient-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: MBTAclient
+Version: 0.1.0
+Summary: A Python client for interacting with the MBTA API
+Author-email: Luca Chiabrera <luca.chiabrera@gmail.com>
+Project-URL: Homepage, https://github.com/chiabre/MBTAclient
+Project-URL: Issues, https://github.com/chiabre/MBTAclient/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# MBTAclient
+
+**MBTAclient** is a Python client library for interacting with the Massachusetts Bay Transportation Authority (MBTA) API. This library provides easy access to MBTA data, including routes, predictions, schedules, and more.
+
+## Features
+
+- Provide simplified access to MBTA routes, stops, trips, schedules, predictions, and alerts data
+- Organize the above information into journeys, collections of trips from stop A to stop B
+- Easily integrate with Home Assistant or other Python-based systems
+
+## Contributing
+
+Contributions are welcome! If you would like to contribute to this project, please fork the repository and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.

mbtaclient-0.1.0/README.md

@@ -0,0 +1,17 @@
+# MBTAclient
+
+**MBTAclient** is a Python client library for interacting with the Massachusetts Bay Transportation Authority (MBTA) API. This library provides easy access to MBTA data, including routes, predictions, schedules, and more.
+
+## Features
+
+- Provide simplified access to MBTA routes, stops, trips, schedules, predictions, and alerts data
+- Organize the above information into journeys, collections of trips from stop A to stop B
+- Easily integrate with Home Assistant or other Python-based systems
+
+## Contributing
+
+Contributions are welcome! If you would like to contribute to this project, please fork the repository and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.

mbtaclient-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "MBTAclient"
+version = "0.1.0"
+authors = [
+  { name="Luca Chiabrera", email="luca.chiabrera@gmail.com" },
+]
+description = "A Python client for interacting with the MBTA API"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/chiabre/MBTAclient"
+Issues = "https://github.com/chiabre/MBTAclient/issues"

mbtaclient-0.1.0/setup.cfg

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

mbtaclient-0.1.0/src/MBTAclient.egg-info/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: MBTAclient
+Version: 0.1.0
+Summary: A Python client for interacting with the MBTA API
+Author-email: Luca Chiabrera <luca.chiabrera@gmail.com>
+Project-URL: Homepage, https://github.com/chiabre/MBTAclient
+Project-URL: Issues, https://github.com/chiabre/MBTAclient/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# MBTAclient
+
+**MBTAclient** is a Python client library for interacting with the Massachusetts Bay Transportation Authority (MBTA) API. This library provides easy access to MBTA data, including routes, predictions, schedules, and more.
+
+## Features
+
+- Provide simplified access to MBTA routes, stops, trips, schedules, predictions, and alerts data
+- Organize the above information into journeys, collections of trips from stop A to stop B
+- Easily integrate with Home Assistant or other Python-based systems
+
+## Contributing
+
+Contributions are welcome! If you would like to contribute to this project, please fork the repository and submit a pull request.
+
+## License
+
+This project is licensed under the MIT License.

mbtaclient-0.1.0/src/MBTAclient.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/__init__.py
+src/main.py
+src/mbta_alert.py
+src/mbta_auth.py
+src/mbta_client.py
+src/mbta_journey.py
+src/mbta_journeys.py
+src/mbta_prediction.py
+src/mbta_route.py
+src/mbta_schedule.py
+src/mbta_stop.py
+src/mbta_trip.py
+src/MBTAclient.egg-info/PKG-INFO
+src/MBTAclient.egg-info/SOURCES.txt
+src/MBTAclient.egg-info/dependency_links.txt
+src/MBTAclient.egg-info/top_level.txt

mbtaclient-0.1.0/src/MBTAclient.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mbtaclient-0.1.0/src/MBTAclient.egg-info/top_level.txt

@@ -0,0 +1,12 @@
+__init__
+main
+mbta_alert
+mbta_auth
+mbta_client
+mbta_journey
+mbta_journeys
+mbta_prediction
+mbta_route
+mbta_schedule
+mbta_stop
+mbta_trip

mbtaclient-0.1.0/src/main.py

@@ -0,0 +1,198 @@
+import aiohttp
+
+from mbta_client import MBTAClient
+from mbta_stop import MBTAStop
+from mbta_route import MBTARoute
+from mbta_journeys import MBTAJourneys
+
+
+from datetime import datetime
+from typing import Dict, List, Any
+
+API_KEY = None
+MAX_JOURNEYS = 2
+
+# ROUTE = 'Framingham/Worcester Line'
+# ARRIVE_AT = 'Wellesley Square'
+# DEPART_FROM = 'South Station'
+
+# ROUTE = 'Framingham/Worcester Line'
+# DEPART_FROM = 'Wellesley Square'
+# ARRIVE_AT = 'South Station'
+
+# ROUTE = 'Red'
+# DEPART_FROM = 'South Station'
+# ARRIVE_AT = 'Alewife'
+
+ROUTE = None
+DEPART_FROM = 'Copley'
+ARRIVE_AT = 'Park Street'
+
+# ROUTE = None
+# DEPART_FROM = 'North Station'
+# ARRIVE_AT = 'Swampscott'
+
+# ROUTE = 'Wakefield Avenue & Truman Parkway - Ashmont Station'
+# DEPART_FROM = 'Dorchester Ave @ Valley Rd'
+# ARRIVE_AT = 'River St @ Standard St'
+
+# ROUTE = 'Forest Hills Station - Back Bay Station'
+# DEPART_FROM = 'Back Bay'
+# ARRIVE_AT = 'Huntington Ave @ Opera Pl'
+
+# DEPART_FROM = 'Charlestown Navy Yard'
+# ARRIVE_AT = 'Long Wharf (South)'
+# ROUTE = 'Charlestown Ferry'
+
+# ROUTE = None
+# DEPART_FROM = 'North Billerica'
+# ARRIVE_AT = 'North Station'
+
+# ROUTE = None
+# DEPART_FROM = 'Back Bay'
+# ARRIVE_AT = 'South Station'
+
+# ROUTE = None
+# DEPART_FROM = 'Pemberton Point'
+# ARRIVE_AT = 'Summer St from Cushing Way to Water St (FLAG)'
+
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        
+        if API_KEY:
+            mbta_client = MBTAClient(session, API_KEY)
+        else:
+            mbta_client = MBTAClient(session)
+            
+
+        params = {
+            'filter[location_type]' :'0'
+        }
+        
+        stops = await mbta_client.list_stops(params)
+        
+       
+        depart_from_stops = MBTAStop.get_stops_by_name(stops,DEPART_FROM )
+        arrive_at_stops = MBTAStop.get_stops_by_name(stops,ARRIVE_AT )
+        
+        del stops
+        
+        if ROUTE:
+            routes = await mbta_client.list_routes()
+            journey_route = None
+
+            for route in routes:
+                if route.long_name == ROUTE:
+                    journey_route: MBTARoute = route
+                    break  # Found the route, no need to continue the loop
+
+            if journey_route:
+                journeys = MBTAJourneys(mbta_client, MAX_JOURNEYS, depart_from_stops, arrive_at_stops, journey_route)
+                del route
+            else:
+                journeys = MBTAJourneys(mbta_client, MAX_JOURNEYS, depart_from_stops, arrive_at_stops)
+        else:
+            journeys = MBTAJourneys(mbta_client, MAX_JOURNEYS, depart_from_stops, arrive_at_stops)
+        
+        await journeys.populate()
+        
+        for journey in journeys.journeys.values():
+            
+                route_type = journeys.get_route_type(journey)
+            
+                # if subway or ferry
+                if route_type == 0 or route_type == 1 or route_type == 4:
+                    
+                    print("###########")
+                    print("Line:", journeys.get_route_long_name(journey))  
+                    print("Type:", journeys.get_route_description(journey))        
+                    print("Color:", journeys.get_route_color(journey))
+                    print() 
+                    print("Direction:", journeys.get_trip_direction(journey)+" to "+journeys.get_trip_destination(journey))
+                    print("Destination:", journeys.get_trip_headsign(journey))
+                    print() 
+                    for i in range(len(journey.journey_stops)):
+                        print("Station:", journeys.get_stop_name(journey, i))
+                        print("Platform:", journeys.get_platform_name(journey, i))
+                        print("Time:", journeys.get_stop_time(journey, i))
+                        print("Delay:", journeys.get_stop_delay(journey, i))
+                        print("Time To:", journeys.get_stop_time_to(journey, i))
+                        print() 
+                    for j in range(len(journey.alerts)):
+                        print("Alert:" , journeys.get_alert_header(journey, j))
+                        print() 
+                
+                # if train
+                elif route_type == 2:    
+                                                      
+                    print("###########")
+                    print("Line:", journeys.get_route_long_name(journey))  
+                    print("Type:", journeys.get_route_description(journey))        
+                    print("Color:", journeys.get_route_color(journey))
+                    print() 
+                    print("Train Number:", journeys.get_trip_name(journey))
+                    print("Direction:", journeys.get_trip_direction(journey)+" to "+journeys.get_trip_destination(journey))
+                    print("Destination:", journeys.get_trip_headsign(journey))
+                    print() 
+                    for i in range(len(journey.journey_stops)):
+                        print("Station:", journeys.get_stop_name(journey, i))
+                        print("Platform:", journeys.get_platform_name(journey, i))
+                        print("Time:", journeys.get_stop_time(journey, i))
+                        print("Delay:", journeys.get_stop_delay(journey, i))
+                        print("Time To:", journeys.get_stop_time_to(journey, i))
+                        print() 
+                        
+                    for j in range(len(journey.alerts)):
+                        print("Alert:" , journeys.get_alert_header(journey, j))
+                        print() 
+                
+                #if bus
+                elif route_type == 3:
+
+                    print("###########")
+                    print("Line:", journeys.get_route_short_name(journey))  
+                    print("Type:", journeys.get_route_description(journey))        
+                    print("Color:", journeys.get_route_color(journey))
+                    print() 
+                    print("Direction:", journeys.get_trip_direction(journey)+" to "+journeys.get_trip_destination(journey))
+                    print("Destination:", journeys.get_trip_headsign(journey))
+                    print() 
+                    for i in range(len(journey.journey_stops)):
+                        print("Stop:", journeys.get_stop_name(journey, i))
+                        print("Time:", journeys.get_stop_time(journey, i))
+                        print("Delay:", journeys.get_stop_delay(journey, i))
+                        print("Time To:", journeys.get_stop_time_to(journey, i))
+                        print() 
+                        
+                    for j in range(len(journey.alerts)):
+                        print("Alert:" , journeys.get_alert_header(journey, j))
+                        print() 
+                        
+                # elif journeys.get_route_type(journey) == 4:
+
+                #     print("###########")
+                #     print("Line:", journeys.get_route_long_name(journey))  
+                #     print("Type:", journeys.get_route_description(journey))        
+                #     print("Color:", journeys.get_route_color(journey))
+                #     print() 
+                #     print("Direction:", journeys.get_trip_direction(journey)+" to "+journeys.get_trip_destination(journey))
+                #     print("Destination:", journeys.get_trip_headsign(journey))
+                #     print() 
+                #     for i in range(len(journey.journey_stops)):
+                #         print("Stop:", journeys.get_stop_name(journey, i))
+                #         print("Time:", journeys.get_stop_time(journey, i))
+                #         print("Delay:", journeys.get_stop_delay(journey, i))
+                #         print("Time To:", journeys.get_stop_time_to(journey, i))
+                #         print() 
+                #     for j in range(len(journey.alerts)):
+                #         print("Alert:" , journeys.get_alert_header(journey, j))
+                #         print()                     
+                else:
+                    
+                     print('ARGH!') 
+                                
+# Run the main function
+import asyncio
+asyncio.run(main())

mbtaclient-0.1.0/src/mbta_alert.py

@@ -0,0 +1,54 @@
+import typing
+from typing import Any, Dict, List, Optional
+
+class MBTAAlert:
+    """An alert object to hold information about an MBTA alert."""
+
+    def __init__(self, alert: Dict[str, Any]) -> None:
+        attributes = alert.get('attributes', {})
+        
+        # Basic attributes
+        self.alert_id: str = alert.get('id', '')
+        self.active_period_start: Optional[str] = attributes.get('active_period', [{}])[0].get('start', None)
+        self.active_period_end: Optional[str] = attributes.get('active_period', [{}])[0].get('end', None)
+        self.cause: str = attributes.get('cause', '')
+        self.effect: str = attributes.get('effect', '')
+        self.header_text: str = attributes.get('header', '')
+        self.description_text: Optional[str] = attributes.get('description', None)
+        self.severity: int = attributes.get('severity', 0)
+        self.created_at: str = attributes.get('created_at', '')
+        self.updated_at: str = attributes.get('updated_at', '')
+        
+        # Informed entities
+        self.informed_entities: List[Dict[str, Any]] = [
+            {
+                "activities": entity.get('activities', []),
+                "route": entity.get('route', ''),
+                "route_type": entity.get('route_type', 0),
+                "stop": entity.get('stop', ''),
+                "trip": entity.get('trip', ''),
+                "facility": entity.get('facility', '')
+            }
+            for entity in attributes.get('informed_entity', [])
+        ]
+
+    def __repr__(self) -> str:
+        return (f"MBTAalert(id={self.alert_id}, active_period_start={self.alert_active_period_start}, active_period_end={self.alert_active_period_end}, "
+                f"cause={self.alert_cause}, effect={self.alert_effect}, header_text={self.alert_header_text}, description_text={self.alert_description_text}, "
+                f"severity={self.alert_severity}, created_at={self.alert_created_at}, updated_at={self.alert_updated_at}, "
+                f"informed_entities={self.informed_entities})")
+
+    def __str__(self) -> str:
+        return f"Alert {self.alert_id}: {self.alert_header_text}"
+
+    def get_informed_stops(self) -> List[str]:
+        """Retrieve a list of unique stops from informed entities."""
+        return list({entity['stop'] for entity in self.informed_entities if entity.get('stop')})
+
+    def get_informed_trips(self) -> List[str]:
+        """Retrieve a list of unique trips from informed entities."""
+        return list({entity['trip'] for entity in self.informed_entities if entity.get('trip')})
+
+    def get_informed_routes(self) -> List[str]:
+        """Retrieve a list of unique routes from informed entities."""
+        return list({entity['route'] for entity in self.informed_entities if entity.get('route')})

mbtaclient-0.1.0/src/mbta_auth.py

@@ -0,0 +1,45 @@
+import logging
+
+from aiohttp import ClientConnectionError, ClientResponse, ClientResponseError, ClientSession
+from typing import Optional, Dict, Any
+
+class MBTAAuth:
+    """Class to make authenticated requests"""
+    
+    def __init__(self, session: ClientSession,  host: str , api_key: Optional[str] = None) -> None:
+        """Initialize the auth."""
+        self._session = session
+        self._api_key = api_key
+        self._host = host
+        
+    async def request(
+        self, method: str, path: str, params: Optional[Dict[str, Any]] = None) -> ClientResponse:
+        """Make an HTTP request with optional query parameters and JSON body."""
+        
+        if params is None:
+            params = {}
+        if self._api_key:
+            params['api_key'] = self._api_key
+        
+        try:
+            response = await self._session.request(
+                method,
+                f'https://{self._host}/{path}',
+                params=params
+            )
+            
+            # Ensure response has a valid status code
+            response.raise_for_status()
+            
+            return response
+            
+        except ClientConnectionError as error:
+            logging.error(f"Connection error: {error}")
+            raise
+        except ClientResponseError as error:
+            logging.error(f"Client response error: {error.status} - {str(error)}")
+            raise
+        except Exception as error:
+            logging.error(f"An unexpected error occurred: {error}")
+            raise
+

mbtaclient-0.1.0/src/mbta_client.py

@@ -0,0 +1,88 @@
+import aiohttp
+import logging
+
+from typing import List, Optional, Dict, Any
+
+from mbta_auth import MBTAAuth
+from mbta_route import MBTARoute
+from mbta_stop import MBTAStop
+from mbta_schedule import MBTASchedule
+from mbta_prediction import MBTAPrediction
+from mbta_trip import MBTATrip
+from mbta_alert import MBTAAlert
+
+MBTA_DEFAULT_HOST = "api-v3.mbta.com"
+
+ENDPOINTS = {
+    'STOPS': 'stops',
+    'ROUTES': 'routes',
+    'PREDICTIONS': 'predictions',
+    'SCHEDULES': 'schedules',
+    'TRIPS': 'trips',
+    'ALERTS': 'alerts'
+}
+
+class MBTAClient:
+    """Class to interact with the MBTA v3 API."""
+
+    def __init__(self, session: aiohttp.ClientSession, api_key: Optional[str] = None) -> None:
+        """Initialize the MBTA client with authentication and optional route details."""
+        if api_key:
+            self.auth = MBTAAuth(session, MBTA_DEFAULT_HOST, api_key)
+        else:
+            self.auth = MBTAAuth(session, MBTA_DEFAULT_HOST)
+  
+    
+    async def get_route(self, id: str, params: Optional[Dict[str, Any]] = None) -> MBTARoute:
+        """Get a route by its ID."""
+        route_data = await self._fetch_data(f'{ENDPOINTS["ROUTES"]}/{id}', params)
+        return MBTARoute(route_data['data'])
+    
+    async def get_stop(self, id: str, params: Optional[Dict[str, Any]] = None) -> MBTAStop:
+        """Get a stop by its ID."""
+        stop_data = await self._fetch_data(f'{ENDPOINTS["STOPS"]}/{id}', params)
+        return MBTAStop(stop_data['data'])
+    
+    async def get_trip(self, id: str, params: Optional[Dict[str, Any]] = None) -> MBTATrip:
+        """Get a trip by its ID."""
+        trip_data = await self._fetch_data(f'{ENDPOINTS["TRIPS"]}/{id}', params)
+        return MBTATrip(trip_data['data'])
+        
+    async def list_routes(self, params: Optional[Dict[str, Any]] = None) -> List[MBTARoute]:
+        """List all routes."""
+        route_data = await self._fetch_data(ENDPOINTS['ROUTES'], params)
+        return [MBTARoute(item) for item in route_data['data']]
+
+    async def list_stops(self, params: Optional[Dict[str, Any]] = None) -> List[MBTAStop]:
+        """List all stops."""
+        stop_data = await self._fetch_data(ENDPOINTS['STOPS'], params)
+        return [MBTAStop(item) for item in stop_data['data']]
+
+    async def list_schedules(self, params: Optional[Dict[str, Any]] = None) -> List[MBTASchedule]:
+        """List all schedules."""
+        schedule_data = await self._fetch_data(ENDPOINTS['SCHEDULES'], params)
+        return [MBTASchedule(item) for item in schedule_data['data']]
+    
+    async def list_predictions(self, params: Optional[Dict[str, Any]] = None) -> List[MBTAPrediction]:
+        """List all predictions."""
+        prediction_data = await self._fetch_data(ENDPOINTS['PREDICTIONS'], params)
+        return [MBTAPrediction(item) for item in prediction_data['data']]
+
+    async def list_alerts(self, params: Optional[Dict[str, Any]] = None) -> List[MBTAAlert]:
+        """List all predictions."""
+        alert_data = await self._fetch_data(ENDPOINTS['ALERTS'], params)
+        return [MBTAAlert(item) for item in alert_data['data']]
+    
+    async def _fetch_data(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Helper method to fetch data from API."""
+        response = await self.auth.request("get", endpoint, params)
+        try:
+            data = await response.json()
+            if 'data' not in data:
+                raise ValueError("Unexpected response format")
+            return data
+        except ValueError as error:
+            logging.error(f"Error processing JSON response: {error}")
+            raise
+
+

mbtaclient-0.1.0/src/mbta_journey.py

@@ -0,0 +1,143 @@
+from typing import Optional, List
+from datetime import datetime
+from mbta_stop import MBTAStop
+from mbta_route import MBTARoute
+from mbta_trip import MBTATrip
+from mbta_alert import MBTAAlert
+from mbta_prediction import MBTAPrediction
+import logging
+
+class MBTAJourney:
+    """A class to manage a journey with multiple stops."""
+
+    def __init__(self) -> None:
+        
+        self.route: Optional[MBTARoute] = None
+        self.trip: Optional[MBTATrip] = None
+        self.alerts: List[MBTAAlert] = []
+        self.journey_stops: List[MBTAJourneyStop] = []
+        
+
+    def __repr__(self) -> str:
+        stops_repr = ', '.join([repr(stop) for stop in self.journey_stops])
+        return f"MBTAjourney(route={self.route}, trip={self.trip}, stops=[{stops_repr}])"
+    
+    def add_stop(self, stop: 'MBTAJourneyStop') -> None:
+        """Add a stop to the journey."""
+        self.journey_stops.append(stop) 
+    
+    def get_stop_ids(self) -> List[str]:
+        """Return a list of stop IDs for all stops in the journey."""
+        return [journey_stop.stop.id for journey_stop in self.journey_stops]
+    
+    def find_jounrey_stop_by_id(self, stop_id: str) -> Optional['MBTAJourneyStop']:
+        """Return the MBTAjourneyStop with the given stop_id, or None if not found."""
+        for journey_stop in self.journey_stops:
+            if journey_stop.stop.id == stop_id:
+                return journey_stop
+        return None
+    
+    def update_journey_stop(self, stop_index: int, stop: MBTAStop, arrival_time: str, departure_time: str, stop_sequence: int = None, arrival_uncertainty: Optional[str] = None,   departure_uncertainty: Optional[str] = None):
+    
+        if (stop_index == 0 and len(self.journey_stops ) == 0) or (stop_index == 1 and len(self.journey_stops ) == 1):
+            journey_stop = MBTAJourneyStop(stop, arrival_time, departure_time, stop_sequence, arrival_uncertainty, departure_uncertainty)
+            self.journey_stops.append(journey_stop)
+        else:
+            self.journey_stops[stop_index].update_stop(stop, arrival_time, departure_time, stop_sequence, arrival_uncertainty, departure_uncertainty)
+            
+class MBTAJourneyStop:
+    """A journey stop object to hold and manage arrival and departure details."""
+
+    def __init__(self, stop: MBTAStop, arrival_time: str, departure_time: str, stop_sequence: int = None, arrival_uncertainty: Optional[str] = None,   departure_uncertainty: Optional[str] = None) -> None:
+        now = datetime.now().astimezone()
+
+        self.stop = stop
+        self.arrival_time = self.__parse_datetime(arrival_time)
+        self.real_arrival_time = None
+        self.arrival_uncertainty = MBTAPrediction.get_uncertainty_description(arrival_uncertainty)
+        self.arrival_delay = None
+        self.time_to_arrival = self.__time_to(self.arrival_time, now)
+
+        self.departure_time = self.__parse_datetime(departure_time)
+        self.real_departure_time = None
+        self.departure_uncertainty = MBTAPrediction.get_uncertainty_description(departure_uncertainty)
+        self.departure_delay = None
+        self.time_to_departure = self.__time_to(self.departure_time, now)
+
+        self.stop_sequence = stop_sequence
+
+    def __repr__(self) -> str:
+        return (f"MBTAjourneyStop(stop={repr(self.stop)}")
+
+    def update_stop(self, stop: MBTAStop, arrival_time: str, departure_time: str, stop_sequence: int = None, arrival_uncertainty: Optional[str] = None,   departure_uncertainty: Optional[str] = None) -> None:
+        """Update the stop details, including real arrival and departure times, uncertainties, and delays."""
+        self.stop = stop
+        self.stop_sequence = stop_sequence
+        if arrival_time is not None:
+            self.real_arrival_time = self.__parse_datetime(arrival_time)
+            if self.arrival_time is not None:
+                self.arrival_delay = self.__compute_delay(self.real_arrival_time, self.arrival_time)
+                self.time_to_arrival = self.__time_to(self.real_arrival_time, datetime.now().astimezone())
+        if departure_time is not None:
+            self.real_departure_time = self.__parse_datetime(departure_time)
+            if self.departure_time is not None:
+                self.departure_delay = self.__compute_delay(self.real_departure_time, self.departure_time)
+                self.time_to_departure = self.__time_to(self.real_departure_time, datetime.now().astimezone())
+        if arrival_uncertainty is not None:
+            self.arrival_uncertainty = arrival_uncertainty
+        if departure_uncertainty is not None:
+            self.departure_uncertainty = departure_uncertainty
+
+    def get_time(self) -> Optional[datetime]:
+        """Return the most relevant time for the stop."""
+        if self.real_departure_time is not None:
+            return self.real_departure_time
+        if self.departure_time is not None:
+            return self.departure_time
+        if self.real_arrival_time is not None:
+            return self.real_arrival_time
+        if self.arrival_time is not None:
+            return self.arrival_time
+        return None
+    
+    def get_delay(self) -> Optional[float]:
+        """Return the most relevant delay for the stop."""
+        if self.departure_delay is None and self.arrival_delay is None:
+            return None
+        if self.departure_delay is not None:
+            return self.departure_delay
+        if self.arrival_delay is not None:
+            return self.arrival_delay
+        return None
+        
+    def get_time_to(self) -> Optional[float]:
+        """Return the most relevant time to for the stop."""
+        return self.time_to_arrival or self.time_to_departure
+    
+    def get_uncertainty(self) -> Optional[str]:
+        """Return the most relevant time to for the stop."""
+        return self.arrival_uncertainty or self.departure_uncertainty
+
+    @staticmethod
+    def __time_to(time: Optional[datetime], now: datetime) -> Optional[float]:
+        if time is None:
+            return None
+        return (time - now).total_seconds()
+
+    @staticmethod
+    def __compute_delay(real_time: Optional[datetime], time: Optional[datetime]) -> Optional[float]:
+        if real_time is None or time is None:
+            return None
+        return (real_time - time).total_seconds()
+
+    @staticmethod
+    def __parse_datetime(time_str: Optional[str]) -> Optional[datetime]:
+        """Parse a string in ISO 8601 format to a datetime object."""
+        if time_str is None:
+            return None
+        try:
+            return datetime.fromisoformat(time_str)
+        except ValueError as e:
+            logging.error(f"Error parsing datetime: {e}")
+            return None
+

mbtaclient-0.1.0/src/mbta_journeys.py

@@ -0,0 +1,402 @@
+import logging
+import traceback
+from typing import Any, Dict, Optional, List
+from datetime import datetime
+from mbta_client import MBTAClient
+from mbta_stop import MBTAStop
+from mbta_route import MBTARoute
+from mbta_trip import MBTATrip
+from mbta_alert import MBTAAlert
+from mbta_schedule import MBTASchedule
+from mbta_prediction import MBTAPrediction
+from mbta_journey import MBTAJourney, MBTAJourneyStop
+
+class MBTAJourneys:
+    """A class to manage a journey on a route from/to stops."""
+
+    def __init__(self, mbta_client: MBTAClient, max_journeys: int, depart_from_stops: List[MBTAStop], arrive_at_stops: List[MBTAStop], route: MBTARoute = None) -> None:
+        self.mbta_client = mbta_client
+        self.max_journeys = max_journeys
+        self.depart_from_stops = depart_from_stops
+        self.arrive_at_stops = arrive_at_stops
+        self.route = route
+        self.journeys: Dict[str, MBTAJourney] = {} 
+        
+    async def populate(self):
+        """Populate the journeys with schedules, predictions, trips, routes, and alerts."""
+        try:
+            logging.debug("Starting to populate journeys...")
+            await self.__schedules()
+            await self.__predictions()
+            self.__finalize_journeys()
+            await self.__trips()
+            await self.__routes()
+            await self.__alerts()
+            logging.debug("Finished populating journeys.")
+        except Exception as e:
+            logging.error(f"Error populating journeys: {e}")
+            traceback.print_exc()  # This will print the full traceback to the console
+            print()
+
+    async def __schedules(self):
+        """Retrieve and process schedules based on the provided stop IDs and route ID."""
+        now = datetime.now()
+        params = {
+            'filter[stop]': ','.join(self._get_stop_ids_from_stops(self.depart_from_stops + self.arrive_at_stops)),
+            'filter[min_time]': now.strftime('%H:%M'),
+            'filter[date]': now.strftime('%Y-%m-%d'),
+            'sort': 'departure_time'
+        }
+        if self.route:  
+            params['filter[route]'] = self.route.id
+        
+        schedules: List[MBTASchedule] = await self.mbta_client.list_schedules(params)
+        
+        for schedule in schedules:
+            # if the schedule trip id not in the journeys
+            if schedule.trip_id not in self.journeys:
+                # journey stops are ordered by departure time
+                # if the first schedule stop is not in the depart stops ( = it's an arrival)
+                if schedule.stop_id not in self._get_stop_ids_from_stops(self.depart_from_stops):
+                    # skip the schedule
+                    continue
+                # create the journey
+                journey = MBTAJourney()
+                # add the journey to the journeys Dict using the trip_id as key
+                self.journeys[schedule.trip_id] = journey
+            
+            # create the stop    
+            journey_stop = MBTAJourneyStop(
+                stop = self._get_stop_by_id((self.depart_from_stops + self.arrive_at_stops), schedule.stop_id),
+                arrival_time=schedule.arrival_time,
+                departure_time=schedule.departure_time,
+                stop_sequence=schedule.stop_sequence
+            )
+            # add the stop to the journey 
+            self.journeys[schedule.trip_id].add_stop(journey_stop)
+            
+            # get the journey stops
+            stops = self.journeys[schedule.trip_id].journey_stops
+            # if there are 2 stops and 
+            # the departure stop (stops[0]) id is not in the departure stop ids OR the arrival stop (stops[1]) id is not in the arrival stop ids
+            # ( = the trip is in the wrong direction)
+            if len(stops) == 2 and (stops[0].stop.id not in self._get_stop_ids_from_stops(self.depart_from_stops) or stops[1].stop.id  not in self._get_stop_ids_from_stops(self.arrive_at_stops)):
+                # delete the yourney from the journeys Dict
+                del self.journeys[schedule.trip_id]
+                              
+    async def __predictions(self):
+        """Retrieve and process predictions based on the provided stop IDs and route ID."""
+        
+        now = datetime.now().astimezone()
+        
+        journey_stops = self.depart_from_stops + self.arrive_at_stops
+        journey_stops_ids = self._get_stop_ids_from_stops(self.depart_from_stops + self.arrive_at_stops)
+        depart_stop_ids = self._get_stop_ids_from_stops(self.depart_from_stops)
+        arrival_stop_ids = self._get_stop_ids_from_stops(self.arrive_at_stops)
+
+        params = {
+            'filter[stop]': ','.join(journey_stops_ids),
+            'sort': 'departure_time'
+        }
+        if self.route:  
+            params['filter[route]'] = self.route.id
+        
+        predictions: List[MBTAPrediction] = await self.mbta_client.list_predictions(params)
+        
+        for prediction in predictions:
+            
+            is_cancelled_trip = prediction.schedule_relationship in ['CANCELLED', 'SKIPPED']
+            is_past_trip = prediction.arrival_time and datetime.fromisoformat(prediction.arrival_time) < now
+            is_departure_stop = prediction.stop_id in depart_stop_ids
+            is_arrival_stop = prediction.stop_id in arrival_stop_ids
+
+            # If the trip of the prediction is cancelled/skipped
+            if is_cancelled_trip:
+                # remove the journey on the same trip_id from the journeys Dict
+                self.journeys.pop(prediction.trip_id, None)
+                continue
+            
+            # If the trip of the prediction is in the past remove it
+            if is_past_trip:
+                # remove the journey on the same trip_id from the journeys Dict
+                self.journeys.pop(prediction.trip_id, None)
+                continue
+            
+            # if the trip of the prediciton is not in the journeys Dict
+            if prediction.trip_id not in self.journeys:
+                # if the first stop is not a departure stop
+                if is_departure_stop:
+                    # skipp the prediction
+                    continue
+                
+                # create the journey
+                journey = MBTAJourney()
+                # add the journey to the journeys Dict using the trip_id as key
+                self.journeys[prediction.trip_id] = journey
+                
+                # add (smart update) the stop to the journey in position 0 (departure)
+                journey.update_journey_stop(
+                    0,
+                    stop=self._get_stop_by_id(journey_stops, prediction.stop_id),
+                    arrival_time=prediction.arrival_time,
+                    departure_time=prediction.departure_time,
+                    stop_sequence=prediction.stop_sequence,
+                    arrival_uncertainty=prediction.arrival_uncertainty,
+                    departure_uncertainty=prediction.departure_uncertainty
+                )
+            
+            # if the prediciton trip is in the journeys
+            else:
+                # get the journey
+                journey: MBTAJourney = self.journeys[prediction.trip_id]
+                
+                # if the prediction stop id is in the departure stop ids
+                if is_departure_stop:
+            
+                    # add (smart update) the stop to the journey in position 0 (departure)
+                    journey.update_journey_stop(
+                        0,
+                        stop=self._get_stop_by_id(journey_stops, prediction.stop_id),
+                        arrival_time=prediction.arrival_time,
+                        departure_time=prediction.departure_time,
+                        stop_sequence=prediction.stop_sequence,
+                        arrival_uncertainty=prediction.arrival_uncertainty,
+                        departure_uncertainty=prediction.departure_uncertainty
+                    )
+                            
+                # if the prediction stop id is in the arrival stop ids 
+                elif is_arrival_stop:
+
+                    # add (smart update) the stop to the journey in position 1 (arrival)                    
+                    journey.update_journey_stop(
+                        1,
+                        stop=self._get_stop_by_id(journey_stops, prediction.stop_id),
+                        arrival_time=prediction.arrival_time,
+                        departure_time=prediction.departure_time,
+                        stop_sequence=prediction.stop_sequence,
+                        arrival_uncertainty=prediction.arrival_uncertainty,
+                        departure_uncertainty=prediction.departure_uncertainty
+                    )
+                         
+    def __finalize_journeys(self):
+        """Clean up and sort valid journeys."""
+        processed_journeys = {}
+        
+        for trip_id, journey in self.journeys.items():
+            # remove journey with 1 stop or with wrong stop sequence
+            stops = journey.journey_stops
+            if len(stops) < 2 or stops[0].stop_sequence > stops[1].stop_sequence:
+                continue
+            processed_journeys[trip_id] = journey
+            
+        # Sort journeys based on departure time
+        sorted_journeys = dict(
+            sorted(
+                processed_journeys.items(),
+                key=lambda item: self._get_first_stop_departure_time(item[1])
+            )
+        )
+        
+        # Limit the number of journeys to `self.max_journeys`
+        self.journeys = dict(list(sorted_journeys.items())[:self.max_journeys])
+
+    async def __trips(self):
+        """Retrieve trip details for each journey."""
+        for trip_id, journey in self.journeys.items():
+            try:
+                trip: MBTATrip = await self.mbta_client.get_trip(trip_id)
+                journey.trip = trip
+            except Exception as e:
+                logging.error(f"Error retrieving trip {trip_id}: {e}")
+            
+    async def __routes(self):
+        """Retrieve route details for each journey."""
+
+        routes: List[MBTARoute] = []
+        
+        if self.route is not None:
+            routes.append(self.route)
+        else:
+            route_ids: List[str] = []
+            for journey in self.journeys.values():
+                if journey.trip and journey.trip.route_id and journey.trip.route_id not in route_ids:
+                    route_ids.append(journey.trip.route_id)
+                    
+            # Fetch route details
+            for route_id in route_ids:
+                try:
+                    route: MBTARoute = await self.mbta_client.get_route(route_id)
+                    routes.append(route)
+                except Exception as e:
+                    logging.error(f"Error retrieving route {route_id}: {e}")
+        
+        route_dict = {route.id: route for route in routes}
+        
+        for journey in self.journeys.values():
+            if journey.trip and journey.trip.route_id in route_dict:
+                journey.route = route_dict[journey.trip.route_id]
+                
+    async def __alerts(self):
+        """Retrieve and associate alerts with the relevant journeys."""
+        params = {
+            'filter[stop]': ','.join(self._get_all_stop_ids()),
+            'filter[trip]': ','.join(self._get_all_trip_ids()),
+            'filter[route]': ','.join(self._get_all_route_ids()),
+            'filter[activity]': 'BOARD,EXIT,RIDE'
+        }
+        
+        alerts: List[MBTAAlert] = await self.mbta_client.list_alerts(params)
+        
+        now = datetime.now().astimezone()
+               
+        for alert in alerts:
+            
+            if datetime.fromisoformat(alert.active_period_start) > now and datetime.fromisoformat(alert.active_period_end) < now:
+            
+                for informed_entity in alert.informed_entities:
+                    for journey in self.journeys.values():
+                        
+                        # if the alert is already in the journey
+                        if alert in journey.alerts:
+                            # skip the journey
+                            continue
+                        # if informed entity stop is not null and the stop id is in not in the journey stop id
+                        if informed_entity.get('stop') != '' and informed_entity['stop'] not in journey.get_stop_ids():
+                            # skip the journey
+                            continue
+                        # if informed entity trip is not null and the trip id is not in the journey trip id
+                        if informed_entity.get('trip')  != '' and informed_entity['trip'] != journey.trip.id:
+                            # skip the journey
+                            continue
+                        # if informed entity route is not null and the route id is not in the journey route id
+                        if informed_entity.get('route') != '' and informed_entity['route'] != journey.route.id:
+                            # skip the journey
+                            continue
+                        # If the informed entity stop is a departure and the informed entity activities don't include BOARD or RIDE
+                        if informed_entity['stop'] == journey.journey_stops[0].stop.id and not any(activity in informed_entity.get('activities', []) for activity in ['BOARD', 'RIDE']):
+                            # Skip the journey
+                            continue
+                        # If the informed entity stop is an arrival and the informed entity activities don't include EXIT or RIDE
+                        if informed_entity['stop'] == journey.journey_stops[1].stop.id and not any(activity in informed_entity.get('activities', []) for activity in ['EXIT', 'RIDE']):
+                            # Skip the journey
+                            continue
+                        # add the alert to the journy
+                        journey.alerts.append(alert)
+
+    def _get_stop_ids_from_stops(self, stops: List[MBTAStop]) -> List[str]:
+        """Extract stop IDs from a list of MBTAstop objects."""
+        stop_ids = [stop.id for stop in stops]
+        return stop_ids
+    
+    def _get_stop_by_id(self, stops: List[MBTAStop], stop_id: str) -> Optional[MBTAStop]:
+        """Retrieve a stop from the list of MBTAstop objects based on the stop ID."""
+        for stop in stops:
+            if stop.id == stop_id:
+                return stop
+        return None
+                           
+    def _get_first_stop_departure_time(self, journey: MBTAJourney) -> datetime:
+        """Get the departure time of the first stop in a journey."""
+        departure_stop = journey.journey_stops[0]
+        return departure_stop.get_time()
+    
+    def _get_all_stop_ids(self) -> List[str]:
+        """Retrieve a list of all unique stop IDs from the journeys."""
+        stop_ids = set()
+        for journey in self.journeys.values():
+            stop_ids.update(journey.get_stop_ids())
+        return sorted(list(stop_ids))
+
+    def _get_all_trip_ids(self) -> List[str]:
+        """Retrieve a list of all trip IDs from the journeys."""
+        return list(self.journeys.keys())
+
+    def _get_all_route_ids(self) -> List[str]:
+        """Retrieve a list of all unique route IDs from the journeys."""
+        route_ids = set()
+        for journey in self.journeys.values():
+            if journey.trip and journey.trip.route_id:
+                route_ids.add(journey.trip.route_id)
+        return sorted(list(route_ids))
+    
+    def get_route_short_name(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the long name of the route for a given journey."""
+        if journey.route:
+            return journey.route.short_name
+        return None
+        
+    def get_route_long_name(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the long name of the route for a given journey."""
+        if journey.route:
+            return journey.route.long_name
+        return None
+
+    def get_route_color(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the color of the route for a given journey."""
+        if journey.route:
+            return journey.route.color
+        return None
+
+    def get_route_description(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the description of the route for a given journey."""
+        if journey.route:
+            return MBTARoute.get_route_type_desc_by_type_id(journey.route.type)
+        return None
+
+    def get_route_type(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the description of the route for a given journey."""
+        if journey.route:
+            return journey.route.type
+        return None
+    
+    def get_trip_headsign(self, journey: MBTAJourney) -> Optional[str]:
+        """Get the headsign of the trip for a given journey."""
+        if journey.trip:
+            return journey.trip.headsign
+        return None
+
+    def get_trip_name(self, journey: MBTAJourney) -> Optional[str]:
+        if journey.trip:
+            return journey.trip.name
+        return None
+
+    def get_trip_destination(self, journey: MBTAJourney) -> Optional[str]:
+        if journey.trip and journey.route:
+            trip_direction = journey.trip.direction_id
+            return journey.route.direction_destinations[trip_direction]
+        return None
+
+    def get_trip_direction(self, journey: MBTAJourney) -> Optional[str]:
+        if journey.trip and journey.route:
+            trip_direction = journey.trip.direction_id
+            return journey.route.direction_names[trip_direction]
+        return None
+
+    def get_stop_name(self, journey: MBTAJourney, stop_index: int) -> Optional[str]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.stop.name
+
+    def get_platform_name(self, journey: MBTAJourney, stop_index: int) -> Optional[str]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.stop.platform_name
+
+    def get_stop_time(self, journey: MBTAJourney, stop_index: int) -> Optional[datetime]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.get_time()
+
+    def get_stop_delay(self, journey: MBTAJourney, stop_index: int) -> Optional[float]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.get_delay()
+    
+    def get_stop_time_to(self, journey: MBTAJourney, stop_index: int) -> Optional[float]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.get_time_to()
+    
+    def get_stop_uncertainty(self, journey: MBTAJourney, stop_index: int) -> Optional[str]:
+        journey_stop = journey.journey_stops[stop_index]
+        return journey_stop.get_uncertainty()
+    
+    def get_alert_header(self, journey: MBTAJourney, alert_index: int) -> Optional[str]:
+        alert = journey.alerts[alert_index]
+        return alert.header_text
+

mbtaclient-0.1.0/src/mbta_prediction.py

@@ -0,0 +1,40 @@
+import typing
+from typing import Any, Dict, Optional
+
+class MBTAPrediction:
+    """A prediction object to hold information about a prediction."""
+    
+    UNCERTAINTY = {
+        '60': 'Trip that has already started',
+        '120': 'Trip not started and a vehicle is awaiting departure at the origin',
+        '300': 'Vehicle has not yet been assigned to the trip',
+        '301': 'Vehicle appears to be stalled or significantly delayed',
+        '360': 'Trip not started and a vehicle is completing a previous trip'
+    }
+
+    def __init__(self, prediction: Dict[str, Any]) -> None:
+        attributes = prediction.get('attributes', {})
+        
+        self.id: str = prediction.get('id', '')
+        self.arrival_time: str = attributes.get('arrival_time', '')
+        self.arrival_uncertainty: str = self.get_uncertainty_description(attributes.get('arrival_uncertainty', ''))
+        self.departure_time: str = attributes.get('departure_time', '')
+        self.departure_uncertainty: str = self.get_uncertainty_description(attributes.get('departure_uncertainty', ''))
+        self.direction_id: int = attributes.get('direction_id', 0)
+        self.last_trip: Optional[bool] = attributes.get('last_trip')
+        self.revenue: Optional[bool] = attributes.get('revenue')
+        self.schedule_relationship: str = attributes.get('schedule_relationship', '')
+        self.status: str = attributes.get('status', '')
+        self.stop_sequence: int = attributes.get('stop_sequence', 0)
+        self.update_type: str = attributes.get('update_type', '')
+
+        self.route_id: str = prediction.get('relationships', {}).get('route', {}).get('data', {}).get('id', '')
+        self.stop_id: str = prediction.get('relationships', {}).get('stop', {}).get('data', {}).get('id', '')
+        self.trip_id: str = prediction.get('relationships', {}).get('trip', {}).get('data', {}).get('id', '')
+
+    def __repr__(self) -> str:
+        return (f"MBTAprediction(id={self.id}, route_id={self.route_id}, stop_id={self.stop_id}, trip_id={self.trip_id})")
+
+    @staticmethod
+    def get_uncertainty_description(key: str) -> str:
+        return MBTAPrediction.UNCERTAINTY.get(key, 'None')

mbtaclient-0.1.0/src/mbta_route.py

@@ -0,0 +1,38 @@
+import typing
+from typing import Any, Dict, List
+
+class MBTARoute:
+    """A route object to hold information about a route."""
+
+    ROUTE_TYPES= {
+        # 0: 'Light Rail',   # Example: Green Line
+        # 1: 'Heavy Rail',   # Example: Red Line
+        0: 'Subway',   
+        1: 'Subway',  
+        2: 'Commuter Rail',
+        3: 'Bus',
+        4: 'Ferry'
+    }
+
+    def __init__(self, route: Dict[str, Any]) -> None:
+        attributes = route.get('attributes', {})
+
+        self.id: str = route.get('id', '')
+        self.color: str = attributes.get('color', '')
+        self.description: str = attributes.get('description', '')
+        self.direction_destinations: List[str] = attributes.get('direction_destinations', [])
+        self.direction_names: List[str] = attributes.get('direction_names', [])
+        self.fare_class: str = attributes.get('fare_class', '')
+        self.long_name: str = attributes.get('long_name', '')
+        self.short_name: str = attributes.get('short_name', '')
+        self.sort_order: int = attributes.get('sort_order', 0)
+        self.text_color: str = attributes.get('text_color', '')
+        self.type: str = attributes.get('type', '')
+
+    def __repr__(self) -> str:
+        return (f"MBTAroute(id={self.id}, short_name={self.short_name})")
+
+    @staticmethod
+    def get_route_type_desc_by_type_id(route_type: int) -> str:
+        """Get a description of the route type."""
+        return MBTARoute.ROUTE_TYPES.get(route_type, 'Unknown')

mbtaclient-0.1.0/src/mbta_schedule.py

@@ -0,0 +1,28 @@
+import typing
+from typing import Any, Dict
+from datetime import datetime, timezone
+
+class MBTASchedule:
+    """A schedule object to hold information about a schedule."""
+
+    def __init__(self, schedule: Dict[str, Any]) -> None:
+        attributes = schedule.get('attributes', {})
+
+        self.id: str = schedule.get('id', '')
+        self.arrival_time: str = attributes.get('arrival_time', '')
+        self.departure_time: str = attributes.get('departure_time', '')
+        self.direction_id: int = attributes.get('direction_id', 0)
+        self.drop_off_type: str = attributes.get('drop_off_type', '')
+        self.pickup_type: str = attributes.get('pickup_type', '')
+        self.stop_headsign: str = attributes.get('stop_headsign', '')
+        self.stop_sequence: int = attributes.get('stop_sequence', 0)
+        self.timepoint: bool = attributes.get('timepoint', False)
+
+        relationships = schedule.get('relationships', {})
+        self.route_id: str = relationships.get('route', {}).get('data', {}).get('id', '')
+        self.stop_id: str = relationships.get('stop', {}).get('data', {}).get('id', '')
+        self.trip_id: str = relationships.get('trip', {}).get('data', {}).get('id', '')
+
+    def __repr__(self) -> str:
+        return (f"MBTAschedule(id={self.id}, route_id={self.route_id}, stop_id={self.stop_id}, trip_id={self.trip_id})")
+

mbtaclient-0.1.0/src/mbta_stop.py

@@ -0,0 +1,38 @@
+import typing
+from typing import Any, Dict, Optional, List
+
+class MBTAStop:
+    """A stop object to hold information about a stop."""
+
+    def __init__(self, stop: Dict[str, Any]) -> None:
+        attributes = stop.get('attributes', {})
+
+        self.id: str = stop.get('id', '')
+        self.address: str = attributes.get('address', '')
+        self.at_street: str = attributes.get('at_street', '')
+        self.description: str = attributes.get('description', '')
+        self.latitude: float = attributes.get('latitude', 0.0)
+        self.location_type: int = attributes.get('location_type', 0)
+        self.longitude: float = attributes.get('longitude', 0.0)
+        self.municipality: str = attributes.get('municipality', '')
+        self.name: str = attributes.get('name', '')
+        self.on_street: str = attributes.get('on_street', '')
+        self.platform_code: str = attributes.get('platform_code', '')
+        self.platform_name: str = attributes.get('platform_name', '')
+        self.vehicle_type: int = attributes.get('vehicle_type', 0)
+        self.wheelchair_boarding: int = attributes.get('wheelchair_boarding', 0)
+
+    def __repr__(self) -> str:
+        return (f"MBTAstop(id={self.id}, name={self.name})")
+
+    @classmethod
+    def get_stop_ids_by_name(cls, stops: List['MBTAStop'], stop_name: str) -> List[str]:
+        """Given a list of MBTAstop objects and a stop name, return a list of stop ids that match the stop name."""
+        matching_stop_ids = [stop.id for stop in stops if stop.name.lower() == stop_name.lower()]
+        return matching_stop_ids
+    
+    @classmethod
+    def get_stops_by_name(cls, stops: List['MBTAStop'], stop_name: str) -> List['MBTAStop']:
+        """Given a list of MBTAstop objects and a stop name, return a list of MBTAstop objects that match the stop name."""
+        matching_stops = [stop for stop in stops if stop.name.lower() == stop_name.lower()]
+        return matching_stops

mbtaclient-0.1.0/src/mbta_trip.py

@@ -0,0 +1,30 @@
+import typing
+from typing import Any, Dict, Optional
+
+class MBTATrip:
+    """A trip object to hold information about a trip."""
+    
+    def __init__(self, trip: Dict[str, Any]) -> None:
+        attributes = trip.get('attributes', {})
+        
+        self.id: str = trip.get('id', '')
+        self.name: str = attributes.get('name', '')
+        self.headsign: str = attributes.get('headsign', '')
+        self.direction_id: int = attributes.get('direction_id', 0)
+        self.block_id: str = attributes.get('block_id', '')
+        self.shape_id: str = attributes.get('shape_id', '')
+        self.wheelchair_accessible: Optional[bool] = attributes.get('wheelchair_accessible')
+        self.bikes_allowed: Optional[bool] = attributes.get('bikes_allowed')
+        self.schedule_relationship: str = attributes.get('schedule_relationship', '')
+
+        self.route_id: str = trip.get('relationships', {}).get('route', {}).get('data', {}).get('id', '')
+        
+        service_data = trip.get('relationships', {}).get('service', {}).get('data', {})
+        self.service_id: str = service_data.get('id', '') if service_data else ''
+
+    
+    def __repr__(self) -> str:
+        return (f"MBTAtrip(id={self.id}, route_id={self.route_id})")
+ 
+
+