apache / apache/datafusion-python

Missing docstring examples in the `unparser` module

Abierto Apto para principiantes
#1,691 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
604
Forks
174
Merge medio
1 d 7 h
PR fusionados (30 d)
4

Descripción

## 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.

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Línea de trabajo

Comienza en python/datafusion/unparser.py y lee los docstrings existentes de Dialect y Unparser; después, inspecciona la prueba actual del unparser para SELECT 1 para conocer la configuración. Añade ejemplos con estilo doctest que muestren las diferencias entre dialectos, aclara los resúmenes de Dialect y with_pretty y ejecuta pytest con --doctest-modules. La tarea estará terminada cuando todas las funciones públicas enumeradas tengan ejemplos de uso que pasen y se haya corregido la redacción.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
python
Área
documentation
Tipo de issue
Documentación
Dificultad
2/5
Tiempo estimado
Medio día
Estado de actividad
Activo
Claridad
Bien especificado
Aptitud para principiantes
88/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.