poetree 0.0.1__tar.gz

poetree-0.0.1/LICENSE.txt

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2021 Petr Plechac
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poetree-0.0.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.1
+Name: poetree
+Version: 0.0.1
+Summary: An easy way to get data from PoeTree dataset
+Home-page: https://github.com/versotym/poetree
+Download-URL: https://github.com/versotym/poetree/archive/v0.0.1.tar.gz
+Author: Petr Plechac
+Author-email: plechac@ucl.cas.cz
+License: MIT
+Keywords: poetry,corpus,versification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.1
+Classifier: Programming Language :: Python :: 3.2
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+# poetree
+Poetree library provides an easy way to get data from PoeTree API.
+
+[PoeTree](https://versologie.cz/poetree) is a standardized collection of poetry corpora comprising over 330,000 poems in ten languages (Czech, English, French, German, Hungarian, Italian, Portuguese, Russian, Slovenian and Spanish). Each corpus has been deduplicated, enriched with Universal Dependencies, provided with additional metadata and converted into a unified JSON structure.
+
+## Install
+```console
+pip install poetree
+```
+or
+```console
+pip3 install poetree
+```
+
+## Usage
+```python
+import poetree
+```
+
+There are five classes available:
+- ```Poetree``` represents the entire PoeTree collection [\[documentation\]](https://versologie.cz/poetree/python-doc/poetree)
+- ```Corpus``` represents single corpus [\[documentation\]](https://versologie.cz/poetree/python-doc/corpus)
+- ```Author``` represents single author [\[documentation\]](https://versologie.cz/poetree/python-doc/author)
+- ```Source``` represents single book [\[documentation\]](https://versologie.cz/poetree/python-doc/source)
+- ```Poem``` represents single poem [\[documentation\]](https://versologie.cz/poetree/python-doc/poem)
+
+Each class has properties corresponding to the keys returned by API. To get for instance the number of authors and the number of poems in PoeTree.cs:
+
+```python
+corpus = poetree.Corpus('cs')
+print('number of authors:', corpus.n_authors)
+print('number of poems:', corpus.n_poems)
+```
+```console
+number of authors: 606
+number of poems: 80229
+```
+
+###  get_corpora(), get_authors(), get_sources(), get_poems()
+Class instance may be created directly (as in the example above) or one may use a more general class to create a number of children instances by means of ```get_[something]()``` methods. To get for instance all the authors in PoeTree.en born between 1750 and 1760:
+
+```python
+corpus = poetree.Corpus('en')
+for author in corpus.get_authors(born_after=1750, born_before=1760):
+    print(f'{author.name} ({author.born})')
+```
+```console
+Barlow, Joel (1754)
+Blake, William (1757)
+Crabbe, George (1754)
+Freneau, Philip Morin (1752)
+Roberts, David (1757)
+Wheatley, Phillis (1753)
+```
+
+Analogous methods in other classes are as follow:
+
+<img src="https://versologie.cz/poetree/img/classes.png" style="width:300px;"/>
+
+Objects created by ```get_[something]()``` are also stored in their parent object's property ```data_[something]``` for later use:
+
+```python
+corpus = poetree.Corpus('en')
+corpus.get_authors(born_after=1750, born_before=1760)
+print([x.name for x in corpus.content_['authors']])
+```
+```console
+['Barlow, Joel', 'Blake, William', 'Crabbe, George', 'Freneau, Philip Morin', 'Roberts, David', 'Wheatley, Phillis']
+```
+
+To iterate over all corpora, over all authors, over all their poems:
+```python
+pt = poetree.Poetree()
+for corpus in pt.get_corpora():
+    for author in corpus.get_authors():
+        for poem in author.get_poems():
+            # Do stuff...
+```
+
+### metadata()
+Each class provides```metadata()``` method. By default it gives access to all metadata properties of the class:
+
+```python
+corpus = poetree.Corpus('de')
+metadata = corpus.metadata(output='pandas')
+print(metadata)
+```
+```console
+  corpus                                               desc  n_authors  n_poems  n_lines  n_types  n_tokens
+0     de  Compiled by Klemens Bobenhausen and Benjamin H...        245    53133  1701234   678426  12482485
+```
+
+It can also be used to get metadata of all children instances it created using the ```target``` attribute:
+```python
+corpus = poetree.Corpus('pt')
+corpus.get_authors()
+df = corpus.metadata(target='authors', output='pandas') 
+print(df)
+```
+```console
+    id_                                     name                    viaf       wiki country  born  died  n_poems corpus
+0    20                      Alberto de Oliveira                29092555   Q1789301      br  1857  1937        1     pt
+1     6                   Antônio Gonçalves Dias                73988798    Q611997      br  1823  1864       15     pt
+2     1  Augusto de Carvalho Rodrigues dos Anjos                44342515    Q769887      br  1884  1914      306     pt
+3    11                          Basílio da Gama                84492428   Q1789371      pt  1740  1795        6     pt
+4     4                  Cláudio Manuel da Costa                41967264   Q1789904      br  1729  1789      190     pt
+5    25               Delminda Silveira de Sousa                99136109  Q10264874      br  1854  1932      548     pt
+6     8          Emílio Nunes Correia de Meneses                71253555  Q10272640      br  1866  1918       90     pt
+7    17               Francisco de Sá de Meneses                32338601   Q4403329      pt  1600  1664       12     pt
+8    15                   Gonçalves de Magalhães                88876973   Q2532628      br  1811  1882       56     pt
+9    16                 Gregório de Matos Guerra               122323020    Q983565      br  1636  1696      704     pt
+10   13                Gustavo de Paula Teixeira                60882245  Q10293150      br  1881  1937      122     pt
+11   23               José Pedro Xavier Pinheiro               121971768  Q15631816      br  1822  1882      100     pt
+12   14          José Joaquim Correia de Almeida                50626334  Q25859802      br  1820  1905      953     pt
+13    7                 José de Santa Rita Durão   730145601965601320827   Q6958165      br  1722  1784       10     pt
+14    5                     João da Cruz e Sousa                 4972695   Q2609059      br  1861  1898      407     pt
+15   10             Juvêncio de Araújo Figueredo  4738150325583310090002  Q10313264      br  1865  1927      438     pt
+16   24            Laurindo José da Silva Rabelo    65149066775765602956   Q6501838      br  1826  1864      184     pt
+17    9             Luís Nicolau Fagundes Varela                24730690   Q2088965      br  1841  1875      215     pt
+18    3                       Luís Vaz de Camões                34454091       Q590      pt  1524  1580       10     pt
+19    2  Manuel Maria Barbosa l'Hedois du Bocage                66536132    Q630116      pt  1765  1805      146     pt
+20   18             Múcio Scevola Lopes Teixeira                11159986  Q10334840      br  1857  1926       86     pt
+21   19             Nicolau Tolentino de Almeida                54191676    Q740967      pt  1740  1811      244     pt
+22   21   Olavo Brás Martins dos Guimarães Bilac                73898176    Q982354      br  1865  1918       75     pt
+23   22    Sebastião Cícero dos Guimarães Passos                25942646  Q10292895      br  1867  1909       75     pt
+24   12                    Tomás Antônio Gonzaga                19760014   Q1334602      br  1744  1810      110     pt
+```
+
+### get_body(), get_all()
+
+When ```Poem``` instance is created, only its metadata are fetched from API. To get the body (lines, words and their annotation) one needs to call ```get_body()``` method first.
+
+```python
+poem = poetree.Poem(id_=1, lang='cs')
+body = poem.get_body()
+print(body[0])
+```
+```console
+{'id_': 1, 'id': 0, 'id_stanza': 1, 'text': 'Tvá loď jde po vysokém moři,', 'part': False, 'words': [{'id_': 1, 'id': 1, 'id_sentence': 1, 'head': 2, 'deprel': 'det', 'form': 'Tvá', 'lemma': 'tvůj', 'upos': 'DET', 'xpos': 'PSFS1-S1------1', 'feats': 'Case=Nom|Gender=Fem|Number=Sing|PronType=Dem'}, {'id_': 2, 'id': 2, 'id_sentence': 1, 'head': 3, 'deprel': 'nsubj', 'form': 'loď', 'lemma': 'loď', 'upos': 'NOUN', 'xpos': 'NNFS1-----A----', 'feats': 'Case=Nom|Gender=Fem|Number=Sing|Polarity=Pos'}, {'id_': 3, 'id': 3, 'id_sentence': 1, 'head': 0, 'deprel': 'root', 'form': 'jde', 'lemma': 'jít', 'upos': 'VERB', 'xpos': 'VB-S---3P-AA---', 'feats': 'Mood=Ind|Number=Sing|Person=3|Polarity=Pos|Tense=Pres|VerbForm=Fin|Voice=Act'}, {'id_': 4, 'id': 4, 'id_sentence': 1, 'head': 6, 'deprel': 'case', 'form': 'po', 'lemma': 'po', 'upos': 'ADP', 'xpos': 'RR--6----------', 'feats': 'AdpType=Prep|Case=Loc'}, {'id_': 5, 'id': 5, 'id_sentence': 1, 'head': 6, 'deprel': 'amod', 'form': 'vysokém', 'lemma': 'vysoký', 'upos': 'ADJ', 'xpos': 'AANS6----1A----', 'feats': 'Case=Loc|Degree=Pos|Gender=Neut|Number=Sing|Polarity=Pos'}, {'id_': 6, 'id': 6, 'id_sentence': 1, 'head': 3, 'deprel': 'obl', 'form': 'moři', 'lemma': 'moře', 'upos': 'NOUN', 'xpos': 'NNNS6-----A----', 'feats': 'Case=Loc|Gender=Neut|Number=Sing|Polarity=Pos'}, {'id_': 7, 'id': 7, 'id_sentence': 1, 'head': 9, 'deprel': 'punct', 'form': ',', 'lemma': ',', 'upos': 'PUNCT', 'xpos': 'Z:-------------', 'feats': '_'}]}
+```
+
+To retrieve both the metadata and the body of the poem at the same time, there is a method ```get_all()```
+
+```python
+poem = poetree.Poem(id_=1, lang='cs')
+metadata_and_body = poem.get_all()
+```

poetree-0.0.1/README.md

@@ -0,0 +1,147 @@
+# poetree
+Poetree library provides an easy way to get data from PoeTree API.
+
+[PoeTree](https://versologie.cz/poetree) is a standardized collection of poetry corpora comprising over 330,000 poems in ten languages (Czech, English, French, German, Hungarian, Italian, Portuguese, Russian, Slovenian and Spanish). Each corpus has been deduplicated, enriched with Universal Dependencies, provided with additional metadata and converted into a unified JSON structure.
+
+## Install
+```console
+pip install poetree
+```
+or
+```console
+pip3 install poetree
+```
+
+## Usage
+```python
+import poetree
+```
+
+There are five classes available:
+- ```Poetree``` represents the entire PoeTree collection [\[documentation\]](https://versologie.cz/poetree/python-doc/poetree)
+- ```Corpus``` represents single corpus [\[documentation\]](https://versologie.cz/poetree/python-doc/corpus)
+- ```Author``` represents single author [\[documentation\]](https://versologie.cz/poetree/python-doc/author)
+- ```Source``` represents single book [\[documentation\]](https://versologie.cz/poetree/python-doc/source)
+- ```Poem``` represents single poem [\[documentation\]](https://versologie.cz/poetree/python-doc/poem)
+
+Each class has properties corresponding to the keys returned by API. To get for instance the number of authors and the number of poems in PoeTree.cs:
+
+```python
+corpus = poetree.Corpus('cs')
+print('number of authors:', corpus.n_authors)
+print('number of poems:', corpus.n_poems)
+```
+```console
+number of authors: 606
+number of poems: 80229
+```
+
+###  get_corpora(), get_authors(), get_sources(), get_poems()
+Class instance may be created directly (as in the example above) or one may use a more general class to create a number of children instances by means of ```get_[something]()``` methods. To get for instance all the authors in PoeTree.en born between 1750 and 1760:
+
+```python
+corpus = poetree.Corpus('en')
+for author in corpus.get_authors(born_after=1750, born_before=1760):
+    print(f'{author.name} ({author.born})')
+```
+```console
+Barlow, Joel (1754)
+Blake, William (1757)
+Crabbe, George (1754)
+Freneau, Philip Morin (1752)
+Roberts, David (1757)
+Wheatley, Phillis (1753)
+```
+
+Analogous methods in other classes are as follow:
+
+<img src="https://versologie.cz/poetree/img/classes.png" style="width:300px;"/>
+
+Objects created by ```get_[something]()``` are also stored in their parent object's property ```data_[something]``` for later use:
+
+```python
+corpus = poetree.Corpus('en')
+corpus.get_authors(born_after=1750, born_before=1760)
+print([x.name for x in corpus.content_['authors']])
+```
+```console
+['Barlow, Joel', 'Blake, William', 'Crabbe, George', 'Freneau, Philip Morin', 'Roberts, David', 'Wheatley, Phillis']
+```
+
+To iterate over all corpora, over all authors, over all their poems:
+```python
+pt = poetree.Poetree()
+for corpus in pt.get_corpora():
+    for author in corpus.get_authors():
+        for poem in author.get_poems():
+            # Do stuff...
+```
+
+### metadata()
+Each class provides```metadata()``` method. By default it gives access to all metadata properties of the class:
+
+```python
+corpus = poetree.Corpus('de')
+metadata = corpus.metadata(output='pandas')
+print(metadata)
+```
+```console
+  corpus                                               desc  n_authors  n_poems  n_lines  n_types  n_tokens
+0     de  Compiled by Klemens Bobenhausen and Benjamin H...        245    53133  1701234   678426  12482485
+```
+
+It can also be used to get metadata of all children instances it created using the ```target``` attribute:
+```python
+corpus = poetree.Corpus('pt')
+corpus.get_authors()
+df = corpus.metadata(target='authors', output='pandas') 
+print(df)
+```
+```console
+    id_                                     name                    viaf       wiki country  born  died  n_poems corpus
+0    20                      Alberto de Oliveira                29092555   Q1789301      br  1857  1937        1     pt
+1     6                   Antônio Gonçalves Dias                73988798    Q611997      br  1823  1864       15     pt
+2     1  Augusto de Carvalho Rodrigues dos Anjos                44342515    Q769887      br  1884  1914      306     pt
+3    11                          Basílio da Gama                84492428   Q1789371      pt  1740  1795        6     pt
+4     4                  Cláudio Manuel da Costa                41967264   Q1789904      br  1729  1789      190     pt
+5    25               Delminda Silveira de Sousa                99136109  Q10264874      br  1854  1932      548     pt
+6     8          Emílio Nunes Correia de Meneses                71253555  Q10272640      br  1866  1918       90     pt
+7    17               Francisco de Sá de Meneses                32338601   Q4403329      pt  1600  1664       12     pt
+8    15                   Gonçalves de Magalhães                88876973   Q2532628      br  1811  1882       56     pt
+9    16                 Gregório de Matos Guerra               122323020    Q983565      br  1636  1696      704     pt
+10   13                Gustavo de Paula Teixeira                60882245  Q10293150      br  1881  1937      122     pt
+11   23               José Pedro Xavier Pinheiro               121971768  Q15631816      br  1822  1882      100     pt
+12   14          José Joaquim Correia de Almeida                50626334  Q25859802      br  1820  1905      953     pt
+13    7                 José de Santa Rita Durão   730145601965601320827   Q6958165      br  1722  1784       10     pt
+14    5                     João da Cruz e Sousa                 4972695   Q2609059      br  1861  1898      407     pt
+15   10             Juvêncio de Araújo Figueredo  4738150325583310090002  Q10313264      br  1865  1927      438     pt
+16   24            Laurindo José da Silva Rabelo    65149066775765602956   Q6501838      br  1826  1864      184     pt
+17    9             Luís Nicolau Fagundes Varela                24730690   Q2088965      br  1841  1875      215     pt
+18    3                       Luís Vaz de Camões                34454091       Q590      pt  1524  1580       10     pt
+19    2  Manuel Maria Barbosa l'Hedois du Bocage                66536132    Q630116      pt  1765  1805      146     pt
+20   18             Múcio Scevola Lopes Teixeira                11159986  Q10334840      br  1857  1926       86     pt
+21   19             Nicolau Tolentino de Almeida                54191676    Q740967      pt  1740  1811      244     pt
+22   21   Olavo Brás Martins dos Guimarães Bilac                73898176    Q982354      br  1865  1918       75     pt
+23   22    Sebastião Cícero dos Guimarães Passos                25942646  Q10292895      br  1867  1909       75     pt
+24   12                    Tomás Antônio Gonzaga                19760014   Q1334602      br  1744  1810      110     pt
+```
+
+### get_body(), get_all()
+
+When ```Poem``` instance is created, only its metadata are fetched from API. To get the body (lines, words and their annotation) one needs to call ```get_body()``` method first.
+
+```python
+poem = poetree.Poem(id_=1, lang='cs')
+body = poem.get_body()
+print(body[0])
+```
+```console
+{'id_': 1, 'id': 0, 'id_stanza': 1, 'text': 'Tvá loď jde po vysokém moři,', 'part': False, 'words': [{'id_': 1, 'id': 1, 'id_sentence': 1, 'head': 2, 'deprel': 'det', 'form': 'Tvá', 'lemma': 'tvůj', 'upos': 'DET', 'xpos': 'PSFS1-S1------1', 'feats': 'Case=Nom|Gender=Fem|Number=Sing|PronType=Dem'}, {'id_': 2, 'id': 2, 'id_sentence': 1, 'head': 3, 'deprel': 'nsubj', 'form': 'loď', 'lemma': 'loď', 'upos': 'NOUN', 'xpos': 'NNFS1-----A----', 'feats': 'Case=Nom|Gender=Fem|Number=Sing|Polarity=Pos'}, {'id_': 3, 'id': 3, 'id_sentence': 1, 'head': 0, 'deprel': 'root', 'form': 'jde', 'lemma': 'jít', 'upos': 'VERB', 'xpos': 'VB-S---3P-AA---', 'feats': 'Mood=Ind|Number=Sing|Person=3|Polarity=Pos|Tense=Pres|VerbForm=Fin|Voice=Act'}, {'id_': 4, 'id': 4, 'id_sentence': 1, 'head': 6, 'deprel': 'case', 'form': 'po', 'lemma': 'po', 'upos': 'ADP', 'xpos': 'RR--6----------', 'feats': 'AdpType=Prep|Case=Loc'}, {'id_': 5, 'id': 5, 'id_sentence': 1, 'head': 6, 'deprel': 'amod', 'form': 'vysokém', 'lemma': 'vysoký', 'upos': 'ADJ', 'xpos': 'AANS6----1A----', 'feats': 'Case=Loc|Degree=Pos|Gender=Neut|Number=Sing|Polarity=Pos'}, {'id_': 6, 'id': 6, 'id_sentence': 1, 'head': 3, 'deprel': 'obl', 'form': 'moři', 'lemma': 'moře', 'upos': 'NOUN', 'xpos': 'NNNS6-----A----', 'feats': 'Case=Loc|Gender=Neut|Number=Sing|Polarity=Pos'}, {'id_': 7, 'id': 7, 'id_sentence': 1, 'head': 9, 'deprel': 'punct', 'form': ',', 'lemma': ',', 'upos': 'PUNCT', 'xpos': 'Z:-------------', 'feats': '_'}]}
+```
+
+To retrieve both the metadata and the body of the poem at the same time, there is a method ```get_all()```
+
+```python
+poem = poetree.Poem(id_=1, lang='cs')
+metadata_and_body = poem.get_all()
+```

poetree-0.0.1/poetree/__init__.py

@@ -0,0 +1,6 @@
+
+from poetree.main   import Poetree
+from poetree.corpus import Corpus
+from poetree.author import Author
+from poetree.source import Source
+from poetree.poem   import Poem

poetree-0.0.1/poetree/author.py

@@ -0,0 +1,166 @@
+from typing import Union
+import pandas as pd
+from .config import BASE_URL
+from .glob import make_request, metadata, get_content
+from .source import Source
+from .poem import Poem
+
+
+class Author:
+    '''
+    Class corresponding to a particular author.
+    '''
+
+    def __init__(
+            self, 
+            lang     : Union[None,str] = None, 
+            base_url : str             = BASE_URL, 
+            id_      : Union[None,int] = None,
+            wiki     : Union[None,str] = None, 
+            viaf     : Union[None,str] = None,
+            metadata : dict            = None 
+        ):
+        '''
+        Store author metadata (if initialized by Poetree instance) or get them 
+        from API (if initialized directly). Create empty dict self.content_ 
+        that will hold lists of Source and Poem instances.
+
+        Arguments:
+            lang     (str|None)  : ISO code of the corpus, required if initialized directly 
+            base_url (str)       : API base URL (default: set in config.py)
+            id_      (int|None)  : Id(DB) of the author
+            wiki     (str|None)  : Wiki id of the author
+            viaf     (str|None)  : Viaf id of the author
+            metadata (dict|None) : Author metadata passed when initialized by Poetree instance
+        
+        Raises:
+            ValueError : If neither [metadata] nor [lang] is passed
+                       : If neither [metadata] nor one of [id_, wiki, viaf] is passed
+
+        Returns:
+            None    
+        '''
+        self.base_url = base_url
+        self.content_ = dict()
+
+        if metadata is not None:
+            self.metadata_ = metadata
+        elif lang is None:
+            raise ValueError (
+                'Argument [lang] is required when initializing ' +
+                f'{__class__.__name__} instance directly'
+            )
+        elif id_ is not None:
+            self._get_author_metadata(lang, 'id_author', id_)
+        elif wiki is not None:
+            self._get_author_metadata(lang, 'wiki', wiki)
+        elif viaf is not None:
+            self._get_author_metadata(lang, 'viaf', viaf)
+        else:
+            raise ValueError (
+                'One of the arguments [id_,wiki,viaf] is required when initializing ' +
+                f'{__class__.__name__} instance directly'
+            )
+        for k, v in self.metadata_.items(): setattr(self, k, v)
+
+
+    def _get_author_metadata(
+            self, 
+            lang    : str, 
+            id_type : str, 
+            id_val  : Union[int,str],
+        ):
+        '''
+        Get metadata on author and store them in self.metadata_
+        
+        Arguments:
+            lang    (str)     : ISO code of the corpus
+            id_type (str)     : Which identifier to use for retrueving author 
+            id_val  (int|str) : Identifier value
+        
+        Returns:
+            None      
+        '''
+        self.metadata_ = make_request(
+            self.base_url, 
+            'author',
+            **{'corpus': lang, id_type: id_val}
+        )
+        self.metadata_['corpus'] = lang
+        
+
+    def get_sources(self, **kwargs) -> list:
+        '''
+        Get metadata of sources by the author. Create a new Source instance 
+        for each source, store it in a list and return it.
+        
+        Arguments:
+            None
+        
+        Keyword arguments:
+            published_after  (int) : Limit to sources published no sooner than a given year
+            published_before (int) : Limit to sources published no later than a given year
+        
+        Returns:
+            (list) : List holding instances of Source      
+        '''
+        self.content_['sources'] = get_content(
+            self.base_url, 'sources', Source, 
+            corpus = self.metadata_['corpus'], 
+            id_author = self.metadata_['id_'],
+            **kwargs
+        )
+        return self.content_['sources']         
+    
+
+    def get_poems(self, **kwargs) -> list:
+        '''
+        Get metadata of poems by the author. Create a new Poem instance 
+        for each poem, store it in a list and return it.
+        
+        Arguments:
+            None
+        
+        Keyword arguments:
+            id_source  (int) : Limit to poems from certain source
+        
+        Returns:
+            (list) : List holding instances of Poem      
+        '''
+        self.content_['poems'] = get_content(
+            self.base_url, 'poems', Poem, 
+            corpus = self.metadata_['corpus'], 
+            id_author = self.metadata_['id_'],
+            **kwargs
+        )
+        return self.content_['poems']       
+    
+
+    def metadata(
+            self, 
+            target  : str             = 'self',
+            output  : str             = 'list', 
+            sortby  : Union[str,list] = None, 
+            reverse : bool            = False
+        ) -> Union[list, pd.DataFrame, None]:
+        '''
+        Returns targt metadata either as a formatted table (tabular=True)
+        or as a list as received from API (tabular=False). The list may be
+        sorted according to any subdict key.
+        
+        Params:
+            target  (str)      : Metadata of what to return; default: 'corpora'
+            output  (str)      : Output format: 'list': list as retrieved from API,
+                                 'pandas': pd.DataFrame, 'print': stringified table
+                                 printed directly; default: 'list'
+            sortby  (str|None) : Subdict key according to which sort the list;
+                                 default: None
+            reverse (bool)     : Sort in reversed (descending) order; default False   
+                              
+        Returns:
+            (list|pd.DataFrame|None) : metadata
+        '''
+        if target == 'self':
+            return metadata([self], output, sortby, reverse)    
+        else:
+            return metadata(self.content_[target], output, sortby, reverse)  

poetree-0.0.1/poetree/config.py

@@ -0,0 +1,2 @@
+
+BASE_URL = 'http://versologie.cz/poetree/api'

poetree-0.0.1/poetree/corpus.py

@@ -0,0 +1,142 @@
+from typing import Union
+import pandas as pd
+from .config import BASE_URL
+from .glob import make_request, metadata, get_content
+from .author import Author
+from .source import Source
+
+
+class Corpus:
+    '''
+    Class corresponding to a particular corpus.
+    '''
+
+    def __init__(
+            self, 
+            lang     : Union[str,None]  = None,
+            base_url : str              = BASE_URL, 
+            metadata : Union[dict,None] = None 
+        ):
+        '''
+        Store corpus metadata (if initialized by Poetree instance) or get them 
+        from API (if initialized directly). Create empty dict self.content_
+        that will hold lists of Author and Source instances.
+        
+        Arguments:
+            lang     (str|None)  : ISO code of the corpus, required if initialized directly 
+            base_url (str)       : API base URL (default: set in config.py)
+            metadata (dict|None) : Corpus metadata passed when initialized by Poetree instance
+        
+        Raises:
+            ValueError : If neither [metadata] nor [lang] is passed
+        
+        Returns:
+            None       
+        '''
+        self.base_url = base_url
+        self.content_ = dict()
+        if metadata is not None:
+            self.metadata_ = metadata
+        elif lang is not None:
+            self._get_corpus_metadata(lang)
+        else:
+            raise ValueError (
+                'Argument [lang] is required when initializing ' +
+                f'{__class__.__name__} instance directly'
+            )
+        for k, v in self.metadata_.items(): setattr(self, k, v)
+
+
+    def _get_corpus_metadata(self, lang:str):
+        '''
+        Get metadata on corpus and store them in self.metadata_
+        
+        Arguments:
+            lang (str) : Language of the corpus (ISO code)
+        
+        Returns:
+            None      
+        '''
+        self.metadata_ = make_request(self.base_url, 'corpus', corpus=lang)
+        self.metadata_['corpus'] = lang
+
+
+    def get_authors(self, **kwargs) -> list:
+        '''
+        Get metadata of all available authors. Create a new Author instance for
+        each author, store it in a list and return it.
+        
+        Arguments:
+            None
+        
+        Keyword arguments:
+            country     (str) : Limit to authors from certain countries. Either a single 
+                                value (country="pt") or stringified list (country="pt,br")
+            born_after  (int) : Limit to authors born no sooner than a given year
+            born_before (int) : Limit to authors born no later than a given year
+            died_after  (int) : Limit to authors that died no sooner than a given year
+            died_before (int) : Limit to authors that died no later than a given year
+        
+        Returns:
+            (list) : List holding instances of Author     
+        '''
+        if 'country' in kwargs and not isinstance(kwargs['country'], list):
+            kwargs['country'] = ','.join(kwargs['country'])
+        self.content_['authors'] = get_content(
+            self.base_url, 'authors', Author, corpus=self.metadata_['corpus'], **kwargs
+        )
+        return self.content_['authors']
+    
+
+    def get_sources(self, **kwargs) -> list:
+        '''
+        Get metadata of all available sources. Create a new Source instance 
+        for each source, store it in a list and return it.
+        
+        Arguments:
+            None
+        
+        Keyword arguments:
+            id_author        (int) : Limit to sources by author with this id(DB)
+            wiki             (str) : Limit to sources by author with this wiki id
+            viaf             (str) : Limit to sources by author with this viaf id
+            published_after  (int) : Limit to sources published no sooner than a given year
+            published_before (int) : Limit to sources published no later than a given year
+        
+        Returns:
+            (list) : List holding instances of Source      
+        '''
+        self.content_['sources'] = get_content(
+            self.base_url, 'sources', Source, corpus=self.metadata_['corpus'], **kwargs
+        )
+        return self.content_['sources']
+
+
+    def metadata(
+            self, 
+            target  : str             = 'self',
+            output  : str             = 'list', 
+            sortby  : Union[str,list] = None, 
+            reverse : bool            = False
+        ) -> Union[list, pd.DataFrame, None]:
+        '''
+        Returns targt metadata either as a formatted table (tabular=True)
+        or as a list as received from API (tabular=False). The list may be
+        sorted according to any subdict key.
+        
+        Params:
+            target  (str)      : Metadata of what to return; default: 'self'
+            output  (str)      : Output format: 'list': list as retrieved from API,
+                                 'pandas': pd.DataFrame, 'print': stringified table
+                                 printed directly; default: 'list'
+            sortby  (str|None) : Subdict key according to which sort the list;
+                                 default: None
+            reverse (bool)     : Sort in reversed (descending) order; default False   
+                              
+        Returns:
+            (list|pd.DataFrame|None) : metadata
+        '''
+        if target == 'self':
+            return metadata([self], output, sortby, reverse)    
+        else:
+            return metadata(self.content_[target], output, sortby, reverse)