# pydracor
pydracor is a Python package which provides access to the [DraCor API](https://dracor.org/doc/api/). It is based on [`pydracor-base`](https://pypi.org/project/pydracor-base/) which was automatically generated using [OpenAPITools](https://github.com/OpenAPITools/openapi-generator).
## 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.
## Installation
```sh
pip install pydracor
```
## Classes
- *DraCorAPI*
> Base class used to represent the Drama Corpus entity with which *Corpus* and *Play* are created.
- *Corpus*
> A class with which the `corpora/{corpusname}` endpoints can be requested
- *Play*
> A class with which the `corpora/{corpusname}/plays/{playname}` endpoint can be requested
- *DTS*
> A class with which the `dts` endpoints can be requested
- *Wikidata*
> A class with which the `wikidata` endpoints can be requested
## Code examples
### Import all classes
```python
from pydracor import DraCorAPI, Corpus, Play, Wikidata, DTS
```
### Dracor
- Initialize a *DraCor* instance
```python
dracor = DraCorAPI()
```
- Initialize a local *DraCor* instance by setting the host
```python
dracor = DraCor(host="http://localhost:8088/api/v1")
```
- Get summary as an Info object (`/info`)
```python
dracor.get_info()
```
- Get the list of available corpora in DraCor (`/info/copora`) and get names
```python
corpora = dracor.get_corpora()
corpora_metrics = dracor.get_corpora(include='metrics')
corpora_names = [corpus.name for corpus in corpora]
```
- Get the resolved id for a play (`/id/{id}`)
```python
dracor.get_resolve_play_id("als000001")
```
- Get the plays with characters by wikidata id
```python
dracor.get_plays_with_character_by_id("Q131412")
```
### Corpus
- Initialize a *Corpus* instance with the DraCor class (`/corpora/{corpusname}`)
```python
corpus = dracor.get_corpus('rus')
```
- Corpus info as dictionary
```python
corpus.to_dict()
```
- Access corpus attributes, plays as a list of PlayInCorpus objects
```python
corpus.name
corpus.plays
```
- Extract all play ids from the corpus
```python
play_ids = [play.id for play in corpus.plays]
```
- Filter plays: normalized year after 1800
```python
plays_after_1800 = [play for play in corpus.plays if play.year_normalized > 1800]
```
- Get list of metadata for all plays in a corpus (`/corpora/{corpusname}/metadata`)
```python
metadata = corpus.metadata()
```
- Filter plays: Number of Acts more than five
```python
plays_more_than_five_acts = [play for play in metadata if play.num_of_acts > 5]
```
- Convert metadata to DataFrame
```python
import pandas as pd
play_metadata_df = pd.DataFrame([play_metadata.to_dict() for play_metadata in metadata])
```
- Get metadata as csv (`/corpora/{corpus}/metadata/csv`)
```python
metadata_csv = corpus.get_metadata_csv()
```
- Create Play in corpus (`corpora/{corpusname}/plays/{playname}`)
```python
play = corpus.get_play("gogol-revizor")
```
### Play
- Initialize a *Play* instance by corpus name and play name (`corpora/{corpusname}/plays/{playname}`)
```python
play = dracor.get_play("ger","gengenbach-der-nollhart")
```
- Extract summary in a dictionary
```python
play.to_dict()
```
- Access Play attributes
```python
play.normalized_genre
play.characters
```
- Get and access network metrics for a single play (`corpora/{corpusname}/plays/{playname}/metrics`)
```python
metrics = play.get_metrics()
metrics.average_degree
```
- Get a list of characters of a play (`corpora/{corpusname}/plays/{playname}/characters`)
```python
characters = play.get_characters()
```
- Convert character list to DataFrame
```python
import pandas as pd
df = pd.DataFrame([character.to_dict() for character in characters])
```
- Get a list of characters of a play as csv (`corpora/{corpusname}/plays/{playname}/characters/csv`)
```python
play.get_characters_csv()
```
- Get networkdata of a play in different formats (`corpora/{corpusname}/plays/{playname}/networkdata/{graphml, gexf, csv}`)
```python
play.get_networkdata("graphml")
play.get_networkdata("gexf")
play.get_networkdata("csv")
```
- Get relations of a play in different formats (`corpora/{corpusname}/plays/{playname}/relations/{graphml, gexf, csv}`)
```python
play.get_relations("graphml")
play.get_relations("gexf")
play.get_relations("csv")
```
- Get spoken text of a play (excluding stage directions) (`corpora/{corpusname}/plays/{playname}/spoken-text`)
```python
play.get_spoken_text()
play.get_spoken_text(sex='MALE')
play.get_spoken_text(relation='siblings')
```
- Get spoken text for each character of a play (`corpora/{corpusname}/plays/{playname}/spoken-text-by-character`)
```python
play.get_spoken_text_by_character()
```
- Get stage directions of a play (`corpora/{corpusname}/plays/{playname}/stage-directions`)
```python
play.get_stage_directions()
```
- Get stage directions and speaker text of a play (`corpora/{corpusname}/plays/{playname}/stage-directions-with-speakers`)
```python
play.get_stage_directions_with_speakers()
```
### DTS (Distributed Text Services)
- Initialize a *DTS* instance
```python
dts = DTS()
```
- Get Entrypoint of the DraCor DTS implementation (`/dts`)
```python
dts.get_dts()
```
- Get the list of the available collections of a corpus (`/dts/collection`)
```python
dts.get_collection("rus")
```
- Use navigation endpoint of DTS (`/dts/navigation`)
```python
dts.get_navigation("rus000160", "body/div[1]")
dts.get_navigation("rus000160", start="body/div[2]/div[1]", end="body/div[2]/div[2]")
```
- Use document endpoint of DTS (`/dts/document`)
```python
dts.get_document("rus000160", "body/div[1]")
dts.get_document("rus000160", start="body/div[2]/div[1]", end="body/div[2]/div[2]")
```
### Wikidata
- Initialize a *Wikidata* instance
```python
wikidata = Wikidata()
```
- Get author information by WikidataID
```python
author_info = wikidata.get_author_info("Q34628")
```
- Get Wikidata Mix'n'match information as CSV
```python
wikidata_mixnmatch = wikidata.get_mixnmatch()
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "pydracor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Henny Sluyter-G\u00e4thje <sluytergaeth@uni-potsdam.de>",
"keywords": "API, Corpus, DraCor, Drama, Drama Corpus, Wrapper, pydracor",
"author": null,
"author_email": "\"Henny Sluyter-G\u00e4thje, Eduard Grigoriev\" <sluytergaeth@uni-potsdam.de>",
"download_url": "https://files.pythonhosted.org/packages/11/18/0a70d41cfa3a725c3822d448b91c79cc417512cbd8adc480d10516011ed9/pydracor-3.0.1.tar.gz",
"platform": null,
"description": "# pydracor\n\npydracor is a Python package which provides access to the [DraCor API](https://dracor.org/doc/api/). It is based on [`pydracor-base`](https://pypi.org/project/pydracor-base/) which was automatically generated using [OpenAPITools](https://github.com/OpenAPITools/openapi-generator).\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## Installation\n```sh\npip install pydracor\n```\n\n## Classes\n - *DraCorAPI*\n > Base class used to represent the Drama Corpus entity with which *Corpus* and *Play* are created. \n - *Corpus*\n > A class with which the `corpora/{corpusname}` endpoints can be requested\n - *Play*\n > A class with which the `corpora/{corpusname}/plays/{playname}` endpoint can be requested\n - *DTS*\n > A class with which the `dts` endpoints can be requested\n - *Wikidata*\n > A class with which the `wikidata` endpoints can be requested \n\n## Code examples\n\n### Import all classes\n\n```python\nfrom pydracor import DraCorAPI, Corpus, Play, Wikidata, DTS\n```\n\n### Dracor\n - Initialize a *DraCor* instance\n ```python\n dracor = DraCorAPI()\n ```\n\n - Initialize a local *DraCor* instance by setting the host\n ```python\n dracor = DraCor(host=\"http://localhost:8088/api/v1\")\n ```\n\n - Get summary as an Info object (`/info`)\n ```python\n dracor.get_info()\n ```\n\n - Get the list of available corpora in DraCor (`/info/copora`) and get names\n ```python\n corpora = dracor.get_corpora()\n corpora_metrics = dracor.get_corpora(include='metrics')\n corpora_names = [corpus.name for corpus in corpora]\n ```\n\n - Get the resolved id for a play (`/id/{id}`)\n ```python \n dracor.get_resolve_play_id(\"als000001\")\n ```\n\n - Get the plays with characters by wikidata id\n ```python \n dracor.get_plays_with_character_by_id(\"Q131412\")\n ```\n\n### Corpus\n - Initialize a *Corpus* instance with the DraCor class (`/corpora/{corpusname}`)\n ```python\n corpus = dracor.get_corpus('rus')\n ```\n\n - Corpus info as dictionary\n ```python\n corpus.to_dict()\n ```\n\n - Access corpus attributes, plays as a list of PlayInCorpus objects\n ```python\n corpus.name\n corpus.plays\n ```\n\n - Extract all play ids from the corpus\n ```python\n play_ids = [play.id for play in corpus.plays]\n ```\n\n - Filter plays: normalized year after 1800\n ```python\n plays_after_1800 = [play for play in corpus.plays if play.year_normalized > 1800]\n ```\n\n - Get list of metadata for all plays in a corpus (`/corpora/{corpusname}/metadata`)\n ```python\n metadata = corpus.metadata()\n ```\n\n - Filter plays: Number of Acts more than five\n ```python\n plays_more_than_five_acts = [play for play in metadata if play.num_of_acts > 5]\n ```\n\n - Convert metadata to DataFrame\n ```python\n import pandas as pd\n play_metadata_df = pd.DataFrame([play_metadata.to_dict() for play_metadata in metadata])\n ```\n\n - Get metadata as csv (`/corpora/{corpus}/metadata/csv`) \n ```python \n metadata_csv = corpus.get_metadata_csv()\n ```\n - Create Play in corpus (`corpora/{corpusname}/plays/{playname}`)\n ```python\n play = corpus.get_play(\"gogol-revizor\")\n ```\n\n\n### Play\n - Initialize a *Play* instance by corpus name and play name (`corpora/{corpusname}/plays/{playname}`)\n ```python\n play = dracor.get_play(\"ger\",\"gengenbach-der-nollhart\")\n ```\n\n - Extract summary in a dictionary\n ```python\n play.to_dict()\n\n ```\n - Access Play attributes\n ```python \n play.normalized_genre\n play.characters\n ```\n\n - Get and access network metrics for a single play (`corpora/{corpusname}/plays/{playname}/metrics`)\n ```python\n metrics = play.get_metrics()\n metrics.average_degree\n ```\n\n - Get a list of characters of a play (`corpora/{corpusname}/plays/{playname}/characters`)\n ```python\n characters = play.get_characters()\n ```\n\n - Convert character list to DataFrame\n ```python\n import pandas as pd\n df = pd.DataFrame([character.to_dict() for character in characters])\n ```\n\n - Get a list of characters of a play as csv (`corpora/{corpusname}/plays/{playname}/characters/csv`)\n ```python\n play.get_characters_csv()\n ```\n\n - Get networkdata of a play in different formats (`corpora/{corpusname}/plays/{playname}/networkdata/{graphml, gexf, csv}`)\n ```python\n play.get_networkdata(\"graphml\")\n play.get_networkdata(\"gexf\")\n play.get_networkdata(\"csv\")\n ```\n\n - Get relations of a play in different formats (`corpora/{corpusname}/plays/{playname}/relations/{graphml, gexf, csv}`)\n ```python\n play.get_relations(\"graphml\")\n play.get_relations(\"gexf\")\n play.get_relations(\"csv\")\n ```\n\n - Get spoken text of a play (excluding stage directions) (`corpora/{corpusname}/plays/{playname}/spoken-text`)\n ```python\n play.get_spoken_text()\n play.get_spoken_text(sex='MALE')\n play.get_spoken_text(relation='siblings')\n ```\n\n - Get spoken text for each character of a play (`corpora/{corpusname}/plays/{playname}/spoken-text-by-character`)\n ```python\n play.get_spoken_text_by_character()\n ```\n\n - Get stage directions of a play (`corpora/{corpusname}/plays/{playname}/stage-directions`)\n ```python\n play.get_stage_directions()\n ```\n\n - Get stage directions and speaker text of a play (`corpora/{corpusname}/plays/{playname}/stage-directions-with-speakers`)\n ```python\n play.get_stage_directions_with_speakers()\n ```\n\n### DTS (Distributed Text Services) \n - Initialize a *DTS* instance\n ```python\n dts = DTS()\n ```\n\n - Get Entrypoint of the DraCor DTS implementation (`/dts`) \n ```python \n dts.get_dts()\n ```\n\n - Get the list of the available collections of a corpus (`/dts/collection`)\n ```python\n dts.get_collection(\"rus\")\n ```\n\n - Use navigation endpoint of DTS (`/dts/navigation`)\n ```python\n dts.get_navigation(\"rus000160\", \"body/div[1]\")\n dts.get_navigation(\"rus000160\", start=\"body/div[2]/div[1]\", end=\"body/div[2]/div[2]\")\n ```\n\n - Use document endpoint of DTS (`/dts/document`)\n ```python\n dts.get_document(\"rus000160\", \"body/div[1]\")\n dts.get_document(\"rus000160\", start=\"body/div[2]/div[1]\", end=\"body/div[2]/div[2]\")\n ```\n\n### Wikidata\n - Initialize a *Wikidata* instance\n ```python\n wikidata = Wikidata()\n ```\n\n - Get author information by WikidataID\n ```python\n author_info = wikidata.get_author_info(\"Q34628\")\n ```\n\n - Get Wikidata Mix'n'match information as CSV\n ```python\n wikidata_mixnmatch = wikidata.get_mixnmatch()\n ```\n\n\n## License\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "Python package which wraps methods from pydracor-base to interact with the DraCor API.",
"version": "3.0.1",
"project_urls": {
"Repository": "https://github.com/dracor-org/pydracor.git"
},
"split_keywords": [
"api",
" corpus",
" dracor",
" drama",
" drama corpus",
" wrapper",
" pydracor"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "42942aba830af51a48214f3b5437a5647af91d497c548c8dae8243f9d6923a5b",
"md5": "ea6b26fd695b38840e6513d1a9903bd5",
"sha256": "3a5074444cc823f22f2b9f6bdfa319687fce48d06264b7246cef54af8887abe6"
},
"downloads": -1,
"filename": "pydracor-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea6b26fd695b38840e6513d1a9903bd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8265,
"upload_time": "2025-09-09T17:49:41",
"upload_time_iso_8601": "2025-09-09T17:49:41.415514Z",
"url": "https://files.pythonhosted.org/packages/42/94/2aba830af51a48214f3b5437a5647af91d497c548c8dae8243f9d6923a5b/pydracor-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "11180a70d41cfa3a725c3822d448b91c79cc417512cbd8adc480d10516011ed9",
"md5": "eccdaa86d6b30feb238b010d09e318fe",
"sha256": "21d5fa83a2c404ecb7f8a47d41d010278eb7888d999cb5555c18f9d237929791"
},
"downloads": -1,
"filename": "pydracor-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "eccdaa86d6b30feb238b010d09e318fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11820,
"upload_time": "2025-09-09T17:49:42",
"upload_time_iso_8601": "2025-09-09T17:49:42.313896Z",
"url": "https://files.pythonhosted.org/packages/11/18/0a70d41cfa3a725c3822d448b91c79cc417512cbd8adc480d10516011ed9/pydracor-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 17:49:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dracor-org",
"github_project": "pydracor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pydracor"
}
JSON
