Lib.rs

提取引用

主执行函数 get_citations() 接收三个参数。

1. plain_text ==> str: 要解析的文本。首先应该进行清理。
2. remove_ambiguous ==> bool，默认 False：是否删除可能指向多个报告且无法通过日期缩小范围的引用。
3. tokenizer ==> Tokenizer，默认 eyecite.tokenizers.default_tokenizer：Tokenizer对象的实例（见下文“分词器”）。

清理输入文本

对于给定的引用文本，例如 "... 1 Baldwin's Rep. 1 ..."，eyecite期望在将其传递给 get_citation 之前，文本将是“清洁”的。这意味着

• 空格将是单个空格字符，而不是多个空格或其他空白字符。
• 引号和连字符将是标准的引号和连字符字符。
• 引用中不应包含HTML标签等垃圾。

您可以使用 clean_text 来帮助完成此操作

from eyecite import clean_text, get_citations

source_text = '<p>foo   1  U.S.  1   </p>'
plain_text = clean_text(text, ['html', 'inline_whitespace', my_func])
found_citations = get_citations(plain_text)

有关如何使用从清理文本中提取的引用在原始文本中插入链接的说明，请参阅标注引用部分。

clean_text 目前接受以下作为清理器的值

1. inline_whitespace：将所有制表符和空格字符的连续序列替换为一个空格字符
2. all_whitespace：将所有空白字符的连续序列替换为一个空格字符
3. underscores：删除两个或多个下划线，这是从PDF中提取的文本中常见的错误
4. html：使用lxml库删除非可见HTML内容
5. 自定义函数：接受字符串并返回字符串的任何函数。

标注引用

对于简单的纯文本，您可以使用 annotate 函数插入引用链接

from eyecite import get_citations, annotate

plain_text = 'bob lissner v. test 1 U.S. 12, 347-348 (4th Cir. 1982)'
citations = get_citations(plain_text)
linked_text = annotate(plain_text, [[c.span(), "<a>", "</a>"] for c in citations])

returns:
'bob lissner v. test <a>1 U.S. 12</a>, 347-348 (4th Cir. 1982)'

get_citations返回的每个引用都记录了其在源文本中的位置。因此，annotate 必须使用与 get_citations 提取引用相同的 相同 清理文本来调用。如果不这样做，引用的 span 方法的返回偏移量将与文本不匹配，您的标注将位于错误的位置。

如果您想清理文本然后向原始文本中插入标注，您可以将原始文本作为 source_text 传递

from eyecite import get_citations, annotate, clean_text

source_text = '<p>bob lissner v. <i>test   1 U.S.</i> 12,   347-348 (4th Cir. 1982)</p>'
plain_text = clean_text(source_text, ['html', 'inline_whitespace'])
citations = get_citations(plain_text)
linked_text = annotate(plain_text, [[c.span(), "<a>", "</a>"] for c in citations], source_text=source_text)

returns:
'<p>bob lissner v. <i>test   <a>1 U.S.</i> 12</a>,   347-348 (4th Cir. 1982)</p>'

上述示例从 plain_text 中提取引用并将其应用于 source_text，使用差异算法在原始文本的正确位置插入标注。

def annotator(before, span_text, after):
    return before + span_text.lower() + after
linked_text = annotate(plain_text, [[c.span(), "<a>", "</a>"] for c in citations], annotator=annotator)

returns:
'bob lissner v. test <a>1 u.s. 12</a>, 347-348 (4th Cir. 1982)'

解决引用

一旦从文档中提取了引用，您可能希望将其解析为常见的参考文献。要这样做，只需将 get_citations() 的结果传递给 resolve_citations()。此函数将尽力将每个 "全"、"简略形式"、"supra" 和 "id" 引用解析为常见的 Resource 对象，并返回一个将资源映射到相关引用列表的字典

from eyecite import get_citations, resolve_citations

text = 'first citation: 1 U.S. 12. second citation: 2 F.3d 2. third citation: Id.'
found_citations = get_citations(text)
resolved_citations = resolve_citations(found_citations)

returns (pseudo):
{
    <Resource object>: [FullCaseCitation('1 U.S. 12')],
    <Resource object>: [FullCaseCitation('2 F.3d 2'), IdCitation('Id.')]
}

重要的是，eyecite 仅使用其对每个引用文本表示形式的内在知识来进行这些解析。如果您想执行更复杂的解析（例如，通过使用第三方API的信息增强每个引用），只需将自定义的 resolve_id_citation()、resolve_supra_citation()、resolve_shortcase_citation() 和 resolve_full_citation() 函数作为关键字参数传递给 resolve_citations()。您还可以配置这些函数以返回更复杂资源对象（例如Django模型），只要该对象继承自 eyecite.models.ResourceType 类型（这仅要求可哈希性）。例如，您可能会实现如下自定义全引用解析函数，其中默认解析逻辑作为后备

def my_resolve(full_cite):
    # special handling for resolution of known cases in our database
    resource = MyOpinion.objects.get(full_cite)
    if resource:
        return resource
    # allow normal clustering of other citations
    return resolve_full_citation(full_cite)

resolve_citations(citations, resolve_full_citation=my_resolve)

returns (pseudo):
{
    <MyOpinion object>: [<full_cite>, <short_cite>, <id_cite>],
    <Resource object>: [<full cite>, <short cite>],
}

分词器

eyecite 在内部通过将一系列正则表达式应用于源文本，将其转换为标记列表来实现。

In [1]: from eyecite.tokenizers import default_tokenizer

In [2]: list(default_tokenizer.tokenize("Foo v. Bar, 123 U.S. 456 (2016). Id. at 457."))
Out[2]:
['Foo',
 StopWordToken(data='v.', ...),
 'Bar,',
 CitationToken(data='123 U.S. 456', volume='123', reporter='U.S.', page='456', ...),
 '(2016).',
 IdToken(data='Id.', ...),
 'at',
 '457.']

然后扫描这些标记以确定引用年份或案例名称等值，从而进行引用解析。

可以通过向 get_citations() 提供标记化器实例来替换其他标记化器。

from eyecite.tokenizers import HyperscanTokenizer
hyperscan_tokenizer = HyperscanTokenizer(cache_dir='.hyperscan')
cites = get_citations(text, tokenizer=hyperscan_tokenizer)

test_FindTest.py 包含了一个使用修改后的正则表达式提取包含 OCR 错误的引用的简化示例。

eyecite 随附了两个标记化器。

hyperscan_tokenizer = HyperscanTokenizer(cache_dir='.hyperscan')

调试

如果您想查看 eyecite 能够为每个引用提取哪些元数据，可以使用 dump_citations。这对于开发 eyecite 主要有用，但也可能有助于探索您可用的数据。

In [1]: from eyecite import dump_citations, get_citations

In [2]: text="Mass. Gen. Laws ch. 1, § 2. Foo v. Bar, 1 U.S. 2, 3-4 (1999). Id. at 3. Foo, supra, at 5."

In [3]: cites=get_citations(text)

In [4]: print(dump_citations(get_citations(text), text))
FullLawCitation: Mass. Gen. Laws ch. 1, § 2. Foo v. Bar, 1 U.S. 2, 3-4 (1
  * groups
    * reporter='Mass. Gen. Laws'
    * chapter='1'
    * section='2'
FullCaseCitation: Laws ch. 1, § 2. Foo v. Bar, 1 U.S. 2, 3-4 (1999). Id. at 3. Foo, s
  * groups
    * volume='1'
    * reporter='U.S.'
    * page='2'
  * metadata
    * pin_cite='3-4'
    * year='1999'
    * court='scotus'
    * plaintiff='Foo'
    * defendant='Bar,'
  * year=1999
IdCitation: v. Bar, 1 U.S. 2, 3-4 (1999). Id. at 3. Foo, supra, at 5.
  * metadata
    * pin_cite='at 3'
SupraCitation: 2, 3-4 (1999). Id. at 3. Foo, supra, at 5.
  * metadata
    * antecedent_guess='Foo'
    * pin_cite='at 5'

在实际终端中，每个提取引用的 span() 将被突出显示。您可以使用 context_chars=30 参数来控制显示多少文本在前后。

Hyperscan 安装

要使用 HyperscanTokenizer，您还必须安装 python hyperscan 库及其依赖项。python-hyperscan 官方只支持 x86 Linux，尽管其他配置也可能可行。

x86 Ubuntu 20.04 上的 Hyperscan 安装示例

apt install libhyperscan-dev
pip install hyperscan

x86 Debian Buster 上的 Hyperscan 安装示例

echo 'deb http://deb.debian.org/debian buster-backports main' > /etc/apt/sources.list.d/backports.list
apt install -t buster-backports libhyperscan-dev
pip install hyperscan

使用 homebrew 在 x86 MacOS 上的 Hyperscan 安装示例

brew install hyperscan
pip install hyperscan