transperth 0.1.3__py3-none-any.whl

transperth/__init__.py

@@ -0,0 +1,6 @@
+__version__ = '0.1.2'
+
+_BASE = '://www.transperth.wa.gov.au/'
+
+BASE_HTTPS = 'https' + _BASE
+BASE_HTTP = 'http' + _BASE

transperth/assets/train_stations.json

@@ -0,0 +1,109 @@
+[
+  {
+    "Armadale Line": [
+      "Perth Stn",
+      "McIver Stn",
+      "Claisebrook Stn",
+      "Burswood Stn",
+      "Victoria Park Stn",
+      "Carlisle Stn",
+      "Oats Street Stn",
+      "Welshpool Stn",
+      "Queens Park Stn",
+      "Cannington Stn",
+      "Beckenham Stn",
+      "Kenwick Stn",
+      "Maddington Stn",
+      "Gosnells Stn",
+      "Seaforth Stn",
+      "Kelmscott Stn",
+      "Challis Stn",
+      "Sherwood Stn",
+      "Armadale Stn"
+    ]
+  },
+  {
+    "Thornlie Line": [
+      "Perth Stn",
+      "McIver Stn",
+      "Claisebrook Stn",
+      "Burswood Stn",
+      "Victoria Park Stn",
+      "Carlisle Stn",
+      "Oats Street Stn",
+      "Welshpool Stn",
+      "Queens Park Stn",
+      "Cannington Stn",
+      "Thornlie Stn"
+    ]
+  },
+  {
+    "Midland Line": [
+      "Perth Stn",
+      "McIver Stn",
+      "Claisebrook Stn",
+      "East Perth Stn",
+      "Mt Lawley Stn",
+      "Maylands Stn",
+      "Meltham Stn",
+      "Bayswater Stn",
+      "Ashfield Stn",
+      "Bassendean Stn",
+      "Success Hill Stn",
+      "Guildford Stn",
+      "East Guildford Stn",
+      "Woodbridge Stn",
+      "Midland Stn"
+    ]
+  },
+  {
+    "Fremantle Line": [
+      "Perth Stn",
+      "City West Stn",
+      "West Leederville Stn",
+      "Subiaco Stn",
+      "Daglish Stn",
+      "Shenton Park Stn",
+      "Karrakatta Stn",
+      "Loch Street Stn",
+      "Claremont Stn",
+      "Swanbourne Stn",
+      "Grant Street Stn",
+      "Cottesloe Stn",
+      "Mosman Park Stn",
+      "Victoria Street Stn",
+      "North Fremantle Stn",
+      "Fremantle Stn"
+    ]
+  },
+  {
+    "Joondalup Line": [
+      "Perth Underground Stn",
+      "Leederville Stn",
+      "Glendalough Stn",
+      "Stirling Stn",
+      "Warwick Stn",
+      "Greenwood Stn",
+      "Whitfords Stn",
+      "Edgewater Stn",
+      "Joondalup Stn",
+      "Currambine Stn",
+      "Clarkson Stn"
+    ]
+  },
+  {
+    "Mandurah Line": [
+      "Perth Underground Stn",
+      "Esplanade Stn",
+      "Canning Bridge Stn",
+      "Bull Creek Stn",
+      "Murdoch Stn",
+      "Cockburn Central Stn",
+      "Kwinana Stn",
+      "Wellard Stn",
+      "Rockingham Stn",
+      "Warnbro Stn",
+      "Mandurah Stn"
+    ]
+  }
+]

transperth/exceptions.py

@@ -0,0 +1,53 @@
+class TransperthException(Exception):
+    """
+    Base exception for all exceptions thrown by this library
+    """
+
+
+class InvalidStopNumber(TransperthException):
+    """
+    Thrown when the provided stop number is not a five digit number
+    """
+
+
+class InvalidDirection(TransperthException):
+    """
+    Thrown when the provided direction is neither to nor from
+    """
+
+
+class InvalidStep(TransperthException):
+    """
+    Thrown when a step is not one of 'bus', 'walk', or 'train'
+    """
+
+
+class NoFareData(TransperthException):
+    """
+    Thrown when transperth does not provide data from which we
+    can assertain the fare for a route
+    """
+
+
+class NotLoggedIn(TransperthException):
+    """
+    Raised when the library detects that the session has expired
+    """
+
+
+class LoginFailed(NotLoggedIn):
+    """
+    Thrown when a login attempt fails
+    """
+
+
+class BadStationError(TransperthException):
+    """
+    Thrown when the library encounters a bad station name
+    """
+
+
+class IncompleteTrip(TransperthException):
+    """
+    Thrown when a trip is missing its conclusion
+    """

transperth/jp/fares.py

@@ -0,0 +1,115 @@
+"""
+Provides faculties for determining the price of a route under different
+circumstances
+"""
+
+from lxml import etree
+import requests
+
+from .. import BASE_HTTP
+from .utils import clean, itertext
+from .routes import determine_routes
+from .location import Location, ResolvedLocation
+from ..exceptions import NoFareData
+
+FARE_URL = BASE_HTTP + 'DesktopModules/JourneyPlannerResults/GetFares.aspx'
+
+
+__all__ = ['determine_fare']
+
+
+def determine_fare(
+        from_loco: Location or ResolvedLocation,
+        to_loco: Location or ResolvedLocation) -> dict:
+    """
+    Returns the fare for the recommended route from `from_loco` to
+    `to_loco` in the format;
+
+    .. code-block:: python
+
+        {
+            '<TICKET-CLASS>': {
+                '<TICKET-TYPE>': <COST>
+            }
+        }
+    """
+    routes = determine_routes(from_loco, to_loco)
+
+    route = routes[0]
+
+    return fares_for_route(route)
+
+
+def fares_for_route(route):
+    arguments = route['meta']['links'].get('getFares', None)
+
+    if arguments is None:
+        raise NoFareData('No fares data seem to have been provided')
+
+    return _get_fare(*arguments)
+
+
+def _get_fare(journeyCount, journeyDate, *values):
+    """
+    Used internally to format the request for a fare for a route
+    """
+
+    keys = [
+        'TripKey0', 'TripStart0', 'TripEnd0', 'TripKey1', 'TripStart1',
+        'TripEnd1', 'TripKey2', 'TripStart2', 'TripEnd2', 'TripKey3',
+        'TripStart3', 'TripEnd3', 'TripKey4', 'TripStart4', 'TripEnd4',
+        'TripKey5', 'TripStart5', 'TripEnd5'
+    ]
+
+    params = dict(zip(keys, values))
+
+    # ASP.net wants the date with normal slashes, but requests will encode
+    # the slashes, so we have to manually append the damn thing
+    url = FARE_URL + '?JDate={}'.format(journeyDate)
+
+    return parse_fares(
+        requests.get(
+            url, params=params
+        ).text
+    )
+
+
+def parse_fares(fares):
+    """
+    Parses the XML representing the fares
+    """
+
+    root = etree.HTML(fares)
+    root = root.xpath('//html/body/table/tr')[1:]  # the first is empty
+
+    # determine ticket class'
+    keys = root.pop(0).itertext()
+    keys = clean(keys)
+    keys = [key.lower() for key in keys]
+
+    # remove the 'comments' and 'fare type' column labels
+    keys = keys[1:-1]
+
+    fares = dict.fromkeys(keys, {})
+
+    root = map(itertext, root)
+    root = map(clean, root)
+
+    for fare_type in root:
+        fare_name, *fare_values = fare_type
+
+        for ticket_type, fare in zip(keys, fare_values):
+            fares[ticket_type][fare_name] = parse_money(
+                fare
+            )
+
+    return fares
+
+
+def parse_money(string):
+    """
+    Parses a string with a character denoting currency into a float
+
+    Until I can get pymoneyed to play ball, ignored the currency
+    """
+    return float(string[1:])

transperth/jp/location.py

@@ -0,0 +1,197 @@
+import re
+from lxml import etree
+from collections import namedtuple
+
+import requests
+
+from .. import BASE_HTTP
+from .utils import format_date, clean
+from ..exceptions import InvalidStopNumber, InvalidDirection
+
+STOPNUM_RE = re.compile(r'\d{5}')
+
+
+__all__ = [
+    'determine_location',
+    'Location',
+    'parse_locations',
+    'ResolvedLocation'
+]
+
+
+is_location = lambda arg: isinstance(arg, Location)
+are_locations = lambda *args: all(map(is_location, args))
+
+
+# Allows the use of Location in function signatures
+class Location():
+    pass
+
+
+def determine_location(from_loco: Location, to_loco: Location) -> dict:
+    """
+    Takes two location objects, and returns a dict of lists of ResolvedLocation
+    mapping possible corresponding real world locations and their codes.
+
+    See :func:`parse_locations` for precise output format.
+    """
+    assert are_locations(from_loco, to_loco)
+
+    URL = BASE_HTTP + 'DesktopModules/JourneyPlanner/JP.aspx'
+
+    params = {
+        'jpDate': format_date(),
+        'jpDirection': 'B',
+        # 'jpAMPM': 'AM',
+        # 'jpHour': '11',
+        # 'jpMinute': '00',
+        'fSet': 'False',
+        'fGadget': 'False',
+        'mode': 't1,b1,f1,s1',
+        'jpnMaxJourneys': '5',
+        'jpMaxChanges': '-1',
+        'jpWalkChange': 'NORMAL',
+        'jpWheelchairOnly': '0'
+    }
+
+    params.update(from_loco.as_('from'))
+    params.update(to_loco.as_('to'))
+
+    return parse_locations(
+        requests.get(URL, params=params).text
+    )
+
+
+def parse_locations(locations: str) -> dict:
+    """
+    Takes the (pure) XML from the locations request and returns it like so;
+
+    .. code-block:: python
+
+        {
+            "from": [
+                ResolvedLocation('<NAME>', '<CODE>')
+            ]
+        }
+    """
+    root = etree.XML(locations)
+
+    return {
+        element.tag.lower(): [
+            ResolvedLocation(
+                *clean(sub_element.itertext())
+            )
+            for sub_element in element
+        ]
+        for element in root
+    }
+
+
+class ResolvedLocation(namedtuple('ResolvedLocation', 'name,code')):
+    """
+    Represents a location as considered by the transperth api
+    """
+
+
+class Location(object):
+    """
+    Represents a location that has not been resolved into a (ResolvedLocation)
+    location code
+    """
+
+    def __init__(self, data: dict):
+        """
+        It is recommend you use one of the specialised methods;
+        from_address, from_stop, or from_location
+        """
+        self._data = {
+            '': 'Location',  # this is required
+            'street': '',
+            'suburb': '',
+            'location': '',
+            'stop': ''
+        }
+
+        self._data.update(data)
+
+    @classmethod
+    def from_address(self, street: str, suburb: str) -> Location:
+        return Location({
+            'street': street,
+            'suburb': suburb,
+            '': 'Point'
+        })
+
+    @classmethod
+    def from_stop(self, stop_number: 'str or int') -> Location:
+        """
+        Creates a Location from a transperth stop number.
+
+        Applies only to bus stops.
+
+        :param stop_number:
+        """
+
+        stop_number = str(stop_number)
+
+        if not STOPNUM_RE.match(stop_number):
+            raise InvalidStopNumber('Invalid stop number')
+
+        return Location({
+            'stop': stop_number,
+            '': 'Node'
+        })
+
+    @classmethod
+    def from_location(self, location: str) -> Location:
+        """
+        Creates a Location from an arbibrary location, such as;
+
+         * Curtin University, Perth
+         * Arena Joondalup
+
+        :param location: arbibrary location
+        """
+        return Location({
+            'location': location,
+            '': 'Location'
+        })
+
+    def as_(self, direction: str) -> dict:
+        """
+        Formats the _data attribute so that it can be incorporated into
+        a request to transperth's api
+
+        .. code-block:: python
+
+            {
+                'to': str,
+                'toStreet': str,
+                'toSuburb': str,
+                'toLocation': str,
+                'toStop': str,
+            }
+        """
+
+        if direction not in {'to', 'from'}:
+            raise InvalidDirection('tf casn')
+
+        self._data[''] = self._data[''].title()
+
+        return {
+            direction + k.title(): v
+            for k, v in self._data.items()
+        }
+
+    def __hash__(self):
+        items = sorted(
+            self._data.items(),
+            key=lambda i: i[0]
+        )
+
+        return hash(','.join(map(':'.join, items)))
+
+    def __eq__(self, other):
+        assert isinstance(other, self.__class__)
+
+        return self.__hash__() == other.__hash__()