alunduil / alunduil/zfs-replicate
venn returns its three groups as a named record
- Ngôn ngữ chính
- Python
- Star
- 24
- Fork
- 6
- Merge trung bình
- 3 giờ 11 phút
- Pull request đã merge (30 ngày)
- 49
Mô tả
## Summary
Give `zfs.replicate.list.venn` a return type that names its three groups, so
callers reach them by name rather than by position.
## Motivation
`venn` returns `tuple[list[T], list[T], list[T]]` (`zfs/replicate/list.py:22`).
All three elements have the same type, so nothing but the docstring maps a
position to a meaning: left-only, common, right-only.
The single caller unpacks it positionally and routes the groups to opposite
actions:
```python
lefts, middles, rights = venn(local_snaps, remote_snapshots[destination])
send_tasks = _send_snapshots(remote, lefts)
destroy_tasks = _destroy_snapshots(destination, rights)
```
Transposing `lefts` and `rights` there would generate destroy tasks for
snapshots that should be sent and send tasks for ones that should be destroyed.
mypy cannot catch it, because it sees three interchangeable `list[T]`.
Fowler's Replace Primitive with Object is the fix. Surfaced while reviewing #501
through the refactoring catalogue and declined there to keep that change to
annotation churn.
## Scope
- Add a `NamedTuple` to `zfs/replicate/list.py` whose fields carry the
docstring's vocabulary for the three groups.
- Return it from `venn`.
- Read the groups by name at `zfs/replicate/task/generate.py:39`.
- Update the three `venn` property tests in
`zfs_test/replicate_test/list_test.py`, which destructure the result.
## Acceptance criteria
- [ ] Transposing two groups at a call site is a type error rather than a
silent behaviour change.
- [ ] `task/generate.py` reads the groups by name.
- [ ] The docstring no longer has to explain what each component position means.
## Additional context
Martin Fowler, _Refactoring_ 2nd edition: Replace Primitive with Object.
Hướng dẫn đóng góp
Hướng nghiên cứu
Start with zfs/replicate/list.py:22 and inspect the caller at zfs/replicate/task/generate.py:39. Run the three venn property tests in zfs_test/replicate_test/list_test.py before and after the change. Done means the result exposes named groups, the caller reads those names, and positional group transposition is rejected by typing.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- cli
- Loại issue
- Tái cấu trúc
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 84/100