32 lines
1.6 KiB
Markdown
32 lines
1.6 KiB
Markdown
# CLI Contract: `convert_article_to_markdown.py`
|
|
|
|
**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21
|
|
|
|
## 1. Script Signature
|
|
|
|
```bash
|
|
python scripts/convert_article_to_markdown.py -i <input_path> [-o <output_path>]
|
|
```
|
|
|
|
## 2. Command-Line Arguments
|
|
|
|
| Flag | Long Option | Type | Required | Default | Description |
|
|
|---|---|---|:---:|---|---|
|
|
| `-i` | `--input` | String / Path | Yes | — | Path to the source JSON file containing exactly one article object. |
|
|
| `-o` | `--output` | String / Path | No | `<input_stem>.md` | Destination path for the generated Markdown file. |
|
|
|
|
## 3. Exit Codes
|
|
|
|
| Exit Code | Meaning | Standard Streams Behavior |
|
|
|:---:|---|---|
|
|
| `0` | **Success**: Article converted and Markdown written atomically. | Diagnostic info on `stderr`, clean execution. |
|
|
| `1` | **Runtime / Validation Error**: Malformed JSON, root `articles` array, missing mandatory fields (title, original URL, body), invalid selected extractor, or write failure. | Descriptive error message printed to `stderr`. Pre-existing target file unmodified. |
|
|
| `2` | **Argument Error**: Missing required `-i/--input` argument, unrecognized arguments, or invalid CLI usage. | Standard `argparse` usage and error output printed to `stderr`. |
|
|
|
|
## 4. Standard Stream Behavior
|
|
|
|
- **`stdout`**: Reserved. No Markdown text is dumped to `stdout` when generating file output.
|
|
- **`stderr`**: Receives progress/error diagnostics, e.g.:
|
|
- `[INFO] Converted 'out/article_001.json' -> 'out/article_001.md' (extractor: trafilatura)`
|
|
- `[ERROR] Invalid input: JSON contains batch 'articles' array. Only single article JSON files are accepted.`
|