time-machine 2.15.0

travel(destination, *, tick=True)

travel() 是一个允许时间旅行的类，可以移动到由 destination 指定的日期时间。它是通过模拟 Python 标准库中所有返回当前日期或日期时间的函数来实现的。它可以独立使用，作为函数装饰器，或作为上下文管理器。

destination 指定了要移动到的日期时间。它可以是指：

• 一个 datetime.datetime。如果是无知的，它将被假定为 UTC 时区。如果设置了 tzinfo 为一个 zoneinfo.ZoneInfo 实例，当前时区也将被模拟。

• 一个 datetime.date。这将转换为 UTC 日期时间，时间为 00:00:00。

• 一个 datetime.timedelta。这将被解释为相对于当前时间。如果在 travel() 块内，则 shift() 方法更易于使用（下面将进行说明）。

• 一个指定 Unix 时间戳 的 float 或 int。

• 一个字符串，它将使用 dateutil.parse 进行解析，并转换为时间戳。如果结果是无知的，它将被假定为本地时间。

此外，您还可以提供一些更复杂的数据类型：

• 一个生成器，在这种情况下，将对它调用 next()，并将结果按上述方式处理。

• 一个可调用对象，在这种情况下，它将不带参数被调用，并将结果按上述方式处理。

tick 定义了在旅行后时间是否继续“滴答”或被冻结。如果为 True，默认值，则对模拟函数的后续调用返回的值将增加自第一次调用以来经过的实时时间。因此，在开始旅行到 0.0（UNIX 纪元）后，对任何日期时间函数的第一次调用将返回其 1970-01-01 00:00:00.000000 的表示。后续调用“滴答”，所以如果调用正好晚半秒钟，它将返回 1970-01-01 00:00:00.500000。

import datetime as dt
import time_machine

traveller = time_machine.travel(dt.datetime(1985, 10, 26))
traveller.start()
# It's the past!
assert dt.date.today() == dt.date(1985, 10, 26)
traveller.stop()
# We've gone back to the future!
assert dt.date.today() > dt.date(2020, 4, 29)

import time
import time_machine


@time_machine.travel("1970-01-01 00:00 +0000")
def test_in_the_deep_past():
    assert 0.0 < time.time() < 1.0

import time
import time_machine


@time_machine.travel("1970-01-01 00:00 +0000")
async def test_in_the_deep_past():
    assert 0.0 < time.time() < 1.0

import time
import time_machine


def test_in_the_deep_past():
    with time_machine.travel(0.0):
        assert 0.0 < time.time() < 1.0

import time
import time_machine
import unittest


@time_machine.travel(0.0)
class DeepPastTests(TestCase):
    def test_in_the_deep_past(self):
        assert 0.0 < time.time() < 1.0

import datetime as dt
import time
from zoneinfo import ZoneInfo
import time_machine

hill_valley_tz = ZoneInfo("America/Los_Angeles")


@time_machine.travel(dt.datetime(2015, 10, 21, 16, 29, tzinfo=hill_valley_tz))
def test_hoverboard_era():
    assert time.tzname == ("PST", "PDT")
    now = dt.datetime.now()
    assert (now.hour, now.minute) == (16, 29)

坐标

start() 方法以及上下文管理器的入口都返回一个与给定“旅行”时间对应的 Coordinates 对象。它有几个可以用来在其它时间旅行的方法。

import datetime as dt
import time
import time_machine

with time_machine.travel(0, tick=False) as traveller:
    assert time.time() == 0

    traveller.move_to(234)
    assert time.time() == 234

import datetime as dt
import time
import time_machine

with time_machine.travel(0, tick=False) as traveller:
    assert time.time() == 0

    traveller.shift(dt.timedelta(seconds=100))
    assert time.time() == 100

    traveller.shift(-dt.timedelta(seconds=10))
    assert time.time() == 90

pytest 插件

time-machine 还可以作为 pytest 插件使用。它提供了一个函数作用域的固定装置，名为 time_machine，具有 move_to() 和 shift() 方法，它们的签名与 Coordinates 中的等效方法相同。这可以用来在不同的时间点模拟测试，并在测试拆解时自动取消模拟。

例如

import datetime as dt


def test_delorean(time_machine):
    time_machine.move_to(dt.datetime(1985, 10, 26))

    assert dt.date.today().isoformat() == "1985-10-26"

    time_machine.move_to(dt.datetime(2015, 10, 21))

    assert dt.date.today().isoformat() == "2015-10-21"

    time_machine.shift(dt.timedelta(days=1))

    assert dt.date.today().isoformat() == "2015-10-22"

如果您正在使用 pytest 测试类，您可以通过添加自动使用固定装置将固定装置应用于类中的所有测试方法

import time

import pytest


class TestSomething:
    @pytest.fixture(autouse=True)
    def set_time(self, time_machine):
        time_machine.move_to(1000.0)

    def test_one(self):
        assert int(time.time()) == 1000.0

    def test_two(self, time_machine):
        assert int(time.time()) == 1000.0
        time_machine.move_to(2000.0)
        assert int(time.time()) == 2000.0

escape_hatch

“escape_hatch”对象提供了绕过时间机的函数。这些函数允许您调用真实的datetime函数，而不进行任何模拟。它还提供了一种方法来检查时间机是否正在当前进行时间旅行。

在罕见情况下，这些功能很有用。例如，如果您需要在时间旅行期间与外部服务进行身份验证，您可能需要datetime.now()的真实值。

这些函数是

• escape_hatch.is_travelling() -> bool - 如果time_machine.travel()处于活动状态，则返回True，否则返回False。

• escape_hatch.datetime.datetime.now() - 包装真实的datetime.datetime.now()。

• escape_hatch.datetime.datetime.utcnow() - 包装真实的datetime.datetime.utcnow()。

• escape_hatch.time.clock_gettime() - 包装真实的time.clock_gettime()。

• escape_hatch.time.clock_gettime_ns() - 包装真实的time.clock_gettime_ns()。

• escape_hatch.time.gmtime() - 包装真实的time.gmtime()。

• escape_hatch.time.localtime() - 包装真实的time.localtime()。

• escape_hatch.time.strftime() - 包装真实的time.strftime()。

• escape_hatch.time.time() - 包装真实的time.time()。

• escape_hatch.time.time_ns() - 包装真实的time.time_ns()。

例如

import time_machine


with time_machine.travel(...):
    if time_machine.escape_hatch.is_travelling():
        print("We need to go back to the future!")

    real_now = time_machine.escape_hatch.datetime.datetime.now()
    external_authenticate(now=real_now)

unittest.mock

标准库的unittest.mock可用于针对datetime和time的导入来更改返回的当前时间值。不幸的是，这是脆弱的，因为它仅影响模拟的目标导入位置。因此，如果您有多个模块在调用树中请求日期/时间，则需要多个模拟。这是unittest.mock的通用问题 - 请参阅为什么你的模拟不起作用。

无法模拟某些引用，例如函数默认参数

def update_books(_now=time.time):  # set as default argument so faster lookup
    for book in books:
        ...

尽管这种情况很少见，但它们有时被用于优化高度重复的循环。

freezegun

Steve Pulec的freezegun库是一种流行的解决方案。它提供了一个清晰的API，这是时间机的大部分灵感来源。

其主要缺点是其实施速度较慢。它基本上是对所有已导入datetime和time模块的位置进行了查找和替换的模拟。这绕过了使用unittest.mock的问题，但意味着模拟所需的时间与加载的模块数量成正比。在大型项目中，这可能需要几秒钟，对于单个测试来说是不切实际的额外开销。

它也不是一个完美的搜索，因为它只搜索模块级别的导入。这种导入无疑是项目使用日期和时间函数最常见的方式，但并非唯一的方式。freezegun无法找到被“隐藏”在任意对象中的函数，例如类级别的属性。

它也无法影响调用标准库函数的C扩展，包括（我相信）Cython化的Python代码。

python-libfaketime

Simon Weber的python-libfaketime封装了libfaketime库。libfaketime用自身的封装替换了所有针对当前时间的C级系统调用。因此，它是对当前进程的“完美”模拟，影响当前时间可能被获取的每个点，并且比freezegun执行速度快得多。

不幸的是，python-libfaketime带有LD_PRELOAD的限制。这是一个在程序加载时替换系统库的机制（解释）。这在使用python-libfaketime时导致两个特别的问题。

首先，LD_PRELOAD仅适用于Unix平台，这阻止你在Windows上使用它。

其次，你必须帮助管理LD_PRELOAD。你可以使用python-libfaketime的reexec_if_needed()函数，该函数在加载时重启（重新执行）你的测试进程，或者手动管理LD_PRELOAD环境变量。这两种方法都不理想。重新执行会破坏可能封装你的测试进程的任何内容，如分析器、调试器和IDE测试运行器。手动管理环境变量会带来一些开销，并且必须在运行测试的每个环境中执行，包括每个开发者的机器。

time-machine

time-machine旨在结合freezegun和libfaketime的优点。它不使用LD_PRELOAD，但仍然在所有可能引用标准库函数的地方进行模拟。它的弱点是它不会模拟使用日期和时间系统调用的其他库。幸运的是，这种情况很少见。也有可能将这些python库添加到time-machine模拟的集合中。

一个缺点是它仅适用于CPython，因此不能与其他Python解释器（如PyPy）一起使用。然而，它可能通过不同的模拟机制扩展以支持其他解释器。