CoNLL-U 解析器

CoNLL-U 解析器可以将CoNLL-U 格式的字符串解析成嵌套的 Python 字典。CoNLL-U 通常是自然语言处理任务的输出格式。

为什么要使用 conllu?

• 简单。代码仅约 300 行。
• 无依赖项
• 完全支持类型提示，使您的编辑器可以自动补全
• 具有完善的测试集和 CI 设置:
• 100% 测试分支覆盖率（并经过突变测试）
• 

安装

注意：从 conllu 5.0 开始，安装 conllu 需要 Python 3.8。请参阅 4.0 到 5.0 的更新说明

pip install conllu

或者，如果您使用 conda：

conda install -c conda-forge conllu

4.0 到 5.0 的更新说明

Conllu 5.0 版本不再支持 Python 3.6 和 3.7，最低要求为 Python 3.8。如果您需要支持旧版本的 Python，可以将安装固定在旧版本的 conllu。您可以使用 pip install conllu==4.5.3 进行安装。

3.0 到 4.0 的更新说明

Conllu 4.0 版本不再支持 Python 2 和所有早于 Python 3.6 的版本。如果您需要支持旧版本的 Python，可以将安装固定在旧版本的 conllu。您可以使用 pip install conllu==3.1.1 进行安装。

2.0 到 3.0 的更新说明

通用依存关系 2.0 发布将两个字段名从 xpostag 改为 xpos，upostag 改为 upos。Conllu 3.0 版本通过将以前的名称别名化为新名称来处理这一变化。这意味着您可以使用 xpos/upos 或 xpostag/upostag，它们都会返回相同的内容。这确实稍微改变了公共 API，所以我将主版本号提升到 3.0，但我已经确保您很可能不需要在更新到 3.0 时修改代码。

0.1 到 1.0 的更新说明

我不喜欢破坏向后兼容性，但为了能够添加新功能，我觉得必须这样做。这意味着从 0.1 更新到 1.0 可能需要代码更改。这里有一个如何升级到 1.0 的指南。

使用示例

在顶层，conllu 提供了两个方法，parse 和 parse_tree。第一个方法解析句子并返回一个扁平列表。第二个返回一个嵌套的树结构。让我们逐一介绍。

使用 parse() 解析为句子列表

>>> from conllu import parse
>>> 
>>> data = """
... # text = The quick brown fox jumps over the lazy dog.
... 1   The     the    DET    DT   Definite=Def|PronType=Art   4   det     _   _
... 2   quick   quick  ADJ    JJ   Degree=Pos                  4   amod    _   _
... 3   brown   brown  ADJ    JJ   Degree=Pos                  4   amod    _   _
... 4   fox     fox    NOUN   NN   Number=Sing                 5   nsubj   _   _
... 5   jumps   jump   VERB   VBZ  Mood=Ind|Number=Sing|Person=3|Tense=Pres|VerbForm=Fin   0   root    _   _
... 6   over    over   ADP    IN   _                           9   case    _   _
... 7   the     the    DET    DT   Definite=Def|PronType=Art   9   det     _   _
... 8   lazy    lazy   ADJ    JJ   Degree=Pos                  9   amod    _   _
... 9   dog     dog    NOUN   NN   Number=Sing                 5   nmod    _   SpaceAfter=No
... 10  .       .      PUNCT  .    _                           5   punct   _   _
...
... """

现在您已经将数据存储在一个名为 data 的变量中。让我们解析它：

>>> sentences = parse(data)
>>> sentences
[TokenList<The, quick, brown, fox, jumps, over, the, lazy, dog, ., metadata={text: "The quick brown fox jumps over the lazy dog."}>]

<blockquote>

高级用法：如果您一次需要解析大量句子（比如超过一兆字节），为了避免一次性将它们全部加载到内存中，您可以使用 parse_incr() 而不是 parse。它接受一个已打开的文件，并返回一个生成器而不是直接返回列表，所以您需要对其进行迭代或调用 list() 来获取 TokenLists。以下是使用方法：

from io import open
from conllu import parse_incr

data_file = open("huge_file.conllu", "r", encoding="utf-8")
for tokenlist in parse_incr(data_file):
    print(tokenlist)

对于大多数文件，parse 就足够了。

</blockquote>

由于一个 CoNLL-U 文件通常包含多个句子，parse() 总是返回一个句子列表。每个句子都由一个 TokenList 表示。

>>> sentence = sentences[0]
>>> sentence
TokenList<The, quick, brown, fox, jumps, over, the, lazy, dog, ., metadata={text: "The quick brown fox jumps over the lazy dog."}>

TokenList 支持索引，因此您可以像这样获取第一个标记（由一个有序字典表示）：

>>> token = sentence[0]
>>> token
{'id': 1,
     'form': 'The',
     'lemma': 'the',
     ...}
>>> token["form"]
'The'

conllu 2.0新功能: 对TokenList使用filter()

>>> sentence = sentences[0]
>>> sentence
TokenList<The, quick, brown, fox, jumps, over, the, lazy, dog, ., metadata={text: "The quick brown fox jumps over the lazy dog."}>
>>> sentence.filter(form="quick")
TokenList<quick>

通过使用filter(field1__field2=value)，你可以基于已解析标记中更深层的子元素进行过滤。

>>> sentence.filter(feats__Degree="Pos")
TokenList<quick, brown, lazy>

过滤器也可以链式使用（意味着你可以执行sentence.filter(...).filter(...)），同时对多个属性进行过滤（sentence.filter(field1=value1, field2=value2)）意味着所有属性都必须匹配。

conllu 4.3新功能: 使用lambda对TokenList进行filter()

你也可以使用lambda函数作为值进行过滤。这在你想要只过滤出具有整数ID的标记时很有用：

>>> from conllu.models import TokenList, Token
>>> sentence2 = TokenList([
...    Token(id=(1, "-", 2), form="It's"),
...    Token(id=1, form="It"),
...    Token(id=2, form="is"),
... ])
>>> sentence2
TokenList<It's, It, is>
>>> sentence2.filter(id=lambda x: type(x) is int)
TokenList<It, is>

将数据写回TokenList

如果你想修改你的CoNLL-U文件，有几个便捷方法值得了解。

你可以通过简单地将一个包含你想要的字段的字典追加到TokenList来添加一个新的标记：

>>> sentence3 = TokenList([
...    {"id": 1, "form": "Lazy"},
...    {"id": 2, "form": "fox"},
... ])
>>> sentence3
TokenList<Lazy, fox>
>>> sentence3.append({"id": 3, "form": "box"})
>>> sentence3
TokenList<Lazy, fox, box>

修改一个句子只需要对其进行索引，并将值设置为你想要的内容：

>>> sentence4 = TokenList([
...    {"id": 1, "form": "Lazy"},
...    {"id": 2, "form": "fox"},
... ])
>>> sentence4[1]["form"] = "crocodile"
>>> sentence4
TokenList<Lazy, crocodile>
>>> sentence4[1] = {"id": 2, "form": "elephant"}
>>> sentence4
TokenList<Lazy, elephant>

如果在传入字典时省略了某个字段，conllu会为这些值填充"_"。

>>> sentences = parse("1  The")
>>> sentences[0].append({"id": 2})
>>> sentences[0]
TokenList<The, _>

从CoNLL-U文件解析元数据

每个句子也可以在句子开始前以注释的形式包含元数据。这可以通过TokenList的metadata属性获取。

>>> sentence.metadata
{'text': 'The quick brown fox jumps over the lazy dog.'}

将TokenList转回CoNLL-U格式

如果你想要获取回CoNLL-U格式的文本（可能是在修改后？），使用serialize()方法：

>>> print(sentence.serialize())
# text = The quick brown fox jumps over the lazy dog.
1   The     the     DET    DT   Definite=Def|PronType=Art   4   det    _   _
2   quick   quick   ADJ    JJ   Degree=Pos                  4   amod   _   _
3   brown   brown   ADJ    JJ   Degree=Pos                  4   amod   _   _
4   fox     fox     NOUN   NN   Number=Sing                 5   nsubj  _   _
5   jumps   jump    VERB   VBZ  Mood=Ind|Number=Sing|Person=3|Tense=Pres|VerbForm=Fin   0   root   _   _
6   over    over    ADP    IN   _                           9   case   _   _
7   the     the     DET    DT   Definite=Def|PronType=Art   9   det    _   _
8   lazy    lazy    ADJ    JJ   Degree=Pos                  9   amod   _   _
9   dog     dog     NOUN   NN   Number=Sing                 5   nmod   _   SpaceAfter=No
10  .       .       PUNCT  .    _                           5   punct  _   _

将TokenList转换为TokenTree（见下文）

你也可以使用to_tree将TokenList转换为TokenTree：

>>> sentence.to_tree()
TokenTree<token={id=5, form=jumps}, children=[...]>

就是这样！

使用parse_tree()解析为依存树列表

有时你对隐藏在CoNLL-U文件的head列中的树结构感兴趣。在这种情况下，使用parse_tree来获取表示句子的嵌套结构。

>>> from conllu import parse_tree
>>> sentences = parse_tree(data)
>>> sentences
[TokenTree<...>]

<blockquote>

高级用法：如果你一次需要解析许多句子（比如超过一兆字节），你可以通过使用parse_tree_incr()而不是parse_tree来避免一次性将它们加载到内存中。它接受一个已打开的文件，并返回一个生成器而不是直接返回列表，所以你需要对它进行迭代，或调用list()来获取TokenTrees。以下是使用方法：

from io import open
from conllu import parse_tree_incr

data_file = open("huge_file.conllu", "r", encoding="utf-8")
for tokentree in parse_tree_incr(data_file):
    print(tokentree)

</blockquote>

由于一个CoNLL-U文件通常包含多个句子，parse_tree()总是返回一个句子列表。每个句子由一个TokenTree表示。

>>> root = sentences[0]
>>> root
TokenTree<token={id=5, form=jumps}, children=[...]>

要快速可视化树结构，你可以对TokenTree调用print_tree。

>>> root.print_tree()
(deprel:root) form:jumps lemma:jump upos:VERB [5]
    (deprel:nsubj) form:fox lemma:fox upos:NOUN [4]
        (deprel:det) form:The lemma:the upos:DET [1]
        (deprel:amod) form:quick lemma:quick upos:ADJ [2]
        (deprel:amod) form:brown lemma:brown upos:ADJ [3]
    (deprel:nmod) form:dog lemma:dog upos:NOUN [9]
        (deprel:case) form:over lemma:over upos:ADP [6]
        (deprel:det) form:the lemma:the upos:DET [7]
        (deprel:amod) form:lazy lemma:lazy upos:ADJ [8]
    (deprel:punct) form:. lemma:. upos:PUNCT [10]

要访问树中当前节点对应的标记，使用token:

>>> root.token
{
    'id': 5,
    'form': 'jumps',
    'lemma': 'jump',
    ...
}

要开始遍历当前节点的子节点，使用children属性:

>>> children = root.children
>>> children
[
    TokenTree<token={id=4, form=fox}, children=[...]>,
    TokenTree<token={id=9, form=dog}, children=[...]>,
    TokenTree<token={id=10, form=.}, children=None>
]

就像parse()一样，如果句子有元数据，它可以在TokenTree根节点的metadata属性中找到。

>>> root.metadata
{'text': 'The quick brown fox jumps over the lazy dog.'}

如果你想获取回CoNLL-U格式的文本(可能在修改某些内容后)，使用serialize()方法:

>>> print(root.serialize())
# text = The quick brown fox jumps over the lazy dog.
1   The     the    DET    DT   Definite=Def|PronType=Art   4   det     _   _
2   quick   quick  ADJ    JJ   Degree=Pos                  4   amod    _   _
...

如果你想将其写回文件，可以这样做:

>>> from conllu import parse_tree
>>> sentences = parse_tree(data)
>>> 
>>> # 在这里对sentences进行一些修改
>>> 
>>> with open('file-to-write-to', 'w') as f:
...     f.writelines([sentence.serialize() + "\n" for sentence in sentences])

自定义解析以处理CoNLL-U的奇怪变体

在实际中发现的CoNLL-U文件并非都遵循CoNLL-U格式规范。CoNLL-U尝试解析即使按规范来说格式不正确的文件，但有时这也无法奏效。对于这些情况，你可以更改conllu解析文件的方式。

一个普通的CoNLL-U文件由一组特定的字段组成(id、form、lemma等)。让我们通过使用三个选项fields、field_parsers、metadata_parsers来解析一个自定义格式。以下是我们将使用的自定义格式。

>>> data = """
... # tagset = TAG1|TAG2|TAG3|TAG4
... # sentence-123
... 1   My       TAG1|TAG2
... 2   custom   TAG3
... 3   format   TAG4
...
... """

现在，让我们用默认设置解析这个，并特别查看第一个标记，看看它是如何被解析的。

>>> sentences = parse(data)
>>> sentences[0][0]
{'id': 1, 'form': 'My', 'lemma': 'TAG1|TAG2'}

解析器错误地假设第三个字段必须是默认的lemma字段，并按此解析。让我们通过在调用parse时设置fields参数来定制这一点，使解析器获得正确的名称。

>>> sentences = parse(data, fields=["id", "form", "tag"])
>>> sentences[0][0]
{'id': 1, 'form': 'My', 'tag': 'TAG1|TAG2'}

唯一的区别是你现在在解析时得到了正确的字段名。现在假设你想将这两个标签作为列表而不是字符串返回。这可以使用field_parsers参数来完成。

>>> split_func = lambda line, i: line[i].split("|")
>>> sentences = parse(data, fields=["id", "form", "tag"], field_parsers={"tag": split_func})
>>> sentences[0][0]
{'id': 1, 'form': 'My', 'tag': ['TAG1', 'TAG2']}

这样好多了！field_parsers指定了从字段名称到可以解析该字段的函数的映射。在我们的例子中，我们指定具有自定义逻辑的字段是"tag"，处理它的函数是split_func。每个field_parser都会接收两个参数：

• line：这一行的所有值的列表，以空白分隔。给你完整的行的原因是，如果你想的话，可以使用field_parser将多个标记合并成一个。
• i：你当前在行中的位置。通常，你会使用line[i]来获取当前值。

在我们的例子中，我们返回line[i].split("|")，这会返回我们想要的列表。

让我们看看这个例子中的元数据。

# tagset = TAG1|TAG2|TAG3|TAG4
# sentence-123

这些值在CoNLL-U中都不是有效的，但由于第一行遵循其他(有效)字段的键值格式，conllu仍然会解析它：

>>> sentences = parse(data)
>>> sentences[0].metadata
{'tagset': 'TAG1|TAG2|TAG3|TAG4'}

让我们使用metadata_parsers参数将其作为列表返回。

>>> sentences = parse(data, metadata_parsers={"tagset": lambda key, value: (key, value.split("|"))})
>>> sentences[0].metadata
{'tagset': ['TAG1', 'TAG2', 'TAG3', 'TAG4']}

元数据解析器的行为类似于字段解析器，但由于大多数注释的形式为"key = value"，这些值会先被解析和清理，然后再发送到自定义的metadata_parser。在这里，我们只是取值，用"|"分割，然后返回一个列表。瞧，我们得到了想要的结果！

现在，让我们处理"sentence-123"注释。指定另一个metadata_parser是行不通的，因为这是每个句子都不同的ID。相反，让我们使用一个特殊的元数据解析器，称为__fallback__。

>>> sentences = parse(data, metadata_parsers={
...    "tagset": lambda key, value: (key, value.split("|")),
...    "__fallback__": lambda key, value: ("sentence-id", key)
... })
>>> sentences[0].metadata
{
    'tagset': ['TAG1', 'TAG2', 'TAG3', 'TAG4'],
    'sentence-id': 'sentence-123'
}

正是我们想要的！__fallback__在其他元数据解析器都不匹配时被调用，和其他解析器一样，它接收当前行的键和值。在我们的例子中，该行不包含"="来分割，所以键将是"sentence-123"，值将为空。我们可以在这里返回任何想要的内容，但让我们假设我们想把这个字段称为"sentence-id"，所以我们返回它作为键，"sentence-123"作为值。

最后，考虑一个更棘手的情况。

>>> data = """
... # id=1-document_id=36:1047-span=1
... 1   My       TAG1|TAG2
... 2   custom   TAG3
... 3   format   TAG4
...
... """

这实际上是三个不同的注释，但它们用"-"分隔，而不是各占一行。为了处理这种情况，我们可以利用元数据解析器从单行返回多个匹配的能力。

>>> sentences = parse(data, metadata_parsers={
...    "__fallback__": lambda key, value: [pair.split("=") for pair in (key + "=" + value).split("-")]
... })
>>> sentences[0].metadata
{
    'id': '1',
    'document_id': '36:1047',
    'span': '1'
}

我们的fallback解析器返回一个匹配列表，每对元数据注释对应一个匹配。key + "=" + value技巧是必要的，因为默认情况下conllu假设这是一个有效的注释，所以key是"id"，value是第一个"="之后的所有内容，即1-document_id=36:1047-span=1（注意开头缺少"id="）。我们需要在用"-"分割之前把它加回去。

就是这样！使用这些技巧，你应该能够解析所有遇到的奇怪文件。

本地开发和运行测试

1. 在你自己的GitHub账户上fork这个仓库。

2. 在你的电脑上本地克隆仓库：

   git clone git@github.com:你的用户名/conllu.git conllu
   cd conllu

3. 安装用于运行测试的库：

   pip install tox

4. 现在你可以运行测试了：

   tox

   这会在所有支持的Python版本上运行tox，并且还会进行代码覆盖率检查、语法错误检查，以及导入排序检查。

5. （替代方案）如果你只安装了一个版本的Python，并且不想麻烦地安装多个版本的Python（提示：安装pyenv和pyenv-tox），用一个版本的Python运行tox也是可以的：

   tox -e py38

6. 提交一个拉取请求。这里有一个GitHub上关于PR的好指南。

感谢你帮助conllu成为一个更好的库！