Description
AGENTS.md requires every public Python function to carry a usage example, but
none of the public functions in python/datafusion/unparser.py have one:
Dialect.defaultDialect.mysqlDialect.postgresDialect.sqliteDialect.duckdbUnparser.plan_to_sqlUnparser.with_pretty
The gap matters more here than in most modules, because the reason Dialect
exists is that different dialects render the same plan differently, and nothing
in the current documentation shows that difference. The existing test unparses
SELECT 1, which is identical across all four dialects.
Two smaller documentation problems sit in the same file:
- the
Dialect class summary reads "DataFusion data catalog."
with_pretty is documented as "Set the pretty flag.", which does not say
what the flag changes.
Expected Behavior
All public functions in the module carry doctest-style usage examples,
consistent with the rest of the package and executed by pytest's
--doctest-modules.
Suggested Improvement
Add examples that unparse the same plan through each dialect so the differences
are visible, and correct the two docstrings noted above.
Description
AGENTS.mdrequires every public Python function to carry a usage example, butnone of the public functions in
python/datafusion/unparser.pyhave one:Dialect.defaultDialect.mysqlDialect.postgresDialect.sqliteDialect.duckdbUnparser.plan_to_sqlUnparser.with_prettyThe gap matters more here than in most modules, because the reason
Dialectexists is that different dialects render the same plan differently, and nothing
in the current documentation shows that difference. The existing test unparses
SELECT 1, which is identical across all four dialects.Two smaller documentation problems sit in the same file:
Dialectclass summary reads"DataFusion data catalog."with_prettyis documented as"Set the pretty flag.", which does not saywhat the flag changes.
Expected Behavior
All public functions in the module carry doctest-style usage examples,
consistent with the rest of the package and executed by pytest's
--doctest-modules.Suggested Improvement
Add examples that unparse the same plan through each dialect so the differences
are visible, and correct the two docstrings noted above.