Python Ellipsis (...) 在文档测试中的高级用法

半杯拿铁

发布时间：2026-10-14 | 2人浏览过

原创

本文详解 Python 中 Ellipsis (...) 单例对象的特殊用法，重点介绍如何在 doctest 文档测试中使用 +ELLIPSIS 选项忽略对象内存地址变化。通过对比报错与成功案例，展示如何利用省略号简化测试用例编写，提高自动化测试的稳定性与代码可读性。

Python Ellipsis 背景与基本概念

背景介绍

在 Python 的基础类型体系中，存在三个具有单例性质的特殊值：None（NoneType）、NotImplemented（NotImplementedType）以及 Ellipsis（EllipsisType，即 ...）。

None 的应用场景极为广泛，NotImplemented 在运算符重载中也较为常见，唯独 Ellipsis（...）虽然作为这三者之一被熟知，但其实际用途往往鲜为人知。

Ellipsis 对象

Ellipsis 在 Python 中象征“省略”，通俗理解即为“忽略细节”。一个典型的应用场景是处理随机生成的值，当具体数值不重要时，可以使用它来忽略细节。

Ellipsis 在文档测试中的核心用法

文档测试中的应用

假设我们编写了一个类，为了验证其语法层面是否存在错误，通常只需简单调用即可发现。为了实现测试自动化，我们可以采用文档测试（doctest）的方式。


#!/usr/bin/evn python3

class Person(object):
  """人类类型
  Parameters:
  ----------
    name: str
    age: int

  Return:
  ------

  >>> Person()
  <main.Person object at 0x7ff36c1ca250>
  """

  name = ''
  age = 0

  def __init__(self, name: str = 'tom', age: int = 10) -> 'Person':
    """初始化
    """
    self.name = name
    self.age = age

  def say_hello(self) -> str:
    """返回打招呼信息
    """
    return f"Hello My name is {self.name} ."

直接运行测试用例时通常会失败，原因在于每次实例化对象时，其内存地址是动态分配的，并不固定等于测试用例中硬编码指定的地址。虽然可以使用 unittest 模块解决此问题，但这并非本文讨论的重点。


python3 -m doctest main.py -v
Trying:
  Person()
Expecting:
  <main.Person object at 0x7ff36c1ca250>
**********************************************************************
File "/private/tmp/main.py", line 12, in main.Person
Failed example:
  Person()
Expected:
  <main.Person object at 0x7ff36c1ca250>
Got:
  <main.Person object at 0x7fe4e078ac70>
3 items had no tests:
  main
  main.Person.__init__
  main.Person.say_hello
**********************************************************************
1 items had failures:
  1 of  1 in main.Person
1 tests in 4 items.
0 passed and 1 failed.
***Test Failed*** 1 failures.

那么，如何让 doctest 忽略返回值中的内存地址细节呢？解决方案是引入 Ellipsis 指令。改造后的代码如下所示。


#!/usr/bin/evn python3


class Person(object):
  """人类类型
  Parameters:
  ----------
    name: str
    age: int

  Return:
  ------

  >>> Person() #doctest: +ELLIPSIS
  <main.Person object at 0x...>
  """

  name = ''
  age = 0

  def __init__(self, name: str = 'tom', age: int = 10) -> 'Person':
    """初始化
    """
    self.name = name
    self.age = age

  def say_hello(self) -> str:
    """返回打招呼信息
    """
    return f"Hello My name is {self.name} ."

执行测试用例后，测试即可顺利通过。


python3 -m doctest main.py -v
Trying:
  Person() #doctest: +ELLIPSIS
Expecting:
  <main.Person object at 0x...>
ok
3 items had no tests:
  main
  main.Person.__init__
  main.Person.say_hello
1 items passed all tests:
  1 tests in main.Person
1 tests in 4 items.
1 passed and 0 failed.
Test passed.

模块级测试的其他应用方式

其他应用场景

如果测试目标是整个模块，可以采用以下更便捷的方式编写测试用例。


#!/usr/bin/evn python3


class Person(object):
  """人类类型
  Parameters:
  ----------
    name: str
    age: int

  Return
  ------

  >>> Person() #doctest: +ELLIPSIS
  <...Person object at 0x...>
  """

  name = ''
  age = 0

  def __init__(self, name: str = 'tom', age: int = 10) -> 'Person':
    """初始化
    """
    self.name = name
    self.age = age

  def say_hello(self) -> str:
    """返回打招呼信息
    """
    return f"Hello My name is {self.name} ."


if __name__ == "__main__":
  # 因为在模块在被 import 的时候 __name__ 直接等于 模块名 不等于 “__main__” ，所以在作为模块被导入时并不会执行测试用例
  # 如果想执行测试用例直接执行模块就行
  import doctest
  doctest.testmod()

以上即为 Python Ellipsis 在文档测试中的详细用法，更多关于 Python Ellipsis 的资料，欢迎查阅本站其他相关文章。