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

Đang mở Phù hợp với người mới
#40 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
88/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
python
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu trong 02_function_classes.qmd, ở quanh phần về quy ước đặt tên, và xem lại ví dụ mikeio.pfs._pfssection.PfsSection hiện có. Thêm hướng dẫn về tiền tố dấu gạch dưới, all, việc tái xuất và dấu gạch dưới kép, sau đó cập nhật slide Breaking changes trong 07_packaging.qmd với phần làm rõ về API công khai và một tham chiếu chéo. Hoàn thành khi cả hai module đều liên kết rõ ràng các quy ước đặt tên nội bộ với việc lập phiên bản.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

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

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

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

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của DHI/python-package-development

Tất cả issue của DHI/python-package-development

Issue tương tự

Thêm issue về Documentation

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.