update example in readme to work with current version

closes #102
mscarey · May 24, 2021 · f5a3d7a · f5a3d7a
1 parent f7a0a0d
commit f5a3d7a
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 66 deletions.
diff --git a/changelog.rst b/changelog.rst
@@ -1,5 +1,11 @@
 Changelog
 =========
+dev
+------------------
+* change "quotes" schema field names to "anchors"
+* add doctests to documentation
+* update example in readme to work with current version
+
 0.7.0 (2021-05-20)
 ------------------
 * remove Enactment download functions (use Legislice download client instead)
@@ -16,7 +22,7 @@ Changelog
 * Procedure has separate add_factor and with_factor methods
 * increase versions of Nettlesome and Legislice dependencies
 * add CAPClient to top level of package
-* add "Creating and Loading Holding Data" documentation page 
+* add "Creating and Loading Holding Data" documentation page
 * Rules select all text of Enactments without selected text only during init, not during schema load
 * change field name from "quotes" to "anchors" in YAML import files
 * fix bug: dump methods couldn't find Decision and Opinion schemas

diff --git a/notebooks/introduction.ipynb b/notebooks/introduction.ipynb
@@ -306,7 +306,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The interface for downloading legislation is a little different. First you create a Client class that holds your API key. Then you can use the `Client.fetch` method to fetch JSON representing the provision at a specified citation on a specified date (or the most recent version, if you don't specify a date). Or you can use `Client.read`, which also fetches the JSON but then loads it into an instance of the `Enactment` class."
+    "AuthoritySpoke also includes an interface for downloading provisions of the United States Constitution and US Code from the API at authorityspoke.com. To use this, first create a LegisClient object that holds your API key. Then you can use the `Client.fetch` method to fetch JSON representing the provision at a specified citation on a specified date (or the most recent version, if you don't specify a date). Or you can use `Client.read`, which also fetches the JSON but then loads it into an instance of the `Enactment` class."
    ]
   },
   {

diff --git a/readme.md b/readme.md
@@ -22,103 +22,102 @@ Even if you don't install AuthoritySpoke, you can try it out by clicking the Bin
 
 ## An Example
 
-Here's an example that discovers contradictory legal holdings in `Oracle America, Inc. v. Google Inc., 750 F.3d 1339` (a famous case that dealt with a claim that the Android operating system infringed the copyright on the Java language) and `Lotus Development Corporation v. Borland International, 49 F.3d 807` (an older case about whether a user interface was copyrightable).
+(A more detailed version of this example is [in the documentation](https://authorityspoke.readthedocs.io/en/latest/guides/introduction.html).)
 
-Copies of both opinions can be loaded from the `example_data` folder. (But you can also use AuthoritySpoke to retrieve opinions from the [Caselaw Access Project API](https://api.case.law/v1/).)
+This example shows how to discover contradictory legal holdings in `Oracle America, Inc. v. Google Inc., 750 F.3d 1339` (a famous circuit court decision that dealt with a claim that the Android operating system infringed the copyright on the Java language) and `Lotus Development Corporation v. Borland International, 49 F.3d 807` (an older case about whether a user interface was copyrightable). Replicating this example on your own computer would require obtaining API keys from both the [Caselaw Access Project API](https://api.case.law/v1/) and the [AuthoritySpoke API](https://authorityspoke.com/).
 
-```python
-from authorityspoke.io.loaders import load_and_read_decision
+AuthoritySpoke includes a download client for retrieving court decisions from the [Caselaw Access Project API](https://api.case.law/v1/). (Or copies of both opinions can be loaded from the `example_data` folder of this repository.)
 
-oracle = load_and_read_decision("oracle_h.json")
-lotus = load_and_read_decision("lotus_h.json")
+```python
+>>> import os
+>>> from dotenv import load_dotenv
+>>> from authorityspoke import CAPClient
+>>> load_dotenv()
+True
+>>> CAP_API_KEY = os.getenv('CAP_API_KEY')
+>>> case_client = CAPClient(api_token=CAP_API_KEY)
+>>> oracle = case_client.read_cite(
+...    cite="750 F.3d 1339", full_case=True)
+>>> str(oracle)
+'Oracle America, Inc. v. Google Inc., 750 F.3d 1339 (2014-05-09)'
+>>> lotus = case_client.read_cite(
+...    cite="49 F.3d 807", full_case=True)
+>>> str(lotus)
+'Lotus Development Corp. v. Borland International, Inc., 49 F.3d 807 (1995-03-09)'
 ```
 
-The `example_data` folder also contains legislation in XML files that can be organized by linking them to a `Regime` object.
-
-Structured annotations about the holdings in _Oracle_ and _Lotus_ can also be loaded from the `example_data` folder, and can be linked to the `Decision` objects.
+AuthoritySpoke can be used to create structured annotations for these cases by bringing together data from two sources: user-created annotations for judicial holdings, and legislative quotations that can be downloaded from the API at [authorityspoke.com](https://authorityspoke.com/). The `example_data` folder contains example annotations for the holdings in several cases, including the _Oracle_ and _Lotus_ cases. The LegisClient class is also a download client, and it can be used to retrieve legislative quotations.
 
 ```python
-from authorityspoke.io.loaders import read_holdings_from_file
-
-oracle.posit(read_holdings_from_file("holding_oracle.json", regime=usa))
-lotus.posit(read_holdings_from_file("holding_lotus.json", regime=usa))
+>>> from authorityspoke.io.downloads import LegisClient
+>>> from authorityspoke.io.loaders import read_holdings_from_file
+>>> LEGISLICE_API_TOKEN = os.getenv("LEGISLICE_API_TOKEN")
+>>> legis_client = LegisClient(api_token=LEGISLICE_API_TOKEN)
+>>> oracle_holdings = read_holdings_from_file("holding_oracle.yaml", client=legis_client)
+>>> lotus_holdings = read_holdings_from_file("holding_lotus.yaml", client=legis_client)
 ```
 
-Now, each `Decision` has a `.contradicts` method that can return a boolean indicating whether its holdings conflict with the holdings of another `Decision`.
+User-created annotations for judicial holdings can be linked to court decisions using the `posit` method.
 
 ```python
-print(lotus.contradicts(oracle))
+>>> oracle.posit(oracle_holdings)
+>>> lotus.posit(lotus_holdings)
 ```
 
-```
+Now, each `Decision` has a `.contradicts` method that can return a boolean indicating whether its holdings conflict with the holdings of another `Decision`.
+
+```python
+>>> lotus.contradicts(oracle)
 True
 ```
 
-That's good to know, but we don't want to take it on faith that a contradiction exists. Let's use the `explain_contradiction` method to find the contradictory Holdings posited by the _Oracle_ and _Lotus_ cases, and to generate a rudimentary explanation of why they contradict.
+AuthoritySpoke has concluded that these decisions do contradict one another. That's good to know, but we don't want to take it on faith that a contradiction exists. We can use the `explain_contradiction` method to find the contradictory Holdings posited by the _Oracle_ and _Lotus_ cases, and to generate a rudimentary explanation of why they contradict.
 
 ```python
-explanation = lotus.explain_contradiction(oracle)
-print(explanation)
-```
-
-```
-EXPLANATION: Because <the Lotus menu command hierarchy> is like <the Java API>,
+>>> explanation = lotus.explain_contradiction(oracle)
+>>> str(explanation)
+"""
+Because <the Lotus menu command hierarchy> is like <the Java API>,
   the Holding to ACCEPT
     the Rule that the court MUST ALWAYS impose the
       RESULT:
-        the Fact it is false that <the Lotus menu command hierarchy> was
-        copyrightable
+        the fact it was false that <the Lotus menu command hierarchy> was copyrightable
       GIVEN:
-        the Fact that <the Lotus menu command hierarchy> was a method of
-        operation
+        the fact that <the Lotus menu command hierarchy> was a method of operation
       DESPITE:
-        the Fact that a text described <the Lotus menu command hierarchy>
-        the Fact that <the Lotus menu command hierarchy> was an original work
-      GIVEN the ENACTMENTS:
-        "In no case does copyright protection for an original work of
-        authorship extend to any" (Title 17, /us/usc/t17/s102/b)
-        "method of operation" (Title 17, /us/usc/t17/s102/b)
+        the fact that a text described <the Lotus menu command hierarchy>
+        the fact that <the Lotus menu command hierarchy> was an original work
+      GIVEN the ENACTMENT:
+        "In no case does copyright protection for an original work of authorship extend to any…method of operation…" (/us/usc/t17/s102/b 2013-07-18)
 CONTRADICTS
   the Holding to ACCEPT
     the Rule that the court MUST SOMETIMES impose the
       RESULT:
-        the Fact that <the Java API> was copyrightable
+        the fact that <the Java API> was copyrightable
       GIVEN:
-        the Fact that <the Java language> was a computer program
-        the Fact that <the Java API> was a set of application programming
-        interface declarations
-        the Fact that <the Java API> was an original work
-        the Fact that <the Java API> was a non-literal element of <the Java
-        language>
-        the Fact that <the Java API> was the expression of an idea
-        the Fact it is false that <the Java API> was essentially the only way
-        to express the idea that it embodied
-        the Fact that <the Java API> was creative
-        the Fact that it was possible to use <the Java language> without
-        copying <the Java API>
+        the fact that <the Java language> was a computer program
+        the fact that <the Java API> was a set of application programming interface declarations
+        the fact that <the Java API> was an original work
+        the fact that <the Java API> was a non-literal element of <the Java language>
+        the fact that <the Java API> was the expression of an idea
+        the fact it was false that <the Java API> was essentially the only way to express the idea that it embodied
+        the fact that <the Java API> was creative
+        the fact that it was possible to use <the Java language> without copying <the Java API>
       DESPITE:
-        the Fact that <the Java API> was a method of operation
-        the Fact that <the Java API> contained short phrases
-        the Fact that <the Java API> became so popular that it was the
-        industry standard
-        the Fact that there was a preexisting community of programmers
-        accustomed to using <the Java API>
+        the fact that <the Java API> was a method of operation
+        the fact that <the Java API> contained short phrases
+        the fact that <the Java API> became so popular that it was the industry standard
+        the fact that there was a preexisting community of programmers accustomed to using <the Java API>
       GIVEN the ENACTMENT:
-        "Copyright protection subsists, in accordance with this title, in
-        original works of authorship fixed in any tangible medium of
-        expression, now known or later developed, from which they can be
-        perceived, reproduced, or otherwise communicated, either directly or
-        with the aid of a machine or device." (Title 17, /us/usc/t17/s102/a)
+        "Copyright protection subsists, in accordance with this title, in original works of authorship fixed in any tangible medium of expression, now known or later developed, from which they can be perceived, reproduced, or otherwise communicated, either directly or with the aid of a machine or device.…" (/us/usc/t17/s102/a 2013-07-18)
       DESPITE the ENACTMENTS:
-        "In no case does copyright protection for an original work of
-        authorship extend to any" (Title 17, /us/usc/t17/s102/b)
-        "method of operation" (Title 17, /us/usc/t17/s102/b)
-        "The following are examples of works not subject to copyright and
-        applications for registration of such works cannot be entertained: (a)
-        Words and short phrases such as names, titles, and slogans;" (Code of
-        Federal Regulations Title 37, /us/cfr/t37/s202.1)
+        "In no case does copyright protection for an original work of authorship extend to any…method of operation…" (/us/usc/t17/s102/b 2013-07-18)
+        "The following are examples of works not subject to copyright and applications for registration of such works cannot be entertained: Words and short phrases such as names, titles, and slogans; familiar symbols or designs; mere variations of typographic ornamentation, lettering or coloring; mere listing of ingredients or contents; Ideas, plans, methods, systems, or devices, as distinguished from the particular manner in which they are expressed or described in a writing;  Blank forms, such as time cards, graph paper, account books, diaries, bank checks, scorecards, address books, report forms, order forms and the like, which are designed for recording information and do not in themselves convey information; Works consisting entirely of information that is common property containing no original authorship, such as, for example: Standard calendars, height and weight charts, tape measures and rulers, schedules of sporting events, and lists or tables taken from public documents or other common sources. Typeface as typeface." (/us/cfr/t37/s202.1 1992-02-21)
+"""
 ```
 
+In other words, because "the Lotus menu command hierarchy" has a similar role in the _Lotus_ case to the role of "the Java API" in the _Oracle_ case, a Holding from the _Lotus_ case (identified by the text before the word "CONTRADICTS") contradicts a Holding from the _Oracle_ case (identified by the text after the word "CONTRADICTS").
+
 ## Learning about AuthoritySpoke
 
 You can find the example above and much more information about using AuthoritySpoke in the [Introduction to AuthoritySpoke](notebooks/introduction.ipynb) Jupyter notebook.