Latest commit 26fee10 Nov 27, 2016 @kmike kmike bump version



This package provides Python interface to


pip install opencorpora-tools


Obtaining corpora

Opencorpora-tools works with XML from

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
>>> corpus.version

Access documents:

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

Work with Doc objects:

>>> doc = corpus[42]
>>> doc
<Doc id=44 tokens:2502 name='18801 Хитрость духа'>
'18801 Хитрость духа'
>>> doc.source
'Хитрость духа  Почему князь Владимир крестил Русь\n\n28 июля православная ...'
>>> doc.tags
['Автор:Олег Давыдов', 'Год:2010', 'Дата:28/07', 'url:', 'Тема:ЧасКор:Общество']
>>> 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.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.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.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


>>> 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 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.


OpenCorpora XML is huge (>250MB) so building full DOM tree requires a lot of memory (several GB, it coud be 10GB+ for full corpus). If RAM is not an issue opencorpora.load should be faster and more convenient; otherwise opencorpora.CorpusReader should work better.

opencorpora.CorpusReader handles it this way:

  1. corpus.get_document(doc_id) or corpus.documents(doc_ids) don't load the original XML to memory and don't parse the whole XML. They use precomputed offset information to slice the XML instead. The offset information is computed on first access and saved to "<name>.~" file.

    Consider document loading O(1) regarding full XML size. Individual documents are not huge so they and loaded and parsed as usual.

  2. There are iterator methods for all corpora API (corpus.iter_words, etc).


Development happens at github: Issue tracker: Feel free to submit ideas, bugs or pull requests.

Running tests

Make sure tox is installed and run

$ tox

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