play-parser 1.0.0__tar.gz

play_parser-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0
+
+Initial public release.
+
+### Features
+
+- Parse raw `.txt` play files into canonical JSON documents.
+- Assemble canonical JSON documents back into normalised play text.
+- Support explicit format profiles for speaker labels and stage directions.
+- Include built-in profiles for common dramatic text layouts.
+- Validate canonical play documents with a shared validator and JSON Schema.
+- Expose a Python API for ingestion, domain access, validation, assembly, and profiles.
+- Provide a `play-parser` CLI for parsing and assembling single files or folders.
+- Include a corpus-backed test suite covering parsing, profiles, ingestion, domain objects, and roundtrips.

play_parser-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stergios Poularakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

play_parser-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include RELEASE.md
+include SECURITY.md
+recursive-include docs *.md *.json
+recursive-include data *.md *.txt *.json

play_parser-1.0.0/PKG-INFO

@@ -0,0 +1,195 @@
+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

play_parser-1.0.0/README.md

@@ -0,0 +1,162 @@
+# 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

play_parser-1.0.0/RELEASE.md

@@ -0,0 +1,62 @@
+# Release checklist
+
+Use this checklist when publishing a new public release.
+
+## 1. Prepare the repository
+
+```bash
+python -m pip install -e .[dev]
+python -m ruff check .
+python -m ruff format --check .
+python -m unittest discover -s tests
+```
+
+Check that the version in `pyproject.toml` and `src/play_parser/__init__.py` has been updated. For the first `1.0.0` release, keep `CHANGELOG.md` simple: list the current release features only, or leave it with no historical entries.
+
+## 2. Build and inspect distributions
+
+```bash
+rm -rf dist build src/*.egg-info
+python -m build
+python -m twine check dist/*
+```
+
+Optional local wheel smoke test:
+
+```bash
+python -m venv /tmp/play-parser-release-test
+/tmp/play-parser-release-test/bin/python -m pip install dist/*.whl
+/tmp/play-parser-release-test/bin/play-parser --version
+/tmp/play-parser-release-test/bin/play-parser --help
+```
+
+## 3. Publish to TestPyPI first
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a fresh environment and check the CLI:
+
+```bash
+python -m venv /tmp/play-parser-testpypi
+/tmp/play-parser-testpypi/bin/python -m pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  play-parser
+/tmp/play-parser-testpypi/bin/play-parser --version
+/tmp/play-parser-testpypi/bin/play-parser --help
+```
+
+## 4. Publish to PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## 5. Tag the release
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```

play_parser-1.0.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are considered for the latest released version of `play-parser`.
+
+## Reporting a vulnerability
+
+Please report security issues privately by email rather than opening a public issue.
+
+Include a clear description, reproduction steps where possible, and the version affected. Please do not disclose the issue publicly until it has been assessed.

play_parser-1.0.0/data/README.md

@@ -0,0 +1,7 @@
+# Test corpus data
+
+The files in this directory are used as test fixtures and reference corpus material for parser development.
+
+The raw play texts are public-domain source texts. The canonical JSON files are generated or curated fixtures used to validate parser behaviour.
+
+These files are not required for normal package use.