yaqpy 0.6.0__tar.gz

yaqpy-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sgtao
+
+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.

yaqpy-0.6.0/NOTICE

@@ -0,0 +1,17 @@
+yaqpy
+=====
+
+yaqpy is an independent, pure-Python re-implementation of the expression
+language and core behaviour of yq (https://github.com/mikefarah/yq), a Go
+program by Mike Farah and contributors, released under the MIT License.
+
+The design of the operator set, the precedence table, the lexer rule order and
+the test scenarios under tests/golden/operators/ were derived from the yq
+source tree (v4.53.6). The extracted scenarios remain subject to the yq MIT
+License:
+
+    MIT License
+    Copyright (c) 2017 Mike Farah
+
+No code from yq is compiled into or linked with yaqpy; yaqpy has zero runtime
+dependencies beyond the Python 3.13 standard library.

yaqpy-0.6.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: yaqpy
+Version: 0.6.0
+Summary: YAML and more—Query editor in Python: query, update and convert YAML / JSON / XML / CSV / TOML / properties / TOON with the mikefarah/yq expression language, in pure Python (stdlib only)
+Keywords: yaml,json,xml,csv,toml,toon,yq,jq,query,cli,json-schema
+Author: sgtao
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: flet>=1.0,<2 ; extra == 'gui'
+Requires-Dist: flet[web]>=1.0,<2 ; extra == 'web'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/sgtao/yaqpy
+Project-URL: Repository, https://github.com/sgtao/yaqpy
+Project-URL: Documentation, https://github.com/sgtao/yaqpy/blob/main/USAGE.ja.md
+Project-URL: Changelog, https://github.com/sgtao/yaqpy/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sgtao/yaqpy/issues
+Provides-Extra: gui
+Provides-Extra: web
+Description-Content-Type: text/markdown
+
+**English** | [日本語](https://github.com/sgtao/yaqpy/blob/main/README.ja.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sgtao/yaqpy/main/logo.svg" alt="yaqpy — YAML and more, Query editor in Python" width="600">
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sgtao/yaqpy/blob/main/LICENSE)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![GitHub release](https://img.shields.io/github/v/release/sgtao/yaqpy.svg)](https://github.com/sgtao/yaqpy/releases)
+
+# yaqpy — YAML and more, Query editor in Python
+
+A lightweight tool to **query, update and convert** YAML, JSON and more with expressions, from the command line or from Python.
+
+- It follows the expression language of the popular CLI tool [mikefarah/yq](https://github.com/mikefarah/yq) (Go, v4.53.6)
+- It is re-implemented with **nothing but the Python standard library**
+- The name stands for **Y**AML **A**nd more, **Q**uery editor in **PY**thon
+
+```console
+$ yaqpy '.server.port' config.yaml
+8080
+$ yaqpy -i '.server.port = 9090' config.yaml     # comments and key order are kept
+```
+
+## Features
+
+- **Keeps your formatting**: comments, key order, anchors (`&` / `*`) and the way numbers and quotes were written (`0x1F`, `1.50`, `'yes'`) survive an update
+- **No dependencies**: all it needs is Python 3.13 or later. The GUI is an optional extra (Flet); the web version adds flet-web
+- **Four ways to use it**: the `yaqpy` command, the Python library (`import yaqpy`), a desktop GUI (`yaqpy-gui`) and the same GUI in a web browser (`yaqpy-web`)
+- **Formats**: YAML, JSON, XML, CSV / TSV, TOML, properties and TOON (a token-saving format for LLMs), both in and out. TOML comments are not kept, so `-i` on TOML is refused by default
+- **Compatible with yq**: 1,091 test scenarios of the Go version are run as compatibility tests (1,047 of the 1,051 comparable ones match). Every operator works except `load` and friends, `eval`, `envsubst`, `system` and `error`
+- **Beyond yq** (not in the Go version):
+  - the input format is detected from the content when the file extension does not tell it
+  - `yaqpy --schema data.yaml` prints a JSON Schema (Draft 2020-12) of the data, as JSON or YAML
+  - `yaqpy --recipe openai-to-gemini request.json` converts request bodies between OpenAI, Gemini and Anthropic, and reports what was dropped, added, or does not fit the target schema (results go to stdout; files are written only with `--apply --out-dir`; no API is called)
+  - yaqpy describes itself for people and AI: `--print-spec` (the operators that work and those that do not), `--example`, `--guide-prompt` (a prompt that lets an AI write yaqpy expressions) and `--skill-md` (a Claude Code skill)
+- **Safe defaults**: as a library, operators that read files or environment variables or run commands are all off. The CLI, like the Go version, allows environment variables and file reads (commands stay off). The web version always turns them off
+
+## Installation
+
+Python 3.13 or later is required.
+
+```bash
+pip install yaqpy                   # the yaqpy command and the library (no dependencies)
+pip install "yaqpy[gui]"            # + the desktop GUI (adds Flet)
+pip install "yaqpy[web]"            # + the GUI in a web browser (adds Flet and flet-web)
+```
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install yaqpy               # install the yaqpy command
+uv tool install "yaqpy[gui,web]"    # ... with what yaqpy-gui and yaqpy-web need
+uvx yaqpy '.server.port' config.yaml   # run it once without installing
+uv add yaqpy                        # use it as a library in a uv project
+```
+
+**From GitHub Releases** (for example, a version that is not on PyPI): pick a version on [Releases](https://github.com/sgtao/yaqpy/releases) and replace `0.6.0` / `v0.6.0` below with it.
+
+```bash
+pip install "yaqpy[gui] @ https://github.com/sgtao/yaqpy/releases/download/v0.6.0/yaqpy-0.6.0-py3-none-any.whl"
+pip install "yaqpy[gui] @ git+https://github.com/sgtao/yaqpy@v0.6.0"
+```
+
+To work on the source, see [DEVELOPMENT.md](https://github.com/sgtao/yaqpy/blob/main/DEVELOPMENT.md) (Japanese).
+
+## Quick start
+
+Take this `config.yaml`:
+
+```yaml
+# server settings
+server:
+  port: 8080 # dev
+  hosts: [a, b]
+items:
+  - {name: pen, price: 120}
+  - {name: book, price: 980}
+```
+
+**Command line**
+
+```bash
+yaqpy '.server.port' config.yaml                              # read -> 8080
+yaqpy '.items[] | select(.price > 500) | .name' config.yaml   # filter -> book
+yaqpy -i '.server.port = 9090' config.yaml                    # update (comments and key order are kept)
+yaqpy -o json '.server' config.yaml                           # convert (yaml / json / xml / csv / tsv / toml / props / toon)
+```
+
+**Python library**
+
+```python
+import yaqpy
+
+yaqpy.evaluate(".server.port", "server:\n  port: 8080\n")        # '8080\n'
+yaqpy.query(".items[] | select(.price > 500)", {"items": [{"price": 1}, {"price": 900}]})   # [{'price': 900}]
+yaqpy.update(".server.port = 9090", {"server": {"port": 8080}})  # {'server': {'port': 9090}}
+```
+
+**GUI**
+
+```bash
+yaqpy-gui                # desktop window (or: yaqpy --gui)
+yaqpy-web                # the same screens in your browser at http://127.0.0.1:8550/ (or: yaqpy --web)
+yaqpy-web --port 9000    # another port; see yaqpy-web --help for the options
+```
+
+The web version listens on this PC only by default and has no authentication. Files are uploaded from the browser and results come back as downloads.
+
+## Documentation
+
+The detailed guides are written in **Japanese**.
+
+| Contents | File |
+|---|---|
+| This README in Japanese | [README.ja.md](https://github.com/sgtao/yaqpy/blob/main/README.ja.md) |
+| The command, each format, JSON Schema output, recipes, the library, the operators, and the differences from Go yq | [USAGE.ja.md](https://github.com/sgtao/yaqpy/blob/main/USAGE.ja.md) |
+| The GUI (desktop and web) | [USAGE-GUI.ja.md](https://github.com/sgtao/yaqpy/blob/main/USAGE-GUI.ja.md) |
+| For developers (setup, design, tests, repository layout) | [DEVELOPMENT.md](https://github.com/sgtao/yaqpy/blob/main/DEVELOPMENT.md) |
+| Changes in each version (features, known limitations) | [CHANGELOG.md](https://github.com/sgtao/yaqpy/blob/main/CHANGELOG.md) |
+
+`yaqpy --help`, `yaqpy-gui --help` and `yaqpy-web --help` are in English.
+
+## License
+
+[MIT License](https://github.com/sgtao/yaqpy/blob/main/LICENSE)
+
+The design and the test scenarios draw on Go yq (MIT); see [NOTICE](https://github.com/sgtao/yaqpy/blob/main/NOTICE).
+
+---
+
+🤖 Built with [Claude Code](https://claude.com/claude-code)

yaqpy-0.6.0/README.md

@@ -0,0 +1,132 @@
+**English** | [日本語](https://github.com/sgtao/yaqpy/blob/main/README.ja.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sgtao/yaqpy/main/logo.svg" alt="yaqpy — YAML and more, Query editor in Python" width="600">
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sgtao/yaqpy/blob/main/LICENSE)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![GitHub release](https://img.shields.io/github/v/release/sgtao/yaqpy.svg)](https://github.com/sgtao/yaqpy/releases)
+
+# yaqpy — YAML and more, Query editor in Python
+
+A lightweight tool to **query, update and convert** YAML, JSON and more with expressions, from the command line or from Python.
+
+- It follows the expression language of the popular CLI tool [mikefarah/yq](https://github.com/mikefarah/yq) (Go, v4.53.6)
+- It is re-implemented with **nothing but the Python standard library**
+- The name stands for **Y**AML **A**nd more, **Q**uery editor in **PY**thon
+
+```console
+$ yaqpy '.server.port' config.yaml
+8080
+$ yaqpy -i '.server.port = 9090' config.yaml     # comments and key order are kept
+```
+
+## Features
+
+- **Keeps your formatting**: comments, key order, anchors (`&` / `*`) and the way numbers and quotes were written (`0x1F`, `1.50`, `'yes'`) survive an update
+- **No dependencies**: all it needs is Python 3.13 or later. The GUI is an optional extra (Flet); the web version adds flet-web
+- **Four ways to use it**: the `yaqpy` command, the Python library (`import yaqpy`), a desktop GUI (`yaqpy-gui`) and the same GUI in a web browser (`yaqpy-web`)
+- **Formats**: YAML, JSON, XML, CSV / TSV, TOML, properties and TOON (a token-saving format for LLMs), both in and out. TOML comments are not kept, so `-i` on TOML is refused by default
+- **Compatible with yq**: 1,091 test scenarios of the Go version are run as compatibility tests (1,047 of the 1,051 comparable ones match). Every operator works except `load` and friends, `eval`, `envsubst`, `system` and `error`
+- **Beyond yq** (not in the Go version):
+  - the input format is detected from the content when the file extension does not tell it
+  - `yaqpy --schema data.yaml` prints a JSON Schema (Draft 2020-12) of the data, as JSON or YAML
+  - `yaqpy --recipe openai-to-gemini request.json` converts request bodies between OpenAI, Gemini and Anthropic, and reports what was dropped, added, or does not fit the target schema (results go to stdout; files are written only with `--apply --out-dir`; no API is called)
+  - yaqpy describes itself for people and AI: `--print-spec` (the operators that work and those that do not), `--example`, `--guide-prompt` (a prompt that lets an AI write yaqpy expressions) and `--skill-md` (a Claude Code skill)
+- **Safe defaults**: as a library, operators that read files or environment variables or run commands are all off. The CLI, like the Go version, allows environment variables and file reads (commands stay off). The web version always turns them off
+
+## Installation
+
+Python 3.13 or later is required.
+
+```bash
+pip install yaqpy                   # the yaqpy command and the library (no dependencies)
+pip install "yaqpy[gui]"            # + the desktop GUI (adds Flet)
+pip install "yaqpy[web]"            # + the GUI in a web browser (adds Flet and flet-web)
+```
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install yaqpy               # install the yaqpy command
+uv tool install "yaqpy[gui,web]"    # ... with what yaqpy-gui and yaqpy-web need
+uvx yaqpy '.server.port' config.yaml   # run it once without installing
+uv add yaqpy                        # use it as a library in a uv project
+```
+
+**From GitHub Releases** (for example, a version that is not on PyPI): pick a version on [Releases](https://github.com/sgtao/yaqpy/releases) and replace `0.6.0` / `v0.6.0` below with it.
+
+```bash
+pip install "yaqpy[gui] @ https://github.com/sgtao/yaqpy/releases/download/v0.6.0/yaqpy-0.6.0-py3-none-any.whl"
+pip install "yaqpy[gui] @ git+https://github.com/sgtao/yaqpy@v0.6.0"
+```
+
+To work on the source, see [DEVELOPMENT.md](https://github.com/sgtao/yaqpy/blob/main/DEVELOPMENT.md) (Japanese).
+
+## Quick start
+
+Take this `config.yaml`:
+
+```yaml
+# server settings
+server:
+  port: 8080 # dev
+  hosts: [a, b]
+items:
+  - {name: pen, price: 120}
+  - {name: book, price: 980}
+```
+
+**Command line**
+
+```bash
+yaqpy '.server.port' config.yaml                              # read -> 8080
+yaqpy '.items[] | select(.price > 500) | .name' config.yaml   # filter -> book
+yaqpy -i '.server.port = 9090' config.yaml                    # update (comments and key order are kept)
+yaqpy -o json '.server' config.yaml                           # convert (yaml / json / xml / csv / tsv / toml / props / toon)
+```
+
+**Python library**
+
+```python
+import yaqpy
+
+yaqpy.evaluate(".server.port", "server:\n  port: 8080\n")        # '8080\n'
+yaqpy.query(".items[] | select(.price > 500)", {"items": [{"price": 1}, {"price": 900}]})   # [{'price': 900}]
+yaqpy.update(".server.port = 9090", {"server": {"port": 8080}})  # {'server': {'port': 9090}}
+```
+
+**GUI**
+
+```bash
+yaqpy-gui                # desktop window (or: yaqpy --gui)
+yaqpy-web                # the same screens in your browser at http://127.0.0.1:8550/ (or: yaqpy --web)
+yaqpy-web --port 9000    # another port; see yaqpy-web --help for the options
+```
+
+The web version listens on this PC only by default and has no authentication. Files are uploaded from the browser and results come back as downloads.
+
+## Documentation
+
+The detailed guides are written in **Japanese**.
+
+| Contents | File |
+|---|---|
+| This README in Japanese | [README.ja.md](https://github.com/sgtao/yaqpy/blob/main/README.ja.md) |
+| The command, each format, JSON Schema output, recipes, the library, the operators, and the differences from Go yq | [USAGE.ja.md](https://github.com/sgtao/yaqpy/blob/main/USAGE.ja.md) |
+| The GUI (desktop and web) | [USAGE-GUI.ja.md](https://github.com/sgtao/yaqpy/blob/main/USAGE-GUI.ja.md) |
+| For developers (setup, design, tests, repository layout) | [DEVELOPMENT.md](https://github.com/sgtao/yaqpy/blob/main/DEVELOPMENT.md) |
+| Changes in each version (features, known limitations) | [CHANGELOG.md](https://github.com/sgtao/yaqpy/blob/main/CHANGELOG.md) |
+
+`yaqpy --help`, `yaqpy-gui --help` and `yaqpy-web --help` are in English.
+
+## License
+
+[MIT License](https://github.com/sgtao/yaqpy/blob/main/LICENSE)
+
+The design and the test scenarios draw on Go yq (MIT); see [NOTICE](https://github.com/sgtao/yaqpy/blob/main/NOTICE).
+
+---
+
+🤖 Built with [Claude Code](https://claude.com/claude-code)

yaqpy-0.6.0/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "yaqpy"
+version = "0.6.0"
+description = "YAML and more—Query editor in Python: query, update and convert YAML / JSON / XML / CSV / TOML / properties / TOON with the mikefarah/yq expression language, in pure Python (stdlib only)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "sgtao" }]
+keywords = ["yaml", "json", "xml", "csv", "toml", "toon", "yq", "jq", "query", "cli", "json-schema"]
+requires-python = ">=3.13"
+dependencies = []
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Markup",
+  "Topic :: Utilities",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/sgtao/yaqpy"
+Repository = "https://github.com/sgtao/yaqpy"
+Documentation = "https://github.com/sgtao/yaqpy/blob/main/USAGE.ja.md"
+Changelog = "https://github.com/sgtao/yaqpy/blob/main/CHANGELOG.md"
+Issues = "https://github.com/sgtao/yaqpy/issues"
+
+[project.scripts]
+yaqpy = "yaqpy.cli.main:main"
+yaqpy-gui = "yaqpy.gui.app:cli_entry"
+yaqpy-web = "yaqpy.gui.app:web_cli_entry"
+
+[project.optional-dependencies]
+gui = [
+    "flet>=1.0,<2",
+]
+web = [
+    "flet[web]>=1.0,<2",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "python-toon>=0.1.3",
+    "tzdata>=2026.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+# The test classes are named XxxTests (and a few TestXxx); helper base classes such as CliTestCase
+# match neither, so they are not collected.
+python_classes = ["Test*", "*Tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+timeout = 300
+markers = [
+    "golden: scenarios taken from the Go yq tests (tests/golden)",
+    "acceptance: runs the CLI in a subprocess (tests/acceptance)",
+    "gui: needs the optional Flet package",
+    "slow: takes several seconds",
+]
+
+[tool.coverage.run]
+source = ["yaqpy"]
+branch = true
+patch = ["subprocess"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    '^\s*\.\.\.$',
+]

yaqpy-0.6.0/src/yaqpy/__init__.py

@@ -0,0 +1,40 @@
+"""yaqpy - a pure-Python (standard library only) implementation of mikefarah/yq.
+
+>>> import yaqpy
+>>> yaqpy.evaluate(".a.b", "a:\\n  b: 3\\n")
+'3\\n'
+>>> yaqpy.query(".items[] | select(. > 1)", {"items": [1, 2, 3]})
+[2, 3]
+"""
+
+from yaqpy.api import (
+    Yq, apply_recipe, compile, detect_format, dump, evaluate, evaluate_all, list_recipes, load,
+    query, update,
+)
+from yaqpy.app.recipe_service import RecipeRun
+from yaqpy.core.lang.parser import Expression
+from yaqpy.core.model.node import Kind, Node, Style
+from yaqpy.errors import (
+    EvaluationError, EvaluationLimitError, ExpressionSyntaxError, FormatError, RecipeError,
+    SecurityError, UnknownFormatError, YamlSyntaxError, YqError,
+)
+from yaqpy.options import (
+    CsvOptions, JsonOptions, Limits, Options, PropertiesOptions, SchemaOptions, SecurityPolicy,
+    TomlOptions, ToonOptions, XmlOptions, YamlOptions,
+)
+from yaqpy.recipes import Recipe, build_recipe
+from yaqpy.recipes.analysis import RecipeReport
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "Yq", "compile", "dump", "evaluate", "evaluate_all", "load", "query", "update",
+    "apply_recipe", "list_recipes", "build_recipe", "Recipe", "RecipeReport", "RecipeRun",
+    "detect_format",
+    "Expression", "Kind", "Node", "Style",
+    "EvaluationError", "EvaluationLimitError", "ExpressionSyntaxError", "FormatError", "RecipeError",
+    "SecurityError", "UnknownFormatError", "YamlSyntaxError", "YqError",
+    "CsvOptions", "JsonOptions", "Limits", "Options", "PropertiesOptions", "SchemaOptions",
+    "SecurityPolicy", "TomlOptions", "ToonOptions", "XmlOptions", "YamlOptions",
+    "__version__",
+]

yaqpy-0.6.0/src/yaqpy/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m yaqpy`` entry point."""
+
+import sys
+
+from yaqpy.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

yaqpy-0.6.0/src/yaqpy/api.py

@@ -0,0 +1,189 @@
+"""Public library API (design doc section 10)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from datetime import datetime
+from typing import Any
+
+from yaqpy.app.dto import EvalMode, EvaluateRequest, InputSource
+from yaqpy.app.ports import SandboxFileSystem, StaticEnvironment
+from yaqpy.app.printer import MemorySink
+from yaqpy.app.recipe_service import RecipeRun, RecipeService
+from yaqpy.app.service import YqService
+from yaqpy.core.lang.parser import Expression
+from yaqpy.core.model.convert import from_python, to_python
+from yaqpy.core.model.node import Node
+from yaqpy.core.operators import OperatorRegistry, builtin_registry
+from yaqpy.formats.registry import FormatRegistry, builtin_formats
+from yaqpy.options import Options
+from yaqpy.recipes import Recipe, builtin_recipes
+
+
+class Yq:
+    """Stateless facade. Safe to share between threads."""
+
+    def __init__(
+        self,
+        options: Options | None = None,
+        *,
+        operators: OperatorRegistry | None = None,
+        formats: FormatRegistry | None = None,
+        environ: Mapping[str, str] | None = None,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.options = options or Options()
+        if environ is None:
+            import os
+
+            environ = os.environ
+        self._service = YqService(
+            SandboxFileSystem(), StaticEnvironment(environ),
+            operators=operators or builtin_registry(), formats=formats or builtin_formats(),
+            clock=clock,
+        )
+
+    # ------------------------------------------------------------------ compile
+
+    def compile(self, expression: str) -> Expression:
+        return self._service.compile(expression)
+
+    # ------------------------------------------------------------------ text in / text out
+
+    def _request(self, expression: str | Expression, texts: Iterable[str], mode: EvalMode,
+                 options: Options | None) -> EvaluateRequest:
+        source = expression.source if isinstance(expression, Expression) else expression
+        inputs = tuple(InputSource("<text>", text) for text in texts)
+        return EvaluateRequest(expression=source, inputs=inputs, mode=mode,
+                               options=options or self.options)
+
+    def evaluate(self, expression: str | Expression, text: str = "", *,
+                 options: Options | None = None) -> str:
+        request = self._request(expression, [text] if text != "" else [], EvalMode.STREAM, options)
+        result = self._service.evaluate(request, MemorySink())
+        return result.output or ""
+
+    def evaluate_all(self, expression: str | Expression, texts: Iterable[str], *,
+                     options: Options | None = None) -> str:
+        request = self._request(expression, texts, EvalMode.ALL, options)
+        result = self._service.evaluate(request, MemorySink())
+        return result.output or ""
+
+    # ------------------------------------------------------------------ nodes / python objects
+
+    def evaluate_nodes(self, expression: str | Expression, documents: Sequence[Node], *,
+                       options: Options | None = None) -> list[Node]:
+        return self._service.evaluate_nodes(expression, documents, options or self.options)
+
+    def iter_results(self, expression: str | Expression, text: str, *,
+                     options: Options | None = None) -> Iterator[Node]:
+        options = options or self.options
+        decoder = self._service.formats.decoder_for(options.input_format, options)
+        for doc in decoder.decode_documents(text):
+            yield from self.evaluate_nodes(expression, [doc], options=options)
+
+    def query(self, expression: str | Expression, data: Any, *,
+              options: Options | None = None) -> list[Any]:
+        root = from_python(data)
+        root.evaluate_together = True
+        results = self.evaluate_nodes(expression, [root], options=options)
+        return [to_python(n) for n in results]
+
+    def update(self, expression: str | Expression, data: Any, *,
+               options: Options | None = None) -> Any:
+        root = from_python(data)
+        root.evaluate_together = True
+        self.evaluate_nodes(expression, [root], options=options)
+        return to_python(root)
+
+    def load(self, text: str, *, format: str = "yaml", options: Options | None = None) -> list[Node]:
+        options = options or self.options
+        decoder = self._service.formats.decoder_for(format, options)
+        return list(decoder.decode_documents(text))
+
+    def dump(self, documents: Iterable[Node], *, format: str = "yaml",
+             options: Options | None = None) -> str:
+        from yaqpy.app.printer import ResultPrinter
+
+        options = options or self.options
+        spec = self._service.formats.get(format)
+        unwrap = options.unwrap_scalar if options.unwrap_scalar is not None else spec.unwrap_scalar_default
+        encoder = self._service.formats.encoder_for(format, options, unwrap)
+        sink = MemorySink()
+        ResultPrinter(encoder, sink).print_results(list(documents))
+        return sink.finish() or ""
+
+
+    # ------------------------------------------------------------------ recipes (a yaqpy extension)
+
+    def apply_recipe(self, recipe: str | Recipe, text: str, *, input_format: str = "json",
+                     output_format: str = "json", prune_null: bool = False, prune_empty: bool = False,
+                     options: Options | None = None) -> RecipeRun:
+        """Convert ``text`` with a recipe: a bundled one by name, or a ``Recipe`` you built.
+
+        Never reads files or environment variables, whatever the options say. The result holds the
+        converted text (``output``) and a ``report`` of what was dropped, added or does not fit the
+        target schema.
+        """
+        service = RecipeService(self._service)
+        if isinstance(recipe, str):
+            recipe = service.load(recipe)
+        return service.run(recipe, InputSource("<text>", text), options or self.options,
+                           input_format=service.input_format_for(recipe, "", input_format),
+                           output_format=service.output_format_for(recipe, output_format),
+                           prune_null=prune_null, prune_empty=prune_empty)
+
+
+_DEFAULT = Yq()
+
+
+def compile(expression: str) -> Expression:  # noqa: A001 - mirrors the design doc
+    return _DEFAULT.compile(expression)
+
+
+def evaluate(expression: str, text: str = "", *, options: Options | None = None) -> str:
+    return _DEFAULT.evaluate(expression, text, options=options)
+
+
+def evaluate_all(expression: str, texts: Iterable[str], *, options: Options | None = None) -> str:
+    return _DEFAULT.evaluate_all(expression, texts, options=options)
+
+
+def query(expression: str, data: Any, *, options: Options | None = None) -> list[Any]:
+    return _DEFAULT.query(expression, data, options=options)
+
+
+def update(expression: str, data: Any, *, options: Options | None = None) -> Any:
+    return _DEFAULT.update(expression, data, options=options)
+
+
+def load(text: str, *, format: str = "yaml", options: Options | None = None) -> list[Node]:
+    return _DEFAULT.load(text, format=format, options=options)
+
+
+def dump(documents: Iterable[Node], *, format: str = "yaml", options: Options | None = None) -> str:
+    return _DEFAULT.dump(documents, format=format, options=options)
+
+
+def detect_format(text: str) -> str:
+    """Guess the format of ``text`` from its content alone (a yaqpy extension; Go yq has no such
+    thing - it only ever looks at a file's extension).
+
+    Meant for text with no filename to go by, or none whose extension names a format: the same
+    guess ``Options(input_format="auto")`` falls back to once a filename's extension gives no
+    answer. Returns a format name ``Options(input_format=...)`` accepts; "yaml" is the fallback
+    when nothing in the content looks confident enough (never an error).
+    """
+    return builtin_formats().guess("", text).name
+
+
+def list_recipes() -> dict[str, Recipe]:
+    """The bundled recipes by name."""
+    return dict(builtin_recipes())
+
+
+def apply_recipe(recipe: str | Recipe, text: str, *, input_format: str = "json",
+                 output_format: str = "json", prune_null: bool = False, prune_empty: bool = False,
+                 options: Options | None = None) -> RecipeRun:
+    return _DEFAULT.apply_recipe(recipe, text, input_format=input_format, output_format=output_format,
+                                 prune_null=prune_null, prune_empty=prune_empty, options=options)