Repository: mapbox/mapbox-sdk-py

Issue:
Deprecate distance module
As of version 0.15, users should get their travel times from the Matrix API, not from the Distance API. We'll mark the methods of the distance module deprecated and call those of the matrix module instead of hitting the Distance API endpoint. 

Discussion:

Patch:
diff --git a/README.rst b/README.rst
index fc69108..635c48b 100644
--- a/README.rst
+++ b/README.rst
@@ -26,11 +26,7 @@ Services
   - GeoJSON & Polyline formatting
   - Instructions as text or HTML
 
-- **Distance V1** `examples <./docs/distance.md#distance>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#directions-matrix>`__
-
-  - Travel-time tables between up to 100 points
-  - Profiles for driving, walking and cycling
-
+- **Distance V1** **DEPRECATED**
 - **Geocoding V5** `examples <./docs/geocoding.md#geocoding>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#geocoding>`__
 
   - Forward (place names ⇢ longitude, latitude)
diff --git a/docs/distance.md b/docs/distance.md
index a46588e..5b1b31f 100644
--- a/docs/distance.md
+++ b/docs/distance.md
@@ -1,5 +1,10 @@
 # Distance
 
+**DEPRECATED**
+
+The `mapbox.services.distance` module will be removed in 1.0. Please switch
+to the new `mapbox.services.matrix` module.
+
 The `Distance` class from the `mapbox.services.distance` module provides
 access to the Mapbox Distance API. You can also import it directly from the
 `mapbox` module.
diff --git a/mapbox/services/distance.py b/mapbox/services/distance.py
index 9362532..7f9e1eb 100644
--- a/mapbox/services/distance.py
+++ b/mapbox/services/distance.py
@@ -1,34 +1,23 @@
-from uritemplate import URITemplate
+"""Distance API V1 **DEPRECATED**"""
 
-from mapbox.encoding import encode_coordinates_json
-from mapbox.errors import InvalidProfileError
-from mapbox.services.base import Service
+import warnings
 
+from mapbox.errors import MapboxDeprecationWarning
+from mapbox.services.matrix import DirectionsMatrix
 
-class Distance(Service):
-    """Access to the Distance API V1"""
 
-    api_name = 'distances'
-    api_version = 'v1'
+class Distance(object):
+    """Access to the Distance API V1 ***DEPRECATED**"""
 
-    valid_profiles = ['driving', 'cycling', 'walking']
-
-    @property
-    def baseuri(self):
-        return 'https://{0}/{1}/{2}/mapbox'.format(
-            self.host, self.api_name, self.api_version)
-
-    def _validate_profile(self, profile):
-        if profile not in self.valid_profiles:
-            raise InvalidProfileError(
-                "{0} is not a valid profile".format(profile))
-        return profile
+    def __init__(self, access_token=None, host=None, cache=None):
+        warnings.warn(
+            "The distance module will be removed in the next version. "
+            "Use the matrix module instead.", MapboxDeprecationWarning)
+        self.access_token = access_token
+        self.host = host
+        self.cache = cache
 
     def distances(self, features, profile='driving'):
-        profile = self._validate_profile(profile)
-        coords = encode_coordinates_json(features)
-        uri = URITemplate(self.baseuri + '/{profile}').expand(profile=profile)
-        res = self.session.post(uri, data=coords,
-                                headers={'Content-Type': 'application/json'})
-        self.handle_http_error(res)
-        return res
+        service = DirectionsMatrix(
+            access_token=self.access_token, host=self.host, cache=self.cache)
+        return service.matrix(features, profile=profile)
diff --git a/mapbox/services/matrix.py b/mapbox/services/matrix.py
index 9ca07cb..394d8bd 100644
--- a/mapbox/services/matrix.py
+++ b/mapbox/services/matrix.py
@@ -102,4 +102,4 @@ class DirectionsMatrix(Service):
         uri = '{0}/{1}/{2}'.format(self.baseuri, profile, coords)
         res = self.session.get(uri, params=query)
         self.handle_http_error(res)
-        return res
+        return res
\ No newline at end of file


Test patch:
diff --git a/tests/test_distances.py b/tests/test_distances.py
index 4c4be8b..d264600 100644
--- a/tests/test_distances.py
+++ b/tests/test_distances.py
@@ -2,6 +2,7 @@ import pytest
 import responses
 
 import mapbox
+from mapbox.errors import MapboxDeprecationWarning
 
 
 points = [{
@@ -18,8 +19,7 @@ points = [{
         "type": "Point",
         "coordinates": [
             -86.577791,
-            36.722137
-            ]}}, {
+            36.722137]}}, {
     "type": "Feature",
     "properties": {},
     "geometry": {
@@ -29,38 +29,19 @@ points = [{
             36.922175]}}]
 
 
-def test_class_attrs():
-    """Get expected class attr values"""
-    serv = mapbox.Distance()
-    assert serv.api_name == 'distances'
-    assert serv.api_version == 'v1'
-
-
-def test_profile_invalid():
-    """'jetpack' is not a valid profile."""
-    with pytest.raises(ValueError):
-        mapbox.Distance(access_token='pk.test')._validate_profile('jetpack')
-
-
-@pytest.mark.parametrize('profile', ['driving', 'cycling', 'walking'])
-def test_profile_valid(profile):
-    """Profiles are valid"""
-    assert profile == mapbox.Distance(
-        access_token='pk.test')._validate_profile(profile)
-
-
 @responses.activate
 def test_distance():
 
     responses.add(
-        responses.POST,
-        'https://api.mapbox.com/distances/v1/mapbox/driving?access_token=pk.test',
+        responses.GET,
+        'https://api.mapbox.com/directions-matrix/v1/mapbox/driving/-87.337875,36.539156;-86.577791,36.722137;-88.247685,36.922175?access_token=pk.test',
         match_querystring=True,
         body='{"durations":[[0,4977,5951],[4963,0,9349],[5881,9317,0]]}',
         status=200,
         content_type='application/json')
 
-    res = mapbox.Distance(access_token='pk.test').distances(points)
+    with pytest.warns(MapboxDeprecationWarning):
+        res = mapbox.Distance(access_token='pk.test').distances(points)
     assert res.status_code == 200
     assert list(res.json().keys()) == ["durations", ]
 
@@ -69,14 +50,15 @@ def test_distance():
 def test_distances_matrix():
 
     responses.add(
-        responses.POST,
-        'https://api.mapbox.com/distances/v1/mapbox/driving?access_token=pk.test',
+        responses.GET,
+        'https://api.mapbox.com/directions-matrix/v1/mapbox/driving/-87.337875,36.539156;-86.577791,36.722137;-88.247685,36.922175?access_token=pk.test',
         match_querystring=True,
         body='{"durations":[[0,4977,5951],[4963,0,9349],[5881,9317,0]]}',
         status=200,
         content_type='application/json')
 
-    res = mapbox.Distance(access_token='pk.test').distances(points)
+    with pytest.warns(MapboxDeprecationWarning):
+        res = mapbox.Distance(access_token='pk.test').distances(points)
     matrix = res.json()['durations']
     # 3x3 list
     assert len(matrix) == 3
diff --git a/tests/test_matrix.py b/tests/test_matrix.py
index 5d8dbf7..f637709 100644
--- a/tests/test_matrix.py
+++ b/tests/test_matrix.py
@@ -91,4 +91,4 @@ def test_matrix(waypoints):
     matrix = res.json()['durations']
     # 3x3 list
     assert len(matrix) == 3
-    assert len(matrix[0]) == 3
+    assert len(matrix[0]) == 3
\ No newline at end of file