feat: support passing data to script via YAML

.github/workflows/main.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Install just
         uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
         with:
-          just-version: "1.43.1"
+          just-version: "1.58.0"
       - run: just typing
 
   run-tests:
@@ -62,7 +62,7 @@ jobs:
       - name: Install just
         uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
         with:
-          just-version: "1.43.1"
+          just-version: "1.58.0"
 
       - name: Run tests
         shell: bash -l {0}

.pre-commit-config.yaml

@@ -18,15 +18,6 @@ repos:
     -   id: no-commit-to-branch
         args: [--branch, main]
     -   id: trailing-whitespace
--   repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.10.0
-    hooks:
-    -   id: python-check-blanket-noqa
-    -   id: python-check-mock-methods
-    -   id: python-no-eval
-    -   id: python-no-log-warn
-    -   id: python-use-type-annotations
-    -   id: text-unicode-replacement-char
 -   repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.16.7
     hooks:
@@ -45,7 +36,7 @@ repos:
         - mdformat-black
         args: [--wrap, "88"]
 -   repo: https://github.com/crate-ci/typos
-    rev: v1
+    rev: v1.49.0
     hooks:
     -   id: typos
 -   repo: meta

CHANGELOG.md

@@ -5,6 +5,14 @@ chronological order. Releases follow [semantic versioning](https://semver.org/)
 releases are available on [PyPI](https://pypi.org/project/pytask-stata) and
 [Anaconda.org](https://anaconda.org/conda-forge/pytask-stata).
 
+## 0.6.0 - 2026-09-19
+
+- {pull}`107` adds YAML configuration files for passing dependencies, products, and
+  other task arguments to Stata. YAML is now the default interface; explicitly supplying
+  `options` selects the command-line compatibility interface.
+- {pull}`107` expands the mock Stata runtime with YAML parsing and validation support.
+- {pull}`114` uses the canonical `pytask-stata` distribution name in package metadata.
+
 ## 0.5.1 - 2026-06-14
 
 - {pull}`50` drops support for Python 3.8 and 3.9 and adds support for Python 3.14.

README.md

@@ -14,6 +14,18 @@ ______________________________________________________________________
 
 Run Stata's do-files with pytask.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Dependencies and Products](#dependencies-and-products)
+  - [Accessing dependencies and products in the script](#accessing-dependencies-and-products-in-the-script)
+    - [YAML Configuration Files](#yaml-configuration-files)
+    - [Command Line Arguments](#command-line-arguments)
+  - [Repeating tasks with different scripts or inputs](#repeating-tasks-with-different-scripts-or-inputs)
+- [Configuration](#configuration)
+- [Changes](#changes)
+
 ## Installation
 
 pytask-stata is available on [PyPI](https://pypi.org/project/pytask-stata) and
@@ -99,9 +111,65 @@ def task_run_do_file(produces: Path = Path("auto.dta")):
 ### Accessing dependencies and products in the script
 
 Dependencies and products registered in the task function signature are used by pytask
-to order tasks and track whether they are up-to-date. They are not automatically passed
-to the Stata script. Use the `options` argument of the decorator to pass paths or other
-values as command line arguments to your Stata executable.
+to order tasks and track whether they are up-to-date. pytask-stata offers two modes to
+pass these paths and other task data to the Stata script.
+
+1. Use the default YAML configuration file. This is the recommended mode if your Stata
+   installation can use the user-written [`yaml`](https://github.com/jpazvd/yaml)
+   package, which is compatible with Stata 14+.
+1. Use the `options` argument of the decorator to pass command line arguments. This is
+   the compatibility mode for Stata installations where `yaml.ado` is not available or
+   not supported.
+
+Do not combine both interfaces. If `options` is supplied, pytask-stata assumes the
+do-file receives all required values through command line arguments and does not create
+a YAML configuration file. Pass `options=None` to select this mode without passing any
+command line arguments.
+
+#### YAML Configuration Files
+
+By default, pytask-stata serializes all task keyword arguments and passes the path to
+the generated YAML file as the first argument to the do-file. To read the file inside
+Stata, install the user-written [`yaml`](https://github.com/jpazvd/yaml) package, which
+is compatible with Stata 14+.
+
+See [YAML Data Passed to Stata](docs/yaml.md) for the supported data types and how they
+are represented in Stata.
+
+```stata
+ssc install yaml
+```
+
+Then read the configuration file in the Stata task.
+
+```python
+from pathlib import Path
+
+from pytask import mark
+
+
+@mark.stata(script=Path("script.do"))
+def task_run_do_file(
+    depends_on: Path = Path("input.dta"),
+    produces: Path = Path("auto.dta"),
+):
+    pass
+```
+
+```do
+args config
+yaml read using "`config'", locals replace
+local depends_on = r(yaml_depends_on)
+local produces = r(yaml_produces)
+
+use "`depends_on'", clear
+save "`produces'"
+```
+
+#### Command Line Arguments
+
+Use the `options` argument of the decorator to pass paths or other values as command
+line arguments to your Stata executable. This mode does not require the `yaml` package.
 
 For example, pass paths for the dependency and product with
 
@@ -119,22 +187,22 @@ def task_run_do_file(
     pass
 ```
 
-And in your `script.do`, you can intercept the value with
+And in your `script.do`, you can intercept the values with
 
 ```do
 * Intercept command line arguments and save them to macros.
 args depends_on produces
 
-sysuse auto, clear
+use "`depends_on'", clear
 save "`produces'"
 ```
 
 The relative path inside the do-file works only because pytask-stata switches the
 current working directory to the directory of the task module before the task is
 executed.
 
-To make the task independent from the current working directory, pass the full path as
-an command line argument. Here is an example.
+To make the task independent from the current working directory, pass the full path as a
+command line argument. Here is an example.
 
 ```python
 # Absolute path to the build directory.
@@ -153,7 +221,7 @@ def task_run_do_file(produces: Path = BLD / "auto.dta"):
 ### Repeating tasks with different scripts or inputs
 
 You can also parametrize the execution of scripts, meaning executing multiple do-files
-as well as passing different command line arguments to the same do-file.
+as well as passing different inputs or task data to the same do-file.
 
 The following task executes two do-files which produce different outputs.
 

docs/yaml.md

@@ -0,0 +1,38 @@
+# YAML Data Passed to Stata
+
+pytask-stata serializes task keyword arguments with PyYAML and passes the path to the
+generated YAML file as the first command line argument to the do-file. Inside Stata,
+read the file with the user-written `yaml` package.
+
+```stata
+args config
+yaml read using "`config'", locals replace
+```
+
+The `yaml` package stores parsed YAML in a Stata dataset with `key`, `value`, `level`,
+`parent`, and `type` columns. With `locals`, scalar leaves are also available as
+`r(yaml_<key>)` macros. Nested keys are flattened with underscores.
+
+## Supported Types
+
+| Python value                     | YAML shape                    | Stata representation                                                 | Access pattern                            |
+| -------------------------------- | ----------------------------- | -------------------------------------------------------------------- | ----------------------------------------- |
+| Non-empty `str`                  | `name: hello`                 | `type=string`, `value=hello`                                         | `r(yaml_name)`                            |
+| `int`                            | `count: 42`                   | `type=numeric`, `value=42`                                           | `r(yaml_count)`                           |
+| `float`                          | `ratio: 3.14`                 | `type=numeric`, `value=3.14`                                         | `r(yaml_ratio)`                           |
+| `bool`                           | `enabled: true`               | `type=boolean`, `value=1` or `0`                                     | `r(yaml_enabled)`                         |
+| `None`                           | `missing: null`               | `type=null`, empty value                                             | validate as `null`; no useful macro value |
+| `pathlib.Path`                   | `path: build/out.dta`         | `type=string`, POSIX-style path                                      | `r(yaml_path)`                            |
+| Flat `list` / `tuple` of scalars | `items:` plus `- value` lines | parent row plus `items_1`, `items_2`, ... rows with `type=list_item` | use flattened keys such as `items_1`      |
+| Nested `dict` with scalar leaves | nested mapping                | flattened keys such as `config_child`                                | `yaml get config, attributes(child)`      |
+
+## Recommended Limits
+
+Keep the YAML bridge to configuration-like data: scalar values, paths, flat scalar
+lists, and nested dictionaries with scalar leaves.
+
+Avoid empty mappings and lists, empty strings, lists of dictionaries, sets, bytes,
+decimals, and arbitrary Python objects. Empty collections use YAML flow syntax, which is
+outside the Stata parser's supported subset. PyYAML may also emit YAML tags such as
+`!!set` or `!!binary`, or fail with a `RepresenterError`; those forms are not useful as
+a stable Stata interface.

justfile

@@ -12,7 +12,7 @@ test-ci:
 
 # Run type checking
 typing:
-    uv run --group typing --group test --isolated ty check
+    uv run --group typing --group test --group test-mock-stata --isolated ty check
 
 # Run linting and formatting
 lint: