Metadata-Version: 2.1
Name: pydracor
Version: 2.0.0
Summary: Python package which provides access to the DraCor API.
Home-page: https://github.com/dracor-org/pydracor
Author: Eduard Grigoriev, Henny Sluyter-Gäthje
Author-email: sluytergaeth@uni-potsdam.de, happypuffin7@gmail.com
License: mit
Keywords: drama corpus,drama,corpus,pydracor,dracor,api,wrapper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: requests>=2.28.2

# pydracor

pydracor is a Python package which provides access to the [DraCor API](https://dracor.org/doc/api/).

## Acknowledgment:

The development of this package was supported by Computational Literary Studies Infrastructure (CLS INFRA). CLS INFRA has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 101004984.

## Classes
  - *DraCor*
    > Base class used to represent Drama Corpus entity.
    > DraCor consists of Corpora.
  - *Corpus*
    > A class used to represent a Corpus of DraCor.
    > Corpus (*als*/*bash*/*cal*/*fre*/*ger*/*gersh*/*greek*/*hun*/*ita*/*rom*/*rus*/*shake*/*span*/*swe*/*tat*) consists of plays.
  - *Play*
    > A class used to represent a Play of a Corpus.
    > Play consists of Characters.
  - *Character*
    > A class used to represent a Character of a Play.

## Code examples

### Import all classes

```python
>>> from pydracor import *
```

### Dracor
  - Initialize a *DraCor* instance
    ```python
    >>> dracor = DraCor()
    ```
  - Summary in a dictionary
    ```python
    >>> dracor.summary()
    ```
  - Summary in a string
    ```python
    >>> str(dracor)
    ```
  - DraCor info in a dictionary
    ```python
    >>> dracor.dracor_info()
    ```
  - List available corpora in DraCor
    ```python
    >>> dracor.corpora()
    >>> dracor.corpora(include='metrics')
    ```
  - List available corpora names in DraCor
    ```python
    >>> dracor.corpora_names()
    ```
  - List available corpora titles in DraCor
    ```python
    >>> dracor.corpora_titles()
    ```
  - Map X to Y
    ```python
    >>> dracor.corpus_name_to_repository()
    >>> dracor.corpus_name_to_title()
    >>> dracor.corpus_name_to_uri()
    >>> dracor.play_title_to_corpus_name()
    >>> dracor.play_title_to_play_id()
    >>> dracor.play_name_to_corpus_name()
    >>> dracor.play_name_to_play_id()
    >>> dracor.play_id_to_play_title()
    >>> dracor.play_id_to_play_name()
    ```
  - Submit SPARQL queries with query parameter
    ```python
    >>> dracor.sparql("PREFIX urn: <http://fliqz.com/> SELECT *  FROM <urn:x-arq:UnionGraph> WHERE {?sub ?pred ?obj .} LIMIT 1")
    ```
### Corpus
  - Initialize a *Corpus* instance
    ```python
    >>> corpus = Corpus('rus')
    >>> corpus = Corpus('cal')
    ...
    ```
  - Summary in a dictionary
    ```python
    >>> corpus.summary()
    ```
  - Summary in a string
    ```python
    >>> str(corpus)
    ```
  - Authors' summary for a corpus
    ```python
    >>> corpus.authors_summary()
    >>> corpus.authors_summary(num_of_authors=5)
    ```
  - String representation of authors_summary method
    ```python
    >>> corpus.authors_summary_str()
    >>> corpus.authors_summary_str(num_of_authors=5)
    ```
  - Corpus info in a dictionary
    ```python
    >>> corpus.corpus_info()
    ```
  - Get all corpus' play Xs
    ```python
    >>> corpus.play_ids()
    >>> corpus.play_names()
    >>> corpus.play_titles()
    ```
  - Map play id to the X year
    ```python
    >>> corpus.years_written()
    >>> corpus.years_premiered()
    >>> corpus.years_normalized()
    ```
  - List of metadata for all plays in a corpus
    ```python
    >>> corpus.metadata()
    ```
  - Filter Plays of a Corpus

    Filters are equivalent to the django filters

    Possible relations: *eq* / *ne* / *gt* / *ge* / *lt* / *le* / *contains* / *icontains* / *exact* / *iexact* / *in*

    Possible fields: all the attributes that the *Corpus* instance contains
    ```python
    >>> corpus.filter(year_written__eq=1913, network_size__lt=20)
    >>> corpus.filter(year_printed__lt=1850, source__icontains='lib.ru', year_premiered__gt=1845)
    >>> corpus.filter(
        id__in=frozenset(f"rus000{num:03d}" for num in range(0, 250, 2)),
        subtitle__icontains='комедия',
        author__name__contains='Крылов'
    )
    >>> corpus.filter(name__contains='mysl')
    >>> corpus.filter(title__exact='Мысль')
    >>> corpus.filter(
        year_normalized__in=frozenset(['1935', '1936'])
        source_url__contains='lib'
    )
    >>> corpus.filter(wikidata_id__iexact='Q1989636')
    >>> corpus.filter(networkdata_csv_url__icontains='/andreyev-ne-ubiy/')
    >>> corpus.filter(authors__name__icontains='Бабель')
    ```
### Play
  - Initialize a *Play* instance

    If *play_id* is not None, *play_name* and *play_title* are not considered

    If *play_id* is None *AND* *play_name* is not None, *play_title* is not considered

    If *play_id* is None *AND* *play_name* is None, *play_title* should not be None, otherwise *ValueError* is raised

    If *play_id* is None, automatic corpus detection is applied
    ```python
    >>> play = Play('rus000160')
    >>> play = Play(play_id='rus000160')
    >>> play = Play(play_name='ostrovsky-dohodnoe-mesto')
    >>> play = Play(play_title='Доходное место')
    ```
  - Summary in a dictionary
    ```python
    >>> play.summary()
    ```
  - Summary in a string
    ```python
    >>> str(play)
    ```
  - Play info in a dictionary
    ```python
    >>> play.play_info()
    ```
  - Get network metrics for a single play
    ```python
    >>> play.metrics()
    ```
  - Get a list of characters of a play
    ```python
    >>> play.get_characters()
    ```
  - Get X of a play
    ```python
    >>> play.num_of_male_characters
    >>> play.num_of_female_characters
    >>> play.num_of_unknown_characters
    >>> play.tei
    >>> play.csv
    >>> play.gexf
    ```
  - Get spoken text of a play (excluding stage directions)
    ```python
    >>> play.spoken_text()
    >>> play.spoken_text(gender='MALE')
    >>> play.spoken_text(gender='FEMALE')
    >>> play.spoken_text(gender='UNKNOWN')
    ```
  - Get spoken text for each character of a play
    ```python
    >>> play.spoken_text_by_character()
    ```
  - Get all stage directions of a play
    ```python
    >>> play.stage_directions()
    ```
  - Get all stage directions of a play including speakers
    ```python
    >>> play.stage_directions_with_speakers()
    ```
### Character
  - Initialize a *Character* instance
    ```python
    >>> character = Character('yakov', 'rus000138')
    >>> character = Character('kraft', 'rus000137')
    ...
    ```
  - Summary in a dictionary
    ```python
    >>> character.summary()
    ```
  - Summary in a string
    ```python
    >>> str(character)
    ```

### Wikidata
  - Initialize a *Wikidata* instance
    ```python
    >>> wikidata = Wikidata()
    ```
  - Get author information by WikidataID
    ```python
    >>> author_info = Wikidata.get_author_info_by_id("Q34628")
    ```
  - Get Wikidata Mix'n'match information as CSV
    ```python
    >>> wikidata_mixnmatch = Wikidata.mixnmatch()
    ```


## Installation
```sh
$ pip install pydracor
```
## Todos
 - write more methods
 - write more tests

## License
MIT
