Fix API by adding 'responses_of' method

`responses_of` replaces `response_of`, since each request can have
several matching responses now.

This breaks backwards compatibility if you are using the
response_of method, so a version bump will be required.

README.md

@@ -162,7 +162,7 @@ part of the API.  The fields are as follows:
 * `responses`: A list of the responses made.
 * `play_count`: The number of times this cassette has had a response
   played back
-* `response_of(request)`: Access the response for a given request.
+* `responses_of(request)`: Access the responses that match a given request
 
 The Request object has the following properties
 

tests/unit/test_cassettes.py

@@ -44,14 +44,22 @@ def test_cassette_contains():
 
 
 @mock.patch('vcr.cassette.requests_match', _mock_requests_match)
-def test_cassette_response_of():
+def test_cassette_responses_of():
     a = Cassette('test')
     a.append('foo', 'bar')
-    assert a.response_of('foo') == 'bar'
+    assert a.responses_of('foo') == ['bar']
 
 
 @mock.patch('vcr.cassette.requests_match', _mock_requests_match)
 def test_cassette_get_missing_response():
     a = Cassette('test')
     with pytest.raises(KeyError):
-        a.response_of('foo')
+        a.responses_of('foo')
+
+@mock.patch('vcr.cassette.requests_match', _mock_requests_match)
+def test_cassette_cant_read_same_request_twice():
+    a = Cassette('test')
+    a.append('foo','bar')
+    a.play_response('foo')
+    with pytest.raises(KeyError):
+        a.play_response('foo')

vcr/cassette.py

@@ -61,10 +61,10 @@ class Cassette(object):
         self.data.append((request, response))
         self.dirty = True
 
-    def response_of(self, request):
+    def play_response(self, request):
         '''
-        Find the response corresponding to a request
-
+        Get the response corresponding to a request, but only if it
+        hasn't been played back before, and mark it as playe.d
         '''
         for index, (stored_request, response) in enumerate(self.data):
             if requests_match(request, stored_request, self._match_on):
@@ -75,6 +75,19 @@ class Cassette(object):
         # if the cassette doesn't contain the request asked for.
         raise KeyError
 
+    def responses_of(self, request):
+        '''
+        Find the responses corresponding to a request.
+	This function isn't actually used by VCR internally, but is
+	provided as an external API.
+        '''
+        responses = [resp for req, resp in self.data if requests_match(req, request, self._match_on)]
+        if responses:
+            return responses
+        # I decided that a KeyError is the best exception to raise
+        # if the cassette doesn't contain the request asked for.
+        raise KeyError
+
     def _as_dict(self):
         return {"requests": self.requests, "responses": self.responses}
 

vcr/stubs/__init__.py

@@ -166,7 +166,7 @@ class VCRConnectionMixin:
         # Check to see if the cassette has a response for this request. If so,
         # then return it
         if self._vcr_request in self.cassette and  self.cassette.record_mode != "all" and self.cassette.rewound:
-            response = self.cassette.response_of(self._vcr_request)
+            response = self.cassette.play_response(self._vcr_request)
             return VCRHTTPResponse(response)
         else:
             if self.cassette.write_protected: