Metadata-Version: 2.5
Name: platen
Version: 0.8.0
Summary: Press structured data into documents
Project-URL: Documentation, https://cariad.github.io/platen/
Project-URL: Issues, https://github.com/cariad/platen/issues
Project-URL: Source, https://github.com/cariad/platen
Author-email: Cariad Eccleston <cariad@cariad.earth>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: crumpet<0.5,>=0.4.0
Requires-Dist: jinja2<4,>=3.1.6
Requires-Dist: mosey<0.9,>=0.8.0
Requires-Dist: rootle<2,>=1.3.0
Requires-Dist: ruamel-yaml<0.20,>=0.19.1
Requires-Dist: tzdata>=2026.6
Requires-Dist: watchfiles<2,>=1.3.0
Description-Content-Type: text/markdown

# platen

In a printing press, the *platen* presses paper against inked type.

**Platen** is a Python package and command-line tool that presses structured data into documents.

## Requirements

- Python 3.14 or later.

## Installation

To install Platen as a package to use in your own Python project, install `platen` from PyPI with your package manager of choice and read [the user guide](https://cariad.github.io/platen/).

To use `platen` as a command-line tool, install it via [pipx](https://pipx.pypa.io/):

```bash
pipx install platen
```

## Usage

```text
platen --template FILE \
       --values   FILE \
       --out      FILE \
       [--watch] [--serve]

platen --templates DIRECTORY \
       --values    FILE      \
       --out       DIRECTORY \
       [--watch] [--serve]
```

`--template` and `--templates` are the same option, so either one can name a file or a directory.

For example, say you have values in `values.yaml`:

```yaml
name: Bob
```

And a [Jinja](https://jinja.palletsprojects.com/en/stable/templates/) template, `hello.md`:

```markdown
# Hello, {{ name }}!
```

Press the values into the template:

```bash
platen --template hello.md --values values.yaml --out build/hello.md
```

Platen creates `build/hello.md`:

```markdown
# Hello, Bob!
```

To press every template in a directory, name that directory with `--templates` and the directory to press into with `--out`:

```bash
platen --templates templates --values values.yaml --out build
```

To press again whenever the templates or values change, add `--watch`. Platen prints a line for every press, and keeps watching until you press Ctrl+C, even when a press fails:

```bash
platen --template hello.md --values values.yaml --out build/hello.md --watch
```

See [Watching for changes](https://cariad.github.io/platen/#watching-for-changes) in the user guide for what's watched, and what isn't.

To see your pages in a browser while you work, add `--serve` instead. Platen serves at `http://localhost:1440/`, re-presses when the templates or values change, and reloads open HTML pages automatically:

```bash
platen --templates templates --values values.yaml --out build --serve
```

See [Serving with live reload](https://cariad.github.io/platen/#serving-with-live-reload) in the user guide for what's served, and how.

Platen also gives templates [built-in functions](https://cariad.github.io/platen/built-in-functions/), like the time of the press.

## Contributing

See [Contributing](https://cariad.github.io/platen/contributing/) in the user guide to set up the project and run its checks.
