Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

alternates docstring wrapping on every run (encoding detection changes)

Đang mở
  • Có gì không ổn?
#385 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ó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
78/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python
Lĩnh vực
tooling

Hướng nghiên cứu

Start in docformatter/encode.py:72-91 and compare its encoding selection with Python tokenize.detect_encoding, using the provided repro.py to observe the alternating guesses and layouts. Add a regression check that repeatedly formats the UTF-8 fixture and verifies the file becomes unchanged with exit 0 on later runs.

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

Mô tả

fresh

Repeated standalone docformatter runs alternate between two layouts of the same UTF-8 Python file. Every run exits 3. A pre-commit hook therefore never reaches a clean result.

Environment

  • Python 3.10.11, macOS 27.0
  • docformatter 1.7.8
  • charset-normalizer 3.4.7
  • Original pre-commit environment also has tomli 2.4.1.
  • Standalone reproduction below requires neither pre-commit nor Ruff, Markdown formatting, RF-DETR, or ML dependencies.

Reproduce

In an empty directory, prepare a Python 3.10 virtual environment:

python3.10 -m venv .venv
.venv/bin/python -m pip install "docformatter==1.7.8" "charset-normalizer==3.4.7"

Save this as repro.py using UTF-8. Preserve the space after the final a_b in the first comment; file contents affect encoding detection.

# a_b a_b a_b a_b a_b 
class ModelWrapper:
    """``ModelWrapper`` (module-scope, importable in isolation) normalizes export-mode output to a tuple.

    The wrapped model is expected to already be in export mode (``forward_export``), which returns a tuple (full
    detector) or a plain list (:class:`rfdetr.export._backend._BackboneExport`) — never a dict. A dict output means
    the caller forgot the mode-switch, which is a caller bug the wrapper must surface loudly rather than silently
    reshape.
    """

Run the same formatter repeatedly (do not use set -e; exit 3 is the symptom):

for n in 1 2 3 4; do
    .venv/bin/python -m docformatter --wrap-summaries 120 --wrap-descriptions 120 --in-place repro.py
    echo "exit=$?"
done

Expected

After initial formatting, further runs leave the file unchanged and exit 0.

Actual

All four runs exit 3. Pass 2 restores the original file byte-for-byte; pass 3 restores pass 1; pass 4 restores the original again.

First-pass diff (second pass reverses it):

--- before.py
+++ after.py
@@ -3,7 +3,6 @@
     """``ModelWrapper`` (module-scope, importable in isolation) normalizes export-mode output to a tuple.
 
     The wrapped model is expected to already be in export mode (``forward_export``), which returns a tuple (full
-    detector) or a plain list (:class:`rfdetr.export._backend._BackboneExport`) — never a dict. A dict output means
-    the caller forgot the mode-switch, which is a caller bug the wrapper must surface loudly rather than silently
-    reshape.
+    detector) or a plain list (:class:`rfdetr.export._backend._BackboneExport`) — never a dict. A dict output means the
+    caller forgot the mode-switch, which is a caller bug the wrapper must surface loudly rather than silently reshape.
     """

Diagnostic evidence

Before successive runs, charset_normalizer.from_path("repro.py").best().encoding returns utf_8, mac_iceland, utf_8, mac_iceland for this small example. Both file states remain valid UTF-8. In the original larger file, the alternate guess was cp1250 instead.

The installed docformatter/encode.py:72-91 selects the heuristic result for decoding. The same UTF-8 em dash is consequently interpreted with a different character count, affecting line wrapping. Formatting changes the input to the next encoding guess, producing the cycle.

On the original file, a diagnostic run forcing UTF-8 decoding stabilized after one pass. Replacing em dashes with ASCII also stabilized; neither diagnostic modification is proposed as a project fix.

Python source encoding has deterministic rules: BOM or encoding cookie, otherwise UTF-8. See Python tokenize.detect_encoding. Please consider using those rules when reading Python files and add a repeated-run idempotence regression check.

Verified locally with the pinned versions above; other dependency versions and platforms untested. No upstream fix verified.

Ngôn ngữ chính
Python
Star
598
Fork
93
Merge trung bình
12 ngày 10 giờ
Pull request đã merge (30 ngày)
1

Chuẩn bị môi trường

Chúng tôi chưa kiểm tra các tệp thiết lập môi trường của dự án này. Hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

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 PyCQA/docformatter

Tất cả issue của PyCQA/docformatter

Issue tương tự

Thêm issue về Python

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.