Metadata-Version: 2.1
Name: libfaketime
Version: 2.1.0
Summary: A fast alternative to freezegun that wraps libfaketime.
Home-page: http://pypi.python.org/pypi/libfaketime/
Author: Simon Weber
Author-email: simon@simonmweber.com
License: GPLv2
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dateutil>=1.3
Requires-Dist: pytz

python-libfaketime: fast date/time mocking
==========================================

[![github actions](https://github.com/simon-weber/python-libfaketime/actions/workflows/tests.yaml/badge.svg)](https://github.com/simon-weber/python-libfaketime/actions/workflows/tests.yaml)
[![pypi](https://img.shields.io/pypi/v/libfaketime.svg)](https://pypi.python.org/pypi/libfaketime)
[![repominder](https://img.shields.io/badge/dynamic/json.svg?label=release&query=%24.status&maxAge=43200&uri=https%3A%2F%2Fwww.repominder.com%2Fbadge%2FeyJmdWxsX25hbWUiOiAic2ltb24td2ViZXIvcHl0aG9uLWxpYmZha2V0aW1lIn0%3D%2F&link=https%3A%2F%2Fwww.repominder.com%2F)](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
