nextrip module

A NexTrip API wrapper. See the NexTrip API reference for more information.

class nextrip.CacheEntry(lifespan, *, initial=None, debug=False)

Bases: object

A cache entry object that contains cached data, a lifespan, and a property that returns whether or not the entry has expired.

exception CacheExpiredException

Bases: Exception

Thrown if an entry was expired upon retrieval.

data

The entry’s cached data value

expired

Whether or not the cache entry has expired

Return type:bool

hook(cache_bust, callback, *args, **kwargs)

Parameters:

• cache_bust (bool) – forces the callback to be made, overwriting any cached data
• callback (Callable) – the function to be called with args and kwargs

Returns:

the entry’s data. If it has expired, it will be updated first with the return value of the callback. Additional (positional) arguments are used as parameters for the callback if it is needed.

Return type:

CacheEntry

class nextrip.NexTrip(*, debug=False)

Bases: object

A NexTrip API wrapper object.

This provides coverage of all of the endpoints available and respects the caching requests as stated on the NexTrip API reference.

The return types of these endpoint methods are those returned by json.loads.

This will raise urllib and json exceptions.

More information regarding return types and constants can be found in the reference.

Note

All endpoint methods that include a cache_bust keyword argument provide the option to bypass the cache by setting it to True.

Example usage:

# Create a NexTrip wrapper object
from nextrip import NexTrip
nt = NexTrip()

# METRO Blue cardinal directions
dirs = nt.directions(901)

# Get stops in the first direction provided
stops = nt.stops(901, dirs[0]['Value'])

# Print the last stop's code and name
print('{0[Value]}: {0[Text]}'.format(stops[-1]))

For a more extensive example, see the demo() source code.

class Directions

Bases: enum.IntEnum

Integer enumeration of available cardinal directions. These are defined on the NexTrip API reference.

EAST = 2

NORTH = 4

SOUTH = 1

WEST = 3

departures(stop_id, cache_bust=False)

Parameters:stop_id (int) – a stop ID. Returns:a list of departures scheduled for the given stop ID.

directions(route, cache_bust=False)

Parameters:route (Union[str, int]) – a route ID Returns:the pair of directions allowed for the given route.

providers(cache_bust=False)

Returns:a list of provider names and their respective provider IDs.

routes(cache_bust=False)

Returns:a list of routes and their respective route IDs.

stops(route, direction, cache_bust=False)

Parameters:

• route (Union[str, int]) – a route ID
• direction (Union[str, int]) – a cardinal direction number

Returns:

a list of stops along the route in the direction specified. Results include the stop name and 4 character stop code.

timepoint_departures(route, direction, stop, cache_bust=False)

Parameters:

• route (Union[str, int]) – a route ID
• direction (Union[str, int]) – a cardinal direction number
• stop (str) – a 4 character stop code

Returns:

a list of departures from the given arguments.

vehicle_locations(route)

Parameters:route (Union[str, int]) – a route ID Returns:the vehicles and their properties for the given route.

nextrip.demo(route_name, stop_name, direction_name, debug=False, session=None)

Demos the functionality of the wrapper.

Parameters:

• route_name (str) – substring of the bus route name
• stop_name (str) – substring of the bus stop name
• direction_name (str) – a cardinal direction name
• session (NexTrip) – an existing NexTrip object can be provided to preserve cache entries

Returns:

the number of minutes until the next bus at the given stop going in the given direction will leave.