DHI / DHI/python-package-development

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

Đang mở
#40 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Jupyter Notebook
Star
8
Fork
1
Merge trung bình
4 phút
Pull request đã merge (30 ngày)
1

Mô tả

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

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.