python / python/cpython

LZMA filtering documentation very poor

Đang mở
#121,186 0 bình luận 1 reaction 0 người được giao Xem trên GitHub

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

docs
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.
    • preset is documented elsewhere, and I assume the value range is the same?
    • lc doesn't say the maximum is 4, you have to read lp to 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_FAST or MODE_NORMAL do?
  • What's the difference between MF_HC3, MF_HC4, MF_BT2, MF_BT3, or MF_BT4?
  • What does lzma.PRESET_EXTREME do? There's no documentation for lzma.PRESET_DEFAULT at 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 an LZMAError. 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 a MemoryError (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

Mở hướng dẫn đóng góp

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.

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

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.