python Sphinx“模块执行模块级语句，它可能会调用 sys.exit()。”

Question

我尝试使用 Sphinx 来记录我的代码。但我看到错误：

模块执行模块级语句，它可能会调用 sys.exit()。

我发现这个错误与代码有关：

import argparse
# parse command line arguments
parser = argparse.ArgumentParser(description='AWS VPN status checker.')
parser.add_argument('account', type=str, help='AWS account name.')
parser.add_argument('region', type=str, help='region of VPN tunnel.')
parser.add_argument('ipaddress', type=str, help='Tunnel IP address.')
parser.add_argument("-d", "--debug", help="debug", action="store_true")
args = parser.parse_args()

我认为这与导入模块时的“副作用”有关。

为什么不好，我该如何解决？

Answer 1

Sphinx 警告是一种效果，由先前的parse_args()错误引起。该arg_parse()函数被调用，在它期望解析的参数中发现一个正常错误，并且存在。

\n

\n

无效参数

\n

在解析命令行时，parse_args()会检查各种错误，包括不明确的选项、无效的类型、无效的选项、错误的位置参数数量等。当遇到此类错误时，它会退出并打印错误以及使用消息：

\n

\n

生成 Sphinx 文档时parse_args()退出的最可能原因是因为您真正调用的是or 。所以在你的 python shell 上执行的是以下签名：sphinx-buildmake html

\n

\n

狮身人面像构建

\n

概要

\n

sphinx-build [选项] <源目录> <输出目录> [文件名 \xe2\x80\xa6]

\n

\n

这意味着您可能没有使用您编码ArgumentParser为 require 的参数来执行脚本。运行sphinx-build或make html包含命令行参数arg_parse()需要ArgumentParser()，或者在生成文档时不调用arg_parse()。

\n

\n

如何解决这个问题？

\n

\n

一种可能的方法如下：

\n

entry_script.py:

\n

from sys import argv\nfrom pathlib import Path\n\nimport cmd_line_module\n\n# Checking what the command line contains can be useful.\nprint(argv)\n\nEXAMPLE_ARGS = [\'-i\', \'../in_dir_test\', \'-o\', \'out_dir_test\']\n\n# Script.\nif __name__ == "__main__":\n\n    # default Namespace\n    print(cmd_line_params.args)\n\n    # command-line\n    cmd_line_module.set_args()\n    print(cmd_line_params.args)\n\n    # test case\n    cmd_line_module.set_args(EXAMPLE_ARGS)\n    print(cmd_line_params.args)\n\n# Sphinx-build or make.\nelif Path(argv[0]).name == "sphinx-build" or Path(argv[0]).name == "build.py":\n\n    cmd_line_module.set_args(EXAMPLE_ARGS)\n\n# Module only.\nelse:\n    cmd_line_module.set_args(EXAMPLE_ARGS)\n\n

\n

cmd_line_module.py:

\n

import argparse\n\n\n_DEFAULT = argparse.Namespace(in_dir=None, out_dir=None)\nargs = _DEFAULT\n\n\ndef command_line_args():\n\n    parser = argparse.ArgumentParser(prog=\'entry_script\', description=\'Does magic :) .\')\n    parser.add_argument("-i", "--in_dir", help="Input directory/file. Use absolute or relative path.")\n    parser.add_argument("-o", "--out_dir", help="Output directory. Use absolute or relative path.")\n\n    return parser\n\n\ndef set_args(cmd_line=None):\n\n    parser = command_line_args()\n    global args\n    args = parser.parse_args(cmd_line)\n\n

\n

关于该解决方案的一些注释可能对读者有用：

\n

1.在模块级别维护为变量cmd_line_module.py，args尽可能类似于argparse 教程示例。可以在此线程中argparse找到特定的 Sphinx 扩展。

\n

2.使用默认命名空间可能args会很方便，它作为建议包含在内。（预期的默认值可以帮助测试导入模块）。

\n

3.测试__main __或sphinx-build可能没有必要，具体取决于，if包含 3 个测试只是为了添加问题的上下文。

\n

4.使用DEFAULT_ARGS展示了如何parse_args()在不读取 的情况下使用sys.argv，以及如何运行sphinx-build分配使用if __name __ == "__main __":（如果您出于任何原因发现它很方便）...

\n

5.脚本的名称和路径sphinx-build可能因操作系统而异。

\n

最后注意：如果您喜欢编写自初始化变量的模块（像我一样），请特别注意在parse_args()导入可能具有依赖于它的变量的模块之前运行。

\n

\n

6.1. 有关模块的更多信息

\n

模块可以包含可执行语句以及函数定义。这些语句旨在初始化模块。它们仅在导入语句中第一次遇到模块名称时执行。（如果文件作为脚本执行，它们也会运行。）

\n

\n