Issue 30 find partial page citations

[mattdahl]

This enables eyecite to find citations that don't yet have a final page number, but just have a placeholder ___ space instead. This is common with the U.S. reporter. This simple parsing change is the first half of addressing #30; figuring out how to match these partial citations will have to be done in CL.

Some other things I thought of but didn't include:

1. Should we add a metadata flag to the citation objects like has_proper_page_number or something? This would be False if the page number is all underscores, True otherwise. I wasn't sure if this would actually be helpful or not.
2. How should this change affect hashing? Would we expect 1 U.S. __ to hash equivalently to 1 U.S. ___ (identical expect one "placeholder page" has more underscores than the other)? Or should neither hash to the other at all, since maybe these are two completely different citations that just happen to have the same volume and reporter?
3. Are there other characters besides underscores that courts use to indicate a placeholder for an eventual page number?

[mlissner]

Wow, this looks simple enough, thanks Matt!

@jcushman do you have time to take a look and chime in before we merge?

(A couple questions/comments in the review.)

[mlissner]

1. Should we add a metadata flag to the citation objects like has_proper_page_number or something? This would be False if the page number is all underscores, True otherwise. I wasn't sure if this would actually be helpful or not.

See my thought about this above.

2. How should this change affect hashing? Would we expect 1 U.S. __ to hash equivalently to 1 U.S. ___ (identical expect one "placeholder page" has more underscores than the other)? Or should neither hash to the other at all, since maybe these are two completely different citations that just happen to have the same volume and reporter?

I forget how we use this hash. Can you elaborate and maybe that help me form an opinion?

3. Are there other characters besides underscores that courts use to indicate a placeholder for an eventual page number?

Not that I know of. @flooie have you seen anything weird in the wild?

[mattdahl]

I forget how we use this hash. Can you elaborate and maybe that help me form an opinion?

It's primarily for resolve_citations() to see if citations are equal enough to be grouped together. I think that we should be conservative and say that missing page full citations do NOT hash to any other full citations so there's no risk of false positives. If the user wants to handle these differently (e.g., in CL we're going to do that "search +-1 year" thing) they can implement a custom resolve_full_citation() function.

[jcushman]

@jcushman do you have time to take a look and chime in before we merge?

Not with anything well informed. :)

For Id. cites I imagine they tend to also give a parallel cite with page numbers, e.g. S.Ct. or a docket number, and you could cite to that? Like "Foo v. Bar, 1 S.Ct. 3, 4 U.S. __ (2000). ... Id. at (something)". I'm not sure how that's handled, though. It wouldn't be a terrible idea to grep through for 2 or 3 underscores and see how these are actually used. Possibly one answer is there's always a parallel cite that's better for resolution of the citation.

[mlissner]

I think that we should be conservative and say that missing page full citations do NOT hash to any other full citations

Sounds good to me.

[mlissner]

I see you working, but let me know when this is ready for another review.

[mattdahl]

For Id. cites I imagine they tend to also give a parallel cite with page numbers, e.g. S.Ct. or a docket number, and you could cite to that? Like "Foo v. Bar, 1 S.Ct. 3, 4 U.S. __ (2000). ... Id. at (something)". I'm not sure how that's handled, though. It wouldn't be a terrible idea to grep through for 2 or 3 underscores and see how these are actually used. Possibly one answer is there's always a parallel cite that's better for resolution of the citation.

I found this to be sometimes the case but often the Id. cite is just Id., at ___, so I changed our behavior to just not match those. Enhancing this with the parallel cite info could be done as a part of #76 perhaps.

Sounds good to me.

Hashability changes done in 08b9625.

---

N.B. I also had to make a change to the joke cite (5ee4145) because it was causing an issue with the CitationBase.__post_init__ method for some reason after I implemented the missing page normalization logic.

[mlissner]

A couple little things, but looks close.

[mlissner]

very nice, thank you!