Added documentation to the classes and also added examples for the AP…

…I services

AUTHORS.rst

@@ -3,4 +3,4 @@ Authors
 
 Lead
 ====
-Bharadwaj Yarlagadda
+Bharadwaj Yarlagadda, yarlagaddabharadwaj@gmail.com

README.rst

@@ -5,4 +5,8 @@
 .. image:: https://coveralls.io/repos/github/bharadwajyarlagadda/bingmaps/badge.svg?branch=develop
     :target: https://coveralls.io/github/bharadwajyarlagadda/bingmaps?branch=develop
 
-Work in Progress!!!
+Links
+=====
+This package is a python implementation of retrieving the data from bing maps API services
+ - Project link: https://github.com/bharadwajyarlagadda/bingmaps
+ - Bing Maps API services: https://msdn.microsoft.com/en-us/library/ff701713.aspx

bingmaps/apiservices/trafficincidents.py

@@ -56,7 +56,6 @@ def __init__(self, data, http_protocol='http'):
         self.schema = TrafficIncidentsUrl(data,
                                           TrafficIncidentsSchema(),
                                           http_protocol)
-        self.file_name = 'traffic_incidents'
         self.incidents_data = None
         self.get_data()
 

bingmaps/urls/elevations_build_urls.py

@@ -209,25 +209,26 @@ class Coordinates(Elevations, Schema):
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/jj158961.aspx):
 
-    :ivar method: A method for calculating elevations
+    :ivar method[Required]: A method for calculating elevations
         (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field
           - 'List' [default]: Use this for returning elevations for a given
             pair of coordinates.
-    :ivar points:  A set of coordinates on the Earth to use in elevation
-        calculations. The exact use of these points depends on the type of
-        elevation request. A set of latitude and longitude values in WGS84
-        decimal degrees. If you are requesting elevations or elevation offsets
-        for a set of points, the maximum number of points is 1024.
+    :ivar points[Required]:  A set of coordinates on the Earth to use in
+        elevation calculations. The exact use of these points depends on the
+        type of elevation request. A set of latitude and longitude values in
+        WGS84 decimal degrees. If you are requesting elevations or elevation
+        offsets for a set of points, the maximum number of points is 1024.
         Points should be given as ``lat1,long1,lat2,long2,latn,longn`` -
         REQUIRED field
-    :ivar heights: A string that specifies which sea level model to use to
-        calculate elevation. One of the following values:
+    :ivar heights[Optional]: A string that specifies which sea level model to
+        use to calculate elevation. One of the following values:
           - sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
           - ellipsoid: Use the ellipsoid Earth model (WGS84).
-    :ivar o: A string specifying the output as JSON or xml.
-    :ivar key: Bing maps key - REQUIRED field
+    :ivar o[Optional]: A string specifying the output as JSON or xml.
+    :ivar key[Required]: Bing maps key - REQUIRED field
 
     This schema helps in serializing the data.
 
@@ -315,30 +316,31 @@ class Polyline(Elevations, Schema):
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/jj158961.aspx):
 
-    :ivar method: A method for calculating elevations
+    :ivar method[Required]: A method for calculating elevations
         (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field
           - 'Polyline' [default]: Use this for returning elevations for a
             given pair of coordinates.
-    :ivar points:  A set of coordinates on the Earth to use in elevation
-        calculations. The exact use of these points depends on the type of
-        elevation request. A set of latitude and longitude values in WGS84
-        decimal degrees. If you are requesting elevations or elevation offsets
-        for a set of points, the maximum number of points is 1024. Points
-        should be at least 2 pairs of latitudes and longitudes for Polyline
-        method - It should be a minimum total of 4 points for Polyline method.
-        Points should be given as ``lat1,long1,lat2,long2,latn,longn`` -
-        REQUIRED field
-    :ivar heights: A string that specifies which sea level model to use to
-        calculate elevation. One of the following values:
+    :ivar points[Required]:  A set of coordinates on the Earth to use in
+        elevation calculations. The exact use of these points depends on the
+        type of elevation request. A set of latitude and longitude values in
+        WGS84 decimal degrees. If you are requesting elevations or elevation
+        offsets for a set of points, the maximum number of points is 1024.
+        Points should be at least 2 pairs of latitudes and longitudes for
+        Polyline method - It should be a minimum total of 4 points for
+        Polyline method. Points should be given as
+        ``lat1,long1,lat2,long2,latn,longn``
+    :ivar heights[Optional]: A string that specifies which sea level model to
+        use to calculate elevation. One of the following values:
           - sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
           - ellipsoid: Use the ellipsoid Earth model (WGS84).
-    :ivar samples: Specifies the number of equally-spaced elevation values to
-        provide along a polyline path. A positive integer. The maximum number
-        of samples is 1024.
-    :ivar o: A string specifying the output as JSON or xml.
-    :ivar key: Bing maps key - REQUIRED field
+    :ivar samples[Required]: Specifies the number of equally-spaced elevation
+        values to provide along a polyline path. A positive integer. The
+        maximum number of samples is 1024.
+    :ivar o[Optional]: A string specifying the output as JSON or xml.
+    :ivar key[Required]: Bing maps key - REQUIRED field
 
     This schema helps in serializing the data.
 
@@ -432,21 +434,22 @@ class Offset(Elevations, Schema):
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/jj158961.aspx:
 
-    :ivar method: A method for calculating elevations
+    :ivar method[Required]: A method for calculating elevations
         (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field
           - 'SeaLevel' [default]: Use this for returning elevations for a given
             pair of coordinates.
-    :ivar points:  A set of coordinates on the Earth to use in elevation
-        calculations. The exact use of these points depends on the type of
-        elevation request. A set of latitude and longitude values in WGS84
-        decimal degrees. If you are requesting elevations or elevation offsets
-        for a set of points, the maximum number of points is 1024.
+    :ivar points[Required]:  A set of coordinates on the Earth to use in
+        elevation calculations. The exact use of these points depends on the
+        type of elevation request. A set of latitude and longitude values in
+        WGS84 decimal degrees. If you are requesting elevations or elevation
+        offsets for a set of points, the maximum number of points is 1024.
         Points should be given as ``lat1,long1,lat2,long2,latn,longn`` -
         REQUIRED field
-    :ivar o: A string specifying the output as JSON or xml.
-    :ivar key: Bing maps key - REQUIRED field
+    :ivar o[Optional]: A string specifying the output as JSON or xml.
+    :ivar key[Required: Bing maps key - REQUIRED field
 
     This schema helps in serializing the data.
 
@@ -531,29 +534,30 @@ class BoundingBox(Elevations, Schema):
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/jj158961.aspx:
 
-    :ivar method: A method for calculating elevations
+    :ivar method[Required]: A method for calculating elevations
         (ex. List/Polyline/SeaLevel/Bounds) - REQUIRED field
           - 'Bounds' [default]: Use this for returning elevations for a given
             pair of coordinates.
-    :ivar bounds: Specifies the rectangular area over which to provide
-        elevation values. A bounding box defined as a set of WGS84 latitudes
-        and longitudes in the following order:
+    :ivar bounds[Required]: Specifies the rectangular area over which to
+        provide elevation values. A bounding box defined as a set of WGS84
+        latitudes and longitudes in the following order:
           - south latitude, west longitude, north latitude, east longitude
           - REQUIRED field
-    :ivar rows,cols: Specifies the number of rows and columns to use to
-        divide the bounding box area into a grid. The rows and columns that
+    :ivar rows,cols[Required]: Specifies the number of rows and columns to use
+        to divide the bounding box area into a grid. The rows and columns that
         define the bounding box each count as two (2) of the rows and columns.
         Elevation values are returned for all vertices of the grid. Integers
         with a value of two (2) or greater. The number of rows and columns
         can define a maximum of 1024 locations (rows * cols <= 1024).
-    :ivar heights: A string that specifies which sea level model to use to
-        calculate elevation. One of the following values:
+    :ivar heights[Optional]: A string that specifies which sea level model to
+        use to calculate elevation. One of the following values:
           - sealevel [default]: Use the geoid Earth model (EGM2008 2.5’).
           - ellipsoid: Use the ellipsoid Earth model (WGS84).
-    :ivar o: A string specifying the output as JSON or xml.
-    :ivar key: Bing maps key - REQUIRED field
+    :ivar o[Optional]: A string specifying the output as JSON or xml.
+    :ivar key[Required]: Bing maps key
 
     This schema helps in serializing the data.
 

bingmaps/urls/locations_build_urls.py

@@ -158,36 +158,41 @@ class Meta:
 
 
 class LocationByAddressSchema(Location, Schema):
-    """Schema for query parameters in which all the fields will be in a ordered
+    """Inherits from :class:`Location`
+
+    Schema for query parameters in which all the fields will be in a ordered
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
-
-    :ivar adminDistrict: A string that contains a subdivision, such as the
-        abbreviation of a US state
-    :ivar locality: A string that contains the locality, such as a US city
-    :ivar postalCode: An integer value that contains the postal code, such as a
-          US ZIP Code
-    :ivar addressLine: A string specifying the street line of an address
-    :ivar countryRegion: A string specifying the ISO country code
-    :ivar c: A string specifying the culture parameter
-    :ivar o: A string for specifying the format of output(response) Ex. -
-        xml/json
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/ff701714.aspx):
+
+    :ivar adminDistrict[Optional]: A string that contains a subdivision, such
+        as the abbreviation of a US state
+    :ivar locality[Optional]: A string that contains the locality, such as a
+        US city
+    :ivar postalCode[Optional]: An integer value that contains the postal
+        code, such as a US ZIP Code
+    :ivar addressLine[Optional]: A string specifying the street line of an
+        address
+    :ivar countryRegion[Optional]: A string specifying the ISO country code
+    :ivar c[Optional]: A string specifying the culture parameter
+    :ivar o[Optional]: A string for specifying the format of output(response)
+        Ex. - xml/json
           - If empty, default output would be a JSON data string
           - If given xml, the output would be an xml data string
-    :ivar includeNeighborhood: One of the following
+    :ivar includeNeighborhood[Optional]: One of the following
         values
           - 1: Include neighborhood information when available
           - 0 [default]: Do not include neighborhood information
-    :ivar include: The only value for this parameter is ciso2. When you
-        specify include=ciso2, the two-letter ISO country code is included
+    :ivar include[Optional]: The only value for this parameter is ciso2. When
+        you specify include=ciso2, the two-letter ISO country code is included
         for addresses in the response
           - default='ciso2'
-    :ivar maxResults: An integer between 1 and 20 (number of
+    :ivar maxResults[Optional]: An integer between 1 and 20 (number of
         results)
           - default=20
-    :ivar key: Bing maps api key
+    :ivar key[Required]: Bing maps api key
           - Required
 
     This schema helps in serializing the data.
@@ -328,15 +333,19 @@ def query(self):
 
 
 class LocationByPointSchema(Location, Schema):
-    """Schema for query parameters in which all the fields will be in a ordered
+    """Inherits from :class:`Location`
+
+    Schema for query parameters in which all the fields will be in a ordered
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/ff701710.aspx):
 
-    :ivar point: A point on the Earth specified by a latitude and longitude.
-    :ivar includeEntityTypes: A comma separated list of entity types selected
-        from the following options:
+    :ivar point[Required]: A point on the Earth specified by a latitude and
+        longitude.
+    :ivar includeEntityTypes[Optional]: A comma separated list of entity types
+        selected from the following options:
           - Address
           - Neighborhood
           - PopulatedPlace
@@ -355,22 +364,22 @@ class LocationByPointSchema(Location, Schema):
         entity types is returned. Also, more than one Neighborhood may be
         returned because the area covered by two different neighborhoods can
         overlap.
-    :ivar includeNeighborhood: One of the following
+    :ivar includeNeighborhood[Optional]: One of the following
         values:
           - 1: Include neighborhood information when available.
           - 0 [default]: Do not include neighborhood information.
-    :ivar include: The only value for this parameter is ciso2. When you
-        specify include=ciso2, the two-letter ISO country code is included
+    :ivar include[Optional]: The only value for this parameter is ciso2. When
+        you specify include=ciso2, the two-letter ISO country code is included
         for addresses in the response.
-    :ivar c: A string specifying the culture parameter
-    :ivar o: A string for specifying the format of output(response) Ex. -
-        xml/json
+    :ivar c[Optional]: A string specifying the culture parameter
+    :ivar o[Optional]: A string for specifying the format of output(response)
+        Ex. - xml/json
           - If empty, default output would be a JSON data string
           - If given xml, the output would be an xml data string
-    :ivar maxResults: An integer between 1 and 20 (number of
+    :ivar maxResults[Optional]: An integer between 1 and 20 (number of
         results)
           - default=20
-    :ivar key: Bing maps api
+    :ivar key[Required]: Bing maps api
         key
           - Required
 
@@ -402,7 +411,10 @@ class LocationByPointSchema(Location, Schema):
         although we haven't specified any values because they are default
         values specified in the schema.
     """
-    point = fields.Str()
+    point = fields.Str(
+        required=True,
+        error_messages={'required': 'coordinates should be provided'}
+    )
     includeEntityTypes = fields.Str()
     includeNeighborhood = fields.Int(
         default=0
@@ -503,35 +515,38 @@ def query(self):
 
 
 class LocationByQuerySchema(Location, Schema):
-    """Schema for query parameters in which all the fields will be in a ordered
+    """Inherits from :class:`Location`
+
+    Schema for query parameters in which all the fields will be in a ordered
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/ff701711.aspx):
 
-    :ivar q: A string (query) that contains information about a location, such
-        as an address or landmark name.
-    :ivar includeNeighborhood: One of the following
+    :ivar q[Required]: A string (query) that contains information about a
+        location, such as an address or landmark name.
+    :ivar includeNeighborhood[Optional]: One of the following
         values:
           - 1: Include neighborhood information when available.
           - 0 [default]: Do not include neighborhood information.
-    :ivar include: One or more of the following
+    :ivar include[Optional]: One or more of the following
         options:
           - queryParse: Specifies that the response shows how the query string
             was parsed into address values, such as addressLine, locality,
             adminDistrict, and postalCode.
           - ciso2: Specifies to include the two-letter ISO country code.
         If you specify more than one include value, separate the values with a
         comma.
-    :ivar c: A string specifying the culture parameter
-    :ivar o: A string for specifying the format of output(response) Ex. -
-        xml/json
+    :ivar c[Optional]: A string specifying the culture parameter
+    :ivar o[Optional]: A string for specifying the format of output(response)
+        Ex. - xml/json
           - If empty, default output would be a JSON data string
           - If given xml, the output would be an xml data string
-    :ivar maxResults: An integer between 1 and 20 (number of
+    :ivar maxResults[Optional]: An integer between 1 and 20 (number of
         results)
           - default=20
-    :ivar key: Bing maps api
+    :ivar key[Required]: Bing maps api
         key
           - Required
 

bingmaps/urls/traffic_build_urls.py

@@ -163,7 +163,8 @@ class TrafficIncidentsSchema(MainParams, Schema):
     way. All the fields will be dumped in the same order as mentioned in the
     schema.
 
-    Data Fields for the schema:
+    Data Fields for the schema (taken from
+    https://msdn.microsoft.com/en-us/library/hh441726.aspx):
 
     :ivar mapArea[Required]: A rectangular area specified as a bounding box.
         The size of the area can be a maximum of 500 km x 500 km. A bounding
@@ -195,7 +196,7 @@ class TrafficIncidentsSchema(MainParams, Schema):
           - 9: Construction
           - 10: Alert
           - 11: Weather
-    :ivar o: A string specifying the output as JSON or xml.
+    :ivar o[Optional]: A string specifying the output as JSON or xml.
     :ivar key[Required]: Bing maps key - REQUIRED field
 
     This schema helps in serializing the data.

docs/devguide.rst

@@ -65,9 +65,9 @@ There are several tasks specified in this project. You can get a list of all the
 
 ::
 
-    $ invoke [--list] [-l]
+    $ invoke [--list|-l]
     # OR
-    $ inv [--list] [-l]
+    $ inv [--list|-l]
 
 For a detailed help on a command, run: