apache / apache/datafusion-python

Missing docstring examples in the `unparser` module

Aberta Para iniciantes
#1,691 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
604
Forks
174
Merge médio
2d 22h
PRs com merge (30d)
5

Descrição

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

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Direção de pesquisa

Comece em python/datafusion/unparser.py e leia as docstrings existentes de Dialect e Unparser; em seguida, inspecione o teste atual do unparser para SELECT 1 para entender a configuração. Adicione exemplos no estilo doctest mostrando as diferenças entre os dialetos, esclareça os resumos de Dialect e with_pretty e execute pytest com --doctest-modules. Está concluído quando todas as funções públicas listadas tiverem exemplos de uso aprovados e a redação tiver sido corrigida.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation
Tipo de issue
Documentação
Dificuldade
2/5
Tempo estimado
Meio dia
Status de atividade
Ativa
Clareza
Claramente especificada
Facilidade para iniciantes
88/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.