play-parser 1.0.0

Parse dramatic play text into ordered dramatic events.

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

pip install play-parser

Python quick start

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:

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:

from play_parser import assemble_play_text

canonical_text = assemble_play_text(document)

Command line usage

Show help and version information:

play-parser --help
play-parser --version

Parse one file:

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

Parse a folder recursively:

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

Assemble canonical JSON files into text:

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

Public API

Stable top-level imports:

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.

from play_parser import list_format_profiles

print(list_format_profiles())

See docs/FORMAT_PROFILES.md for the profile schema and examples.

Documentation

• docs/API.md: Python API and CLI profile usage.
• docs/JSON_SCHEMA.md: canonical JSON document format.
• docs/FORMAT_PROFILES.md: built-in and custom format profiles.

Development

Install development dependencies:

python -m pip install -e .[dev]

Run local checks:

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.

Licence

MIT