DHI / DHI/python-package-development

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

Abierto
#40 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Jupyter Notebook
Estrellas
8
Forks
1
Merge medio
4 min
PR fusionados (30 d)
1

Descripción

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

Guía de contribución

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

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.