Missing docstring examples in the `unparser` module
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- Half a day
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- python
- Domain
- documentation
Research direction
Start in python/datafusion/unparser.py and read the existing Dialect and Unparser docstrings, then inspect the current SELECT 1 unparser test for setup. Add doctest-style examples showing the dialect differences, clarify the Dialect and with_pretty summaries, and run pytest with --doctest-modules. Done means all listed public functions have passing usage examples and the wording is corrected.
Written by the indexing model from the issue text.
Description
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
Dialectclass summary reads"DataFusion data catalog." with_prettyis 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.
- Dominant language
- Python
- Stars
- 605
- Forks
- 176
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 8
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from apache/datafusion-python
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
apache/datafusion-python#1726 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
apache/datafusion-python#1644 ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 30/100
apache/datafusion-python#1737 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 76/100
apache/datafusion-python#1735 · 1 comment ·
-
bug good first issue
Difficulty 4/5 3-5 days Newbie friendliness 48/100
apache/datafusion-python#1728 ·
All issues in apache/datafusion-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100