python-libfaketime: fast date/time mocking
python-libfaketime is a wrapper of libfaketime for python. Some brief details:
- Linux and OS X, Pythons 3.5 through 3.8, pypy and pypy3
- Mostly compatible with freezegun.
- Microsecond resolution.
- Accepts datetimes and strings that can be parsed by dateutil.
- Not threadsafe.
- Will break profiling. A workaround: use
libfaketime.{begin, end}_callbackto disable/enable your profiler (nosetest example).
Installation
$ pip install libfaketime
Usage
import datetime
from libfaketime import fake_time, reexec_if_needed
# libfaketime needs to be preloaded by the dynamic linker.
# This will exec the same command, but with the proper environment variables set.
# You can also skip this and manually manage your env (see "How to avoid re-exec").
reexec_if_needed()
def test_datetime_now():
# fake_time can be used as a context_manager
with fake_time('1970-01-01 00:00:01'):
# Every calls to a date or datetime function returns the mocked date
assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)
assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 0, 0, 1)
assert time.time() == 1
# fake_time can also be used as a decorator
@fake_time('1970-01-01 00:00:01', tz_offset=12)
def test_datetime_now_with_offset():
# datetime.utcnow returns the mocked datetime without offset
assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)
# datetime.now returns the mocked datetime with the offset passed to fake_time
assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 12, 0, 1)
Performance
libfaketime tends to be significantly faster than freezegun. Here's the output of a totally unscientific benchmark on my laptop:
$ python benchmark.py
re-exec with libfaketime dependencies
timing 1000 executions of <class 'libfaketime.fake_time'>
0.021755 seconds
$ python benchmark.py freezegun
timing 1000 executions of <function freeze_time at 0x10aaa1140>
6.561472 seconds
Use with py.test
The pytest-libfaketime plugin will automatically configure python-libfaketime for you:
$ pip install pytest-libfaketime
Alternatively, you can reexec manually from inside the pytest_configure hook:
# conftest.py
import os
import libfaketime
def pytest_configure():
libfaketime.reexec_if_needed()
_, env_additions = libfaketime.get_reload_information()
os.environ.update(env_additions)
Use with tox
In your tox configuration file, under the testenv bloc, add the libfaketime environment variables to avoid re-execution:
setenv =
LD_PRELOAD = {envsitepackagesdir}/libfaketime/vendor/libfaketime/src/libfaketime.so.1
DONT_FAKE_MONOTONIC = 1
FAKETIME_DID_REEXEC = true
Migration from freezegun
python-libfaketime should have the same behavior as freezegun when running on supported code. To migrate to it, you can run:
find . -type f -name "*.py" -exec sed -i 's/freezegun/libfaketime/g' "{}" \;
How to avoid re-exec
In some cases - especially when your tests start other processes - re-execing can cause unexpected problems. To avoid this, you can preload the necessary environment variables yourself. The necessary environment for your system can be found by running python-libfaketime on the command line:
$ python-libfaketime
export LD_PRELOAD="/home/foo/<snip>/vendor/libfaketime/src/libfaketime.so.1"
export DONT_FAKE_MONOTONIC="1"
export FAKETIME_DID_REEXEC=true
You can easily put this in a script like:
$ eval $(python-libfaketime)
$ pytest # ...or any other code that imports libfaketime
Contributing and testing
Contributions are welcome! You should compile libfaketime before running tests:
make -C libfaketime/vendor/libfaketime
Then you can install requirements with pip install -r requirements.txt and use pytest and tox to run the tests.
uuid1 deadlock
Calling uuid.uuid1() multiple times while in a fake_time context can result in a deadlock when an OS-level uuid library is available. To avoid this, python-libtaketime will monkeypatch uuid._uuid_generate_time (or similar, it varies by version) to None inside a fake_time context. This may slow down uuid1 generation but should not affect correctness.
7 Dec 27, 2022
41 Dec 31, 2022
26 Nov 15, 2022
1 Nov 19, 2021
2 Jan 17, 2022
11 Nov 25, 2022
325 Dec 30, 2022
3.8k Feb 13, 2021
362 Dec 23, 2022
6 Sep 12, 2022
147 Dec 15, 2022
7 Dec 29, 2022
1 Jan 27, 2022
4 Dec 28, 2022
6 Dec 22, 2022
452 Dec 28, 2022
2k Jan 6, 2023
3.8k Jan 3, 2023