Add support for SearchResult.

stripe/api_resources/__init__.py

@@ -5,6 +5,7 @@
 
 from stripe.api_resources.error_object import ErrorObject, OAuthErrorObject
 from stripe.api_resources.list_object import ListObject
+from stripe.api_resources.search_result_object import SearchResultObject
 
 from stripe.api_resources import billing_portal
 from stripe.api_resources import checkout

stripe/api_resources/abstract/__init__.py

@@ -19,6 +19,9 @@
 from stripe.api_resources.abstract.listable_api_resource import (
     ListableAPIResource,
 )
+from stripe.api_resources.abstract.searchable_api_resource import (
+    SearchableAPIResource,
+)
 from stripe.api_resources.abstract.verify_mixin import VerifyMixin
 
 from stripe.api_resources.abstract.custom_method import custom_method

stripe/api_resources/abstract/searchable_api_resource.py

@@ -0,0 +1,28 @@
+from __future__ import absolute_import, division, print_function
+
+from stripe import api_requestor, util
+from stripe.api_resources.abstract.api_resource import APIResource
+
+
+class SearchableAPIResource(APIResource):
+    @classmethod
+    def _search(
+        cls,
+        search_url,
+        api_key=None,
+        stripe_version=None,
+        stripe_account=None,
+        **params
+    ):
+        requestor = api_requestor.APIRequestor(
+            api_key,
+            api_base=cls.api_base(),
+            api_version=stripe_version,
+            account=stripe_account,
+        )
+        response, api_key = requestor.request("get", search_url, params)
+        stripe_object = util.convert_to_stripe_object(
+            response, api_key, stripe_version, stripe_account
+        )
+        stripe_object._retrieve_params = params
+        return stripe_object

stripe/api_resources/search_result_object.py

@@ -0,0 +1,111 @@
+from __future__ import absolute_import, division, print_function
+
+from stripe import api_requestor, six, util
+from stripe.stripe_object import StripeObject
+
+
+class SearchResultObject(StripeObject):
+    OBJECT_NAME = "search_result"
+
+    def search(
+        self, api_key=None, stripe_version=None, stripe_account=None, **params
+    ):
+        stripe_object = self._request(
+            "get",
+            self.get("url"),
+            api_key=api_key,
+            stripe_version=stripe_version,
+            stripe_account=stripe_account,
+            **params
+        )
+        stripe_object._retrieve_params = params
+        return stripe_object
+
+    def _request(
+        self,
+        method_,
+        url_,
+        api_key=None,
+        idempotency_key=None,
+        stripe_version=None,
+        stripe_account=None,
+        **params
+    ):
+        api_key = api_key or self.api_key
+        stripe_version = stripe_version or self.stripe_version
+        stripe_account = stripe_account or self.stripe_account
+
+        requestor = api_requestor.APIRequestor(
+            api_key, api_version=stripe_version, account=stripe_account
+        )
+        headers = util.populate_headers(idempotency_key)
+        response, api_key = requestor.request(method_, url_, params, headers)
+        stripe_object = util.convert_to_stripe_object(
+            response, api_key, stripe_version, stripe_account
+        )
+        return stripe_object
+
+    def __getitem__(self, k):
+        if isinstance(k, six.string_types):
+            return super(SearchResultObject, self).__getitem__(k)
+        else:
+            raise KeyError(
+                "You tried to access the %s index, but SearchResultObject types "
+                "only support string keys. (HINT: Search calls return an object "
+                "with  a 'data' (which is the data array). You likely want to "
+                "call .data[%s])" % (repr(k), repr(k))
+            )
+
+    def __iter__(self):
+        return getattr(self, "data", []).__iter__()
+
+    def __len__(self):
+        return getattr(self, "data", []).__len__()
+
+    def auto_paging_iter(self):
+        page = self
+
+        while True:
+            for item in page:
+                yield item
+            page = page.next_search_result_page()
+
+            if page.is_empty:
+                break
+
+    @classmethod
+    def empty_search_result(
+        cls, api_key=None, stripe_version=None, stripe_account=None
+    ):
+        return cls.construct_from(
+            {"data": [], "has_more": False, "next_page": None},
+            key=api_key,
+            stripe_version=stripe_version,
+            stripe_account=stripe_account,
+            last_response=None,
+        )
+
+    @property
+    def is_empty(self):
+        return not self.data
+
+    def next_search_result_page(
+        self, api_key=None, stripe_version=None, stripe_account=None, **params
+    ):
+        if not self.has_more:
+            return self.empty_search_result(
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+            )
+
+        params_with_filters = self._retrieve_params.copy()
+        params_with_filters.update({"page": self.next_page})
+        params_with_filters.update(params)
+
+        return self.search(
+            api_key=api_key,
+            stripe_version=stripe_version,
+            stripe_account=stripe_account,
+            **params_with_filters
+        )

stripe/object_classes.py

@@ -7,6 +7,7 @@
 OBJECT_CLASSES = {
     # data structures
     api_resources.ListObject.OBJECT_NAME: api_resources.ListObject,
+    api_resources.SearchResultObject.OBJECT_NAME: api_resources.SearchResultObject,
     # business objects
     api_resources.Account.OBJECT_NAME: api_resources.Account,
     api_resources.AccountLink.OBJECT_NAME: api_resources.AccountLink,

tests/api_resources/abstract/test_searchable_api_resource.py

@@ -0,0 +1,92 @@
+from __future__ import absolute_import, division, print_function
+
+import stripe
+
+
+class TestSearchableAPIResource(object):
+    class MySearchable(stripe.api_resources.abstract.SearchableAPIResource):
+        OBJECT_NAME = "mysearchable"
+
+        @classmethod
+        def search(cls, *args, **kwargs):
+            return cls._search(
+                search_url="/v1/mysearchables/search", *args, **kwargs
+            )
+
+    def test_search(self, request_mock):
+        request_mock.stub_request(
+            "get",
+            "/v1/mysearchables/search",
+            {
+                "object": "search_result",
+                "data": [
+                    {"object": "charge", "name": "jose"},
+                    {"object": "charge", "name": "curly"},
+                ],
+                "url": "/v1/charges",
+                "has_more": False,
+                "next_page": None,
+            },
+            rheaders={"request-id": "req_id"},
+        )
+
+        res = self.MySearchable.search(query='currency:"CAD"')
+        request_mock.assert_requested("get", "/v1/mysearchables/search", {})
+        assert len(res.data) == 2
+        assert all(isinstance(obj, stripe.Charge) for obj in res.data)
+        assert res.data[0].name == "jose"
+        assert res.data[1].name == "curly"
+
+        assert res.last_response is not None
+        assert res.last_response.request_id == "req_id"
+
+    def test_search_multiple_pages(self, request_mock):
+        request_mock.stub_request(
+            "get",
+            "/v1/mysearchables/search",
+            {
+                "object": "search_result",
+                "data": [
+                    {"object": "charge", "name": "jose"},
+                    {"object": "charge", "name": "curly"},
+                ],
+                "url": "/v1/charges",
+                "has_more": True,
+                "next_page": "next-page-token",
+            },
+            rheaders={"request-id": "req_id"},
+        )
+
+        res = self.MySearchable.search(query='currency:"CAD"')
+        request_mock.assert_requested(
+            "get", "/v1/mysearchables/search", {"query": 'currency:"CAD"'}
+        )
+
+        assert res.next_page == "next-page-token"
+
+        request_mock.stub_request(
+            "get",
+            "/v1/mysearchables/search",
+            {
+                "object": "list",
+                "data": [
+                    {"object": "charge", "name": "test"},
+                ],
+                "url": "/v1/charges",
+                "has_more": False,
+                "next_page": None,
+            },
+            rheaders={"request-id": "req_id"},
+        )
+        res2 = self.MySearchable.search(
+            query='currency:"CAD"', page=res.next_page
+        )
+        request_mock.assert_requested(
+            "get",
+            "/v1/mysearchables/search",
+            {"page": "next-page-token", "query": 'currency:"CAD"'},
+        )
+
+        assert len(res2.data) == 1
+        assert all(isinstance(obj, stripe.Charge) for obj in res2.data)
+        assert res2.data[0].name == "test"