LZMA filtering documentation very poor
Chưa có ai nhận issue này.
- Ngôn ngữ chính
- Python
- Star
- 77.2k
- Fork
- 35.9k
- Chỉ số merge pull request
- Chỉ số pull request đang chờ
Mô tả
I'm trying to optimise compressing some documents, so I'm using LZMA's filters. These are really badly documented: https://docs.python.org/3/library/lzma.html#filter-chain-specs
General problems:
- The filters are using short-hand for variable names
lc,lp,mf, which is really bad practice for a publically available interface (and even for internal ones!). (ok, so this isn't a doc problem, but a library one). - It's not at all clear what any of the variables do. There's no links to any documentation (even third-party) which explain what any of these things do.
- It's not clear what values are acceptable for some of them.
-
presetis documented elsewhere, and I assume the value range is the same?
-
lcdoesn't say the maximum is 4, you have to readlpto see the combined maximum is 4, and then deduce.
-
lc,lp,pc,nice_len, don't state minimums
- No defaults stated other than
depth (0), - It's not at all clear what the different Filters do.
- The limited blurb that does exist about Filter chains seems to assume a high degree of expertise in these things. For example:
The last filter in the chain must be a compression filter, and any other filters must be delta or BCJ filters.- that has cleared nothing up. - What's a
MODE_FASTorMODE_NORMALdo? - What's the difference between
MF_HC3, MF_HC4, MF_BT2, MF_BT3, or MF_BT4? - What does
lzma.PRESET_EXTREMEdo? There's no documentation forlzma.PRESET_DEFAULTat all (which my IDE exposed to me via autocomplete).
Etc etc.
Some specific problems as well:
-
'filters': [{'id': 33, 'preset': 6, 'dict_size': 262144, 'lc': 1, 'lp': 1, 'mode': 2, 'nice_len': 1, 'mf': 3}]
That creates anLZMAError. It's only after generating thousands of combinations of these that I notice a pattern:nice_len: 1. It seems there's a minimum nice_len size. This is not documented. -
'filters': [{'id': 33, 'preset': 2147483653, 'dict_size': 1073741824, 'lc': 1, 'lp': 0, 'mode': 2, 'nice_len': 201, 'mf': 20}]
Generates aMemoryError(as do lots of others of my tests). No idea why as I have plenty of RAM. I presume some combination of those settings are causing an issue, but there's no documentation warning about this.
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Hướng nghiên cứu
Bắt đầu với phần đặc tả chuỗi bộ lọc LZMA trên trang tài liệu Python được liên kết và xem lại các mô tả về tùy chọn bộ lọc, preset, chế độ và chuỗi bộ lọc. Ghi lại ý nghĩa của các tham số, phạm vi hợp lệ, giá trị mặc định, sự khác biệt giữa các bộ lọc và những ràng buộc liên quan về lỗi hoặc bộ nhớ để các ví dụ và trường hợp thất bại được giải thích.
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
- documentation
- Loại issue
- Tài liệu
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100