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

02_function_classes.qmd の命名規則のセクション付近から始め、既存の mikeio.pfs._pfssection.PfsSection の例を確認します。アンダースコア接頭辞、all、再エクスポート、ダブルアンダースコアに関する指針を追加し、その後 07_packaging.qmd の Breaking changes スライドを、公開 API であることの明記と相互参照を含むよう更新します。完了の条件は、両方のモジュールで内部名の規則とバージョニングが明確に結び付けられていることです。

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