add read methods to CAPClient

authorityspoke/io/downloads.py

@@ -8,8 +8,8 @@
 from eyecite.models import CaseCitation
 import requests
 
-from authorityspoke.decisions import CAPCitation
-from authorityspoke.io.schemas_json import RawDecision
+from authorityspoke.decisions import CAPCitation, Decision
+from authorityspoke.io.schemas_json import RawDecision, DecisionSchema
 
 
 class AuthoritySpokeAPIError(Exception):
@@ -94,6 +94,32 @@ def fetch_decision_list_by_cite(
         response = requests.get(self.endpoint, params=params, headers=headers).json()
         return response["results"]
 
+    def read_decision_list_by_cite(
+        self, cite: Union[str, CaseCitation, CAPCitation], full_case: bool = False
+    ) -> Decision:
+        """
+        Download and deserialize the "results" list for a queried citation from the CAP API.
+
+        :param cite:
+            a citation linked to an opinion in the
+            `Caselaw Access Project database <https://case.law/api/>`_.
+            Usually these will be in the traditional format
+            ``[Volume Number] [Reporter Name Abbreviation] [Page Number]``, e.g.
+            `750 F.3d 1339 <https://case.law/search/#/cases?page=1&cite=%22750%20F.3d%201339%22>`_
+            for Oracle America, Inc. v. Google Inc.
+
+        :param full_case:
+            whether to request the full text of the opinion from the
+            `Caselaw Access Project API <https://api.case.law/v1/cases/>`_.
+            If this is ``True``, the CAPClient must have the `api_token` attribute.
+
+        :returns:
+            the first case in the "results" list for this queried citation.
+        """
+        response = self.fetch_decision_list_by_cite(cite=cite, full_case=full_case)
+        schema = DecisionSchema(many=True)
+        return schema.load(response)
+
     def fetch_by_cite(
         self, cite: Union[str, CaseCitation, CAPCitation], full_case: bool = False
     ) -> RawDecision:
@@ -119,6 +145,32 @@ def fetch_by_cite(
         result_list = self.fetch_decision_list_by_cite(cite=cite, full_case=full_case)
         return result_list[0]
 
+    def read_by_cite(
+        self, cite: Union[str, CaseCitation, CAPCitation], full_case: bool = False
+    ) -> Decision:
+        """
+        Download and deserialize a Decision from Caselaw Access Project API.
+
+        :param cite:
+            a citation linked to an opinion in the
+            `Caselaw Access Project database <https://case.law/api/>`_.
+            Usually these will be in the traditional format
+            ``[Volume Number] [Reporter Name Abbreviation] [Page Number]``, e.g.
+            `750 F.3d 1339 <https://case.law/search/#/cases?page=1&cite=%22750%20F.3d%201339%22>`_
+            for Oracle America, Inc. v. Google Inc.
+
+        :param full_case:
+            whether to request the full text of the opinion from the
+            `Caselaw Access Project API <https://api.case.law/v1/cases/>`_.
+            If this is ``True``, the CAPClient must have the `api_token` attribute.
+
+        :returns:
+            the first case in the "results" list for this queried citation.
+        """
+        response = self.fetch_by_cite(cite=cite, full_case=full_case)
+        schema = DecisionSchema()
+        return schema.load(response)
+
     def fetch_by_id(self, cap_id: int, full_case: bool = False) -> RawDecision:
         """
         Download a decision from Caselaw Access Project API.
@@ -146,3 +198,26 @@ def fetch_by_id(self, cap_id: int, full_case: bool = False) -> RawDecision:
         if cap_id and response.get("detail") == "Not found.":
             raise AuthoritySpokeAPIError(f"API returned no cases with id {cap_id}")
         return response
+
+    def read_by_id(self, cap_id: int, full_case: bool = False) -> Decision:
+        """
+        Download a decision from Caselaw Access Project API.
+
+        :param cap_id:
+            an identifier for an opinion in the
+            `Caselaw Access Project database <https://case.law/api/>`_,
+            e.g. 4066790 for
+            `Oracle America, Inc. v. Google Inc. <https://api.case.law/v1/cases/4066790/>`_.
+
+        :param full_case:
+            whether to request the full text of the opinion from the
+            `Caselaw Access Project API <https://api.case.law/v1/cases/>`_.
+            If this is ``True``, the CAPClient must have the `api_token` attribute.
+
+        :returns:
+            a Decision created from the first case in the "results" list for
+            this queried citation.
+        """
+        response = self.fetch_by_id(cap_id=cap_id, full_case=full_case)
+        schema = DecisionSchema()
+        return schema.load(response)

tests/io/cassettes/TestDownload.test_read_case_using_client.yaml

@@ -0,0 +1,87 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - python-requests/2.25.1
+    method: GET
+    uri: https://api.case.law/v1/cases/?cite=621+F.3d+205
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAC/41W227bRhD9lQWBAi0qUXu/6E2IbaCAk4fKeUkRCCvuMmJDkwQvdhPD/95ZkrJE
+        2onyIpHLs3M5c2Z3nqKk7Io2WpNFVPj/4KHo8nwRVbV/yMquOb7XvunyFl7/eYoyF62Z0pwxuoi6
+        Oo/W0aFtq2a9WtkqixPb+Di3j6sHsgrPzWoEryLwYe894D9++Ovu+gpt7zZ311tUpmhz7+sssQu0
+        qSqf594v0EOM3tsOVrMSbfK0LJoSvd98+rRZbm43tx9vFujKp75wtmiXwy54Gl3s7H4fMrBtVhbB
+        X5G13qFta1vfDJa/f7fLTW7zLoU9zidZA9CdAwDgKSZ4ic2S0vCxTL76dld093tfw8er/h19KGME
+        EGY4XiY14NKsbtpdZb8MFgQs5fZshYSVJGv7oAYq229V+FSmKaRp8+F7WJGUoJuYORTsPH9eRA9l
+        3gXqni4wPuCAc4o5J4xSoaTpqR++nNIAF7C6t3VSuuByuiN6DkWvyroN4Etej8hmZRgLzlJQzW4s
+        9o13vrY5+nsEIUhrC+X2DQCDmGAPeAMh1u1lVz2sWVG3TLJ6+SKqecWpQ++yOoavTd596ReGDaNP
+        rZQ+yXEij3fBQy9KUJXNG5SWNWoPHoJOyqK3m3RZGxj6F/TZuCwZnI6tYcaI8rL4MjceXeqYc4vN
+        qmtWpwy6sPvxANbyrAGT0TqF6Pwpi3gbh6CChJpdW/YKG/UkBB70ZFtEtA5CA6e7zAUdfn5evAAl
+        VgDcdlUV0x7NDf0xWig+mCVYTlFMKqmwmZgmcgQrPgMrqbHiE8tsbAAi2RQstMKSTMHn2Rnyk3gx
+        PbbVLAQhKEgfn4OJ1Og2vnaBCIpnUTChGMZTPFVoG79rY0S5mNPxGi4EQaFkiDF9GczMELhRMyyh
+        hAtxjuVaDFg555ljpRgxb1JHNJ4xojissSkj5oURrsmrigup6ZQRPTIixDzH12gowUCIFhex8ljI
+        XqH8xxUn5gSkhv0CkJoZEYSAd2ImtHE1cszlPDElqBHkzWB/rZeCiLH5CZCMrcHoq/pKLchEDESx
+        U8n4XMRSMD5tJULNWDLyRs1ewRkfdUlnujRYcqrVlAZ+1OUsDolB33gKJup4ssyDVgp0OOkOrQIj
+        oU31jGCCBdVw1p+jKT0eWvMECaFMgmingbzwJ+RMGZJoCk1yDjdH+qiaN8gbaKjIeAZgdREsXvpa
+        zLJkHI7P2YFhjoUhs27ikD+m05N5cuhzPZcVBetCfg5zSFqXRQtT1256jQVDp3ssZW4F48UKhpd+
+        GDjuqVz6033w/WVYHK7N3ygeLk54eIjh53xwW8A7uIHfkCn8gT/4/T1Mb3/EYCwaB1n/GFpoEdnC
+        5t+arAlX9WNZu904/IJS4dJuDpbCuQ1yMnavUswJJtY7x81+r7imlmIrvdR7k1CFiROcWmxAYFI5
+        uNuM5UZzw3pRlUkNxos0c75IgGIcS8mB1IOtj06pElxBgDAd1rb4GmKqfJ34os3yfodhkjMDB0+v
+        YAXY2kIiIsZKctAu5ZRLJohfYhWufVu7DBLM2m8wzmMjIKPs/mCbQ2jrdUp5mu4Vc1q7/V72A14/
+        nnZVGHpdP7NSssR8SfEdkWsi1ozGGuZbY/7EeI0xDKLP/wP0b/g8MQwAAA==
+    headers:
+      Accept-Ranges:
+      - bytes
+      Access-Control-Allow-Headers:
+      - Authorization
+      Access-Control-Allow-Origin:
+      - '*'
+      Allow:
+      - GET, HEAD, OPTIONS
+      CF-Cache-Status:
+      - MISS
+      CF-RAY:
+      - 64a4a8b3ffa50e4a-DFW
+      Cache-Control:
+      - s-maxage=86400, max-age=3600
+      Connection:
+      - keep-alive
+      Content-Encoding:
+      - gzip
+      Content-Length:
+      - '1240'
+      Content-Type:
+      - application/json
+      Date:
+      - Tue, 04 May 2021 21:00:30 GMT
+      Expect-CT:
+      - max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
+      Referrer-Policy:
+      - same-origin
+      Server:
+      - cloudflare
+      Set-Cookie:
+      - __cfduid=d8fb1b8e7fa5e5eb19f42d55f5872faa71620162030; expires=Thu, 03-Jun-21
+        21:00:30 GMT; path=/; domain=.case.law; HttpOnly; SameSite=Lax
+      Strict-Transport-Security:
+      - max-age=15768000
+      Vary:
+      - Accept, Cookie, Accept-Encoding
+      X-Content-Type-Options:
+      - nosniff
+      X-Frame-Options:
+      - DENY
+      cf-request-id:
+      - 09dac7c47e00000e4a03b04000000001
+    status:
+      code: 200
+      message: OK
+version: 1

tests/io/test_download.py

@@ -75,3 +75,13 @@ def test_full_case_download(self):
         """
         lotus = self.client.fetch_by_cite(cite="49 F.3d 807", full_case=True)
         assert lotus["casebody"]["data"]["opinions"][0]["author"].startswith("STAHL")
+
+    @pytest.mark.vcr
+    def test_read_case_using_client(self):
+        licensing_case = self.client.read_by_cite(cite="621 F.3d 205", full_case=False)
+        assert licensing_case.name_abbreviation == "United States v. Mazza-Alaluf"
+
+    @pytest.mark.vcr
+    def test_read_case_from_id_using_client(self):
+        case = self.client.read_by_id(cap_id=3675682, full_case=False)
+        assert case.name_abbreviation == "Kimbrough v. United States"