Skip to content

Commit f8247b4

Browse files
RonnyPfannschmidtCursor AIclaude
committed
Add --allow-recursion CLI flag for recursive $ref specs (#124)
Add --allow-recursion/--no-allow-recursion flag to the validate and compile CLI commands, wiring through keep_ref_on_recursion as the recursion_limit_handler when enabled. This allows specs with self-referencing $ref (e.g. recursive types like linked lists or trees) to be processed without raising ResolutionError. Co-authored-by: Cursor AI <[email protected]> Co-authored-by: Anthropic Claude Opus 4.6 <[email protected]>
1 parent 318aed9 commit f8247b4

4 files changed

Lines changed: 72 additions & 4 deletions

File tree

‎changelog.d/124.feature.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add ``--allow-recursion`` CLI flag to ``validate`` and ``compile`` commands,
2+
allowing specs with self-referencing ``$ref`` (e.g. recursive types like
3+
linked lists or trees) to be processed without raising ``ResolutionError``.

‎prance/cli.py‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,14 @@ def __write_to_file(filename, specs): # noqa: N802
2424
fs.write_file(filename, contents)
2525

2626

27-
def __parser_for_url(url, resolve, backend, strict, encoding): # noqa: N802
27+
def __parser_for_url( # noqa: N802
28+
url: str,
29+
resolve: bool,
30+
backend: str,
31+
strict: bool,
32+
encoding: str | None,
33+
allow_recursion: bool = False,
34+
) -> tuple:
2835
"""Return a parser instance for the URL and the given parameters."""
2936
# Try the URL
3037
formatted = click.format_filename(url)
@@ -42,9 +49,15 @@ def __parser_for_url(url, resolve, backend, strict, encoding): # noqa: N802
4249
parser = None
4350
if resolve:
4451
click.echo(" -> Resolving external references.")
45-
parser = prance.ResolvingParser(
46-
url, lazy=True, backend=backend, strict=strict, encoding=encoding
52+
kwargs: dict = dict(
53+
lazy=True, backend=backend, strict=strict, encoding=encoding
4754
)
55+
if allow_recursion:
56+
from prance.util.resolver import keep_ref_on_recursion
57+
58+
kwargs["recursion_limit_handler"] = keep_ref_on_recursion
59+
click.echo(" -> Allowing recursive references (will be kept as $ref).")
60+
parser = prance.ResolvingParser(url, **kwargs)
4861
else:
4962
click.echo(" -> Not resolving external references.")
5063
parser = prance.BaseParser(
@@ -144,12 +157,19 @@ def command_invoke(ctx):
144157
help="If given, override file encoding detection and use the given "
145158
"encoding for all files. Does not work on remote URLs.",
146159
)
160+
@click.option(
161+
"--allow-recursion/--no-allow-recursion",
162+
default=False,
163+
help="When resolving, keep recursive $ref entries in place instead of "
164+
"raising an error. Useful for specs with self-referencing schemas.",
165+
)
147166
@click.pass_context
148-
def backend_options(ctx, resolve, backend, strict, encoding):
167+
def backend_options(ctx, resolve, backend, strict, encoding, allow_recursion):
149168
ctx.obj["resolve"] = resolve
150169
ctx.obj["backend"] = backend
151170
ctx.obj["strict"] = strict
152171
ctx.obj["encoding"] = encoding
172+
ctx.obj["allow_recursion"] = allow_recursion
153173

154174

155175
@backend_options.command()
@@ -203,6 +223,7 @@ def validate(ctx, output_file, urls):
203223
ctx.obj["backend"],
204224
ctx.obj["strict"],
205225
ctx.obj["encoding"],
226+
ctx.obj["allow_recursion"],
206227
)
207228

208229
# Try parsing
@@ -243,6 +264,7 @@ def compile(ctx, url_or_path, output_file):
243264
ctx.obj["backend"],
244265
ctx.obj["strict"],
245266
ctx.obj["encoding"],
267+
ctx.obj["allow_recursion"],
246268
)
247269

248270
# Try parsing

‎tests/specs/self_recursive.yaml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
swagger: "2.0"
2+
info:
3+
version: 1.0.0
4+
title: Self-recursive spec
5+
basePath: /v1
6+
paths:
7+
/files:
8+
get:
9+
summary: List files
10+
operationId: listFiles
11+
responses:
12+
"200":
13+
description: A file
14+
schema:
15+
$ref: '#/definitions/File'
16+
definitions:
17+
File:
18+
type: object
19+
properties:
20+
name:
21+
type: string
22+
parent:
23+
$ref: '#/definitions/File'

‎tests/test_cli.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,26 @@ def test_validate_output(runner):
115115
assert result.exit_code == 0
116116

117117

118+
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
119+
def test_validate_recursive_fails_by_default(runner):
120+
from prance import cli
121+
122+
result = runner.invoke(cli.validate, ["tests/specs/self_recursive.yaml"])
123+
assert result.exit_code == 1
124+
assert "ResolutionError" in result.output
125+
126+
127+
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
128+
def test_validate_recursive_with_allow_recursion(runner):
129+
from prance import cli
130+
131+
result = runner.invoke(
132+
cli.validate, ["--allow-recursion", "tests/specs/self_recursive.yaml"]
133+
)
134+
assert "Allowing recursive references" in result.output
135+
assert "ResolutionError" not in result.output
136+
137+
118138
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
119139
def test_compile_defaults(runner):
120140
from prance import cli

0 commit comments

Comments
 (0)