Missing docstring examples in the `unparser` module

Offen Anfängerfreundlich

#1,691 erstellt am 16.8.2026 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit: 2/5
Geschätzter Aufwand: Ein halber Tag
Anfängerfreundlichkeit: 88/100

Issue-Typ: Dokumentation
Klarheit: Klar beschrieben
Aktivitätsstatus: Aktiv
Tech-Stack: python
Bereich: documentation

Rechercherichtung

Beginne in python/datafusion/unparser.py und lies die vorhandenen Docstrings von Dialect und Unparser. Sieh dir anschließend den aktuellen Unparser-Test für SELECT 1 an, um die Einrichtung zu verstehen. Füge Beispiele im doctest-Stil hinzu, die die Unterschiede zwischen den Dialekten zeigen, präzisiere die Zusammenfassungen von Dialect und with_pretty und führe pytest mit --doctest-modules aus. Erledigt ist die Aufgabe, wenn alle aufgelisteten öffentlichen Funktionen über erfolgreiche Verwendungsbeispiele verfügen und die Formulierungen korrigiert sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.default
Dialect.mysql
Dialect.postgres
Dialect.sqlite
Dialect.duckdb
Unparser.plan_to_sql
Unparser.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.

Vorherrschende Sprache: Python
Sterne: 605
Forks: 176
Ø Merge: 1 T. 23 Std.
Gemergte PRs (30 T.): 8

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Erste Schritte

Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
Forken Sie das Repository und arbeiten Sie in einem Branch.
Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus apache/datafusion-python

Rewrite the "Encode metadata, not a handle to a live object" section Offen

documentation

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100

apache/datafusion-python#1726 · Erstellt am 11.9.2026
Build fails against DataFusion 54.1.0 due to new `schema` field on `RecursiveQuery` Offen

bug

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 78/100

apache/datafusion-python#1644 · Erstellt am 24.7.2026
Allow extension libraries to contribute object stores over FFI Offen

enhancement

Schwierigkeit 5/5 Über eine Woche Anfängerfreundlichkeit 30/100

apache/datafusion-python#1737 · Erstellt am 15.9.2026
CsvReadOptions.null_regex has no effect: matching values are read as literal strings, and fail the read in a numeric column Offen

Schwierigkeit 3/5 1-2 Tage Anfängerfreundlichkeit 76/100

apache/datafusion-python#1735 · 1 Kommentar · Erstellt am 12.9.2026
Nothing in CI runs examples/*.py, and one of them is broken Offen

bug good first issue

Schwierigkeit 4/5 3-5 Tage Anfängerfreundlichkeit 48/100

apache/datafusion-python#1728 · Erstellt am 11.9.2026

Alle Issues in apache/datafusion-python