py-shakespeare 0.1.0
Python package to obtain Shakespeare script and monologue
License: MIT
Requires Python: >=3.9,<4.0

# py_shakespeare

`py_shakespeare` is a Python package to obtain Shakespeare script and monologue.

## Installation

```bash
$ pip install py_shakespeare
```

## Usage

### Classes

#### shake_play

`shake_play(min_num_character=20, play_complexity, play_length)`
> Base class to obtain the list of Shakespeare play based on minimum number of character, length of the play, and complexity of the play. This class will obtain data from DraCor API and merge the data to genre of Shakespeare play that was obtained by scraping "www.opensourceshakespeare.org" website.

#### shake_monologue

`shake_monologue(gender='ALL', min_line=30, include_all=True, play_list)`
> Base class to obtain a list of monologues from Shakespeare plays based on gender of the monologues speaker, minimum line of monologue, and list of plays which monologues want to be obtained. This class will obtain data from both DraCor and The Folger Shakespeare API to help user choose monologue based on several inputs.

### How to use

### Import all classes

```python
>>> from py_shakespeare import py_shakespeare
```

### shake_play

  - Initialize shake play based on minimum number of character, play complexity (optional), and play length (optional)
    ```python
    >>> pl = py_shakespeare.shake_play(min_num_character=30, play_complexity = "Medium", play_length = "Medium")
    ```
    
  - Get the summarized table. 
    ```python
    >>> pl.get_summary()
    ```
    This function returned a table with following variables:
        * title: title of the play
        * popularity: relative popularity (from the number of Wikipedia links referring to this play) to other plays with similar minimum number of character
        * genre: genre of the play (based on Open Source Shakespeare website)
        * num_character: number of character/cast in this play
        * play_length: relative length of the play to other plays with similar minimum number of character. Obtained by using number of words variable divided by rate of speech in a drama (170 words per minute)
        * play_complexity: relative complexity of the play to other plays with similar minimum number of character. Obtained by using average degree of dialogue between each character in the play
        
  - Get detailed table
    ```python
    >>> pl.get_complete()
    ```
    This function returned a table with same variables of summary table plus below variables:
        * num_male_character: number of male character/cast in this play
        * num_female_character: number of female character/cast in this play
        * num_unknown_character: number of unknown gender character/cast in this play
        * num_scene: number of scene/segment in this play
        * play_length_hr: length of the play in hours. Obtained by using number of words variable divided by rate of speech in a drama (170 words per minute)

  - Download selected script in xml format. The file will be downloaded to the device.
    ```python
    >>> pl.get_script(row = 2)
    ```
 
### shake_monologue

  - Initialize a table of monologues from Shakespeare plays based on gender of character, minimum line, and list of plays. **WARNING**: if choose `include_all = True` the run time for the function will be quite long
    ```python
    >>> ml = py_shakespeare.shake_monologue(gender = "ALL", min_line = 40, include_all = False, play_list = ["Rom", "Ham"])
    ```
    
  - Get the summarized table
    ```python
    >>> ml.get_summary()
    ```
    This function returned a table with following variables:
        * play: title of the play
        * name: name of the character
        * gender: gender of the character
        * degree: how many other characters this character interacted with
        * monologue_link: Link to the monologue
        * line_num: number of lines of the monologue
    
  - Get the complexity score of the monologue. Complexity score is calculated using [Flesch Kincaid Grade readibility score](https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/).
    ```python
    >>> ml.get_complexity()
    ```
    This function returned a summary table with 2 additional variables:
        * complexity_score: Flesch Kincaid Grade readibility score
        * complexity_category: Complexity category based on the readibility score
        
  - Download selected monologue script in txt format. The file will be downloaded to the device.
    ```python
    >>> ml.get_script(row = 2)
    ```
    
  - Folger ID as input of `play_list`. If `include_all = False`, an array of `play_list` should be passed in the function parameter. Below is the list of Folger ID:
  
    | Folger ID | Play                       |
    |-----------|----------------------------|
    | AWW       | All’s Well That Ends Well  |
    | Ant       | Antony and Cleopatra       |
    | AYL       | As You Like It             |
    | Err       | The Comedy of Errors       |
    | Cor       | Coriolanus                 |
    | Cym       | Cymbeline                  |
    | Ham       | Hamlet                     |
    | 1H4       | Henry IV, Part 1           |
    | 2H4       | Henry IV, Part 2           |
    | H5        | Henry V                    |
    | 1H6       | Henry VI, Part 1           |
    | 2H6       | Henry VI, Part 2           |
    | 3H6       | Henry VI, Part 3           |
    | H8        | Henry VIII                 |
    | JC        | Julius Caesar              |
    | Jn        | King John                  |
    | Lr        | King Lear                  |
    | LLL       | Love’s Labor’s Lost        |
    | Mac       | Macbeth                    |
    | MM        | Measure for Measure        |
    | MV        | The Merchant of Venice     |
    | Wiv       | The Merry Wives of Windsor |
    | MND       | A Midsummer Night’s Dream  |
    | Ado       | Much Ado About Nothing     |
    | Oth       | Othello                    |
    | Per       | Pericles                   |
    | R2        | Richard II                 |
    | R3        | Richard III                |
    | Rom       | Romeo and Juliet           |
    | Shr       | The Taming of the Shrew    |
    | Tmp       | The Tempest                |
    | Tim       | Timon of Athens            |
    | Tit       | Titus Andronicus           |
    | Tro       | Troilus and Cressida       |
    | TN        | Twelfth Night              |
    | TGV       | Two Gentlemen of Verona    |
    | TNK       | Two Noble Kinsmen          |
    | WT        | The Winter’s Tale          |


## Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.

## License

`py_shakespeare` was created by Hamidah Alatas. It is licensed under the terms of the MIT license.

## Credits

`py_shakespeare` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

`py_shakespeare` used DraCor API. Fischer, Frank, et al. (2019). Programmable Corpora: Introducing DraCor, an Infrastructure for the Research on European Drama. In Proceedings of DH2019: "Complexities", Utrecht University, doi:10.5281/zenodo.4284002.

`py_shakespeare` used The Folger Shakespeare API. Folger Shakespeare Library. (n.d.) Shakespeare’s Plays, Sonnets and Poems from The Folger Shakespeare API. Retrieved from https://shakespeare.folger.edu