# 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
Raw data
{
"_id": null,
"home_page": "https://github.com/dracor-org/pydracor",
"name": "pydracor",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "drama corpus,drama,corpus,pydracor,dracor,api,wrapper",
"author": "Eduard Grigoriev, Henny Sluyter-G\u00e4thje",
"author_email": "sluytergaeth@uni-potsdam.de, happypuffin7@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/53/2c/a7b69e0a4738757cbb0cbb25c2bc67db752e55d2f633d90bf13bb1aa3b37/pydracor-2.0.0.tar.gz",
"platform": null,
"description": "# pydracor\n\npydracor is a Python package which provides access to the [DraCor API](https://dracor.org/doc/api/).\n\n## Acknowledgment:\n\nThe development of this package was supported by Computational Literary Studies Infrastructure (CLS INFRA). CLS INFRA has received funding from the European Union\u2019s Horizon 2020 research and innovation programme under grant agreement No 101004984.\n\n## Classes\n - *DraCor*\n > Base class used to represent Drama Corpus entity.\n > DraCor consists of Corpora.\n - *Corpus*\n > A class used to represent a Corpus of DraCor.\n > Corpus (*als*/*bash*/*cal*/*fre*/*ger*/*gersh*/*greek*/*hun*/*ita*/*rom*/*rus*/*shake*/*span*/*swe*/*tat*) consists of plays.\n - *Play*\n > A class used to represent a Play of a Corpus.\n > Play consists of Characters.\n - *Character*\n > A class used to represent a Character of a Play.\n\n## Code examples\n\n### Import all classes\n\n```python\n>>> from pydracor import *\n```\n\n### Dracor\n - Initialize a *DraCor* instance\n ```python\n >>> dracor = DraCor()\n ```\n - Summary in a dictionary\n ```python\n >>> dracor.summary()\n ```\n - Summary in a string\n ```python\n >>> str(dracor)\n ```\n - DraCor info in a dictionary\n ```python\n >>> dracor.dracor_info()\n ```\n - List available corpora in DraCor\n ```python\n >>> dracor.corpora()\n >>> dracor.corpora(include='metrics')\n ```\n - List available corpora names in DraCor\n ```python\n >>> dracor.corpora_names()\n ```\n - List available corpora titles in DraCor\n ```python\n >>> dracor.corpora_titles()\n ```\n - Map X to Y\n ```python\n >>> dracor.corpus_name_to_repository()\n >>> dracor.corpus_name_to_title()\n >>> dracor.corpus_name_to_uri()\n >>> dracor.play_title_to_corpus_name()\n >>> dracor.play_title_to_play_id()\n >>> dracor.play_name_to_corpus_name()\n >>> dracor.play_name_to_play_id()\n >>> dracor.play_id_to_play_title()\n >>> dracor.play_id_to_play_name()\n ```\n - Submit SPARQL queries with query parameter\n ```python\n >>> dracor.sparql(\"PREFIX urn: <http://fliqz.com/> SELECT * FROM <urn:x-arq:UnionGraph> WHERE {?sub ?pred ?obj .} LIMIT 1\")\n ```\n### Corpus\n - Initialize a *Corpus* instance\n ```python\n >>> corpus = Corpus('rus')\n >>> corpus = Corpus('cal')\n ...\n ```\n - Summary in a dictionary\n ```python\n >>> corpus.summary()\n ```\n - Summary in a string\n ```python\n >>> str(corpus)\n ```\n - Authors' summary for a corpus\n ```python\n >>> corpus.authors_summary()\n >>> corpus.authors_summary(num_of_authors=5)\n ```\n - String representation of authors_summary method\n ```python\n >>> corpus.authors_summary_str()\n >>> corpus.authors_summary_str(num_of_authors=5)\n ```\n - Corpus info in a dictionary\n ```python\n >>> corpus.corpus_info()\n ```\n - Get all corpus' play Xs\n ```python\n >>> corpus.play_ids()\n >>> corpus.play_names()\n >>> corpus.play_titles()\n ```\n - Map play id to the X year\n ```python\n >>> corpus.years_written()\n >>> corpus.years_premiered()\n >>> corpus.years_normalized()\n ```\n - List of metadata for all plays in a corpus\n ```python\n >>> corpus.metadata()\n ```\n - Filter Plays of a Corpus\n\n Filters are equivalent to the django filters\n\n Possible relations: *eq* / *ne* / *gt* / *ge* / *lt* / *le* / *contains* / *icontains* / *exact* / *iexact* / *in*\n\n Possible fields: all the attributes that the *Corpus* instance contains\n ```python\n >>> corpus.filter(year_written__eq=1913, network_size__lt=20)\n >>> corpus.filter(year_printed__lt=1850, source__icontains='lib.ru', year_premiered__gt=1845)\n >>> corpus.filter(\n id__in=frozenset(f\"rus000{num:03d}\" for num in range(0, 250, 2)),\n subtitle__icontains='\u043a\u043e\u043c\u0435\u0434\u0438\u044f',\n author__name__contains='\u041a\u0440\u044b\u043b\u043e\u0432'\n )\n >>> corpus.filter(name__contains='mysl')\n >>> corpus.filter(title__exact='\u041c\u044b\u0441\u043b\u044c')\n >>> corpus.filter(\n year_normalized__in=frozenset(['1935', '1936'])\n source_url__contains='lib'\n )\n >>> corpus.filter(wikidata_id__iexact='Q1989636')\n >>> corpus.filter(networkdata_csv_url__icontains='/andreyev-ne-ubiy/')\n >>> corpus.filter(authors__name__icontains='\u0411\u0430\u0431\u0435\u043b\u044c')\n ```\n### Play\n - Initialize a *Play* instance\n\n If *play_id* is not None, *play_name* and *play_title* are not considered\n\n If *play_id* is None *AND* *play_name* is not None, *play_title* is not considered\n\n If *play_id* is None *AND* *play_name* is None, *play_title* should not be None, otherwise *ValueError* is raised\n\n If *play_id* is None, automatic corpus detection is applied\n ```python\n >>> play = Play('rus000160')\n >>> play = Play(play_id='rus000160')\n >>> play = Play(play_name='ostrovsky-dohodnoe-mesto')\n >>> play = Play(play_title='\u0414\u043e\u0445\u043e\u0434\u043d\u043e\u0435 \u043c\u0435\u0441\u0442\u043e')\n ```\n - Summary in a dictionary\n ```python\n >>> play.summary()\n ```\n - Summary in a string\n ```python\n >>> str(play)\n ```\n - Play info in a dictionary\n ```python\n >>> play.play_info()\n ```\n - Get network metrics for a single play\n ```python\n >>> play.metrics()\n ```\n - Get a list of characters of a play\n ```python\n >>> play.get_characters()\n ```\n - Get X of a play\n ```python\n >>> play.num_of_male_characters\n >>> play.num_of_female_characters\n >>> play.num_of_unknown_characters\n >>> play.tei\n >>> play.csv\n >>> play.gexf\n ```\n - Get spoken text of a play (excluding stage directions)\n ```python\n >>> play.spoken_text()\n >>> play.spoken_text(gender='MALE')\n >>> play.spoken_text(gender='FEMALE')\n >>> play.spoken_text(gender='UNKNOWN')\n ```\n - Get spoken text for each character of a play\n ```python\n >>> play.spoken_text_by_character()\n ```\n - Get all stage directions of a play\n ```python\n >>> play.stage_directions()\n ```\n - Get all stage directions of a play including speakers\n ```python\n >>> play.stage_directions_with_speakers()\n ```\n### Character\n - Initialize a *Character* instance\n ```python\n >>> character = Character('yakov', 'rus000138')\n >>> character = Character('kraft', 'rus000137')\n ...\n ```\n - Summary in a dictionary\n ```python\n >>> character.summary()\n ```\n - Summary in a string\n ```python\n >>> str(character)\n ```\n\n### Wikidata\n - Initialize a *Wikidata* instance\n ```python\n >>> wikidata = Wikidata()\n ```\n - Get author information by WikidataID\n ```python\n >>> author_info = Wikidata.get_author_info_by_id(\"Q34628\")\n ```\n - Get Wikidata Mix'n'match information as CSV\n ```python\n >>> wikidata_mixnmatch = Wikidata.mixnmatch()\n ```\n\n\n## Installation\n```sh\n$ pip install pydracor\n```\n## Todos\n - write more methods\n - write more tests\n\n## License\nMIT\n",
"bugtrack_url": null,
"license": "mit",
"summary": "Python package which provides access to the DraCor API.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/dracor-org/pydracor"
},
"split_keywords": [
"drama corpus",
"drama",
"corpus",
"pydracor",
"dracor",
"api",
"wrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62236ad1cd08170d9154f11b5988095b3a9b6a44997a620671f081cb82122bed",
"md5": "1754b820e5610d543a49f746d94320df",
"sha256": "1a1173989dd1eadc71e400b7d70ebe91a597b3ab5d948a2f1b7d204b30b14056"
},
"downloads": -1,
"filename": "pydracor-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1754b820e5610d543a49f746d94320df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19978,
"upload_time": "2023-12-07T15:34:58",
"upload_time_iso_8601": "2023-12-07T15:34:58.880717Z",
"url": "https://files.pythonhosted.org/packages/62/23/6ad1cd08170d9154f11b5988095b3a9b6a44997a620671f081cb82122bed/pydracor-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "532ca7b69e0a4738757cbb0cbb25c2bc67db752e55d2f633d90bf13bb1aa3b37",
"md5": "42eac4a57985045606f040443dd688d6",
"sha256": "ed6dc9d424cfffab3d9186f7a3cef4a2fb672aa4d8d9dcbe3bb098db8ed941e2"
},
"downloads": -1,
"filename": "pydracor-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "42eac4a57985045606f040443dd688d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21162,
"upload_time": "2023-12-07T15:35:01",
"upload_time_iso_8601": "2023-12-07T15:35:01.031467Z",
"url": "https://files.pythonhosted.org/packages/53/2c/a7b69e0a4738757cbb0cbb25c2bc67db752e55d2f633d90bf13bb1aa3b37/pydracor-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-07 15:35:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dracor-org",
"github_project": "pydracor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pydracor"
}
JSON
