Merge pull request #110 from mattdahl/issue-109-rename-nonopinion-cit…

…ation

Rename NonopinionCitation to UnknownCitation

CHANGES.md

@@ -8,7 +8,7 @@ Features:
  - None yet
 
 Changes:
- - None yet
+ - The `NonopinionCitation` class has been renamed `UnknownCitation` to better reflect its purpose. This change is purely semantic -- there is no change in how these citations are handled.
 
 Fixes:
  - Initial support for finding short cites with non-standard regexes, including fixing short cite extraction for `Mich.`, `N.Y.2d` and `Pa.`. 

README.rst

@@ -439,8 +439,8 @@ If you would like to create mock citation objects to assist you in writing your
     from eyecite.test_factories import (
         case_citation,
         id_citation,
-        nonopinion_citation,
         supra_citation,
+        unknown_citation,
     )
 
 

eyecite/find.py

@@ -15,13 +15,13 @@
     FullLawCitation,
     IdCitation,
     IdToken,
-    NonopinionCitation,
     ResourceCitation,
     SectionToken,
     ShortCaseCitation,
     SupraCitation,
     SupraToken,
     Tokens,
+    UnknownCitation,
 )
 from eyecite.regexes import SHORT_CITE_ANTECEDENT_REGEX, SUPRA_ANTECEDENT_REGEX
 from eyecite.tokenizers import Tokenizer, default_tokenizer
@@ -60,7 +60,8 @@ def get_citations(
         citation: CitationBase
         token_type = type(token)
 
-        # CASE 1: Citation token is a reporter (e.g., "U. S.").
+        # CASE 1: Token is a CitationToken (i.e., a reporter, a law journal,
+        # or a law).
         # In this case, first try extracting it as a standard, full citation,
         # and if that fails try extracting it as a short form citation.
         if token_type is CitationToken:
@@ -70,26 +71,27 @@ def get_citations(
             else:
                 citation = _extract_full_citation(words, i)
 
-        # CASE 2: Citation token is an "Id." or "Ibid." reference.
+        # CASE 2: Token is an "Id." or "Ibid." reference.
         # In this case, the citation should simply be to the item cited
         # immediately prior, but for safety we will leave that resolution up
         # to the user.
         elif token_type is IdToken:
             citation = _extract_id_citation(words, i)
 
-        # CASE 3: Citation token is a "supra" reference.
+        # CASE 3: Token is a "supra" reference.
         # In this case, we're not sure yet what the citation's antecedent is.
         # It could be any of the previous citations above. Thus, like an Id.
         # citation, for safety we won't resolve this reference yet.
         elif token_type is SupraToken:
             citation = _extract_supra_citation(words, i)
 
-        # CASE 4: Citation token is a section marker.
-        # In this case, it's likely that this is a reference to a non-
-        # opinion document. So we record this marker in order to keep
-        # an accurate list of the possible antecedents for id citations.
+        # CASE 4: Token is a section marker.
+        # In this case, it's likely that this is a reference to a citation,
+        # but we're not sure what it is if it doesn't match any of the above.
+        # So we record this marker in order to keep an accurate list of the
+        # possible antecedents for id citations.
         elif token_type is SectionToken:
-            citation = NonopinionCitation(cast(SectionToken, token), i)
+            citation = UnknownCitation(cast(SectionToken, token), i)
 
         # CASE 5: The token is not a citation.
         else:

eyecite/models.py

@@ -454,19 +454,25 @@ def formatted(self):
 
 
 @dataclass(eq=True, unsafe_hash=True, repr=False)
-class NonopinionCitation(CitationBase):
-    """Convenience class which represents a citation to something that we know
-    is not an opinion. This could be a citation to a statute, to the U.S. code,
-    the U.S. Constitution, etc.
-
-    Examples:
-    ```
-    18 U.S.C. §922(g)(1)
-    U. S. Const., Art. I, §8
-    ```
+class UnknownCitation(CitationBase):
+    """Convenience class which represents an unknown citation. A recognized
+    citation should theoretically be parsed as a CaseCitation, FullLawCitation,
+    or a FullJournalCitation. If it's something else, this class serves as
+    a naive catch-all.
     """
 
 
+def NonopinionCitation(*args, **kwargs):
+    from warnings import warn
+
+    warn(
+        """NonopinionCitation will be deprecated in eyecite 2.5.0.
+        Please use UnknownCitation instead.""",
+        DeprecationWarning,
+    )
+    return UnknownCitation(*args, **kwargs)
+
+
 @dataclass(eq=True, unsafe_hash=True)
 class Token(UserString):
     """Base class for special tokens. For performance, this isn't used

eyecite/resolve.py

@@ -286,7 +286,7 @@ def resolve_citations(
                 citation, last_resolution, resolutions
             )
 
-        # If the citation is to a non-opinion document, ignore for now
+        # If the citation is to an unknown document, ignore for now
         else:
             resolution = None
 

eyecite/test_factories.py

@@ -6,11 +6,11 @@
     FullLawCitation,
     IdCitation,
     IdToken,
-    NonopinionCitation,
     SectionToken,
     ShortCaseCitation,
     SupraCitation,
     SupraToken,
+    UnknownCitation,
 )
 from eyecite.tokenizers import EDITIONS_LOOKUP
 
@@ -98,11 +98,20 @@ def id_citation(source_text=None, index=0, **kwargs):
     return IdCitation(IdToken(source_text, 0, 99), index, **kwargs)
 
 
-def nonopinion_citation(source_text=None, index=0, **kwargs):
-    """Convenience function for creating mock NonopinionCitation objects."""
-    return NonopinionCitation(
-        SectionToken(source_text, 0, 99), index, **kwargs
+def unknown_citation(source_text=None, index=0, **kwargs):
+    """Convenience function for creating mock UnknownCitation objects."""
+    return UnknownCitation(SectionToken(source_text, 0, 99), index, **kwargs)
+
+
+def nonopinion_citation(*args, **kwargs):
+    from warnings import warn
+
+    warn(
+        """nonopinion_citation() will be deprecated in eyecite 2.5.0.
+        Please use unknown_citation() instead.""",
+        DeprecationWarning,
     )
+    return unknown_citation(*args, **kwargs)
 
 
 def supra_citation(source_text=None, index=0, **kwargs):

tests/test_FindTest.py

@@ -13,8 +13,8 @@
     id_citation,
     journal_citation,
     law_citation,
-    nonopinion_citation,
     supra_citation,
+    unknown_citation,
 )
 from eyecite.tokenizers import (
     EDITIONS_LOOKUP,
@@ -425,9 +425,9 @@ def test_find_citations(self):
              [id_citation("Id.",
                           metadata={'pin_cite': 'at 2',
                                     'parenthetical': 'overruling ...'})]),
-            # Test non-opinion citation
+            # Test unknown citation
             ('lorem ipsum see §99 of the U.S. code.',
-             [nonopinion_citation('§99')]),
+             [unknown_citation('§99')]),
             # Test address that's not a citation (#1338)
             ('lorem 111 S.W. 12th St.',
              [],),

tests/test_ResolveTest.py

@@ -210,8 +210,8 @@ def test_id_resolution(self):
             (None, "2 F.2d, at 2."),
             (None, "Id. at 2."),
         )
-        # Test resolving an Id. citation when the previous citation is to a
-        # non-opinion document. Since we can't resolve those documents,
+        # Test resolving an Id. citation when the previous citation is to an
+        # unknown document. Since we can't resolve those documents,
         # we expect the Id. citation to also not be matched.
         self.checkResolution(
             (0, "Foo v. Bar, 1 U.S. 1."),