Metadata-Version: 2.4
Name: play-parser
Version: 1.0.0
Summary: Parse dramatic play text into ordered dramatic events.
Author: Stergios Poularakis
License-Expression: MIT
Project-URL: Homepage, https://github.com/stpoular/play-parser
Project-URL: Documentation, https://github.com/stpoular/play-parser/tree/main/docs
Project-URL: Repository, https://github.com/stpoular/play-parser
Project-URL: Issues, https://github.com/stpoular/play-parser/issues
Project-URL: Changelog, https://github.com/stpoular/play-parser/blob/main/CHANGELOG.md
Keywords: theatre,drama,plays,parser,json
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# play-parser

`play-parser` parses theatrical play text into a canonical JSON document and assembles canonical documents back into normalised play text.

Canonical text uses a stable output format. For example, speech labels are emitted in colon form such as `Hamlet: ...`, even when the source text used another supported layout.

## Features

- Parse raw `.txt` play files into structured JSON.
- Assemble canonical JSON documents into normalised `.txt` output.
- Read and validate existing canonical `.json` documents.
- Work with explicit parsing profiles for different source formats.
- Preserve speeches, stage directions, acts, scenes, metadata, characters, and document statistics.
- Use the package from Python or through the `play-parser` command line interface.

## Supported inputs

- Raw `.txt` play files.
- Canonical `.json` documents produced by this package.

The package does not parse PDFs, DOCX files, HTML pages, scans, images, or audio directly. Convert those sources to text first.

## Installation

```bash
pip install play-parser
```

## Python quick start

```python
from play_parser import Play, PlayIngestor

ingestor = PlayIngestor("Hamlet.txt", profile="colon_inline")
play = Play(ingestor.data)

print(play.title)
print(play.author)
print(len(play.acts))
print(len(play.scenes))
print(len(play.characters))
print(len(play.speeches))

play.save_json("Hamlet.json")
play.save_text("Hamlet.canonical.txt")
```

Parse text that is already in memory:

```python
from play_parser import PlayIngestor

text = "ACT I\n\nSCENE I.\n\nHAMLET: Who's there?"
ingestor = PlayIngestor.from_text(text, source_name="Hamlet.txt", profile="colon_inline")
document = ingestor.data
```

Assemble a canonical document:

```python
from play_parser import assemble_play_text

canonical_text = assemble_play_text(document)
```

## Command line usage

Show help and version information:

```bash
play-parser --help
play-parser --version
```

Parse one file:

```bash
play-parser parse Hamlet.txt \
  --profile colon_inline \
  --json-output Hamlet.json \
  --text-output Hamlet.canonical.txt
```

Parse a folder recursively:

```bash
play-parser parse \
  --input-root data/text/raw \
  --recursive \
  --profile colon_inline \
  --json-output-root data/json/generated
```

Assemble canonical JSON files into text:

```bash
play-parser assemble \
  --input-root data/json/generated \
  --recursive \
  --output-root data/text/canonical
```

## Public API

Stable top-level imports:

```python
from play_parser import (
    Play,
    PlayIngestor,
    assemble_play_text,
    get_format_profile,
    list_format_profiles,
    load_format_profile_config,
    load_format_profile_file,
    validate_play_document,
)
```

Domain classes such as `Act`, `Scene`, `Speech`, `Character`, `Monologue`, and `Dialogue` are also available from the top-level package.

## Format profiles

Built-in profiles are available through `list_format_profiles()` and can be passed to `PlayIngestor` or the CLI by name.

```python
from play_parser import list_format_profiles

print(list_format_profiles())
```

See [`docs/FORMAT_PROFILES.md`](docs/FORMAT_PROFILES.md) for the profile schema and examples.

## Documentation

- [`docs/API.md`](docs/API.md): Python API and CLI profile usage.
- [`docs/JSON_SCHEMA.md`](docs/JSON_SCHEMA.md): canonical JSON document format.
- [`docs/FORMAT_PROFILES.md`](docs/FORMAT_PROFILES.md): built-in and custom format profiles.

## Development

Install development dependencies:

```bash
python -m pip install -e .[dev]
```

Run local checks:

```bash
python -m ruff check .
python -m ruff format --check .
python -m unittest discover -s tests
python -m build
python -m twine check dist/*
```

Release steps are documented in [`RELEASE.md`](RELEASE.md).

## Licence

MIT
