opencorpora-tools 0.5

Obtaining corpora

Opencorpora-tools works with XML from http://opencorpora.org/.

You can download and unpack the XML manually (from ‘Downloads’ page) or just use the provided command-line util:

$ opencorpora download

Run opencorpora download --help for more options.

Using corpora

opencorpora-tools package provides two entirely different APIs for working with OpenCorpora XML files:

• opencorpora.load - loads XML in memory using lxml library and uses lxml custom Element classes to provide a nice API. Note that the full OpenCorpora XML corpus can take up to 10GB RAM.

• opencorpora.CorpusReader - it is slower and likely less convenient, but it allows to avoid loading the whole XML in memory. It also doesn’t depend on lxml.

opencorpora.load API

First, load corpus to memory:

>>> import opencorpora
>>> corpus = opencorpora.load('annot.opcorpora.xml')
>>> corpus
<Corpus revision=4213997 docs:3489 tokens:1740169>
>>> corpus.revision
'4213997'
>>> corpus.version
'0.12'

Access documents:

>>> len(corpus.docs)
3489
>>> corpus.docs[42]
<Doc id=44 tokens:2502 name='18801 Хитрость духа'>
>>> corpus[42]   # it is the same as corpus.docs[42]
<Doc id=44 tokens:2502 name='18801 Хитрость духа'>

Sentences, paragraphs and tokens can be accessed directly:

>>> corpus.sentences[0]
<Sentence id=1 source='«Школа злословия» учит прикусить язык'>
>>> corpus.paragraphs[0]
<Paragraph id=1 source='«Школа злословия» учит прикусить язык  Сохранится ли градус дискуссии в новом сезоне?'>
>>> len(corpus.tokens)
1740169

Work with Doc objects:

>>> doc = corpus[42]
>>> doc
<Doc id=44 tokens:2502 name='18801 Хитрость духа'>
>>> doc.id
'44'
>>> doc.name
'18801 Хитрость духа'
>>> doc.source
'Хитрость духа  Почему князь Владимир крестил Русь\n\n28 июля православная ...'
>>> doc.tags
['Автор:Олег Давыдов', 'Год:2010', 'Дата:28/07', 'url:http://www.chaskor.ru/article/28_iyulyahitrost_duha_18801', 'Тема:ЧасКор:Общество']
>>> doc.paragraphs
[<Paragraph id=1176 source='Хитрость духа  Почему князь Владимир крестил Русь'>, ...]
>>> doc.sentences
[<Sentence id=3433 source='Хитрость духа'>,
 <Sentence id=3434 source='Почему князь Владимир крестил Русь'>,
 ...
]
>>> doc.tokens
[<Token id=64838 source='Хитрость'>, <Token id=64839 source='духа'>, ...]
>>> doc[0]  # the same as doc.tokens[0]
<Token id=64838 source='Хитрость'>

Paragraph objects:

>>> para = doc.paragraphs[0]
>>> para.id
'1176'
>>> para.source
'Хитрость духа  Почему князь Владимир крестил Русь'
>>> para.sentences
[<Sentence id=3433 source='Хитрость духа'>, <Sentence id=3434 source='Почему князь Владимир крестил Русь'>]
>>> para.tokens
[<Token id=64838 source='Хитрость'>, <Token id=64839 source='духа'>, ...]
>>> para[0]  # the same as para.tokens[0]
<Token id=64838 source='Хитрость'>

Sentence objects:

>>> sent = doc.sentences[6]
>>> sent
<Sentence id=3439 source='У князя Святослава Игоревича было три сына: Ярополк, Олег и Владимир.'>
>>> sent.id
'3439'
>>> sent.source
'У князя Святослава Игоревича было три сына: Ярополк, Олег и Владимир.'
>>> sent.tokens
[<Token id=64912 source='У'>, <Token id=64913 source='князя'>, <Token id=64914 source='Святослава'>, ...]
>>> sent[1]  # the same as sent.tokens[1]
<Token id=64913 source='князя'>

Token objects:

>>> token = sent[1]
>>> token
<Token id=64913 source='князя'>
>>> token.id
'64913'
>>> token.source
'князя'
>>> token.parses
[<Parse id=134923 lemma=князь grammemes=['NOUN', 'anim', 'masc', 'sing', 'gent']>,
 <Parse id=134923 lemma=князь grammemes=['NOUN', 'anim', 'masc', 'sing', 'accs']>]
>>> token.lemma  # lemma of a first parse, the same as token.parses[0].lemma
'князь'
>>> token.grammemes  # the same as token.parses[0].grammemes
['NOUN', 'anim', 'masc', 'sing', 'gent']
>>> token.parse  # the same as token.parses[0]
<Parse id=134923 lemma=князь grammemes=['NOUN', 'anim', 'masc', 'sing', 'gent']>

Corpus, Doc, Paragraph, Sentence, Token and Parse are custom etree Element subclasses. You’re not limited to the API described above - e.g. it is possible to process corpus using XPath expressions, and lxml will return these custom Element classes in results if a tree is loaded using opencorpora.load.

opencorpora.CorpusReader API

Initialize:

>>> import opencorpora
>>> corpus = opencorpora.CorpusReader('annot.opcorpora.xml')

Get table of contents:

>>> corpus.catalog()
[('1', '"Частный корреспондент"'),
 ('2', '00021 Школа злословия'),
 ('3', '00022 Последнее восстание в Сеуле'),
 ('4', '00023 За кота - ответишь!'),
...

Work with documents:

>>> seoul_words = corpus.words('3')
>>> seoul_words
['«', 'Последнее', 'восстание', '»', 'в', 'Сеуле', ...

>>> corpus.documents(categories='Тема:ЧасКор:Книги*')
[Document: 21759 2001-2010-й: книги, которые потрясали,
 Document: 12824 86 снов, вызванных полётом пчелы вокруг граната за секунду до пробуждения,
 Document: 10930 А бойтесь единственно только того, кто скажет: «Я знаю, как надо!»,
 ...

opencorpora.Corpora is modelled after NLTK’s CorpusReader interface; consult with http://nltk.googlecode.com/svn/trunk/doc/book/ch02.html to get an idea how to work with the API. It it not exactly the same, but should be very similar.

Currently CorposReader doesn’t provide a way to access original OpenCorpora ids of paragraphs/sentences/tokens.

Running tests

Make sure tox is installed and run

$ tox

from the source checkout. Tests should pass under Python 2.7 and 3.3+.