维燕的知识花园

使用 Python 的 argparse 构建命令行界面

Thu, 29 Oct 2026 02:52:26 GMT

原文：Build Command-Line Interfaces With Python's argparse

命令行应用在普通用户空间中可能并不常见，但它们存在于开发、数据科学、系统管理和许多其他操作中。每个命令行应用都需要一个用户友好的命令行界面（CLI），以便你可以与应用本身进行交互。在 Python 中，您可以使用标准库中的 argparse 模块创建功能齐全的 CLI。

在本文中，你将了解如何：

命令行界面入门；
在 Python 中组织和布局命令行应用项目；
使用 Python argparse 创建命令行界面（command-line interfaces）；
使用 argparse 一些强大的功能深度自定义您的 CLI；

若要充分利用本教程，应熟悉 Python 编程，包括面向对象编程、脚本开发和执行以及 Python 包和模块等概念。如果您熟悉与使用命令行或终端相关的一般概念和主题，这也将很有帮助。

了解命令行界面

自从计算机发明以来，人类一直需要并找到与这些机器交互和共享信息的方法。信息交换在人、计算机软件和硬件组件之间流动。其中任意两个元素之间的共享边界通常称为接口(interface)。

在软件开发中，接口是给定软件的特殊部分，它允许计算机系统组件之间的交互。当涉及到人机交互和软件交互时，这个重要的组件被称为用户界面（user interface）。

您会在编程中找到不同类型的用户界面。图形用户界面（GUI）可能是当今最常见的。但是，您还可以找到为其用户提供命令行界面（CLI）的应用和程序。在本教程中，你将了解 CLI 以及如何在 Python 中创建它们。

命令行界面（CLI）

命令行界面允许您通过操作系统命令行、终端或控制台与应用程序或程序进行交互。

要了解命令行界面及其工作原理，请考虑此实际示例。假设您有一个名为 sample 包含三个示例文件的目录。如果您使用的是类 Unix 操作系统，例如 Linux 或 macOS，请继续在父目录中打开命令行窗口或终端，然后执行以下命令：

$ ls sample/
hello.txt     lorem.md      realpython.md

Unix 的 ls 命令列出目标目录中包含的文件和子目录，该目录默认为当前工作目录。上面的命令调用没有显示有关的内容 sample 的太多信息。它只在屏幕上显示文件名。

假设你想要获取有关目录及其内容的更丰富信息，那么你不需要寻找其他程序，因为 ls 命令有一个功能齐全的命令行界面，并且提供了一组有用的选项，可以用来定制命令的行为。

例如，继续执行带有 -l 选项的 ls 命令：

$ ls -l sample/
total 24
-rw-r--r--@ 1 user  staff    83 Aug 17 22:15 hello.txt
-rw-r--r--@ 1 user  staff  2609 Aug 17 22:15 lorem.md
-rw-r--r--@ 1 user  staff   428 Aug 17 22:15 realpython.md

现在，ls 命令的输出完全不同了。该命令显示了有关 sample 目录中文件的更多信息，包括权限、所有者、组、日期和大小。它还显示了这些文件在你计算机磁盘上使用的总空间。

这种更丰富的输出结果是由于使用了 -l 选项，这是 Unix ls 命令行界面的一部分，它启用了详细的输出格式。

命令、参数、选项、参数和子命令

在本教程中，您将深入了解命令(commands)及其子命令(subcommands)，同时还会学习到命令行参数(command-line arguments)、选项(options)和参数(parameters)的相关知识。因此，建议您将这些术语纳入您的技术词汇库中。

命令(Command)：在命令行或终端窗口中运行的程序或例程。通常，您可以通过其背后的程序(underlying program)或例程(routine)的名称来识别一个命令。
参数(Argument)：命令在执行其预期操作时所需或可选的信息片段。命令通常接受一个或多个参数，您可以在命令行中以空格分隔或逗号分隔的列表形式提供这些参数。
选项(Option)，也称为 flag 或 switch：一种可选的参数，用于修改命令的行为。选项通过特定的名称（如前一个示例中的 -l）传递给命令。
参数(Parameter)：一个选项用于执行其预期操作或动作时所使用的参数。
子命令(Subcommand)**：一个预定义的名称，可以传递给应用程序来执行特定的操作。

参考上一节中的示例命令结构：

$ ls -l sample/

在这个例子中，您组合了命令行界面（CLI）的以下组件：

ls：命令的名称或应用的名称；
-l：启用详细输出的选项(option)、开关(switch)或标志(flag)；
sample：为命令执行提供附加信息的参数(argument)；

现在，让我们来看下面的命令结构，它展示了 Python 包管理器 pip 的命令行界面（CLI）：

$ pip install -r requirements.txt

这是一个常见的 pip 命令结构，您可能之前已经见过。它允许您使用 requirements.txt 文件来给指定的 Python 项目安装依赖项。在这个例子中，您使用了以下命令行界面（CLI）组件：

pip：命令的名称；
install：pip 的子命令(subcommand)名称；
-r：install 子命令的选项(option)；
requirements.txt：一个参数，特别是 -r 选项的参数。

现在您已经了解了命令行界面（CLI）是什么以及其主要部分或组件有哪些。接下来，是时候学习如何在 Python 中创建自己的 CLI 了。

Python 中的 CLI 入门

Python 附带了一些工具，这些工具可帮助您为程序和应用程序编写命令行界面（CLI）。若您需要快速为小型程序构建一个简洁的 CLI，那么可以利用 sys 模块中的 argv 属性。这个属性会自动存储您在命令行中传递给特定程序的参数。

使用 `sys.argv` 构建最小的 CLI

以使用 argv 创建最小命令行界面（CLI）为例，假设您需要编写一个小程序，该程序类似于 ls 命令，能够列出给定目录下的所有文件。在这种情况下，您可以编写如下代码：

# ls_argv.py

import sys
from pathlib import Path

if (args_count := len(sys.argv)) > 2:
    print(f"One argument expected, got {args_count - 1}")
    raise SystemExit(2)
elif args_count < 2:
    print("You must specify the target directory")
    raise SystemExit(2)

target_dir = Path(sys.argv[1])

if not target_dir.is_dir():
    print("The target directory doesn't exist")
    raise SystemExit(1)

for entry in target_dir.iterdir():
    print(entry.name)

该程序通过手动处理命令行提供的参数来实现了一个简单的命令行界面（CLI），这些参数会自动存储在 sys.argv 中。sys.argv 的第一个元素始终是程序名称，第二个元素则是目标目录。由于应用程序不应接受超过一个目标目录，因此 args_count 不得超过 2。

在检查 sys.argv 的内容后，您创建一个pathlib.Path对象来存储目标目录的路径。如果该目录不存在，您将通知用户并退出程序。接下来的for循环将列出目录内容，每行一个条目。

如果从命令行运行该脚本，您将得到以下结果：

$ python ls_argv.py sample/
hello.txt
lorem.md
realpython.md

$ python ls_argv.py
You must specify the target directory

$ python ls_argv.py sample/ other_dir/
One argument expected, got 2

$ python ls_argv.py non_existing/
The target directory doesn't exist

您的程序接受一个目录作为参数，并列出其内容。如果您运行命令时没有提供参数，您将收到一个错误消息。如果您运行命令时指定了超过一个目标目录，您同样会收到一个错误消息。如果尝试运行命令并指定一个不存在的目录，程序将输出另一个错误消息。

虽然您的程序运行正常，但对于更复杂的 CLI 应用程序来说，使用sys.argv属性手动解析命令行参数并不是一个可扩展的解决方案。如果您的应用需要接受更多的参数和选项，那么解析sys.argv将变得复杂且容易出错。您需要一个更好的解决方案，这就是 Python 中的argparse模块所提供的。

使用 `argparse` 创建 CLI

在 Python 中创建 CLI 应用程序的更便捷方法是使用标准库中的 argparse 模块。该模块首次在 Python 3.2 中随 PEP-389 一同发布，是快速创建 Python CLI 应用程序的利器，无需安装如 Typer 或 Click 这样的第三方库。

argparse 模块是作为较旧的 getopt 和 optparse 模块的替代品而发布的，因为它们缺乏一些重要的功能。

Python 的 argparse 模块允许您：

解析命令行参数(arguments)和选项(options)；
在一个单一选项中接受可变数量的参数(variable number of parameters)；
在 CLI 中提供子命令(subcommands)。

这些特性使 argparse 成为了一个强大的 CLI 框架，您在创建 CLI 应用程序时可以放心地依赖它。要使用 Python 的 argparse，您需要遵循以下四个简单的步骤：

导入 argparse；
通过实例化 ArgumentParser 创建参数解析器(argument parser)；
使用 .add_argument() 方法向解析器添加参数(arguments)和选项(options)；
在解析器上调用 .parse_args() 以获取参数 Namespace。

例如，您可以使用 argparse 来改进您的 ls_argv.py 脚本。现在，您可以创建一个名为 ls.py 的脚本，并编写以下代码：

# ls.py v1

import argparse
from pathlib import Path

parser = argparse.ArgumentParser()

parser.add_argument("path")

args = parser.parse_args()

target_dir = Path(args.path)

if not target_dir.exists():
    print("The target directory doesn't exist")
    raise SystemExit(1)

for entry in target_dir.iterdir():
    print(entry.name)

随着 argparse 的引入，您的代码发生了显著的变化。与之前的版本相比，最明显的不同是，用于检查用户提供的参数的条件语句已经消失了。这是因为 argparse 会自动为您检查参数的存在性。

在这个新的实现中，您首先导入 argparse 并创建一个参数解析器。要创建解析器，您可以使用 ArgumentParser 类。接下来，您定义一个名为 path 的参数，用于获取用户的目标目录。

接下来，您需要调用 .parse_args() 方法来解析输入参数，并获取一个包含所有用户参数的 Namespace 对象。请注意，现在 args 变量保存了一个 Namespace 对象，该对象具有从命令行收集的每个参数所对应的属性。

在这个例子中，您只有一个参数，名为 path。Namespace 对象允许您使用点表示法通过 args 来访问 path。其余的代码与第一个实现相同。

现在继续从命令行运行这个新脚本：

$ python ls.py sample/
lorem.md
realpython.md
hello.txt

$ python ls.py
usage: ls.py [-h] path
ls.py: error: the following arguments are required: path

$ python ls.py sample/ other_dir/
usage: ls.py [-h] path
ls.py: error: unrecognized arguments: other_dir/

$ python ls.py non_existing/
The target directory doesn't exist

第一个命令的输出与您的原始脚本 ls_argv.py 相同。而第二个命令的输出则与 ls_argv.py 中的输出大不相同。程序现在会显示一个使用说明消息，并发出错误提示，告诉您必须提供 path 参数。

在第三个命令中，您传递了两个目标目录，但应用程序并未为此做好准备。因此，它再次显示使用说明消息，并抛出一个错误，告知您潜在的问题。

最后，如果您运行脚本时传递了一个不存在的目录作为参数，那么您会收到一个错误，告知您目标目录不存在，因此程序无法执行其工作。

现在，您可以使用一个新的隐式特性。现在，您的程序接受一个可选的 -h 标志。不妨尝试一下：

$ python ls.py -h
usage: ls.py [-h] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit

太棒了，现在您的程序会自动响应 -h 或 --help 标志，并为您显示带有使用说明的帮助消息。这真是一个很棒的特性，而且您只需在代码中引入 argparse 就能轻松获得！

经过这个快速介绍如何在 Python 中创建 CLI 应用后，您现在就可以深入研究 argparse 模块及其所有炫酷特性了。

使用 Python 的 argparse 创建 CLI

您可以使用 argparse 模块为您的应用程序和项目编写用户友好的命令行界面。该模块允许您定义应用程序所需的参数和选项。然后，argparse 将负责为您解析 sys.argv 的参数和选项。

argparse 的另一个酷炫特性是它可以自动为您的 CLI 应用程序生成使用说明和帮助消息。该模块还会在参数无效时发出错误提示，并具备更多功能。

在深入研究 argparse 之前，您需要知道该模块的文档可识别两种不同类型的命令行参数：

位置参数(Positional arguments)，您称为参数(arguments)；
可选参数(Optional arguments)，即选项(options)、标志(flags)或开关(switches)。

在 ls.py 的示例中，path 是一个位置参数(positional argument)。这样的参数之所以被称为位置参数，是因为它在命令构造中的相对位置定义了其作用。

与位置参数不同，可选参数(Optional arguments)并不是必需的。它们允许你修改命令的行为。以 Unix 命令 ls 为例，-l 标志就是一个可选参数，它使得命令以详细模式显示输出。

在明确了这些概念之后，你就可以着手使用 Python 和 argparse 库来构建自己的命令行界面（CLI）应用程序了。

创建命令行参数解析器

命令行参数解析器是任何使用 argparse 的命令行界面（CLI）中最为关键的部分。你在命令行上提供的所有参数和选项都会经过这个解析器的处理，它会为你完成繁重的解析工作。

要使用 argparse 创建命令行参数解析器，您需要实例化 ArgumentParser 类：

>>> from argparse import ArgumentParser

>>> parser = ArgumentParser()
>>> parser
ArgumentParser(
    prog='',
    usage=None,
    description=None,
    formatter_class=<class 'argparse.HelpFormatter'>,
    conflict_handler='error',
    add_help=True
)

ArgumentParser 的构造函数接受多种不同的参数，你可以利用这些参数来微调你的 CLI 的多个特性。由于所有这些参数都是可选的，因此你可以通过不传入任何参数直接实例化 ArgumentParser 来创建一个最基本的解析器。

在本教程中，你将会更深入地了解 ArgumentParser 构造函数的参数，特别是在定制你的参数解析器的部分。目前，你可以开始使用 argparse 创建 CLI 的下一步了。这一步就是通过解析器对象来添加参数和选项。

添加参数和选项

要为 argparse 的 CLI 添加参数和选项，你将使用 ArgumentParser 实例的 .add_argument() 方法。请注意，这个方法对参数和选项都是通用的。在 argparse 的术语中，参数被称为位置参数(positional arguments)，而选项被称为可选参数(optional arguments)。

.add_argument() 方法的第一个参数决定了参数和选项之间的区别。这个参数被标识为名称（name）或标志（flag）。因此，如果你提供一个 name，那么你将定义一个参数(argument)。相反，如果你使用一个 flag，那么你将添加一个选项(option)。

你已经在使用 argparse 时处理过命令行参数了。现在，考虑以下你自定义的 ls 命令的增强版本，它向 CLI 添加了一个 -l 选项：

# ls.py v2

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser()

parser.add_argument("path")

parser.add_argument("-l", "--long", action="store_true")

args = parser.parse_args()

target_dir = Path(args.path)

if not target_dir.exists():
    print("The target directory doesn't exist")
    raise SystemExit(1)

def build_output(entry, long=False):
    if long:
        size = entry.stat().st_size
        date = datetime.datetime.fromtimestamp(
            entry.stat().st_mtime).strftime(
            "%b %d %H:%M:%S"
        )
        return f"{size:>6d} {date} {entry.name}"
    return entry.name

for entry in target_dir.iterdir():
    print(build_output(entry, long=args.long))

在这个例子中，第 11 行代码创建了一个带有 -l 和 --long 标志的选项。参数(arguments)和选项(options)在语法上的区别在于，选项名称以短横线 - 开头表示简写标志，以双短横线 -- 开头表示完整标志。

请注意，在这个特定例子中，与 -l 或 --long 选项一同设置了一个 action 参数为 "store_true"，这意味着这个选项将存储一个布尔值。如果你在命令行上提供了这个选项，那么它的值将为 True。如果你省略了这个选项，那么它的值将为 False。在 "设置 Option 背后的 Action" 部分内容中，你将了解更多关于 .add_argument() 中的 action 参数的信息。

在第 21 行的 build_output() 函数中，当 long 为 True 时，它会返回一个详细的输出，否则返回一个简短的输出。详细的输出将包含目标目录中所有条目的大小、修改日期和名称。它使用了诸如 Path.stat() 这样的工具，以及带有自定义字符串格式的 datetime.datetime 对象。

继续在 sample 上执行您的程序，以检查 -l 选项如何工作：

$ python ls.py -l sample/
  2609 Oct 28 14:07:04 lorem.md
   428 Oct 28 14:07:04 realpython.md
    83 Oct 28 14:07:04 hello.txt

新增的 -l 选项允许你生成并显示关于目标目录内容的更详细输出。

既然你已经知道了如何向 CLI 添加命令行参数和选项，接下来就是深入解析这些参数和选项的时候了。这将是你在接下来部分要探索的内容。

解析命令行参数和选项

解析命令行参数是基于 argparse 的任何 CLI 应用中的另一个重要步骤。一旦你解析了参数，你就可以根据它们的值来执行相应的操作。在你自定义的 ls 命令示例中，参数解析发生在包含 args = parser.parse_args() 语句的行上。

这个语句调用了 .parse_args() 方法，并将其返回值赋给 args 变量。.parse_args() 的返回值是一个 Namespace 对象，其中包含了在命令行上提供的所有参数和选项以及它们对应的值。

考虑以下简单的示例：

>>> from argparse import ArgumentParser

>>> parser = ArgumentParser()

>>> parser.add_argument("site")
_StoreAction(...)

>>> parser.add_argument("-c", "--connect", action="store_true")
_StoreTrueAction(...)

>>> args = parser.parse_args(["Real Python", "-c"])
>>> args
Namespace(site='Real Python', connect=True)

>>> args.site
'Real Python'
>>> args.connect
True

通过在命令行参数解析器上调用 .parse_args() 方法得到的 Namespace 对象，你可以使用点表示法(dot notation)访问所有输入参数、选项以及它们对应的值。这样，你就可以检查输入参数和选项的列表，并根据用户在命令行上的选择来执行相应的操作。

你将在应用程序的主代码中使用这个 Namespace 对象。这与你在自定义 ls 命令示例中的 for 循环下所做的类似。

到目前为止，你已经了解了创建基于 argparse 的 CLI 的主要步骤。现在，你可以花些时间学习如何在 Python 中组织和构建 CLI 应用程序的基础知识了。

设置 CLI 应用程序的布局和构建系统

在继续你的 argparse 学习之旅之前，你应该暂停一下，思考如何组织你的代码和规划一个 CLI 项目。首先，你应该考虑以下几点：

你可以创建模块和包来组织代码。
你可以将 Python 应用的核心包命名为应用本身的名字。
你会根据每个 Python 模块的具体内容或功能来命名它们。
如果你希望某个包可以直接执行，你可以在该 Python 包中添加一个 __main__.py 模块。

将这些想法铭记于心，并考虑到模型-视图-控制器（MVC）模式是一种有效组织应用程序结构的方法，你在规划 CLI 项目时可以采用以下目录结构：

hello_cli/
│
├── hello_cli/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   └── model.py
│
├── tests/
│   ├── __init__.py
│   ├── test_cli.py
│   └── test_model.py
│
├── pyproject.toml
├── README.md
└── requirements.txt

hello_cli/ 目录是项目的根目录。在那里，您将放置以下文件：

pyproject.toml 是一个 TOML 文件，用于指定项目的构建系统(build system)和其他配置(configurations)。
README.md 文件提供了项目的描述以及安装和运行应用程序的说明。为你的项目添加一个描述性且详细的 README.md 文件是编程中的最佳实践，特别是如果你打算将项目作为开源解决方案发布的话。
requirements.txt 是一个常规文件，列出了项目的外部依赖项(external dependencies)。你将使用这个文件，结合 pip 的 -r 选项，来自动安装这些依赖项。

接下来是 hello_cli/ 目录，它包含了应用的核心包，该包包含以下模块：

__init__.py 文件使得 hello_cli/ 可以作为一个 Python 包被识别。
__main__.py 文件提供了应用程序的入口点脚本(entry-point script)或可执行文件，这是启动程序的主要入口。
cli.py 文件为应用提供了命令行界面。在此文件中的代码将扮演基于 MVC 架构中的视图-控制器角色。
model.py 文件包含了支持应用主要功能的代码。这部分代码将在你的 MVC 布局中扮演模型角色。

你还需要一个 tests/ 包，其中包含针对应用程序组件的单元测试文件。在这个具体的项目布局示例中，你有 test_cli.py 用于检查 CLI 功能的单元测试，以及 test_model.py 用于检查你的模型代码的单元测试。

pyproject.toml 文件允许你定义应用程序的构建系统以及许多其他常规配置。以下是一个如何为你的示例 hello_cli 项目填写此文件的简单示例：

# pyproject.toml

[build-system]
requires = ["setuptools>=64.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "hello_cli"
version = "0.0.1"
description = "My awesome Hello CLI application"
readme = "README.md"
authors = [{ name = "Real Python", email = "info@realpython.com" }]

[project.scripts]
hello_cli = "hello_cli.__main__:main"

[build-system] 表头将 setuptools 设置为应用程序的构建系统，并指定 Python 需要安装哪些依赖项来构建应用程序。[project] 表头为你的应用提供了通用元数据。这些元数据在你想要将应用发布到 Python 包索引（PyPI）时非常有用。最后， [project.scripts] 表头定义了你的应用程序的入口点。

经过这次对 CLI 项目布局和构建的快速探索，你已经准备好继续学习 argparse 了，特别是如何自定义你的命令行参数解析器。

自定义你的命令行参数解析器

在前面的部分中，你已经学习了如何使用 Python 的 argparse 模块为你的程序或应用实现命令行接口的基础知识。同时，你也了解了如何按照 MVC 模式组织和规划 CLI 应用项目。

在接下来的部分中，你将更深入地探索 argparse 的许多其他强大功能。特别是，你将学习如何在 ArgumentParser 构造函数中使用一些最有用的参数，这将使你能够自定义 CLI 应用的一般行为。

调整程序的 Help 和 Usage 内容

向 CLI 应用程序的用户提供使用说明和帮助是一种最佳实践，可以通过出色的用户体验 (UX) 让用户更加愉快。在本节中，你将了解如何利用 ArgumentParser 的一些参数来微调 CLI 应用程序向用户显示帮助和使用消息的方式。你将学习如何：

设置程序名称
定义程序的描述和结束消息
对参数和选项进行分组显示帮助

首先，你将开始设置你的程序名称，并指定该名称在帮助或使用说明消息中的显示方式。

设置程序名称

默认情况下，argparse 会使用 sys.argv 中的第一个值来设置程序的名称。这个第一项包含你刚刚执行的 Python 文件的名称。这个文件名在使用说明消息中看起来会有些奇怪。

例如，继续使用 -h 选项运行自定义 ls 命令：

$ python ls.py -h
usage: ls.py [-h] [-l] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit
  -l, --long

命令输出中的高亮行显示 argparse 正在使用文件名 ls.py 作为程序的名称。这看起来有些奇怪，因为在使用说明消息中，应用名称很少包含文件扩展名。

幸运的是，你可以使用 prog 参数来指定你的程序名称，就像下面的代码片段所示：

# ls.py v3

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(prog="ls")

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, long=args.long))

使用 prog 参数，你可以指定将在使用说明消息中使用的程序名称。在这个例子中，你使用了字符串 "ls"。现在，继续运行你的应用：

$ python ls.py -h
usage: ls [-h] [-l] path

positional arguments:
  path

options:
  -h, --help  show this help message and exit
  -l, --long

很好！这个输出的第一行中的使用说明消息显示程序名称为 ls，而不是 ls.py。

除了设置程序名称外，argparse 还允许你定义应用的描述和结尾信息。在接下来的部分中，你将学习如何进行这两方面的操作。

定义程序的描述和结语消息

你还可以为你的应用定义一个通用的描述和一个结尾或结束语。为此，你将分别使用 description 和 epilog 参数。接下来，请更新 ls.py 文件，在 ArgumentParser 构造函数中添加以下内容：

# ls.py v4

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(
    prog="ls",
    description="List the content of a directory",
    epilog="Thanks for using %(prog)s! :)",
)

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, long=args.long))

在这次更新中，description 参数允许你为应用提供一个通用的描述。这个描述将显示在帮助消息的开头。epilog 参数则允许你定义一些文本作为应用的结尾或结束语。请注意，你可以使用旧式的字符串格式化操作符(%)将 prog 参数插入到 epilog 字符串中。

如果再次运行该应用程序，你将得到如下输出：

$ python ls.py -h
usage: ls [-h] [-l] path

List the content of a directory

positional arguments:
  path

options:
  -h, --help  show this help message and exit
  -l, --long

Thanks for using ls! :)

现在，输出会在使用消息之后显示描述消息，并在帮助文本末尾显示结语消息。

显示参数和选项的分组帮助

帮助分组(Help groups)是 argparse 的另一个有趣特性。它们允许你将相关的命令和参数进行分组，从而帮助你组织应用的帮助消息。要创建这些帮助分组，你将使用 ArgumentParser 的 .add_argument_group() 方法。

作为一个例子，请考虑你自定义的 ls 命令的以下更新版本：

# ls.py v5
# ...

parser = argparse.ArgumentParser(
    prog="ls",
    description="List the content of a directory",
    epilog="Thanks for using %(prog)s! :)",
)

general = parser.add_argument_group("general output")
general.add_argument("path")

detailed = parser.add_argument_group("detailed output")
detailed.add_argument("-l", "--long", action="store_true")

args = parser.parse_args()

# ...

for entry in target_dir.iterdir():
    print(build_output(entry, long=args.long))

在这次更新中，你为显示一般输出的参数和选项创建了一个帮助分组，并为显示详细输出的参数和选项创建了另一个分组。

如果你在命令行中使用 -h 选项运行应用程序，那么你将获得以下输出：

python ls.py -h
usage: ls [-h] [-l] path

List the content of a directory

options:
  -h, --help  show this help message and exit

general output:
  path

detailed output:
  -l, --long

Thanks for using ls! :)

现在，你的应用的参数和选项在帮助消息中以描述性的标题进行了方便的分组。这个整洁的特性将帮助你为用户提供更多的上下文，并帮助他们更好地理解应用的工作原理。

为参数和选项提供全局设置

除了自定义使用说明和帮助消息外，ArgumentParser 还允许你对命令行界面（CLI）应用进行其他一些有趣的调整。这些调整包括：

为参数和选项定义全局默认值
从外部文件中加载参数和选项
允许或禁止选项缩写

有时，你可能需要为你的应用的参数和选项指定一个全局默认值。你可以通过在调用 ArgumentParser 构造函数时，将默认值传递给 argument_default 参数来实现这一点（注意：实际上 ArgumentParser 没有 argument_default 这个参数，但这里是为了说明可以全局设置默认值的概念。在实际应用中，你可能需要为每个参数单独设置默认值）。

这个特性可能并不常用，因为参数和选项通常具有不同的数据类型或意义，很难找到一个满足所有需求的值。

然而，argument_default(尽管 ArgumentParser 并没有直接提供这个参数，但这里是为了说明概念）的一个常见用例是当你想要避免将参数和选项添加到 Namespace 对象中。在这种情况下，你可以使用 SUPPRESS 常量作为默认值。这个默认值将确保只有命令行中提供的参数和选项才会被存储在 arguments 的 Namespace 中。

作为一个例子，请继续修改你的自定义 ls 命令，如下面的代码片段所示：

# ls.py v6

import argparse
import datetime
from pathlib import Path

parser = argparse.ArgumentParser(
    prog="ls",
    description="List the content of a directory",
    epilog="Thanks for using %(prog)s! :)",
    argument_default=argparse.SUPPRESS,
)

# ...

for entry in target_dir.iterdir():
    try:
        long = args.long
    except AttributeError:
        long = False
    print(build_output(entry, long=long))

通过将 SUPPRESS 传递给 ArgumentParser 构造函数，你可以防止未提供的参数被存储在 argparse.Namespace 对象中。这就是为什么在调用 build_output() 之前，你需要检查 -l 或 --long 选项是否实际被传递了。否则，你的代码会因为 args 中不存在 long 属性而引发 AttributeError 错误。

ArgumentParser 的另一个酷炫功能是允许你从外部文件中加载参数值。当你有一个具有冗长或复杂的命令行结构的应用，并希望自动化加载参数值的过程时，这个功能就非常有用。

在这种情况下，你可以将参数值存储在一个外部文件中，并让你的程序从该文件中加载它们。为了尝试这个功能，请继续创建一个简单的命令行界面（CLI）应用，如下所示：

# fromfile.py

import argparse

parser = argparse.ArgumentParser(fromfile_prefix_chars="@")

parser.add_argument("one")
parser.add_argument("two")
parser.add_argument("three")

args = parser.parse_args()

print(args)

在这里，你向 ArgumentParser 的 fromfile_prefix_chars 参数传递 @ 符号。然后，你创建了三个必须在命令行中提供的必需参数。

现在，假设你经常使用此应用程序，并且总是使用相同的一组参数值。为了简化和优化你的工作流程，你可以创建一个文件，其中包含所有必需参数的适当值，每个参数占一行，就像下面的 args.txt 文件一样：

first
second
third

有了这个文件，您现在可以调用您的程序并指示它从 args.txt 文件加载值，如以下命令运行所示：

$ python fromfile.py @args.txt
Namespace(one='first', two='second', three='third')

在此命令的输出中，你可以看到 argparse 已经读取了 args.txt 的内容，并顺序地将值分配给了 fromfile.py 程序的每个参数。所有参数及其值都已成功存储在 Namespace 对象中。

接受缩写选项名称的能力是 argparse 命令行界面（CLI）的另一个酷炫特性。这个特性是默认启用的，当你的程序具有长选项名称时非常有用。例如，考虑以下程序，它会在命令行下打印出你在 --argument-with-a-long-name 选项后指定的值：

# abbreviate.py

import argparse

parser = argparse.ArgumentParser()

parser.add_argument("--argument-with-a-long-name")

args = parser.parse_args()

print(args.argument_with_a_long_name)

这个程序会打印出你在 --argument-with-a-long-name 选项后传入的任何参数值。现在，请继续运行以下命令来检查 Python 的 argparse 模块如何处理这些缩写：

$ python abbreviate.py --argument-with-a-long-name 42
42

$ python abbreviate.py --argument 42
42

$ python abbreviate.py --a 42
42

这些示例展示了如何缩写 --argument-with-a-long-name 选项的名称，而应用程序仍能正常工作。此功能是默认启用的。如果你希望禁用它并禁止缩写，那么可以在 ArgumentParser 中使用 allow_abbrev 参数：

# abbreviate.py

import argparse

parser = argparse.ArgumentParser(allow_abbrev=False)

parser.add_argument("--argument-with-a-long-name")

args = parser.parse_args()

print(args.argument_with_a_long_name)

将 allow_abbrev 设置为 False 会禁用命令行选项中的缩写。从这一点开始，你将需要为程序提供完整的选项名称才能正确工作。否则，你会收到一个错误：

$ python abbreviate.py --argument-with-a-long-name 42
42

$ python abbreviate.py --argument 42
usage: abbreviate.py [-h] [--argument-with-a-long-name ...]
abbreviate.py: error: unrecognized arguments: --argument 42

第二个示例中的错误消息告诉你 --argument 选项没有被识别为有效的选项。要使用该选项，你需要提供它的完整名称。

微调你的命令行参数和选项

到目前为止，你已经学习了如何定制 ArgumentParser 类的多个功能，以改善你的命令行界面（CLI）的用户体验。现在，你知道了如何调整你的应用程序的使用说明和帮助信息，以及如何微调命令行参数和选项的一些全局方面。

在本节中，你将学习如何定制你的 CLI 的命令行参数和选项的其他几个功能。在这种情况下，你将使用 .add_argument() 方法及其一些最相关的参数，包括 action、type、nargs、default、help 等。

设置 Option 背后的 Action

当你向命令行界面添加一个选项或标志时，通常需要定义如何将选项的值存储在调用 .parse_args() 后得到的 Namespace 对象中。为此，你会使用 .add_argument() 的 action 参数。action 参数的默认值为 "store"，意味着提供的选项值将原样存储在 Namespace 中。

action 参数可以接受几个可能的值。以下是这些可能值的列表及其含义：

Pandas 处理 Excel 常用方法技巧

Thu, 29 Oct 2026 02:50:07 GMT

在使用 Pandas 前需要学习了解一下 Series 和 DataFrame 的基本数据结构和索引的相关概念，之后就可以练习基本的 Excel操作。Pandas 读取一个 Excel 文件后会将其转化为 DataFrame 对象，每一列或行就是一个 Series 对象。这里我们看下如何对一个 excel 进行读写，以及 Sheet、行列、表头处理的一些常用技巧。

读取 Excel

如果您想读取 Excel 表格中的数据，可以使用 read_excel() 方法，其语法格式如下：

pd.read_excel(io, sheet_name=0, header=0, names=None, index_col=None,
              usecols=None, squeeze=False,dtype=None, engine=None,
              converters=None, true_values=None, false_values=None,
              skiprows=None, nrows=None, na_values=None, parse_dates=False,
              date_parser=None, thousands=None, comment=None, skipfooter=0,
              convert_float=True, **kwds)

下表对常用参数做了说明：

参数名称	说明
io	表示 Excel 文件的存储路径。
sheet_name	要读取的工作表名称，默认0，即读取第一个工作表作为 DataFrame(一定要加`sheet_name=None`，才能读取出所有的 sheet，否则默认读取第一个 sheet)。
header	指定作为列名的行，默认0，即取第一行的值为列名；若数据不包含列名，则设定 header = None。若将其设置为 header=2，则表示将前两行作为多重索引。
names	一般适用于Excel缺少列名，或者需要重新定义列名的情况；names的长度必须等于Excel表格列的长度，否则会报错。
index_col	用做行索引的列，可以是工作表的列名称，如 index_col = '列名'，也可以是整数或者列表。
usecols	int或list类型，默认为None，表示需要读取所有列。
squeeze	boolean，默认为False，如果解析的数据只包含一列，则返回一个Series。
converters	规定每一列的数据类型。
skiprows	接受一个列表，表示跳过指定行数的数据，从头部第一行开始。
nrows	需要读取的行数。
skipfooter	接受一个列表，省略指定行数的数据，从尾部最后一行开始。

示例如下所示：

import pandas as pd

# 读取所有Sheet
df = pd.read_excel('example.xlsx', sheet_name=None)

# 读取第一个、第二个和名为"Sheet5"的工作表作为 DataFrame 的字典
df = pd.read_excel('example.xlsx', sheet_name=[0, 1, "Sheet5"])

获取行数和列数

import pandas as pd
 
df = pd.read_excel('example.xlsx')
# 行索引
print(df.index)  
# RangeIndex(start=0, stop=3747, step=1)

# 输出元祖,分别为行数和列数,默认第一行是表头不算行数
print(df.shape) 
# (3747, 4)

获取表头

read_excel 默认是把 excel 的第一行当成表头。注意：如果 read_excel 的 sheet_name=None，读取的是所有 excel 的 sheet_name(key) 和 sheet_values(values) 组成的字典，df.keys() 的结果是所有 sheet_name，即名字(字典的键)。

获取第一个 sheet

这时候 df.keys() 和 df.columns 的结果是一样的，都是第一个 sheet 的表头。

import pandas as pd
 
df = pd.read_excel('input.xlsx')
print(df.keys())
print('---------------')
print(df.columns)

获取所有 sheet

import pandas as pd
 
# 参数为 None 代表读取所有 sheet
df = pd.read_excel('input.xlsx',sheet_name=None)

# 获取所有sheet名字, 如果read_excel参数不是None, 则df.keys()为表头
sheet_names = list(df.keys())
print(sheet_names)

参考资料

老董，《pandas获取excel的行数,列数,表头,sheet,前后行等数据》，Python编程网
《Pandas Excel读写操作详解》，C语言中文网
《pandas.read_excel — pandas 2.1.4 documentation》，pandas documentation — pandas 2.1.4 documentation

不要使用 requirements.txt

Thu, 29 Oct 2026 02:48:42 GMT

原文：Do not use requirements.txt

你是否在用 Python 开发后端服务？我有两条建议：

不要使用 pip 和 requirements.txt 来管理 Python 依赖。它们缺乏一些应该内置的关键功能。
改用 Poetry。

对我来说，第一条建议毋庸置疑。第二条则更具有暂时性：Poetry 是一个很好的选择，但并非唯一值得考虑的选择。

我将在下面进行解释。

请注意：如果你使用 Python 做其他事情而不是构建后端服务，那么本文中的建议可能并不适用于你。例如，如果你是一个正在迁移 setup.py 的库开发者，Poetry 并不明显是一个完美的选择。

PIP 缺失的功能

pip 是一个工具，你可以用它从 The Python Package Index (PyPI) 中安装软件包。它随 Python 一起安装，如果你是 Python 开发者，你可能已经多次使用过它。

管理 Python 项目依赖的传统方式是将它们列在一个名为 requirements.txt 的文件中，并使用 pip install -r requirements.txt 进行安装。然而，pip 被设计成一个软件包安装工具，而不是一个功能齐全的项目工作流工具。pip 缺乏两个关键功能，即依赖的锁定文件 (dependency lockfiles) 和虚拟环境的自动管理(automatic management of virtualenvs)。

依赖锁定文件

如果你希望在所有环境中（比如你的笔记本电脑、持续集成(CI)、生产环境）获得相同的行为，你需要锁定你的依赖项及其传递依赖的版本。你可以在 requirements.txt 中锁定你直接依赖的版本，例如，使用 requests==2.31.0 而不是 requests。

然而，pip 不会锁定传递依赖的版本。这可以通过使用 pip-tools 来解决，将 requirements.txt 扩展成一个列出完整依赖图的文件，包括准确版本和构件的校验和(checksums for the artifacts)。pip-tools 很不错，但你需要自行设置并弄清楚它如何适应你的工作流程。

在其他编程语言中，这个功能是基本要求的 - 例如，npm 多年来一直有 package-lock.json，Cargo 也有 Cargo.lock。这个功能实在应该是一个项目工作流工具中的内置功能。

虚拟环境的自动管理

在 Python 中创建隔离环境的方式是使用 virtualenvs。传统上，你需要手动管理它们：通过一个 shell 命令创建一个（比如 python -m venv example 来创建名为 example 的虚拟环境），当你想要使用它时，需要用另一个 shell 命令来激活它。

这容易出错：忘记激活虚拟环境或者激活错误的虚拟环境是常见的错误。有一堆的解决方法。例如，你可以使用 pyenv-virtualenv，在进入项目目录时让你的 shell 自动激活一个虚拟环境。direnv 也可以做到。

同样，这也应该成为工作流工具中的一个内置功能。你不应该需要将多个工具粘合在一起。你不会听到 npm 或 Cargo 用户在虚拟环境上遇到问题的。

Poetry 及其他选择

幸运的是，许多人已经意识到这些问题并努力解决它们。不太幸运的是，这导致了大量的 Python 项目工作流工具涌现。那么该如何选择呢？

我的建议是：选择 Poetry。它有锁定文件，有虚拟环境管理，而且很受欢迎且在积极开发中。根据我的经验，它并不完美，但是它起作用。

你也可以考虑 Hatch 或 PDM。它们与 Poetry 相似。我自己没有使用过它们，但我听说其他人成功地使用了它们。Hatch 似乎在库作者 (library authors) 中特别受欢迎。

如果你正在寻找一个更强大的选项，可以处理多个子项目，Pants 构建系统在 Python 支持方面做得很好。然而，它的学习曲线相对陡峭。

最后，如果你正在寻找一个类似 rustup 那样可以为你安装 Python 的解决方案，那么有 rye。它是新的实验性工具，但也许它对你来说是正确的选择？

哪个是权威的工作流工具？

如果 Python 自带一个权威的项目工作流工具会很好。很多人希望 pip 成为这样一个工具。Node.js 自带 npm，Rust 自带 Cargo，那么为什么 Python 就不能有一个呢？为什么会有这么多竞争的选择呢？

据我所知，最大的障碍是，由于 Python 被广泛使用且用于许多不同的用例，制定一个通用的官方解决方案是困难且缓慢的（并且资金不足的）工作。另外，也不清楚 pip 是否适合这些功能。

如果你想了解更多信息，请阅读和听取这些与我不同、深度参与 Python 社区的人的意见：

Stargirl (Thea Flowers) on Fediverse：《所以你想解决 Python 打包问题：一个实用指南》
Pradyun Gedam：《关于 Python 打包生态系统的思考》
Talk Python to Me (podcast)：《重新构想 Python 的打包工作流程》

关于 Clojure

阅读我的博客的 Clojure 开发者可能会问：嘿，Clojure 怎么样？为什么我们没有锁定文件呢？这是一个很好的问题！

Clojure 社区通过始终使用明确的版本而不是版本范围来解决了这个问题，即使在库中也是如此。版本描述实际上支持范围，但没有人会使用它们。这样，只要版本解析算法稳定，你总是会得到相同的版本。

理论上，传递依赖项版本不匹配可能是一个问题，但 Clojure 支持一种编码风格，很少引起问题。

相比之下，在 Python 和 Node.js 社区，通常期望库列出其依赖项的版本范围，而软件包管理工具会抱怨版本不匹配的问题。

MkDocs 的缓慢崩溃

Mon, 26 Oct 2026 06:06:34 GMT

从 2023 年 7 月开始，个人的博客站点从 Hugo 换成了 Material for MkDocs 并在 2026 年换成了 MaterialX，但始终都没有脱离过 MkDocs 的框架。

作为使用者，和 MkDocs 生态关注者，现如今 MkDocs 生态系统分崩离析，给大家分享一篇来自 Florian Maas 在 2026 年 3 月 22 写的《The Slow Collapse of MkDocs》文章，看看性格冲突、创始人缺席以及备受争议的重新设计如何导致 Python 最受欢迎的项目之一分崩离析。

2026 年 3 月 9 日， MkDocs 的一位前维护者接管了 PyPI 代码库的控制权，并撤销了原作者的权限。原作者迅速作出回应：

然后他们提交了一份 PyPI 支持工单以重新获得控制权，但在工单得到处理之前，问题就已得到了解决。

MkDocs 为超过 90,000 个 GitHub 项目提供文档支持，其中大多数项目都依赖于由 @squidfunk 开发的 Material for MkDocs 主题，该主题非常受欢迎，其获得的星标数甚至超过了 MkDocs 本身。

PyPI 被接管事件不过是更深层次问题的一个最为显眼的症状表现。如今，任何使用 Material for MkDocs 的人都会在终端中看到以下警告信息：

MkDocs 项目已经超过 18 个月没有进行任何实质性的开发。Material for MkDocs 目前处于维护模式。而曾经两大主导工具携手共进的局面已不复存在，如今有多款工具竞相涌现，试图取而代之：如 ProperDocs、MaterialX（"新一代的 mkdocs-material"）以及 Zensical（"由 Material for MkDocs 开发者打造的现代化静态网站生成器"）。

我们怎么会走到这一步？要了解事情的全貌，我们需要稍微回顾一下过去 ……

2014年1月11日 - MkDocs 的诞生

2014 年 1 月 11 日，Mia Kimberly Christie（ @lovelydinosaur ）提交了第一个代码，也就是后来的 MkDocs，并附上了 "Hell yeah" 的消息。接下来的几个月里，提交数量激增。

这种活跃期并没有持续太久。到 2014 年年中，他们在代码库中的活动就完全停止了。

其他开发者也加入了这个项目，比如 @d0ugal 和 @waylan。@lovelydinosaur 此后便不再活跃，而在 2016 年 7 月至 2021 年 7 月期间，@waylan 似乎是该项目的唯一维护者。

该项目越来越受欢迎，到 2022 年年中，该项目在 GitHub 上积累了超过 14,000 个星标。

2020年4月27日 - oprypin 加入了该项目

2020 年 4 月 27 日，新贡献者 @oprypin 首次为该项目做出贡献：提交了一个 bug 修复方案。@waylan 同意了这些更改,并合并了 PR。

在首次提交贡献后，@oprypin 有大约半年时间未参与该项目，之后他又进入了一段长时间的高频活跃期；修复 bug、添加新功能等等，不一而足。

@oprypin 和 @waylan 之间似乎存在一些摩擦。例如，@waylan 就不同意 @oprypin 提出的一个潜在的性能改进方案：

2021年5月16日 - waylan 下台

@oprypin 的不满情绪日益加剧，最终他发起了一个题为 "关于 MkDocs 维护工作的担忧（Concerns about maintainership of MkDocs）" 的讨论帖。在这篇长文中，他指责 @waylan 对项目进行独断专行式的管控，且在没有技术依据的情况下拒绝他人贡献，并提出了另一种维护模式，以减轻单一维护者的责任负担。

他将该帖子的副本发布到他自己 fork 的仓库中。两个帖子均未引发过多讨论，但普遍共识是，尽管事实与观点难以分辨，但该帖子过于针对个人，项目原作者（且基本已不再活跃）也提到了这一点：

就在 @oprypin 发起讨论的同一天，@waylan 宣布退出该项目：

2021年6月7日 - oprypin 接管

由于 @waylan 已不再担任项目维护者，因此需要新的维护者。@lovelydinosaur 发起了一项讨论，征求关于维护者人选的建议。@oprypin 立即表示他愿意接手项目的维护工作。

@lovelydinosaur 并没有立即接受他的提议，但 @oprypin 希望继续开发这个项目，所以几周后他又回到了这个帖子：

一段时间后，@lovelydinosaur 似乎不太愿意授予 @oprypin 项目写入权限，且回复迟缓，此时 Material for MkDocs 的原作者兼维护者 @squidfunk 也加入了讨论。

之后，@lovelydinosaur 邀请了一群维护者加入 MkDocs：

大约一年后，@oprypin 请求提升对 Github 仓库和 PyPI 项目的权限：

获得所有者权限后，@oprypin 成为 MkDocs 的主要维护者。在接下来的两年里，他与其他维护者和贡献者一起稳步推进项目。修复 bug、更新依赖项、添加新功能，项目持续向前发展。

请注意，由于 @oprypin 目前已被禁止参与该项目，因此无法在 MkDocs 存储库中找到上述图表中的数据，但仍然可以在 MkDocs 的分支中找到，例如这里。

2024年2月25日 - 紧张局势公开爆发

一次常规的文档问题讨论，因 @squidfunk 在帖子中指责 Read the Docs 从 MkDocs 项目中获利却未回馈社区而升级，演变成了另一回事。@oprypin 趁机表态：

@squidfunk 回复：

随后，双方公开长篇追溯过往恩怨：@oprypin 坚称自己并无过错，@squidfunk 则回忆曾作为 @oprypin 的首位赞助者，力排众议推荐其加入 MkDocs 团队，但因多次个人冲突，最终选择将沟通限制在公开渠道。

在完成对文档小问题的修复后，该问题被标记为已解决。

2024年3月16日 - oprypin 将 squidfunk 从组织中移除

我们回到之前的帖子，@lovelydinosaur 在其中宣布他们已将 @oprypin、 @squidfunk 和 @ultrabug 添加为该项目的维护者。

3 月 16 日，@squidfunk 发帖：

原来，这个决定是 @oprypin 独自做出的：

不久后，@lovelydinosaur 加入讨论，恢复了 @squidfunk 在 MkDocs 组织中的成员身份，并撤销了 @oprypin 对代码仓库的所有权。

2024年4月6日 - oprypin 下台

4 月 6 日，@lovelydinosaur 写道：

三个小时后，@oprypin 宣布他将从 MkDocs 项目卸任。在他的帖子中，他详细阐述了他与 @squidfunk 的分歧、对 @lovelydinosaur 介入的不满，以及维护该项目的孤独感：

他决定协助团队于 2024 年 4 月 20 日发布 1.6.0 版本，除同年 8 月 30 日发布的 1.6.1 版本外，截至本文撰写时该版本仍是最新版本。

2024年4月8日 - 社区短暂集结

@oprypin 卸任两天后，活跃社区成员兼 mkdocstrings 作者 @pawamoy 在一个题为 "推动 MkDocs 迈向新高度" 的帖子中，邀请约 25 位插件和主题作者共同参与 MkDocs 的维护工作，反响热烈。@squidfunk 表示对此 "深感振奋（eally psyched to see this happening）"，他还补充道：

4 月 23 日，在 @oprypin 发布最后一个版本几天后，@lovelydinosaur 发帖宣布将回归担任首席维护者。此时，距离其上一次向代码仓库提交的拉取请求被合并已过去整整八年。其明确目标为：MkDocs 应拥有 "独立于Material for MkDocs的强有力领导团队"。他们标记了 28 位社区成员，并安排了周六的线上电话会议。

会议如期举行。@squidfunk 拒绝参加。仅两人到场。此后十八个月，该帖子再无公开活动记录。

2024年5月17日 - lovelydinosaur 回归

由于 @oprypin 不再参与该项目，MkDocs 的开发基本上停止了。

在向 MkDocs 提交部分拉取请求的同时，他们还开始在 mkdocs/sketch 代码库中着手对 MkDocs 进行重新设计。

2024年8月1日 - 无需插件的重新设计

@lovelydinosaur 向 MkDocs 核心团队展示了其提出的 MkDocs 重新设计方案演示。MkDocs 目前会一次性构建整个站点，而新方案则按需动态生成页面。此提议引发了维护者及核心贡献者的担忧：

在另一个无关的讨论帖中，@lovelydinosaur 表示其正致力于对 MkDocs 进行无需任何插件的重新设计。

该帖子收到的反对票表明，这并非社区真正希望看到的。

2024年8月30日 - MkDocs 的最新版本

MkDocs 1.6.1 版本已发布。截至目前，这仍是最新版本，除对文档进行一两次修订及更新持续集成（CI）徽章外，该代码库没有进行任何积极的开发。

2025年7月17日 - 这个项目被搁置了吗？

插件作者 @facelessuser 发起了一个直接提问的讨论：

他指出，尽管有积极的赞助商，但修复 bug 的 PR 已经几个月没有经过审核了。

@pawamoy 的回应清晰呈现了自 2024 年 4 月以来发生的情况。他表示曾尝试围绕 @lovelydinosaur 的回归构建协作维护模式，却发现 @lovelydinosaur 对现有代码库兴趣寥寥，转而专注于重新设计。当 @pawamoy 致力于整理待办事项列表并尝试维护项目的同时，@lovelydinosaur 在被提及 PR 时却杳无音信。

@lovelydinosaur 回复称，其一直专注于当前处于早期预发布阶段的 httpx 1.0 项目，并正在考虑是否有时间为 MkDocs 腾出时间。@facelessuser 回应如下：

8 月 3 日，大约十天后，@oprypin 自离开后首次重新出现在该帖子中。他提出回归的条件只有一个：

@lovelydinosaur 没有回复。

2025年10月15日 - 幕后工作仍在继续

当 MkDocs 用户纷纷要求修复漏洞时，@lovelydinosaur 却在另一个尚未公开的代码库（encode/mkdocs）中继续推进 MkDocs 的重新设计工作。

2025年11月11日 - squidfunk 宣布推出 Zensical

2025 年 11 月 11 日，mkdocs-material 9.7.0 版本发布，同时宣布 Material for MkDocs 项目进入维护模式。与之同步发布的还有 Zensical —— 一款由 Material for MkDocs 团队全新打造的现代化静态网站生成器。团队表示，该工具可原生解析现有 mkdocs.yml 配置文件，重建速度提升5倍，并配备全新设计的搜索引擎。

在 2024 年 4 月的维护者讨论帖中（该帖已沉寂数月），有人发布了一篇博文链接，并询问 Material for Mkdocs 进入维护模式是否意味着 MkDocs 需要重新开始。@oprypin 再次出现，指出 Zensical 就是一个新的开始。关于 MkDocs，他说道：

在 Material for MkDocs 宣布进入维护模式几周后， @jaywhj 发布了 MaterialX 的第一个版本，它是 Material for MkDocs 的延续。

2026年1月14日 - MkDocs 2.0

2026 年 1 月 14 日，@lovelydinosaur 表示，欢迎他人发布 MkDocs 1.6.2 版本，而其正私下开展 MkDocs v2 的开发工作。

然后，在 1 月 21 日，@lovelydinosaur 发起了一个讨论，宣布推出 MkDocs 版本 2：

绝大多数用户都持负面态度。。社区认为，拟议的 MkDocs 2.0 主要缺点在于缺乏插件支持，而插件正是 MkDocs 最初成功的关键所在。

@facelessuser 道出了社区中许多人的心声：

@oprypin 一个月前也表达了相同观点。社区成员注意到，MkDocs 2.0 版本代码库被放置在 encode 组织而非 MkDocs 组织下，且 encode 组织的贡献指南明确禁止提交 issue 或 pull request。他们还强调，不公开源代码违背了开源软件开发的原则。最终，@lovelydinosaur 解释了该代码库设为私有的原因：

2 月 13 日，@lovelydinosaur 删除了关于计划使 MkDocs 2.x 向后兼容 MkDocs 1.x 的通知。

2 月 18 日，Material for MkDocs 团队发布了一篇详尽的博客文章，全面分析了 MkDocs v2 版本为何与其工作及更广泛的插件生态系统不兼容，涵盖从移除插件系统到缺失许可证等诸多问题。

2026年3月9日 - PyPI 接管事件

2 月 18 日，Material for MkDocs 在每次 mkdocs 构建时均显示警告信息，提醒用户可能存在与 MkDocs 2 未来不兼容的问题，并附上上述博客文章链接。

@oprypin 此前提出的获取 PyPI 所有权的请求已于过去某个时间获得批准。虽然他在 2024 年卸任后，其对 GitHub 代码库的权限已被剥夺，但他对 PyPI 仓库的权限仍然有效。

3 月 9 日，为防止用户项目因意外升级至不受欢迎的 MkDocs 2.0 版本而受损，@oprypin 采取最后手段，利用其权限将所有其他维护者（包括原作者 @lovelydinosaur）移出项目。他在 GitHub 的两个讨论区宣布接管：一个在 mkdocs（后被编辑），另一个在 mkdocs-community（该组织后更名为 ProperDocs）。其核心理由是，静默发布 v2 版本会导致运行 pip install mkdocs 的用户意外地破坏他们的项目。他随后在 mkdocs-community/mkdocs 创建新仓库，宣布未来 PyPI 版本将由此发布，并呼吁社区支持。

@lovelydinosaur 向 PyPI 提交了支持工单，并将 @oprypin 排除在 MkDocs GitHub 组织之外。

6 小时内， @oprypin 做出让步并道歉：

@lovelydinosaur 重新获得 PyPI 访问权限。

在另一场讨论中， @Andre601 表达了他对项目现状的担忧，并就项目维护的未来提出了各种问题， @lovelydinosaur 对此作出了回应：

2026年3月15日 - oprypin 推出 ProperDocs

在接管 PyPI 六天后，@oprypin 正式发布 ProperDocs：一款可无缝替代 MkDocs 1.x 的工具。用户只需将 pip install mkdocs 替换为 pip install properdocs，将 mkdocs build 替换为 properdocs build 即可。现有插件无需修改代码即可使用。该项目还发布警告，引导用户远离 MkDocs 2.0。

那么，如今的情况又如何呢？

原 MkDocs 代码库已有 18 个月未进行实质性开发。其原作者兼唯一维护者 @lovelydinosaur 正在推进一项缺乏社区支持且会破坏现有插件生态系统的重新设计。encode/mkdocs v2 代码库自 2026 年 2 月 19 日起已停止更新。

与此同时，构建该生态系统最广泛使用组件的核心人员已转向其他项目。

@oprypin 表示，继续推进需要双方达成一致，但认为此举难以成功，因此独立启动了 ProperDocs 项目。该项目并未立即获得巨大成功，一周后，它在 GitHub 上获得了 21 个星标。

@jaywhj 正在维护 MaterialX，由于原项目 Material for MkDocs 进入了维护模式，该项目似乎在社区中获得了一些关注。

负责 MkDocs Material 的 @squidfunk 团队已停止开发，转而从零开始构建 Zensical。MkDocs 生态系统中最活跃的贡献者之一 @pawamoy 也加入了该项目。截至撰写本文时，Zensical 在 GitHub 上已获得超过 3700 个 star，目前看来是最受欢迎的项目，因此它也极有可能成功，并在未来取代 MkDocs。

MkDocs 生态系统正在实时分裂。三个继任者，三种愿景，以及一个需要决定押注哪一方的社区。

用 Github Discussions 搭建自己的论坛、博客、个人笔记

Mon, 26 Oct 2026 06:02:55 GMT

分享一下我的经验。你也可以用 Github Discussions 搭建自己的论坛、博客、个人笔记等。

欢迎订阅

用户有自主选择权，只看他感兴趣的内容。

可以点击项目的 Watch 按钮来订阅消息。具体用法请看 Github - 查看订阅。
也可以只订阅某个讨论。进入某个讨论，点击右边 Notifications 的 Subscribe 按钮。
用户可以在 https://github.com/notifications 里看到订阅的新消息。

本仓库谈论说明

这里所有的 Discussion Format 都是 Announcement：Only maintainers and admins can post new discussions in these categories, but anyone can comment and reply.

使用讨论 (Discussion)

搜索讨论

版块搜索：在 Discussions 页面的搜索框输入搜索词即可。
全局搜索：在最上面的 Github 搜索框输入 org:shenweiyan 搜索词 就能搜索所有版块的讨论。比如搜"生信"。

排序讨论

可以按时间来排序讨论。

使用 Label 筛选讨论

Label 是可以无限加的。一个讨论可以有多个 Label。
标记 Label 的好处在于，用户可以在讨论列表里筛选、多选、反选 Label 对应的讨论。

评论有两种。一种是在别人的评论下继续回复评论。一种是最底下的评论框，这会回复到主线里。

如果你针对某个评论进行回复，建议在别人的评论下回复，不要回复到主线。这样其他订阅这个讨论的人不会收到消息提醒的干扰。

讨论管理

讨论分类

讨论分类由项目管理员维护。按需创建。分类根据名称排序。所以加个数字前缀用来控制显示顺序。

删除讨论

点进讨论详情页，在右侧最底下有个 delete discussion。

迁移讨论

Transfer this discussion 功能可以把讨论移到同组织的另一个项目下。
也可以切换讨论分类。

置顶讨论

在讨论详情页面可以选择置到项目 Discussion 的顶部，或者置到讨论分类的顶部。

周报月报

可以考虑使用 Github Action 自动跑脚本，通过 Github API 来获取 Discussion 的消息。然后自动创建 release，把简报内容写到 release body 里。这样订阅了项目 release 的人就可以收到。可以单独创建一个项目来管理，避免订阅的人受到干扰。

Github Discussion API:

数据备份

可以考虑使用 Github Action 自动跑脚本，通过 Github API 来获取 Discussion 的消息。

移动端

Github 有移动端 App。除了不支持 Polls 功能，其他功能都挺好用的。能查看提醒，也能发布新讨论，也能回复评论。

邮件端

消息提醒同时会发到你绑定的邮箱里。你也可以用邮箱来查收。

博文中加评论

借助 giscus，可以非常方便在文章页中插入指定的 discussions —— 在导出 discussions 的时候，在文章尾部增加类似以下 JavaScript 即可：

<script src="https://giscus.app/client.js"
        data-repo="shenweiyan/shenweiyan.github.io"
        data-repo-id="R_kgDOKgxWlg"
        data-mapping="number"
        data-term="4"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="light"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

Welcome to repozine-demo Discussions!

Mon, 26 Oct 2026 05:17:34 GMT

👋 Welcome!

We’re using Discussions as a place to connect with other members of our community. We hope that you:

Ask questions you’re wondering about.
Share ideas.
Engage with other community members.
Welcome others and are open-minded. Remember that this is a community we
build together 💪.

To get started, comment below with an introduction of yourself and tell us about what you do with this community.