adding documentation to functions and classes

Author: Colum31

doc/source/classdoc/station.rst

@@ -4,4 +4,3 @@ Station
 .. autoclass:: vbbpy.station.Station
     :members:
     :undoc-members:
-

setup.py

@@ -3,6 +3,7 @@
 setup(
     name='vbbpy',
     version='1.1.5',
+    python_requires='>3.6',
     description='A python wrapper for the VBB REST-API by derhuerst',
     url="https://github.com/Colum31/vbb-pythonWrapper",
     author='colum31',

vbbpy/connections.py

@@ -1,3 +1,4 @@
+import requests
 from vbbpy import line, modes, station, leg, vbbHelper, journey, location
 
 
@@ -54,15 +55,21 @@ def __str__(self):
 
         return stationStr + allRoutesStr
 
-    def getConnections(self):
-        response = self.makeJourneyRequest(modes.Modes.JOURNEY_BY_ID)
+    def getConnections(self) -> None:
+        """
+        Gets routes between origin and destination that are stored in calling object.
+
+        :return: None
+        """
+
+        response = self.makeJourneyRequest()
 
         if response.status_code == 200:
             self.parseJourneyResponse(response.json(), modes.Modes.JOURNEY_BY_ID)
         else:
             print("Got invalid response\nstatus={}\n".format(response.status_code))
 
-    def makeJourneyRequest(self, mode):
+    def makeJourneyRequest(self) -> requests.Response:
         """
         Makes a request string and parameters in order to fetch information from journey API endpoint. Makes the
         request via fetchRequest().
@@ -90,7 +97,7 @@ def makeJourneyRequest(self, mode):
 
         return vbbHelper.VbbHelper.fetchRequest(requestString, data)
 
-    def parseJourneyResponse(self, response, mode):
+    def parseJourneyResponse(self, response: dict, mode: modes.Modes) -> None:
         # TODO: split this function into journey and leg class member functions
         """
         Parses a journey request.

vbbpy/departure.py

@@ -1,4 +1,4 @@
-from vbbpy import vbbHelper
+from vbbpy import vbbHelper, line
 
 class Departure:
     """
@@ -8,19 +8,19 @@ class Departure:
     tripId = ""
     plannedWhen = ""
     delay = 0
-    line = None
+    depLine = None
     direction = ""
     cancelled = False
 
-    def __init__(self, tripId, plannedWhen, delay, line, direction):
+    def __init__(self, tripId: str, plannedWhen: str, delay: int, depLine: line.Line, direction: str):
         self.plannedWhen = plannedWhen
         self.tripId = tripId
         self.delay = delay
-        self.line = line
+        self.depLine = depLine
         self.direction = direction
 
     def __str__(self):
-        info = "{}  {}  {}".format(self.line.name, self.direction, vbbHelper.VbbHelper.getMinutesToDepartures(self.plannedWhen, self.delay))
+        info = "{}  {}  {}".format(self.depLine.name, self.direction, vbbHelper.VbbHelper.getMinutesToDepartures(self.plannedWhen, self.delay))
 
         if self.cancelled:
             info = info + " CANCELLED"

vbbpy/journey.py

@@ -38,10 +38,21 @@ def __str__(self):
 
         return stationStr + journeyString
 
-    def getTransfers(self):
+    def getTransfers(self) -> None:
+        """
+        Gets the amount of transfers and stores them in the calling object.
+
+        :return:
+        """
         self.numberTransfers = len(self.legs) - 1
 
-    def getTimeInfo(self):
+    def getTimeInfo(self) -> None:
+        """
+        Gets the length of the journey in minutes and stores it into calling object.
+
+        :return: None
+        """
+
         firstLeg = self.legs[0]
         lastLeg = self.legs[-1]
 

vbbpy/leg.py

@@ -1,6 +1,6 @@
 import datetime
 
-from vbbpy import vbbHelper
+from vbbpy import vbbHelper, line
 
 class Leg:
     """
@@ -26,7 +26,7 @@ class Leg:
     walking = False
     walkingDistance = 0
 
-    def __init__(self, origin, destination, transportLine, plannedDeparture, plannedArrival,  lineDirection, walking):
+    def __init__(self, origin: str, destination: str, transportLine: line.Line, plannedDeparture, plannedArrival,  lineDirection: str, walking: bool):
 
         self.origin = origin
         self.destination = destination
@@ -52,7 +52,12 @@ def __str__(self):
             lineStr = "{} {}".format(self.transportLine.name, self.lineDirection)
             return depStr + lineStr + arrStr
 
-    def setTimeDuration(self):
+    def setTimeDuration(self) -> None:
+        """
+        Calculates and sets time required for the leg.
+
+        :return: None
+        """
 
         diff = datetime.datetime.fromisoformat(self.plannedArrival) - datetime.datetime.fromisoformat(self.plannedDeparture)
         diff_seconds = diff.total_seconds()

vbbpy/line.py

@@ -7,7 +7,7 @@ class Line:
     name = ""
     product = ""
 
-    def __init__(self, lineId, name, product):
+    def __init__(self, lineId: str, name: str, product: str):
         self.lineId = lineId
         self.name = name
         self.product = product

vbbpy/location.py

@@ -1,6 +1,9 @@
 from geopy.geocoders import Nominatim
 
 class Address:
+    """
+    The Address class contains information about a physical address or place.
+    """
 
     name = ""
     streetName = ""
@@ -10,8 +13,16 @@ class Address:
 
     cords = None
 
-    def getCords(self, inputStr):
-        geolocator = Nominatim(user_agent="vbbpy: address lookup")
+    def getCords(self, inputStr: str, userAgent: str) -> None:
+        """
+        Gets the coordinates and address information for a address encoded in a string.
+
+        :param inputStr: a string containing the address or place
+        :param userAgent: a user agent to use when requesting address information
+        :return: None
+        """
+
+        geolocator = Nominatim(user_agent=userAgent)
         loc = geolocator.geocode(inputStr, addressdetails=True)
 
         self.name = loc.address
@@ -24,14 +35,17 @@ def getCords(self, inputStr):
         self.postalCode = addressData.get("postcode", "")
         self.city = addressData.get("city", "")
 
-    def __init__(self, inputStr):
-        self.getCords(inputStr)
+    def __init__(self, inputStr: str, geopyUserAgent: str = "vbbpy: address lookup"):
+        self.getCords(inputStr, geopyUserAgent)
 
     def __str__(self):
         return self.streetName + " " + self.number + '\n' + self.postalCode + " " + self.city + '\n' + str(self.cords)
 
 
 class Coordinates:
+    """
+    The Coordinates class contains floats encoding coordinates.
+    """
 
     longitude = 0
     latitude = 0

vbbpy/station.py

@@ -111,7 +111,7 @@ def getDepartures(self, span=10) -> None:
         """
         Requests the next departures from the station and stores them into calling object.
 
-        :param span Optional time limit for the departures to fetch.
+        :param span: Optional time limit for the departures to fetch.
         :return: None
         """
 
@@ -275,7 +275,7 @@ def parseStopsResponse(self, response: dict, mode: modes.Modes, station) -> int:
 
             for dep in response:
 
-                lineResponse = dep["line"]
+                lineResponse = dep["depLine"]
                 newLine = line.Line(lineResponse["id"], lineResponse["name"], lineResponse["product"])
 
                 newDeparture = departure.Departure(dep["tripId"], dep["plannedWhen"], dep["delay"], newLine,

vbbpy/vbbHelper.py

@@ -10,9 +10,12 @@
 
 
 class VbbHelper:
+    """
+    A helper class for the library.
+    """
 
     @staticmethod
-    def fetchRequest(requestString, queryParams):
+    def fetchRequest(requestString: str, queryParams: dict) -> requests.Response:
         """
         Sends the request.
 
@@ -35,7 +38,7 @@ def fetchRequest(requestString, queryParams):
         return response
 
     @staticmethod
-    def getMinutesToDepartures(depTime, delay):
+    def getMinutesToDepartures(depTime: str, delay: int) -> int:
         """
         Calculates approximate minutes to a departure.
         :param depTime: ISO datetime string of the planned departure
@@ -54,7 +57,7 @@ def getMinutesToDepartures(depTime, delay):
         return int(diff_seconds / 60)
 
     @staticmethod
-    def getDateTimeHourMinuteString(dt, delay=0):
+    def getDateTimeHourMinuteString(dt: str, delay: int = 0) -> str:
         """
         Makes a string containing hour and minute of a given datetime.
         :param dt: datetime string to calculate string for