runspec 0.76.2__tar.gz → 0.77.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- runspec-0.77.1/PKG-INFO +130 -0
- runspec-0.77.1/README.md +100 -0
- {runspec-0.76.2 → runspec-0.77.1}/pyproject.toml +6 -7
- {runspec-0.76.2 → runspec-0.77.1}/runspec/cli.py +4 -2
- runspec-0.77.1/runspec/compose.py +245 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/loader.py +31 -1
- runspec-0.77.1/runspec.egg-info/PKG-INFO +130 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/SOURCES.txt +3 -0
- runspec-0.77.1/tests/test_compose.py +418 -0
- runspec-0.76.2/PKG-INFO +0 -29
- runspec-0.76.2/runspec.egg-info/PKG-INFO +0 -29
- {runspec-0.76.2 → runspec-0.77.1}/runspec/__init__.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/ansiblegen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/auditlog.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/become.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/denylist.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/discovery.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/emitutil.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/env.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/errors.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/execute.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/finder.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/inbox.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/inference.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/jump.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/logging_setup.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/logs.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/mock.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/models.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/parser.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/py.typed +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/rebrand.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/rundeckgen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/runexec.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/runsdb.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/runspec.toml +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/schemacheck.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/serve.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/stubgen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/testing.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/types.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec/validator.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/dependency_links.txt +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/entry_points.txt +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/requires.txt +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/runspec.egg-info/top_level.txt +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/setup.cfg +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/__init__.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/conftest.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_agent.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_ansiblegen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_audit.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_become.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_discover.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_emit.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_init.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_cli_test.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_denylist.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_discovery.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_env.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_exec.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_finder.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_inbox.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_inference.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_jump.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_loader.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_log_resilience.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_logging_setup.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_logs.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_mock.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_models.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_parser.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_password.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_rebrand.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_run_as_enforce.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_run_summary.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_rundeckgen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb_events.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_runsdb_sync.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_schemacheck.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_secret_argv.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_serve.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_serve_e2e.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_stubgen.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_testing.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_types.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_typing.py +0 -0
- {runspec-0.76.2 → runspec-0.77.1}/tests/test_validator.py +0 -0
runspec-0.77.1/PKG-INFO
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: runspec
|
|
3
|
+
Version: 0.77.1
|
|
4
|
+
Summary: A language-agnostic, TOML-based interface specification for anything runnable
|
|
5
|
+
Author-email: Jason Finestone <jason@finestone.dev>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://runspec.app
|
|
8
|
+
Project-URL: Documentation, https://runspec.app
|
|
9
|
+
Project-URL: Repository, https://github.com/runspec-app/runspec
|
|
10
|
+
Project-URL: Issues, https://github.com/runspec-app/runspec/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: cli,argparse,arguments,agents,mcp,tools
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Classifier: Topic :: Utilities
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
Requires-Dist: tomli>=2.0; python_version < "3.11"
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest-cov>=5.0; extra == "dev"
|
|
28
|
+
Requires-Dist: ruff==0.15.20; extra == "dev"
|
|
29
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
30
|
+
|
|
31
|
+
# runspec
|
|
32
|
+
|
|
33
|
+
A language-agnostic, TOML-based interface specification for anything runnable:
|
|
34
|
+
scripts, applications and MCP tools, readable by people and AI agents without
|
|
35
|
+
conversion.
|
|
36
|
+
|
|
37
|
+
This is the Python package (the reference implementation). The Node pack is
|
|
38
|
+
[`runspec-node`](https://www.npmjs.com/package/runspec-node).
|
|
39
|
+
Full documentation is at **[runspec.app](https://runspec.app)**.
|
|
40
|
+
|
|
41
|
+
## Why
|
|
42
|
+
|
|
43
|
+
Argument definitions are usually buried in code. When an AI agent needs to call a
|
|
44
|
+
script as a tool, the interface gets described a second time in a separate tool
|
|
45
|
+
or skills file.
|
|
46
|
+
|
|
47
|
+
An interface definition already *is* a tool description. runspec puts it in one
|
|
48
|
+
`runspec.toml` next to your code, and that one file drives argument parsing and
|
|
49
|
+
validation, `--help`, agent tool schemas, forms, and how much an agent may do
|
|
50
|
+
without asking (autonomy).
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install runspec
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Python 3.10+. No runtime dependencies on Python 3.11+ (`tomli` on 3.10).
|
|
59
|
+
|
|
60
|
+
## Quick start
|
|
61
|
+
|
|
62
|
+
Describe the runnable in `mypkg/runspec.toml`, inside your package directory:
|
|
63
|
+
|
|
64
|
+
```toml
|
|
65
|
+
[greet]
|
|
66
|
+
description = "Greet someone from the command line"
|
|
67
|
+
autonomy = "autonomous"
|
|
68
|
+
|
|
69
|
+
[greet.args]
|
|
70
|
+
name = {type = "str"}
|
|
71
|
+
loud = {default = false}
|
|
72
|
+
times = {default = 1}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Read the arguments in your code:
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from runspec import parse
|
|
79
|
+
|
|
80
|
+
def main():
|
|
81
|
+
args = parse()
|
|
82
|
+
message = f"Hello, {args.name.value}!"
|
|
83
|
+
if args.loud.value:
|
|
84
|
+
message = message.upper()
|
|
85
|
+
for _ in range(args.times.value):
|
|
86
|
+
print(message)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Register `greet = "mypkg.greet:main"` as a console script (the entry point name
|
|
90
|
+
matches the runnable name), install the package, and it runs as a normal CLI:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
greet --name Ada --loud --times 2
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
List every runspec runnable in the environment, or serve them to an agent over
|
|
97
|
+
MCP:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
runspec local
|
|
101
|
+
runspec serve
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Features
|
|
105
|
+
|
|
106
|
+
- **Spec first**: write the interface before the implementation.
|
|
107
|
+
- **One call**: `parse()` finds the spec, validates the arguments and returns
|
|
108
|
+
them typed.
|
|
109
|
+
- **Self-describing values**: each argument carries its value plus its type,
|
|
110
|
+
default, options and where the value came from (CLI, environment or default).
|
|
111
|
+
- **Inference**: type, required and choice are inferred from defaults and
|
|
112
|
+
options.
|
|
113
|
+
- **Autonomy control**: declare whether an agent may run a tool freely, must ask
|
|
114
|
+
first, or must leave it to a person.
|
|
115
|
+
- **Agent discovery**: `runspec local` and `runspec serve` expose installed
|
|
116
|
+
runnables as tools.
|
|
117
|
+
- **Run logging and audit** on by default.
|
|
118
|
+
- **Language agnostic**: the same format for Python, Node, shell or anything else.
|
|
119
|
+
|
|
120
|
+
## Links
|
|
121
|
+
|
|
122
|
+
- [Documentation](https://runspec.app)
|
|
123
|
+
- [Format specification](https://github.com/runspec-app/runspec/blob/main/spec/SPEC.md)
|
|
124
|
+
- [Changelog](https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md)
|
|
125
|
+
- [Source](https://github.com/runspec-app/runspec)
|
|
126
|
+
- [runspec-console](https://pypi.org/project/runspec-console/), the desktop console for runspec runnables
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT
|
runspec-0.77.1/README.md
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# runspec
|
|
2
|
+
|
|
3
|
+
A language-agnostic, TOML-based interface specification for anything runnable:
|
|
4
|
+
scripts, applications and MCP tools, readable by people and AI agents without
|
|
5
|
+
conversion.
|
|
6
|
+
|
|
7
|
+
This is the Python package (the reference implementation). The Node pack is
|
|
8
|
+
[`runspec-node`](https://www.npmjs.com/package/runspec-node).
|
|
9
|
+
Full documentation is at **[runspec.app](https://runspec.app)**.
|
|
10
|
+
|
|
11
|
+
## Why
|
|
12
|
+
|
|
13
|
+
Argument definitions are usually buried in code. When an AI agent needs to call a
|
|
14
|
+
script as a tool, the interface gets described a second time in a separate tool
|
|
15
|
+
or skills file.
|
|
16
|
+
|
|
17
|
+
An interface definition already *is* a tool description. runspec puts it in one
|
|
18
|
+
`runspec.toml` next to your code, and that one file drives argument parsing and
|
|
19
|
+
validation, `--help`, agent tool schemas, forms, and how much an agent may do
|
|
20
|
+
without asking (autonomy).
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install runspec
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Python 3.10+. No runtime dependencies on Python 3.11+ (`tomli` on 3.10).
|
|
29
|
+
|
|
30
|
+
## Quick start
|
|
31
|
+
|
|
32
|
+
Describe the runnable in `mypkg/runspec.toml`, inside your package directory:
|
|
33
|
+
|
|
34
|
+
```toml
|
|
35
|
+
[greet]
|
|
36
|
+
description = "Greet someone from the command line"
|
|
37
|
+
autonomy = "autonomous"
|
|
38
|
+
|
|
39
|
+
[greet.args]
|
|
40
|
+
name = {type = "str"}
|
|
41
|
+
loud = {default = false}
|
|
42
|
+
times = {default = 1}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Read the arguments in your code:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from runspec import parse
|
|
49
|
+
|
|
50
|
+
def main():
|
|
51
|
+
args = parse()
|
|
52
|
+
message = f"Hello, {args.name.value}!"
|
|
53
|
+
if args.loud.value:
|
|
54
|
+
message = message.upper()
|
|
55
|
+
for _ in range(args.times.value):
|
|
56
|
+
print(message)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Register `greet = "mypkg.greet:main"` as a console script (the entry point name
|
|
60
|
+
matches the runnable name), install the package, and it runs as a normal CLI:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
greet --name Ada --loud --times 2
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
List every runspec runnable in the environment, or serve them to an agent over
|
|
67
|
+
MCP:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
runspec local
|
|
71
|
+
runspec serve
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Features
|
|
75
|
+
|
|
76
|
+
- **Spec first**: write the interface before the implementation.
|
|
77
|
+
- **One call**: `parse()` finds the spec, validates the arguments and returns
|
|
78
|
+
them typed.
|
|
79
|
+
- **Self-describing values**: each argument carries its value plus its type,
|
|
80
|
+
default, options and where the value came from (CLI, environment or default).
|
|
81
|
+
- **Inference**: type, required and choice are inferred from defaults and
|
|
82
|
+
options.
|
|
83
|
+
- **Autonomy control**: declare whether an agent may run a tool freely, must ask
|
|
84
|
+
first, or must leave it to a person.
|
|
85
|
+
- **Agent discovery**: `runspec local` and `runspec serve` expose installed
|
|
86
|
+
runnables as tools.
|
|
87
|
+
- **Run logging and audit** on by default.
|
|
88
|
+
- **Language agnostic**: the same format for Python, Node, shell or anything else.
|
|
89
|
+
|
|
90
|
+
## Links
|
|
91
|
+
|
|
92
|
+
- [Documentation](https://runspec.app)
|
|
93
|
+
- [Format specification](https://github.com/runspec-app/runspec/blob/main/spec/SPEC.md)
|
|
94
|
+
- [Changelog](https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md)
|
|
95
|
+
- [Source](https://github.com/runspec-app/runspec)
|
|
96
|
+
- [runspec-console](https://pypi.org/project/runspec-console/), the desktop console for runspec runnables
|
|
97
|
+
|
|
98
|
+
## License
|
|
99
|
+
|
|
100
|
+
MIT
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "runspec"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.77.1"
|
|
4
4
|
description = "A language-agnostic, TOML-based interface specification for anything runnable"
|
|
5
5
|
readme = "README.md"
|
|
6
|
-
license =
|
|
6
|
+
license = "MIT"
|
|
7
7
|
authors = [
|
|
8
8
|
{ name = "Jason Finestone", email = "jason@finestone.dev" }
|
|
9
9
|
]
|
|
@@ -12,7 +12,6 @@ keywords = ["cli", "argparse", "arguments", "agents", "mcp", "tools"]
|
|
|
12
12
|
classifiers = [
|
|
13
13
|
"Development Status :: 3 - Alpha",
|
|
14
14
|
"Intended Audience :: Developers",
|
|
15
|
-
"License :: OSI Approved :: MIT License",
|
|
16
15
|
"Programming Language :: Python :: 3",
|
|
17
16
|
"Programming Language :: Python :: 3.10",
|
|
18
17
|
"Programming Language :: Python :: 3.11",
|
|
@@ -41,12 +40,12 @@ runspec = "runspec.cli:main"
|
|
|
41
40
|
[project.urls]
|
|
42
41
|
Homepage = "https://runspec.app"
|
|
43
42
|
Documentation = "https://runspec.app"
|
|
44
|
-
Repository = "https://github.com/
|
|
45
|
-
Issues = "https://github.com/
|
|
46
|
-
Changelog = "https://github.com/
|
|
43
|
+
Repository = "https://github.com/runspec-app/runspec"
|
|
44
|
+
Issues = "https://github.com/runspec-app/runspec/issues"
|
|
45
|
+
Changelog = "https://github.com/runspec-app/runspec/blob/main/CHANGELOG.md"
|
|
47
46
|
|
|
48
47
|
[build-system]
|
|
49
|
-
requires = ["setuptools>=
|
|
48
|
+
requires = ["setuptools>=77.0", "wheel"]
|
|
50
49
|
build-backend = "setuptools.build_meta"
|
|
51
50
|
|
|
52
51
|
|
|
@@ -288,8 +288,10 @@ def _emit_meta(source: str, runnable: str, key: str) -> tuple[dict[str, Any], di
|
|
|
288
288
|
Runnable-level `meta` is a pass-through the loader drops from the normalised
|
|
289
289
|
spec (loader `_normalise_script`), so the emitter reads it straight from the
|
|
290
290
|
raw TOML — keeping every platform-specific setting out of the core spec."""
|
|
291
|
+
from runspec.loader import read_resolved
|
|
292
|
+
|
|
291
293
|
try:
|
|
292
|
-
raw =
|
|
294
|
+
raw = read_resolved(Path(source))
|
|
293
295
|
except Exception:
|
|
294
296
|
return {}, {}
|
|
295
297
|
config_meta = (raw.get("config", {}) or {}).get("meta", {}) or {}
|
|
@@ -1878,7 +1880,7 @@ def _init_claude_md(project_root: Path, pkg_name: str) -> None:
|
|
|
1878
1880
|
path.write_text(
|
|
1879
1881
|
"# AI Context\n"
|
|
1880
1882
|
"\n"
|
|
1881
|
-
"This project uses [runspec](https://github.com/
|
|
1883
|
+
"This project uses [runspec](https://github.com/runspec-app/runspec) for CLI interfaces.\n"
|
|
1882
1884
|
"\n"
|
|
1883
1885
|
"## Key files\n"
|
|
1884
1886
|
f"- `{pkg_name}/runspec.toml` — defines runnables: args, types, autonomy levels\n"
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
"""
|
|
2
|
+
compose.py — resolve ``include`` and ``shared-args`` in a parsed runspec.toml.
|
|
3
|
+
|
|
4
|
+
Two authoring features that let a big ``runspec.toml`` be split up and stop
|
|
5
|
+
repeating itself. Both are resolved here, on the raw TOML dict, *before* the
|
|
6
|
+
loader normalises it, so every later stage (inference, validation, ``--help``,
|
|
7
|
+
``serve``, stubs, emit, the console) sees an ordinary single-file spec.
|
|
8
|
+
|
|
9
|
+
``include``
|
|
10
|
+
A runnable or command table may say ``include = "path/to/file.toml"``. The
|
|
11
|
+
file holds that table's body (``description``, ``args``, ``commands``, …,
|
|
12
|
+
with no ``[runnable.commands.x]`` prefix) and is merged into the table. The
|
|
13
|
+
path is relative to the file that names it and must stay inside the
|
|
14
|
+
directory holding ``runspec.toml``. Included files may include others; a
|
|
15
|
+
cycle is an error, and the chain is capped at ``MAX_INCLUDE_DEPTH`` files.
|
|
16
|
+
A key set both in the table and in the included file is an error.
|
|
17
|
+
|
|
18
|
+
``shared-args`` / ``use``
|
|
19
|
+
``[config.shared-args]``, ``[<runnable>.shared-args]`` and
|
|
20
|
+
``[<…>.commands.<c>.shared-args]`` define args once. An arg written as
|
|
21
|
+
``project = {use = "project"}`` takes that definition; any other keys next
|
|
22
|
+
to ``use`` override it. The nearest definition wins (the command's own,
|
|
23
|
+
then each parent up to the runnable, then ``[config]``). A definition can't
|
|
24
|
+
itself contain ``use``.
|
|
25
|
+
|
|
26
|
+
The functions are pure: file access goes through a ``reader`` callback that
|
|
27
|
+
takes a path relative to the ``runspec.toml`` directory (POSIX ``/``
|
|
28
|
+
separators) and returns the file's text, or ``None`` when it doesn't exist —
|
|
29
|
+
so the console can resolve a spec it fetched over SSH without a filesystem.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import copy
|
|
35
|
+
import difflib
|
|
36
|
+
import posixpath
|
|
37
|
+
import sys
|
|
38
|
+
from collections.abc import Callable
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
from typing import Any
|
|
41
|
+
|
|
42
|
+
if sys.version_info >= (3, 11):
|
|
43
|
+
import tomllib
|
|
44
|
+
else:
|
|
45
|
+
import tomli as tomllib # type: ignore[no-redef]
|
|
46
|
+
|
|
47
|
+
Reader = Callable[[str], "str | None"]
|
|
48
|
+
|
|
49
|
+
ROOT_FILE = "runspec.toml"
|
|
50
|
+
MAX_INCLUDE_DEPTH = 8
|
|
51
|
+
SHARED_ARGS_KEY = "shared-args"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def resolve(data: dict[str, Any], reader: Reader | None = None, source: str = ROOT_FILE) -> dict[str, Any]:
|
|
55
|
+
"""Return a copy of ``data`` with every ``include`` and ``use`` resolved and
|
|
56
|
+
every ``shared-args`` table removed.
|
|
57
|
+
|
|
58
|
+
A file that uses neither feature comes back equal to ``data``.
|
|
59
|
+
|
|
60
|
+
Args:
|
|
61
|
+
data: the parsed ``runspec.toml``.
|
|
62
|
+
reader: reads an included file by its package-relative POSIX path;
|
|
63
|
+
returns ``None`` when the file doesn't exist. Without a reader
|
|
64
|
+
an ``include`` is an error.
|
|
65
|
+
source: the package-relative name of the file ``data`` came from.
|
|
66
|
+
|
|
67
|
+
Raises:
|
|
68
|
+
ValueError: a bad include path, a missing or malformed included file,
|
|
69
|
+
a cycle, a key defined twice, or an unknown ``use`` name.
|
|
70
|
+
"""
|
|
71
|
+
out = copy.deepcopy(data)
|
|
72
|
+
for name, table in out.items():
|
|
73
|
+
if name == "config" or not isinstance(table, dict):
|
|
74
|
+
continue
|
|
75
|
+
_resolve_includes(table, f"[{name}]", source, reader, (source,))
|
|
76
|
+
_resolve_uses(out)
|
|
77
|
+
return out
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def has_include(text: str) -> bool:
|
|
81
|
+
"""Cheap textual check: could this runspec.toml text use ``include``?
|
|
82
|
+
|
|
83
|
+
Used by the console to decide whether a scanned file needs its fragments.
|
|
84
|
+
False positives are harmless (a key named ``include`` inside ``args`` …).
|
|
85
|
+
"""
|
|
86
|
+
for line in text.splitlines():
|
|
87
|
+
stripped = line.lstrip()
|
|
88
|
+
if stripped.startswith("include") and stripped[len("include") :].lstrip().startswith("="):
|
|
89
|
+
return True
|
|
90
|
+
return False
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def fs_reader(root: Path) -> Reader:
|
|
94
|
+
"""A reader over the real filesystem, rooted at the ``runspec.toml`` directory.
|
|
95
|
+
|
|
96
|
+
Refuses a path that resolves outside ``root`` (a symlink pointing out of the
|
|
97
|
+
package), so a wheel can only include its own files.
|
|
98
|
+
"""
|
|
99
|
+
base = root.resolve()
|
|
100
|
+
|
|
101
|
+
def read(rel: str) -> str | None:
|
|
102
|
+
target = (base / rel).resolve()
|
|
103
|
+
if target != base and base not in target.parents:
|
|
104
|
+
raise ValueError(f"✗ include '{rel}' resolves outside the package directory ({base}).")
|
|
105
|
+
if not target.is_file():
|
|
106
|
+
return None
|
|
107
|
+
return target.read_text(encoding="utf-8")
|
|
108
|
+
|
|
109
|
+
return read
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
# ── include ────────────────────────────────────────────────────────────────────
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _include_path(value: Any, cur_file: str, where: str) -> str:
|
|
116
|
+
"""The package-relative POSIX path an ``include`` value points at."""
|
|
117
|
+
if not isinstance(value, str) or not value.strip():
|
|
118
|
+
raise ValueError(f'✗ {where} include must be a path string, e.g. include = "commands/deploy.toml".')
|
|
119
|
+
raw = value.strip()
|
|
120
|
+
if "\\" in raw:
|
|
121
|
+
raise ValueError(f"✗ {where} include '{raw}': use '/' in include paths, not '\\'.")
|
|
122
|
+
if raw.startswith("/") or (len(raw) > 1 and raw[1] == ":"):
|
|
123
|
+
raise ValueError(f"✗ {where} include '{raw}' must be a relative path inside the package directory.")
|
|
124
|
+
if not raw.endswith(".toml"):
|
|
125
|
+
raise ValueError(f"✗ {where} include '{raw}' must name a .toml file.")
|
|
126
|
+
rel = posixpath.normpath(posixpath.join(posixpath.dirname(cur_file), raw))
|
|
127
|
+
if rel == ".." or rel.startswith("../"):
|
|
128
|
+
raise ValueError(f"✗ {where} include '{raw}' (in {cur_file}) points outside the package directory.")
|
|
129
|
+
return rel
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _read_fragment(rel: str, reader: Reader | None, where: str, cur_file: str) -> dict[str, Any]:
|
|
133
|
+
if reader is None:
|
|
134
|
+
raise ValueError(f"✗ {where} include '{rel}' can't be read here (no file access).")
|
|
135
|
+
text = reader(rel)
|
|
136
|
+
if text is None:
|
|
137
|
+
raise ValueError(f"✗ {where} include '{rel}' (named in {cur_file}) was not found.\n Is the file shipped in the package?")
|
|
138
|
+
try:
|
|
139
|
+
frag = tomllib.loads(text)
|
|
140
|
+
except tomllib.TOMLDecodeError as e:
|
|
141
|
+
raise ValueError(f"✗ {rel} is not valid TOML: {e}") from e
|
|
142
|
+
return frag
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def _resolve_includes(
|
|
146
|
+
table: dict[str, Any],
|
|
147
|
+
where: str,
|
|
148
|
+
cur_file: str,
|
|
149
|
+
reader: Reader | None,
|
|
150
|
+
stack: tuple[str, ...],
|
|
151
|
+
) -> None:
|
|
152
|
+
"""Merge every ``include`` into ``table`` (in place), then recurse into its commands.
|
|
153
|
+
|
|
154
|
+
``cur_file`` is the file ``table`` was written in; ``stack`` is the chain of
|
|
155
|
+
files from ``runspec.toml`` down to here, for cycle detection.
|
|
156
|
+
"""
|
|
157
|
+
origin = dict.fromkeys(table, cur_file) # key → file it came from
|
|
158
|
+
file = cur_file
|
|
159
|
+
while "include" in table:
|
|
160
|
+
rel = _include_path(table.pop("include"), file, where)
|
|
161
|
+
if rel in stack:
|
|
162
|
+
chain = " → ".join((*stack[stack.index(rel) :], rel))
|
|
163
|
+
raise ValueError(f"✗ {where} include cycle: {chain}")
|
|
164
|
+
if len(stack) > MAX_INCLUDE_DEPTH:
|
|
165
|
+
raise ValueError(f"✗ {where} includes are nested more than {MAX_INCLUDE_DEPTH} files deep: {' → '.join((*stack, rel))}")
|
|
166
|
+
frag = _read_fragment(rel, reader, where, file)
|
|
167
|
+
dupes = sorted(k for k in frag if k in table)
|
|
168
|
+
if dupes:
|
|
169
|
+
keys = ", ".join(dupes)
|
|
170
|
+
raise ValueError(f"✗ {where} sets {keys} both in {origin[dupes[0]]} and in its include {rel}.\n Set each key in one place.")
|
|
171
|
+
table.update(frag)
|
|
172
|
+
origin.update(dict.fromkeys(frag, rel))
|
|
173
|
+
stack = (*stack, rel)
|
|
174
|
+
file = rel
|
|
175
|
+
|
|
176
|
+
commands = table.get("commands")
|
|
177
|
+
if isinstance(commands, dict):
|
|
178
|
+
cmd_file = origin.get("commands", file)
|
|
179
|
+
for name, sub in commands.items():
|
|
180
|
+
if isinstance(sub, dict):
|
|
181
|
+
_resolve_includes(sub, f"{where[:-1]}.commands.{name}]", cmd_file, reader, stack)
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
# ── shared-args / use ──────────────────────────────────────────────────────────
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def _shared_defs(raw: Any, where: str) -> dict[str, dict[str, Any]]:
|
|
188
|
+
if raw is None:
|
|
189
|
+
return {}
|
|
190
|
+
if not isinstance(raw, dict):
|
|
191
|
+
raise ValueError(f"✗ {where} must be a table of arg definitions.")
|
|
192
|
+
defs: dict[str, dict[str, Any]] = {}
|
|
193
|
+
for name, value in raw.items():
|
|
194
|
+
definition = value if isinstance(value, dict) else {"default": value}
|
|
195
|
+
if "use" in definition:
|
|
196
|
+
raise ValueError(f"✗ {where} {name}: a shared arg can't itself use another one.")
|
|
197
|
+
defs[name] = definition
|
|
198
|
+
return defs
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def _resolve_uses(data: dict[str, Any]) -> None:
|
|
202
|
+
config = data.get("config")
|
|
203
|
+
scopes: list[dict[str, dict[str, Any]]] = []
|
|
204
|
+
if isinstance(config, dict):
|
|
205
|
+
scopes.append(_shared_defs(config.pop(SHARED_ARGS_KEY, None), f"[config.{SHARED_ARGS_KEY}]"))
|
|
206
|
+
for name, table in data.items():
|
|
207
|
+
if name == "config" or not isinstance(table, dict):
|
|
208
|
+
continue
|
|
209
|
+
_resolve_uses_table(table, f"[{name}]", scopes)
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _resolve_uses_table(table: dict[str, Any], where: str, scopes: list[dict[str, dict[str, Any]]]) -> None:
|
|
213
|
+
if SHARED_ARGS_KEY in table:
|
|
214
|
+
scopes = [*scopes, _shared_defs(table.pop(SHARED_ARGS_KEY), f"{where[:-1]}.{SHARED_ARGS_KEY}]")]
|
|
215
|
+
args = table.get("args")
|
|
216
|
+
if isinstance(args, dict):
|
|
217
|
+
for arg_name, value in args.items():
|
|
218
|
+
if isinstance(value, dict) and "use" in value:
|
|
219
|
+
args[arg_name] = _use(value, arg_name, where, scopes)
|
|
220
|
+
commands = table.get("commands")
|
|
221
|
+
if isinstance(commands, dict):
|
|
222
|
+
for name, sub in commands.items():
|
|
223
|
+
if isinstance(sub, dict):
|
|
224
|
+
_resolve_uses_table(sub, f"{where[:-1]}.commands.{name}]", scopes)
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _use(value: dict[str, Any], arg_name: str, where: str, scopes: list[dict[str, dict[str, Any]]]) -> dict[str, Any]:
|
|
228
|
+
ref = value["use"]
|
|
229
|
+
if not isinstance(ref, str) or not ref:
|
|
230
|
+
raise ValueError(f'✗ {where} arg {arg_name}: use must name a shared arg, e.g. {{use = "{arg_name}"}}.')
|
|
231
|
+
for defs in reversed(scopes):
|
|
232
|
+
if ref in defs:
|
|
233
|
+
merged: dict[str, Any] = copy.deepcopy(defs[ref])
|
|
234
|
+
merged.update({k: v for k, v in value.items() if k != "use"})
|
|
235
|
+
return merged
|
|
236
|
+
known = sorted({n for defs in scopes for n in defs})
|
|
237
|
+
hint = ""
|
|
238
|
+
close = difflib.get_close_matches(ref, known, n=1)
|
|
239
|
+
if close:
|
|
240
|
+
hint = f"\n Did you mean '{close[0]}'?"
|
|
241
|
+
elif known:
|
|
242
|
+
hint = f"\n Shared args in scope: {', '.join(known)}"
|
|
243
|
+
else:
|
|
244
|
+
hint = f"\n No [{SHARED_ARGS_KEY}] table is in scope here."
|
|
245
|
+
raise ValueError(f"✗ {where} arg {arg_name}: unknown shared arg '{ref}'.{hint}")
|
|
@@ -20,11 +20,17 @@ if sys.version_info >= (3, 11):
|
|
|
20
20
|
else:
|
|
21
21
|
import tomli as tomllib # type: ignore[no-redef]
|
|
22
22
|
|
|
23
|
+
from runspec.compose import Reader, fs_reader, resolve
|
|
24
|
+
|
|
23
25
|
|
|
24
26
|
def load_raw(config_path: Path) -> dict[str, Any]:
|
|
25
27
|
"""
|
|
26
28
|
Read runspec.toml and return the normalised spec dict.
|
|
27
29
|
|
|
30
|
+
``include`` and ``shared-args`` / ``use`` are resolved first (see
|
|
31
|
+
:mod:`runspec.compose`), so the result looks the same as if the spec had
|
|
32
|
+
been written as one file.
|
|
33
|
+
|
|
28
34
|
Args:
|
|
29
35
|
config_path: Path to runspec.toml
|
|
30
36
|
|
|
@@ -32,12 +38,36 @@ def load_raw(config_path: Path) -> dict[str, Any]:
|
|
|
32
38
|
Normalised dict with keys: config, runnables
|
|
33
39
|
|
|
34
40
|
Raises:
|
|
35
|
-
ValueError: if the runspec section is malformed
|
|
41
|
+
ValueError: if the runspec section is malformed, or an include / use
|
|
42
|
+
can't be resolved
|
|
36
43
|
FileNotFoundError: if config_path does not exist
|
|
37
44
|
"""
|
|
45
|
+
return normalise(read_resolved(config_path))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def read_resolved(config_path: Path) -> dict[str, Any]:
|
|
49
|
+
"""Read runspec.toml as a raw TOML dict with ``include`` and ``use`` resolved.
|
|
50
|
+
|
|
51
|
+
For callers that need keys the normaliser drops (e.g. ``meta`` tables).
|
|
52
|
+
"""
|
|
53
|
+
config_path = Path(config_path)
|
|
38
54
|
with open(config_path, "rb") as f:
|
|
39
55
|
data = tomllib.load(f)
|
|
56
|
+
return resolve(data, fs_reader(config_path.parent), config_path.name)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def load_text(text: str, reader: Reader | None = None) -> dict[str, Any]:
|
|
60
|
+
""":func:`load_raw` for runspec.toml *text*.
|
|
61
|
+
|
|
62
|
+
``reader`` reads an included file by its path relative to the runspec.toml
|
|
63
|
+
directory (``None`` when missing); without one, a spec that uses
|
|
64
|
+
``include`` raises ``ValueError``.
|
|
65
|
+
"""
|
|
66
|
+
return normalise(resolve(tomllib.loads(text), reader))
|
|
67
|
+
|
|
40
68
|
|
|
69
|
+
def normalise(data: dict[str, Any]) -> dict[str, Any]:
|
|
70
|
+
"""Normalise a parsed (and resolved) runspec.toml dict."""
|
|
41
71
|
runnables_raw = {key: value for key, value in data.items() if key != "config" and isinstance(value, dict)}
|
|
42
72
|
|
|
43
73
|
return {
|