Merge pull request #1 from Aclima/add_tilesets_api

Add tilesets api

README.rst

@@ -70,6 +70,10 @@ Services
   - Retrieve TileJSON metadata for a tileset
   - Retrieve a single marker image without any background map
 
+- **Tilesets V1** `examples <./docs/tilesets.md#tilesets>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#tilesets>`__
+
+  - Read metadata for raster and vector tilesets
+
 Please note that there may be some lag between the release of new Mapbox web
 services and releases of this package.
 

docs/index.rst

@@ -68,6 +68,10 @@ Services
   - Retrieve TileJSON metadata for a tileset
   - Retrieve a single marker image without any background map
 
+- **Tilesets V1** `examples <./docs/tilesets.md#tilesets>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#tilesets>`__
+
+  - Read metadata for raster and vector tilesets
+
 Please note that there may be some lag between the release of new Mapbox web
 services and releases of this package.
 
@@ -116,6 +120,7 @@ Documentation
    mapmatching.md
    static_style.md
    tilequery.md
+   tilesets.md
    maps.md
    api/mapbox.rst
    api/mapbox.services.rst

docs/tilesets.md

@@ -0,0 +1,43 @@
+# Tilesets
+
+The `Tilesets` class provides access to the Mapbox Tilesets API.  You can import it from either the `mapbox` module or the `mapbox.services.tilesets` module.
+
+__mapbox__:
+
+```python
+>>> from mapbox import Tilesets
+```
+
+__mapbox.services.tilesets__:
+
+```python
+>>> from mapbox.services.tilesets import Tilesets
+```
+
+See https://www.mapbox.com/api-documentation/#tilesets for general documentation of the API.
+
+Use of the Tilesets API requires an access token, which you should set in your environment.  For more information, see the [access tokens](access_tokens.md) documentation.
+
+## Tilesets Method
+
+The public method of the `Tilesets` class provides access to the Tilesets API and returns an instance of [`requests.Response`](http://docs.python-requests.org/en/latest/api/#requests.Response).
+
+## Usage: Listing Tilesets
+
+Instantiate `Tilesets`.
+
+```python
+>>> tilesets = Tilesets()
+```
+
+Call the `list` method, passing in values for optional arguments as necessary - `tileset_type`, `visibility`, `sortby`, and `limit`.
+
+```python
+>>> response = tilesets.list()
+```
+
+Evaluate whether the request succeeded, and retrieve the tileset object from the response object.
+
+```python
+>>> if response.status_code == 200:
+...     tileset_object = response.get_json()

mapbox/__init__.py

@@ -1,16 +1,17 @@
 # mapbox
 __version__ = "0.18.0"
 
+from .services.analytics import Analytics
 from .services.datasets import Datasets
 from .services.directions import Directions
+from .services.matrix import DirectionsMatrix
 from .services.geocoding import (
     Geocoder, InvalidCountryCodeError, InvalidPlaceTypeError)
+from .services.maps import Maps
 from .services.mapmatching import MapMatcher
-from .services.matrix import DirectionsMatrix
-from .services.surface import Surface
 from .services.static import Static
 from .services.static_style import StaticStyle
-from .services.uploads import Uploader
-from .services.analytics import Analytics
+from .services.surface import Surface
 from .services.tilequery import Tilequery
-from .services.maps import Maps
+from .services.tilesets import Tilesets
+from .services.uploads import Uploader

mapbox/errors.py

@@ -81,6 +81,50 @@ class InvalidRowError(ValidationError):
 class InvalidFileFormatError(ValidationError):
     pass
 
+class InvalidTilesetTypeError(ValidationError):
+    """InvalidTilesetTypeError
+
+    Parameters
+    ----------
+    message : str, optional
+        A human-readable string describing the error.
+    """
+
+    pass
+
+
+class InvalidVisibilityError(ValidationError):
+    """InvalidVisibilityError
+
+    Parameters
+    ----------
+    message : str, optional
+        A human-readable string describing the error.
+    """
+
+    pass
+
+
+class InvalidSortbyError(ValidationError):
+    """InvalidSortbyError
+
+    Parameters
+    ----------
+    message : str, optional
+        A human-readable string describing the error.
+    """
+
+    pass
+
+
+class InvalidLimitError(ValidationError):
+    """InvalidLimitError
+
+    Parameters
+    ----------
+    message : str, optional
+        A human-readable string describing the error.
+    """
 
 class InvalidFeatureFormatError(ValidationError):
     pass

mapbox/services/tilesets.py

@@ -0,0 +1,175 @@
+"""The Tilesets class provides access to Mapbox's Tilesets API."""
+
+from mapbox.errors import (
+    InvalidTilesetTypeError,
+    InvalidVisibilityError,
+    InvalidSortbyError,
+    InvalidLimitError
+)
+
+from mapbox.services.base import Service
+
+from uritemplate import URITemplate
+
+class Tilesets(Service):
+    """Access to Tilesets API V1
+
+    Attributes
+    ----------
+    api_name : str
+        The API's name.
+
+    api_version : str
+        The API's version number.
+
+    valid_tileset_types : list
+        The possible values for tileset_type.
+
+    valid_visibilities : list
+        The possible values for visibility.
+
+    valid_sortbys : list
+        The possible values for sortby.
+
+    base_uri : str
+         The API's base URI, currently https://api.mapbox.com/tilesets/v1
+    """
+
+    api_name = "tilesets"
+
+    api_version = "v1"
+
+    valid_tileset_types = [
+        "raster",
+        "vector"
+    ]
+
+    valid_visibilities = [
+        "private",
+        "public"
+    ]
+
+    valid_sortbys = [
+        "created",
+        "modified"
+    ]
+
+    @property
+    def base_uri(self):
+        """Forms base URI."""
+
+        return "https://{}/{}/{}".format(
+            self.host,
+            self.api_name,
+            self.api_version
+        )
+
+    def _validate_tileset_type(self, tileset_type):
+        """Validates tileset type, raising error if invalid."""
+
+        if tileset_type not in self.valid_tileset_types:
+            raise InvalidTilesetTypeError(
+                "{} is not a valid tileset type".format(tileset_type)
+            )
+
+        return tileset_type
+
+    def _validate_visibility(self, visibility):
+        """Validates visibility, raising error if invalid."""
+
+        if visibility not in self.valid_visibilities:
+            raise InvalidVisibilityError(
+                "{} is not a valid value for visibility".format(visibility)
+            )
+
+        return visibility
+
+    def _validate_sortby(self, sortby):
+        """Validates sortby, raising error if invalid."""
+
+        if sortby not in self.valid_sortbys:
+            raise InvalidSortbyError(
+                "{} is not a valid value for sortby".format(sortby)
+            )
+
+        return sortby
+
+    def _validate_limit(self, limit):
+        """Validates limit, raising error if invalid."""
+
+        if (limit < 1) or (limit > 500):
+            raise InvalidLimitError(
+                "{} is not a valid value for limit".format(limit)
+            )
+
+        return limit
+
+    def list(self, tileset_type=None, visibility=None,
+                 sortby=None, limit=None):
+        """Lists all tilesets for an account.
+
+        tileset_type : str, optional
+            Filter results by tileset type.
+
+            Valid values are raster or vector.
+
+        visibility : str, optional
+            Filter results by visibility.
+
+            Valid values are private or public.
+
+            Private tilesets require an access token
+            belonging to the owner, while public
+            tilesets may be requested with an access
+            token belonging to any user.
+
+        sortby : str, optional
+            Sort results by timestamp.
+
+            Valid values are created or modified
+
+        limit : int, optional
+            The maximum number of objects to return
+            (pagination), where 1 is the minimum value
+            and 500 is the maxium value.
+
+            The default value is 100.
+
+        Returns
+        -------
+        request.Response
+            The response object with a tileset object.
+        """
+
+        # Build URI resource path.
+
+        path_part = "/{username}"
+        path_values = dict(username=self.username)
+        uri = URITemplate(self.base_uri + path_part).expand(**path_values)
+
+        # Validate tileset_type, visibility, sortby, and limit
+        # and build URI query parameters.
+
+        query_parameters = dict()
+
+        if tileset_type:
+            tileset_type = self._validate_tileset_type(tileset_type)
+            query_parameters["type"] = tileset_type
+
+        if visibility:
+            visibility = self._validate_visibility(visibility)
+            query_parameters["visibility"] = visibility
+
+        if sortby:
+            sortby = self._validate_sortby(sortby)
+            query_parameters["sortby"] = sortby
+
+        if limit:
+            limit = self._validate_limit(limit)
+            query_parameters["limit"] = str(limit)
+
+        # Send HTTP GET request.
+
+        response = self.session.get(uri, params=query_parameters)
+
+        return response