python - 自动格式化 Python 注释

Question

是否有可用的 Python 脚本来搜索文件并自动将所有文本包装在注释 block 中？我要:

1. 用于处理过长评论行并自动换行到栏指南的脚本。
2. 该脚本用于获取超过 2 行的注释并尝试将它们放入更少的行中。

我不认为 autopep8 做 2，如果我错了请纠正我。我正在使用 PyCharm，它的自动格式选项也不执行 2。

我很想编写自己的脚本来执行此操作，因为我认为这不会花费很长时间，但我想先与社区核实一下。

Answer 1

我找不到执行此操作的脚本。我自己写了一个使用 textwrap 的。空注释行被跳过，包含“=========”或“--------”的行被视为特殊情况并被跳过，例如:

# =============================================================================
# Code Block
# =============================================================================

被跳过。该脚本还包装了文档字符串。这是在 Windows 中的 Python 2.7 中测试的代码，使用风险自负:

#!/usr/bin/env python

# =====================================================================================================================
#
# Overview: This script takes as input a python script and automatically wraps all comment blocks and docstrings.
#
# Usage:    Run python <script_name>.py -h to see the usage of this script.
#
# =====================================================================================================================

# =====================================================================================================================
# Imports
# =====================================================================================================================

import sys
import os
import shutil
import textwrap

# =====================================================================================================================
# Constants
# =====================================================================================================================

# All possible script return values.
EXIT_OK = 0
EXIT_ERROR = 1

# The number of characters allowed on a single line.
LINE_LENGTH = 119

# =====================================================================================================================
# File Global Variables
# =====================================================================================================================

#
# (Currently none)
#

# =====================================================================================================================
# Functions
# =====================================================================================================================


def parse_arguments():
    """ This function parses the command line arguments and returns the user-specified configuration options. """
    import argparse

    parser = argparse.ArgumentParser(description="Auto-format comments and docstrings.")

    parser.add_argument(
        "input",
        help="input file")

    parser.add_argument(
        "-o", "--out",
        help="output file, input file modified in-place if not specified")

    args = parser.parse_args()

    return EXIT_OK, args.input, args.out


def _print_message(message_type, message):
    """ This function prints a message formatted to display well in an 80 character terminal. """
    print(textwrap.fill(
        (message_type + ": ").ljust(max(len("Error"), len("Warning"), len("Status")) + 2) + message,
        initial_indent="",
        subsequent_indent="          ",
        width=79))


def print_error(message):
    """ This function prints an error message. """
    _print_message("Error", message)


def print_warning(message):
    """ This function prints a warning message. """
    _print_message("Warning", message)


def print_status(message):
    """ This function prints a status message. """
    _print_message("Status", message)


def print_status_pending_begin(message):
    """ This function prints a message to notify the user that an action has started and is pending completion. """
    sys.stdout.write("Status:  " + message.ljust(41, "."))


def print_status_pending_end(message):
    """ This function prints a message to notify the user a pending action has completed. """
    print(" " + message)


def write_comment(file_handle, comment_whitespace_prefix, comment, line_ending_str):
    """ This function writes a comment to the specified output file handle. """

    line_start_str = comment_whitespace_prefix + "# "

    comment_lines = textwrap.wrap(
        comment,
        initial_indent=line_start_str,
        subsequent_indent=line_start_str,
        width=LINE_LENGTH)

    for line in comment_lines:
        file_handle.write(line + line_ending_str)


def write_doc_string(file_handle, comment_whitespace_prefix, comment, line_ending_str):
    """ This function writes a doc string to the specified output file handle. """

    if (len(comment_whitespace_prefix) + len(comment) + len('""" ') + len(' """')) <= LINE_LENGTH:
        file_handle.write(comment_whitespace_prefix + '""" ' + comment + ' """' + line_ending_str)
    else:
        file_handle.write(comment_whitespace_prefix + '"""' + line_ending_str)

        comment_lines = textwrap.wrap(
            comment,
            initial_indent=comment_whitespace_prefix,
            subsequent_indent=comment_whitespace_prefix,
            width=LINE_LENGTH)

        for line in comment_lines:
            file_handle.write(line + line_ending_str)

        file_handle.write(comment_whitespace_prefix + '"""' + line_ending_str)


# =====================================================================================================================
# Script's Main Function
# =====================================================================================================================

def main():
    """ This function is the main entry point of the script. """

    # Check if this version of Python meets the minimum requirement for this
    # script. Currently the version dependencies are:
    #   1) v2.6 is needed for the print() function (print() is required in v3.0
    #      and greater).
    #   2) v2.7 is needed for the argparse module.
    if sys.hexversion < 0x02070000:
        print_error("This script requires Python v2.7 or greater.")
        return EXIT_ERROR

    return_value, input_file, output_file = parse_arguments()

    if return_value != EXIT_OK:
        return return_value

    input_file = os.path.abspath(input_file)

    if not os.path.exists(input_file):
        print_error("Input file " + input_file + " does not exist.")

    if output_file is None:
        split_path = os.path.split(input_file)
        output_file = os.path.join(split_path[0], "__temp__" + split_path[1])
        modify_in_place = True
    else:
        modify_in_place = False

    # Enumerate the states we can be in.
    (
        SEARCHING_COMMENT_START,
        READING_COMMENT,
        READING_DOCSTRING,
        SKIPPING_COMMENT
    ) = range(4)

    with open(input_file, "rb") as input_file_handle:
        with open(output_file, "wb") as temp_output_file_handle:
            line_ending_str = None

            state = SEARCHING_COMMENT_START

            for line in input_file_handle:
                if line_ending_str is None:
                    index = -1
                    while (line[index] == "\r") or (line[index] == "\n"):
                        index -= 1

                    line_ending_str = line[index + 1:]

                    # Skip the first "shebang" line.
                    if line.startswith("#!"):
                        temp_output_file_handle.write(line)
                        continue

                lstripped_line = line.lstrip()

                if state == SEARCHING_COMMENT_START:
                    if lstripped_line.startswith("#"):
                        if ("=================" not in lstripped_line) and ("-----------------" not in lstripped_line):
                            comment_start_index = line.index("#")
                            comment_whitespace_prefix = line[:comment_start_index]
                            comment = line[comment_start_index + 1:].strip()

                            # Check if this a blank line.
                            if comment != "":
                                # It's not a blank line, continue trying to read the subsequent comment lines, if any.
                                state = READING_COMMENT
                            else:
                                # It is a blank line, flush the line, and don't change the state.
                                temp_output_file_handle.write(line)

                        else:
                            temp_output_file_handle.write(line)
                            state = SKIPPING_COMMENT

                    elif lstripped_line.startswith('"""'):
                        comment_start_index = line.index('"""')
                        comment_whitespace_prefix = line[:comment_start_index]
                        comment = line[comment_start_index + len('"""'):].strip()

                        if not comment.endswith('"""'):
                            if comment == "":
                                doc_string_separator = ""
                            else:
                                doc_string_separator = ""

                            state = READING_DOCSTRING
                        else:
                            comment = comment.rsplit('"""', 1)[0].rstrip()
                            write_doc_string(temp_output_file_handle, comment_whitespace_prefix, comment,
                                             line_ending_str)

                    else:
                        temp_output_file_handle.write(line)

                elif state == READING_COMMENT:
                    if lstripped_line.startswith("#"):
                        comment_start_index = line.index("#")
                        comment_line = line[comment_start_index + 1:].strip()

                        # Check if this a blank line.
                        if comment_line != "":
                            # It's not a blank line, continue trying to read the subsequent comment lines, if any.
                            comment += " " + line[comment_start_index + 1:].strip()
                        else:
                            # It is a blank line, write the comment, and flush the line.
                            write_comment(temp_output_file_handle, comment_whitespace_prefix, comment, line_ending_str)
                            temp_output_file_handle.write(line)
                            state = SEARCHING_COMMENT_START
                    else:
                        write_comment(temp_output_file_handle, comment_whitespace_prefix, comment, line_ending_str)
                        temp_output_file_handle.write(line)
                        state = SEARCHING_COMMENT_START

                elif state == READING_DOCSTRING:
                    if '"""' not in lstripped_line:
                        comment += doc_string_separator + lstripped_line.rstrip()
                        doc_string_separator = " "
                    else:
                        comment += (doc_string_separator + lstripped_line).rsplit('"""', 1)[0].rstrip()
                        write_doc_string(temp_output_file_handle, comment_whitespace_prefix, comment, line_ending_str)
                        state = SEARCHING_COMMENT_START

                elif state == SKIPPING_COMMENT:
                    temp_output_file_handle.write(line)

                    if "#" not in line:
                        state = SEARCHING_COMMENT_START

                else:
                    raise Exception("Unknown state, check script's logic.")

    if modify_in_place:
        shutil.move(output_file, input_file)

    return EXIT_OK

if __name__ == "__main__":
    sys.exit(main())