diff --git a/docs/conf.py b/docs/conf.py index f1ae248..75be07f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -177,3 +177,6 @@ epub_exclude_files = ['search.html'] # -- Extension configuration ------------------------------------------------- + +# Concatenate the class' and __init__'s docstrings when documenting a class +autoclass_content = 'both' diff --git a/urbantz/delivery.py b/urbantz/delivery.py index 836954b..467d761 100644 --- a/urbantz/delivery.py +++ b/urbantz/delivery.py @@ -10,19 +10,58 @@ class Delivery(object): """ def __init__(self, id): + """ + :param str id: A delivery ID. + """ self.id = id + """ + The delivery ID. + + :type: str + """ + self.last_updated = None + """ + Last API update date/time. Is None if data has never been fetched + from the API. + + :type: datetime or None + """ + self.position = None + """ + Coordinates of the delivery truck's position. + + :type: urbantz.utils.Coordinates + """ + self.destination = None + """ + Coordinates of the delivery destination. + + :type: urbantz.utils.Coordinates + """ def __repr__(self): return '{}({})'.format(self.__class__.__name__, self.id) @property def api_url(self): + """ + URL pointing to the API endpoint to use for the specific delivery. + + :type: str + """ return 'https://backend.urbantz.com/public/task/tracking/' + self.id def update(self): + """ + Fetch the latest delivery information from the API. + + :raises requests.exceptions.HTTPError: If the response has an + HTTP 4xx or 5xx code. + :raises urbantz.exceptions.APIError: If the API returned an error. + """ resp = requests.get(self.api_url) resp.raise_for_status() data = resp.json() diff --git a/urbantz/exceptions.py b/urbantz/exceptions.py index c3cc237..36cb336 100644 --- a/urbantz/exceptions.py +++ b/urbantz/exceptions.py @@ -1,6 +1,14 @@ class APIError(Exception): + """ + An error returned by the UrbanTZ API. + This does not include HTTP errors. + """ def __init__(self, error): + """ + :param error: Parsed JSON error from the API. + :type error: dict + """ self.message = error.get('message') self.code = error.get('code') diff --git a/urbantz/utils.py b/urbantz/utils.py index ea754ca..d1b86df 100644 --- a/urbantz/utils.py +++ b/urbantz/utils.py @@ -10,7 +10,10 @@ class Coordinates(object): def __init__(self, lat=0, lng=0): """ - Coordinates from decimal degrees + Get coordinates from decimal degrees. + + :param float lat: Latitude in decimal degrees. + :param float lng: Longitude in decimal degrees. """ self.lat = lat self.lng = lng @@ -82,11 +85,22 @@ class Coordinates(object): return self.__class__(lat=ceil(self.lat), lng=ceil(self.lng)) def to_radians(self): + """ + Convert to a ``(lat, lng)`` tuple in radians. + + :returns: Coordinates in radians. + :rtype: tuple(float, float) + """ return tuple(map(radians, self)) def distance(self, other): """ - Compute Haversine distance between two coordinates. + Compute Haversine distance between two coordinates in meters. + + :param other: Another pair of coordinates to compute distance against. + :type other: Coordinates + :returns: Distance between the two coordinates, in meters. + :rtype: float """ if not hasattr(other, 'to_radians'): raise NotImplementedError( @@ -100,9 +114,19 @@ class Coordinates(object): def toJSON(self): """ Convert to UrbanTZ JSON geometry + + :returns: UrbanTZ-compatible JSON geometry data + :rtype: list(float) """ return [self.lng, self.lat] @staticmethod def fromJSON(geometry): + """ + Get a Coordinates instance from parsed UrbanTZ JSON geometry data. + + :param geometry: Parsed UrbanTZ geometry data: a list holding + ``[lng, lat]`` in decimal degrees. + :type geometry: list(float) + """ return Coordinates(lng=geometry[0], lat=geometry[1])