python-libfaketime: fast date/time mocking
==========================================
[](https://github.com/simon-weber/python-libfaketime/actions/workflows/tests.yaml)
[](https://pypi.python.org/pypi/libfaketime)
[](https://www.repominder.com)
python-libfaketime is a wrapper of [libfaketime](https://github.com/wolfcw/libfaketime) for python.
Some brief details:
* Linux and OS X, Pythons 3.8 through 3.12, pypy and pypy3
* Mostly compatible with [freezegun](https://github.com/spulec/freezegun).
* Microsecond resolution.
* Accepts datetimes and strings that can be parsed by dateutil.
* Not threadsafe.
* Will break profiling. A workaround: use ``libfaketime.{begin, end}_callback`` to disable/enable your profiler ([nosetest example](https://gist.github.com/simon-weber/8d43e33448684f85718417ce1a072bc8)).
Installation
------------
```sh
$ pip install libfaketime
```
Usage
-----
```python
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)
```
### remove_vars
By default, ``reexec_if_needed`` removes the ``LD_PRELOAD`` variable after the
re-execution, to keep your environment as clean as possible. You might want it
to stick around, for example when using parallelized tests that use subprocess
like ``pytest-xdist``, and simply for tests where subprocess is called. To
keep them around, pass ``remove_vars=False`` like:
```python
reexec_if_needed(remove_vars=False)
```
### quiet
To avoid displaying the informative text when re-executing, you can set the
`quiet` parameter:
```python
reexec_if_needed(quiet=True)
```
### timestamp_file
A common time can be shared between several execution contexts by using a file
to store the time to mock, instead of environment variables. This is useful
to control the time of a running process for instance. Here is a schematized
use case:
```python
reexec_if_needed(remove_vars=False)
with fake_time("1970-01-01 00:00:00", timestamp_file="/tmp/timestamp"):
subprocess.run("/some/server/process")
with fake_time("2000-01-01 00:00:00", timestamp_file="/tmp/timestamp"):
assert request_the_server_process_date() == "2000-01-01 00:00:00"
```
Performance
-----------
libfaketime tends to be significantly faster than [freezegun](https://github.com/spulec/freezegun).
Here's the output of a [totally unscientific benchmark](https://github.com/simon-weber/python-libfaketime/blob/master/benchmark.py) on my laptop:
```sh
$ 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](https://github.com/pytest-dev/pytest-libfaketime) plugin will automatically configure python-libfaketime for you:
```sh
$ pip install pytest-libfaketime
```
Alternatively, you can reexec manually from inside the pytest_configure hook:
```python
# 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:
```ini
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:
```bash
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:
```sh
$ python-libfaketime
export LD_PRELOAD="/home/foo/<snip>/vendor/libfaketime/src/libfaketime.so.1"
export DONT_FAKE_MONOTONIC="1"
export FAKETIME_NO_CACHE="1"
export FAKETIME_DID_REEXEC=true
```
You can easily put this in a script like:
```sh
$ eval $(python-libfaketime)
$ pytest # ...or any other code that imports libfaketime
```
Contributing and testing
------------------------
Contributions are welcome! You should compile libfaketime before running tests:
```bash
git submodule init --update
# For Linux:
env FAKETIME_COMPILE_CFLAGS="-UFAKE_STAT -UFAKE_UTIME -UFAKE_SLEEP" make -C libfaketime/vendor/libfaketime
# For macOS
env 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.
Changelog
=========
[Semantic versioning](http://semver.org/) is used.
2.1.0
-----
released 2024-05-17
Thanks for @azmeuk for all their contributions to this release!
- add support for timestamp files, which enables freezing time across subprocesses: [#78](https://github.com/simon-weber/python-libfaketime/pull/78)
- upgrade underlying libfaketime to 0.9.10 without modifications: [#75](https://github.com/simon-weber/python-libfaketime/pull/75)
- add a quiet param to rexec_if_needed: [#72](https://github.com/simon-weber/python-libfaketime/pull/72)
2.0.0
-----
released 2020-04-17
- breaking: drop python 2.7 support
- set LD_LIBRARY_PATH on linux to support paths containing spaces: [#57](https://github.com/simon-weber/python-libfaketime/pull/57)
- fix compatibility with non-pytz tzinfo objects: [#58](https://github.com/simon-weber/python-libfaketime/pull/58)
1.2.1
-----
released 2019-01-20
- fix a deadlock on python 3.7+
1.2.0
-----
released 2018-10-28
- offset-aware datetimes now properly fake the timezone as well: [#49](https://github.com/simon-weber/python-libfaketime/pull/49)
1.1.0
-----
released 2018-10-07
- decorated classes can access the fake_time object with ``self._faked_time``: [#47](https://github.com/simon-weber/python-libfaketime/pull/47)
1.0.0
-----
released 2018-06-16
- **backwards incompatible**: the monotonic clock is no longer mocked: [#45](https://github.com/simon-weber/python-libfaketime/pull/45)
- ensure TZ is set to a valid timezone: [#46](https://github.com/simon-weber/python-libfaketime/pull/46)
0.5.2
-----
released 2018-05-19
- fix a bug causing incorrect times after unpatching under python 3.6+: [#43](https://github.com/simon-weber/python-libfaketime/pull/43)
- fix compilation under gcc8: [#44](https://github.com/simon-weber/python-libfaketime/pull/44)
0.5.1
-----
released 2018-01-19
- fix usage as a class decorator : [#41](https://github.com/simon-weber/python-libfaketime/pull/41)
0.5.0
-----
released 2017-09-10
- alias fake_time for freeze_time: [#31](https://github.com/simon-weber/python-libfaketime/pull/31)
- add tz_offset parameter: [#36](https://github.com/simon-weber/python-libfaketime/pull/36)
0.4.4
-----
released 2017-07-16
- allow contextlib2 as an alternative to contextdecorator: [#30](https://github.com/simon-weber/python-libfaketime/pull/30)
0.4.3
-----
released 2017-07-07
- add macOS Sierra compatibility: [#29](https://github.com/simon-weber/python-libfaketime/pull/29)
0.4.2
-----
released 2016-06-30
- fix only_main_thread=False: [#24](https://github.com/simon-weber/python-libfaketime/pull/24)
0.4.1
-----
released 2016-05-02
- fix deadlocks from uuid.uuid1 when faking time: [#14](https://github.com/simon-weber/python-libfaketime/pull/14)
- remove contextdecorator dependency on python3: [#15](https://github.com/simon-weber/python-libfaketime/pull/15)
0.4.0
-----
released 2016-04-02
- freezegun's tick() is now supported; see [their docs](https://github.com/spulec/freezegun/blob/f1f5148720dd715cfd6dc03bf1861dbedfaad493/README.rst#manual-ticks) for usage.
0.3.0
-----
released 2016-03-04
- invoking ``libfaketime`` from the command line will now print the necessary environment to avoid a re-exec.
0.2.1
-----
released 2016-03-01
- python 3 support
0.1.1
-----
released 2015-09-11
- prevent distribution of test directory: https://github.com/simon-weber/python-libfaketime/pull/4
0.1.0
-----
released 2015-06-23
- add global start/stop callbacks
0.0.3
-----
released 2015-03-28
- initial packaged release
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/libfaketime/",
"name": "libfaketime",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Simon Weber",
"author_email": "simon@simonmweber.com",
"download_url": "https://files.pythonhosted.org/packages/c9/ec/a02a79d0254957f340a11c350de2a8ae43cfe2ececc11fc7a951f6f9d263/libfaketime-2.1.0.tar.gz",
"platform": null,
"description": "python-libfaketime: fast date/time mocking\n==========================================\n\n[](https://github.com/simon-weber/python-libfaketime/actions/workflows/tests.yaml)\n[](https://pypi.python.org/pypi/libfaketime)\n[](https://www.repominder.com)\n\npython-libfaketime is a wrapper of [libfaketime](https://github.com/wolfcw/libfaketime) for python.\nSome brief details:\n\n* Linux and OS X, Pythons 3.8 through 3.12, pypy and pypy3\n* Mostly compatible with [freezegun](https://github.com/spulec/freezegun).\n* Microsecond resolution.\n* Accepts datetimes and strings that can be parsed by dateutil.\n* Not threadsafe.\n* Will break profiling. A workaround: use ``libfaketime.{begin, end}_callback`` to disable/enable your profiler ([nosetest example](https://gist.github.com/simon-weber/8d43e33448684f85718417ce1a072bc8)).\n\n\nInstallation\n------------\n\n```sh\n$ pip install libfaketime\n```\n\nUsage\n-----\n\n```python\nimport datetime\nfrom libfaketime import fake_time, reexec_if_needed\n\n# libfaketime needs to be preloaded by the dynamic linker.\n# This will exec the same command, but with the proper environment variables set.\n# You can also skip this and manually manage your env (see \"How to avoid re-exec\").\nreexec_if_needed()\n\ndef test_datetime_now():\n\n # fake_time can be used as a context_manager\n with fake_time('1970-01-01 00:00:01'):\n\n # Every calls to a date or datetime function returns the mocked date\n assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)\n assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 0, 0, 1)\n assert time.time() == 1\n\n\n# fake_time can also be used as a decorator\n@fake_time('1970-01-01 00:00:01', tz_offset=12)\ndef test_datetime_now_with_offset():\n\n # datetime.utcnow returns the mocked datetime without offset\n assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)\n\n # datetime.now returns the mocked datetime with the offset passed to fake_time\n assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 12, 0, 1)\n```\n\n### remove_vars\n\nBy default, ``reexec_if_needed`` removes the ``LD_PRELOAD`` variable after the\nre-execution, to keep your environment as clean as possible. You might want it\nto stick around, for example when using parallelized tests that use subprocess\nlike ``pytest-xdist``, and simply for tests where subprocess is called. To\nkeep them around, pass ``remove_vars=False`` like:\n\n```python\nreexec_if_needed(remove_vars=False)\n```\n\n### quiet\n\nTo avoid displaying the informative text when re-executing, you can set the\n`quiet` parameter:\n\n```python\nreexec_if_needed(quiet=True)\n```\n\n### timestamp_file\n\nA common time can be shared between several execution contexts by using a file\nto store the time to mock, instead of environment variables. This is useful\nto control the time of a running process for instance. Here is a schematized\nuse case:\n\n```python\nreexec_if_needed(remove_vars=False)\n\nwith fake_time(\"1970-01-01 00:00:00\", timestamp_file=\"/tmp/timestamp\"):\n subprocess.run(\"/some/server/process\")\n\nwith fake_time(\"2000-01-01 00:00:00\", timestamp_file=\"/tmp/timestamp\"):\n assert request_the_server_process_date() == \"2000-01-01 00:00:00\"\n```\n\nPerformance\n-----------\n\nlibfaketime tends to be significantly faster than [freezegun](https://github.com/spulec/freezegun).\nHere's the output of a [totally unscientific benchmark](https://github.com/simon-weber/python-libfaketime/blob/master/benchmark.py) on my laptop:\n\n```sh\n$ python benchmark.py\nre-exec with libfaketime dependencies\ntiming 1000 executions of <class 'libfaketime.fake_time'>\n0.021755 seconds\n\n$ python benchmark.py freezegun\ntiming 1000 executions of <function freeze_time at 0x10aaa1140>\n6.561472 seconds\n```\n\nUse with py.test\n----------------\n\nThe [pytest-libfaketime](https://github.com/pytest-dev/pytest-libfaketime) plugin will automatically configure python-libfaketime for you:\n\n```sh\n$ pip install pytest-libfaketime\n```\n\nAlternatively, you can reexec manually from inside the pytest_configure hook:\n\n```python\n# conftest.py\nimport os\nimport libfaketime\n\ndef pytest_configure():\n libfaketime.reexec_if_needed()\n _, env_additions = libfaketime.get_reload_information()\n os.environ.update(env_additions)\n```\n\nUse with tox\n------------\n\nIn your tox configuration file, under the ``testenv`` bloc, add the libfaketime environment variables to avoid re-execution:\n\n```ini\nsetenv =\n LD_PRELOAD = {envsitepackagesdir}/libfaketime/vendor/libfaketime/src/libfaketime.so.1\n DONT_FAKE_MONOTONIC = 1\n FAKETIME_DID_REEXEC = true\n```\n\nMigration from freezegun\n------------------------\n\npython-libfaketime should have the same behavior as freezegun when running on supported code. To migrate to it, you can run:\n\n```bash\nfind . -type f -name \"*.py\" -exec sed -i 's/freezegun/libfaketime/g' \"{}\" \\;\n```\n\nHow to avoid re-exec\n--------------------\n\nIn 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:\n\n```sh\n$ python-libfaketime\nexport LD_PRELOAD=\"/home/foo/<snip>/vendor/libfaketime/src/libfaketime.so.1\"\nexport DONT_FAKE_MONOTONIC=\"1\"\nexport FAKETIME_NO_CACHE=\"1\"\nexport FAKETIME_DID_REEXEC=true\n```\n\nYou can easily put this in a script like:\n\n```sh\n$ eval $(python-libfaketime)\n$ pytest # ...or any other code that imports libfaketime\n```\n\nContributing and testing\n------------------------\n\nContributions are welcome! You should compile libfaketime before running tests:\n\n```bash\ngit submodule init --update\n# For Linux:\nenv FAKETIME_COMPILE_CFLAGS=\"-UFAKE_STAT -UFAKE_UTIME -UFAKE_SLEEP\" make -C libfaketime/vendor/libfaketime\n# For macOS\nenv make -C libfaketime/vendor/libfaketime\n```\n\nThen you can install requirements with ``pip install -r requirements.txt`` and use ``pytest`` and ``tox`` to run the tests.\n\nuuid1 deadlock\n--------------\n\nCalling ``uuid.uuid1()`` multiple times while in a fake_time context can result in a deadlock when an OS-level uuid library is available.\nTo avoid this, python-libtaketime will monkeypatch uuid._uuid_generate_time (or similar, it varies by version) to None inside a fake_time context.\nThis may slow down uuid1 generation but should not affect correctness.\n\n\nChangelog\n=========\n\n[Semantic versioning](http://semver.org/) is used.\n\n2.1.0\n-----\nreleased 2024-05-17\n\nThanks for @azmeuk for all their contributions to this release!\n\n- add support for timestamp files, which enables freezing time across subprocesses: [#78](https://github.com/simon-weber/python-libfaketime/pull/78)\n- upgrade underlying libfaketime to 0.9.10 without modifications: [#75](https://github.com/simon-weber/python-libfaketime/pull/75)\n- add a quiet param to rexec_if_needed: [#72](https://github.com/simon-weber/python-libfaketime/pull/72)\n\n2.0.0\n-----\nreleased 2020-04-17\n\n- breaking: drop python 2.7 support\n- set LD_LIBRARY_PATH on linux to support paths containing spaces: [#57](https://github.com/simon-weber/python-libfaketime/pull/57)\n- fix compatibility with non-pytz tzinfo objects: [#58](https://github.com/simon-weber/python-libfaketime/pull/58)\n\n1.2.1\n-----\nreleased 2019-01-20\n\n- fix a deadlock on python 3.7+\n\n1.2.0\n-----\nreleased 2018-10-28\n\n- offset-aware datetimes now properly fake the timezone as well: [#49](https://github.com/simon-weber/python-libfaketime/pull/49)\n\n1.1.0\n-----\nreleased 2018-10-07\n\n- decorated classes can access the fake_time object with ``self._faked_time``: [#47](https://github.com/simon-weber/python-libfaketime/pull/47)\n\n1.0.0\n-----\nreleased 2018-06-16\n\n- **backwards incompatible**: the monotonic clock is no longer mocked: [#45](https://github.com/simon-weber/python-libfaketime/pull/45)\n- ensure TZ is set to a valid timezone: [#46](https://github.com/simon-weber/python-libfaketime/pull/46)\n\n0.5.2\n-----\nreleased 2018-05-19\n\n- fix a bug causing incorrect times after unpatching under python 3.6+: [#43](https://github.com/simon-weber/python-libfaketime/pull/43)\n- fix compilation under gcc8: [#44](https://github.com/simon-weber/python-libfaketime/pull/44)\n\n0.5.1\n-----\nreleased 2018-01-19\n\n- fix usage as a class decorator : [#41](https://github.com/simon-weber/python-libfaketime/pull/41)\n\n0.5.0\n-----\nreleased 2017-09-10\n\n- alias fake_time for freeze_time: [#31](https://github.com/simon-weber/python-libfaketime/pull/31)\n- add tz_offset parameter: [#36](https://github.com/simon-weber/python-libfaketime/pull/36)\n\n0.4.4\n-----\nreleased 2017-07-16\n\n- allow contextlib2 as an alternative to contextdecorator: [#30](https://github.com/simon-weber/python-libfaketime/pull/30)\n\n0.4.3\n-----\nreleased 2017-07-07\n\n- add macOS Sierra compatibility: [#29](https://github.com/simon-weber/python-libfaketime/pull/29)\n\n0.4.2\n-----\nreleased 2016-06-30\n\n- fix only_main_thread=False: [#24](https://github.com/simon-weber/python-libfaketime/pull/24)\n\n0.4.1\n-----\nreleased 2016-05-02\n\n- fix deadlocks from uuid.uuid1 when faking time: [#14](https://github.com/simon-weber/python-libfaketime/pull/14)\n- remove contextdecorator dependency on python3: [#15](https://github.com/simon-weber/python-libfaketime/pull/15)\n\n0.4.0\n-----\nreleased 2016-04-02\n\n- freezegun's tick() is now supported; see [their docs](https://github.com/spulec/freezegun/blob/f1f5148720dd715cfd6dc03bf1861dbedfaad493/README.rst#manual-ticks) for usage.\n\n0.3.0\n-----\nreleased 2016-03-04\n\n- invoking ``libfaketime`` from the command line will now print the necessary environment to avoid a re-exec.\n\n0.2.1\n-----\nreleased 2016-03-01\n\n- python 3 support\n\n0.1.1\n-----\nreleased 2015-09-11\n\n- prevent distribution of test directory: https://github.com/simon-weber/python-libfaketime/pull/4\n\n0.1.0\n-----\nreleased 2015-06-23\n\n- add global start/stop callbacks\n\n0.0.3\n-----\nreleased 2015-03-28\n\n- initial packaged release\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "A fast alternative to freezegun that wraps libfaketime.",
"version": "2.1.0",
"project_urls": {
"Homepage": "http://pypi.python.org/pypi/libfaketime/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0312c28cdc2834bbd71e9300f97093766dfcd4b8f3c7b7059c1e8543c6f3b14c",
"md5": "f733fd47d7b78fa9e2a354cf1783f424",
"sha256": "df72634f79900e71160f4e3ba4cf8f1d7ba6167e7c9a4f28d67c08e0a4f03ba2"
},
"downloads": -1,
"filename": "libfaketime-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f733fd47d7b78fa9e2a354cf1783f424",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 92845,
"upload_time": "2024-05-17T14:23:40",
"upload_time_iso_8601": "2024-05-17T14:23:40.461931Z",
"url": "https://files.pythonhosted.org/packages/03/12/c28cdc2834bbd71e9300f97093766dfcd4b8f3c7b7059c1e8543c6f3b14c/libfaketime-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c9eca02a79d0254957f340a11c350de2a8ae43cfe2ececc11fc7a951f6f9d263",
"md5": "44033c79ab1e73970780ae3d6bf38e01",
"sha256": "5fecd1770565154f892235a39dfc2388b092864ecca24d05456e4f5a947127a3"
},
"downloads": -1,
"filename": "libfaketime-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "44033c79ab1e73970780ae3d6bf38e01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 75103,
"upload_time": "2024-05-17T14:23:42",
"upload_time_iso_8601": "2024-05-17T14:23:42.294929Z",
"url": "https://files.pythonhosted.org/packages/c9/ec/a02a79d0254957f340a11c350de2a8ae43cfe2ececc11fc7a951f6f9d263/libfaketime-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-17 14:23:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "libfaketime"
}
JSON