DHI / DHI/python-package-development

Module 02: cover the underscore-prefix 'private/internal' convention

Aberta Para iniciantes
#40 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Jupyter Notebook
Estrelas
8
Forks
1
Merge médio
4min
PRs com merge (30d)
1

Descrição

Module 02 (`02_function_classes.qmd`) teaches Python naming conventions but does not cover the leading-underscore convention for internal/private names. This came up in practice: a user upgraded a dependency, found that several `_`-prefixed functions had been removed, and was upset — not realising those were never part of the public API.

The breaking-changes slide in [`07_packaging.qmd`](../blob/main/07_packaging.qmd) (Removing a function / Renaming / Changing signature → bump major) is the counterpart to this: removing a `_private` function is **not** a breaking change. Worth a forward reference between the two modules.

### Suggested content for module 02

Add a slide near the existing naming-conventions section (around `02_function_classes.qmd:802`) covering:

- `_foo` signals **internal** — not part of the public API
- Consumers who import underscore-prefixed names do so at their own risk
- Maintainers may change/remove them without bumping the major version
- `__all__` in `__init__.py` to declare the public surface
- Re-exporting internals into the package namespace (the existing `mikeio.pfs._pfssection.PfsSection` example at `02_function_classes.qmd:795` is a natural lead-in)
- Double-underscore (`__name`) name mangling is a separate thing — mention briefly to avoid confusion

### Cross-reference

Update the "Breaking changes" slide in `07_packaging.qmd` to note that the rules apply to the **public** API only, with a pointer back to module 02.

See [PEP 8 — Naming Conventions / Public and internal interfaces](https://peps.python.org/pep-0008/#naming-conventions).

Guia de contribuição

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

Direção de pesquisa

Comece em 02_function_classes.qmd, na seção sobre convenções de nomenclatura, e revise o exemplo existente de mikeio.pfs._pfssection.PfsSection. Adicione as orientações sobre o prefixo de sublinhado, __all__, reexportação e sublinhado duplo; em seguida, atualize o slide Breaking changes em 07_packaging.qmd com a qualificação sobre a API pública e uma referência cruzada. Está concluído quando ambos os módulos conectarem claramente as convenções de nomes internos ao versionamento.

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
1-2 dias
Status de atividade
Pouca atividade
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.