Write docstrings
This commit is contained in:
parent
fa5c126eb3
commit
239a2481f9
|
@ -177,3 +177,6 @@ epub_exclude_files = ['search.html']
|
||||||
|
|
||||||
|
|
||||||
# -- Extension configuration -------------------------------------------------
|
# -- Extension configuration -------------------------------------------------
|
||||||
|
|
||||||
|
# Concatenate the class' and __init__'s docstrings when documenting a class
|
||||||
|
autoclass_content = 'both'
|
||||||
|
|
|
@ -10,19 +10,58 @@ class Delivery(object):
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, id):
|
def __init__(self, id):
|
||||||
|
"""
|
||||||
|
:param str id: A delivery ID.
|
||||||
|
"""
|
||||||
self.id = id
|
self.id = id
|
||||||
|
"""
|
||||||
|
The delivery ID.
|
||||||
|
|
||||||
|
:type: str
|
||||||
|
"""
|
||||||
|
|
||||||
self.last_updated = None
|
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
|
self.position = None
|
||||||
|
"""
|
||||||
|
Coordinates of the delivery truck's position.
|
||||||
|
|
||||||
|
:type: urbantz.utils.Coordinates
|
||||||
|
"""
|
||||||
|
|
||||||
self.destination = None
|
self.destination = None
|
||||||
|
"""
|
||||||
|
Coordinates of the delivery destination.
|
||||||
|
|
||||||
|
:type: urbantz.utils.Coordinates
|
||||||
|
"""
|
||||||
|
|
||||||
def __repr__(self):
|
def __repr__(self):
|
||||||
return '{}({})'.format(self.__class__.__name__, self.id)
|
return '{}({})'.format(self.__class__.__name__, self.id)
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def api_url(self):
|
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
|
return 'https://backend.urbantz.com/public/task/tracking/' + self.id
|
||||||
|
|
||||||
def update(self):
|
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 = requests.get(self.api_url)
|
||||||
resp.raise_for_status()
|
resp.raise_for_status()
|
||||||
data = resp.json()
|
data = resp.json()
|
||||||
|
|
|
@ -1,6 +1,14 @@
|
||||||
class APIError(Exception):
|
class APIError(Exception):
|
||||||
|
"""
|
||||||
|
An error returned by the UrbanTZ API.
|
||||||
|
This does not include HTTP errors.
|
||||||
|
"""
|
||||||
|
|
||||||
def __init__(self, error):
|
def __init__(self, error):
|
||||||
|
"""
|
||||||
|
:param error: Parsed JSON error from the API.
|
||||||
|
:type error: dict
|
||||||
|
"""
|
||||||
self.message = error.get('message')
|
self.message = error.get('message')
|
||||||
self.code = error.get('code')
|
self.code = error.get('code')
|
||||||
|
|
||||||
|
|
|
@ -10,7 +10,10 @@ class Coordinates(object):
|
||||||
|
|
||||||
def __init__(self, lat=0, lng=0):
|
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.lat = lat
|
||||||
self.lng = lng
|
self.lng = lng
|
||||||
|
@ -82,11 +85,22 @@ class Coordinates(object):
|
||||||
return self.__class__(lat=ceil(self.lat), lng=ceil(self.lng))
|
return self.__class__(lat=ceil(self.lat), lng=ceil(self.lng))
|
||||||
|
|
||||||
def to_radians(self):
|
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))
|
return tuple(map(radians, self))
|
||||||
|
|
||||||
def distance(self, other):
|
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'):
|
if not hasattr(other, 'to_radians'):
|
||||||
raise NotImplementedError(
|
raise NotImplementedError(
|
||||||
|
@ -100,9 +114,19 @@ class Coordinates(object):
|
||||||
def toJSON(self):
|
def toJSON(self):
|
||||||
"""
|
"""
|
||||||
Convert to UrbanTZ JSON geometry
|
Convert to UrbanTZ JSON geometry
|
||||||
|
|
||||||
|
:returns: UrbanTZ-compatible JSON geometry data
|
||||||
|
:rtype: list(float)
|
||||||
"""
|
"""
|
||||||
return [self.lng, self.lat]
|
return [self.lng, self.lat]
|
||||||
|
|
||||||
@staticmethod
|
@staticmethod
|
||||||
def fromJSON(geometry):
|
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])
|
return Coordinates(lng=geometry[0], lat=geometry[1])
|
||||||
|
|
Reference in New Issue