============
time-machine
============
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/time-machine/main.yml.svg?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/time-machine/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/time-machine/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/time-machine.svg?style=for-the-badge
:target: https://pypi.org/project/time-machine/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
Travel through time in your tests.
A quick example:
.. code-block:: python
import datetime as dt
from zoneinfo import ZoneInfo
import time_machine
hill_valley_tz = ZoneInfo("America/Los_Angeles")
@time_machine.travel(dt.datetime(1985, 10, 26, 1, 24, tzinfo=hill_valley_tz))
def test_delorean():
assert dt.date.today().isoformat() == "1985-10-26"
For a bit of background, see `the introductory blog post <https://adamj.eu/tech/2020/06/03/introducing-time-machine/>`__ and `the benchmark blog post <https://adamj.eu/tech/2021/02/19/freezegun-versus-time-machine/>`__.
----
**Testing a Django project?**
Check out my book `Speed Up Your Django Tests <https://adamchainz.gumroad.com/l/suydt>`__ which covers loads of ways to write faster, more accurate tests.
I created time-machine whilst writing the book.
----
Installation
============
Use **pip**:
.. code-block:: sh
python -m pip install time-machine
Python 3.8 to 3.13 supported.
Only CPython is supported at this time because time-machine directly hooks into the C-level API.
Usage
=====
If you’re coming from freezegun or libfaketime, see also the below section on migrating.
``travel(destination, *, tick=True)``
-------------------------------------
``travel()`` is a class that allows time travel, to the datetime specified by ``destination``.
It does so by mocking all functions from Python's standard library that return the current date or datetime.
It can be used independently, as a function decorator, or as a context manager.
``destination`` specifies the datetime to move to.
It may be:
* A ``datetime.datetime``.
If it is naive, it will be assumed to have the UTC timezone.
If it has ``tzinfo`` set to a |zoneinfo-instance|_, the current timezone will also be mocked.
* A ``datetime.date``.
This will be converted to a UTC datetime with the time 00:00:00.
* A ``datetime.timedelta``.
This will be interpreted relative to the current time.
If already within a ``travel()`` block, the ``shift()`` method is easier to use (documented below).
* A ``float`` or ``int`` specifying a `Unix timestamp <https://en.m.wikipedia.org/wiki/Unix_time>`__
* A string, which will be parsed with `dateutil.parse <https://dateutil.readthedocs.io/en/stable/parser.html>`__ and converted to a timestamp.
If the result is naive, it will be assumed to be local time.
.. |zoneinfo-instance| replace:: ``zoneinfo.ZoneInfo`` instance
.. _zoneinfo-instance: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo
Additionally, you can provide some more complex types:
* A generator, in which case ``next()`` will be called on it, with the result treated as above.
* A callable, in which case it will be called with no parameters, with the result treated as above.
``tick`` defines whether time continues to "tick" after travelling, or is frozen.
If ``True``, the default, successive calls to mocked functions return values increasing by the elapsed real time *since the first call.*
So after starting travel to ``0.0`` (the UNIX epoch), the first call to any datetime function will return its representation of ``1970-01-01 00:00:00.000000`` exactly.
The following calls "tick," so if a call was made exactly half a second later, it would return ``1970-01-01 00:00:00.500000``.
Mocked Functions
^^^^^^^^^^^^^^^^
All datetime functions in the standard library are mocked to move to the destination current datetime:
* ``datetime.datetime.now()``
* ``datetime.datetime.utcnow()``
* ``time.clock_gettime()`` (only for ``CLOCK_REALTIME``)
* ``time.clock_gettime_ns()`` (only for ``CLOCK_REALTIME``)
* ``time.gmtime()``
* ``time.localtime()``
* ``time.monotonic()`` (not a real monotonic clock, returns ``time.time()``)
* ``time.monotonic_ns()`` (not a real monotonic clock, returns ``time.time_ns()``)
* ``time.strftime()``
* ``time.time()``
* ``time.time_ns()``
The mocking is done at the C layer, replacing the function pointers for these built-ins.
Therefore, it automatically affects everywhere those functions have been imported, unlike use of ``unittest.mock.patch()``.
Usage with ``start()`` / ``stop()``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To use independently, create an instance, use ``start()`` to move to the destination time, and ``stop()`` to move back.
For example:
.. code-block:: python
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)
``travel()`` instances are nestable, but you'll need to be careful when manually managing to call their ``stop()`` methods in the correct order, even when exceptions occur.
It's recommended to use the decorator or context manager forms instead, to take advantage of Python features to do this.
Function Decorator
^^^^^^^^^^^^^^^^^^
When used as a function decorator, time is mocked during the wrapped function's duration:
.. code-block:: python
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
You can also decorate asynchronous functions (coroutines):
.. code-block:: python
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
Beware: time is a *global* state - `see below <#caveats>`__.
Context Manager
^^^^^^^^^^^^^^^
When used as a context manager, time is mocked during the ``with`` block:
.. code-block:: python
import time
import time_machine
def test_in_the_deep_past():
with time_machine.travel(0.0):
assert 0.0 < time.time() < 1.0
Class Decorator
^^^^^^^^^^^^^^^
Only ``unittest.TestCase`` subclasses are supported.
When applied as a class decorator to such classes, time is mocked from the start of ``setUpClass()`` to the end of ``tearDownClass()``:
.. code-block:: python
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
Note this is different to ``unittest.mock.patch()``\'s behaviour, which is to mock only during the test methods.
For pytest-style test classes, see the pattern `documented below <#pytest-plugin>`__.
Timezone mocking
^^^^^^^^^^^^^^^^
If the ``destination`` passed to ``time_machine.travel()`` or ``Coordinates.move_to()`` has its ``tzinfo`` set to a |zoneinfo-instance2|_, the current timezone will be mocked.
This will be done by calling |time-tzset|_, so it is only available on Unix.
The ``zoneinfo`` module is new in Python 3.8 - on older Python versions use the |backports-zoneinfo-package|_, by the original ``zoneinfo`` author.
.. |zoneinfo-instance2| replace:: ``zoneinfo.ZoneInfo`` instance
.. _zoneinfo-instance2: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo
.. |time-tzset| replace:: ``time.tzset()``
.. _time-tzset: https://docs.python.org/3/library/time.html#time.tzset
.. |backports-zoneinfo-package| replace:: ``backports.zoneinfo`` package
.. _backports-zoneinfo-package: https://pypi.org/project/backports.zoneinfo/
``time.tzset()`` changes the ``time`` module’s `timezone constants <https://docs.python.org/3/library/time.html#timezone-constants>`__ and features that rely on those, such as ``time.localtime()``.
It won’t affect other concepts of “the current timezone”, such as Django’s (which can be changed with its |timezone-override|_).
.. |timezone-override| replace:: ``timezone.override()``
.. _timezone-override: https://docs.djangoproject.com/en/stable/ref/utils/#django.utils.timezone.override
Here’s a worked example changing the current timezone:
.. code-block:: python
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)
``Coordinates``
---------------
The ``start()`` method and entry of the context manager both return a ``Coordinates`` object that corresponds to the given "trip" in time.
This has a couple methods that can be used to travel to other times.
``move_to(destination, tick=None)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``move_to()`` moves the current time to a new destination.
``destination`` may be any of the types supported by ``travel``.
``tick`` may be set to a boolean, to change the ``tick`` flag of ``travel``.
For example:
.. code-block:: python
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
``shift(delta)``
^^^^^^^^^^^^^^^^
``shift()`` takes one argument, ``delta``, which moves the current time by the given offset.
``delta`` may be a ``timedelta`` or a number of seconds, which will be added to destination.
It may be negative, in which case time will move to an earlier point.
For example:
.. code-block:: python
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 plugin
-------------
time-machine also works as a pytest plugin.
It provides a function-scoped fixture called ``time_machine`` with methods ``move_to()`` and ``shift()``, which have the same signature as their equivalents in ``Coordinates``.
This can be used to mock your test at different points in time and will automatically be un-mock when the test is torn down.
For example:
.. code-block:: python
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"
If you are using pytest test classes, you can apply the fixture to all test methods in a class by adding an autouse fixture:
.. code-block:: python
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``
----------------
The ``escape_hatch`` object provides functions to bypass time-machine.
These allow you to call the real datetime functions, without any mocking.
It also provides a way to check if time-machine is currently time travelling.
These capabilities are useful in rare circumstances.
For example, if you need to authenticate with an external service during time travel, you may need the real value of ``datetime.now()``.
The functions are:
* ``escape_hatch.is_travelling() -> bool`` - returns ``True`` if ``time_machine.travel()`` is active, ``False`` otherwise.
* ``escape_hatch.datetime.datetime.now()`` - wraps the real ``datetime.datetime.now()``.
* ``escape_hatch.datetime.datetime.utcnow()`` - wraps the real ``datetime.datetime.utcnow()``.
* ``escape_hatch.time.clock_gettime()`` - wraps the real ``time.clock_gettime()``.
* ``escape_hatch.time.clock_gettime_ns()`` - wraps the real ``time.clock_gettime_ns()``.
* ``escape_hatch.time.gmtime()`` - wraps the real ``time.gmtime()``.
* ``escape_hatch.time.localtime()`` - wraps the real ``time.localtime()``.
* ``escape_hatch.time.strftime()`` - wraps the real ``time.strftime()``.
* ``escape_hatch.time.time()`` - wraps the real ``time.time()``.
* ``escape_hatch.time.time_ns()`` - wraps the real ``time.time_ns()``.
For example:
.. code-block:: python
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)
Caveats
=======
Time is a global state.
Any concurrent threads or asynchronous functions are also be affected.
Some aren't ready for time to move so rapidly or backwards, and may crash or produce unexpected results.
Also beware that other processes are not affected.
For example, if you use SQL datetime functions on a database server, they will return the real time.
Comparison
==========
There are some prior libraries that try to achieve the same thing.
They have their own strengths and weaknesses.
Here's a quick comparison.
unittest.mock
-------------
The standard library's `unittest.mock <https://docs.python.org/3/library/unittest.mock.html>`__ can be used to target imports of ``datetime`` and ``time`` to change the returned value for current time.
Unfortunately, this is fragile as it only affects the import location the mock targets.
Therefore, if you have several modules in a call tree requesting the date/time, you need several mocks.
This is a general problem with unittest.mock - see `Why Your Mock Doesn't Work <https://nedbatchelder.com//blog/201908/why_your_mock_doesnt_work.html>`__.
It's also impossible to mock certain references, such as function default arguments:
.. code-block:: python
def update_books(_now=time.time): # set as default argument so faster lookup
for book in books:
...
Although such references are rare, they are occasionally used to optimize highly repeated loops.
freezegun
---------
Steve Pulec's `freezegun <https://github.com/spulec/freezegun>`__ library is a popular solution.
It provides a clear API which was much of the inspiration for time-machine.
The main drawback is its slow implementation.
It essentially does a find-and-replace mock of all the places that the ``datetime`` and ``time`` modules have been imported.
This gets around the problems with using unittest.mock, but it means the time it takes to do the mocking is proportional to the number of loaded modules.
In large projects, this can take several seconds, an impractical overhead for an individual test.
It's also not a perfect search, since it searches only module-level imports.
Such imports are definitely the most common way projects use date and time functions, but they're not the only way.
freezegun won’t find functions that have been “hidden” inside arbitrary objects, such as class-level attributes.
It also can't affect C extensions that call the standard library functions, including (I believe) Cython-ized Python code.
python-libfaketime
------------------
Simon Weber's `python-libfaketime <https://github.com/simon-weber/python-libfaketime/>`__ wraps the `libfaketime <https://github.com/wolfcw/libfaketime>`__ library.
libfaketime replaces all the C-level system calls for the current time with its own wrappers.
It's therefore a "perfect" mock for the current process, affecting every single point the current time might be fetched, and performs much faster than freezegun.
Unfortunately python-libfaketime comes with the limitations of ``LD_PRELOAD``.
This is a mechanism to replace system libraries for a program as it loads (`explanation <http://www.goldsborough.me/c/low-level/kernel/2016/08/29/16-48-53-the_-ld_preload-_trick/>`__).
This causes two issues in particular when you use python-libfaketime.
First, ``LD_PRELOAD`` is only available on Unix platforms, which prevents you from using it on Windows.
Second, you have to help manage ``LD_PRELOAD``.
You either use python-libfaketime's ``reexec_if_needed()`` function, which restarts (*re-execs*) your test process while loading, or manually manage the ``LD_PRELOAD`` environment variable.
Neither is ideal.
Re-execing breaks anything that might wrap your test process, such as profilers, debuggers, and IDE test runners.
Manually managing the environment variable is a bit of overhead, and must be done for each environment you run your tests in, including each developer's machine.
time-machine
------------
time-machine is intended to combine the advantages of freezegun and libfaketime.
It works without ``LD_PRELOAD`` but still mocks the standard library functions everywhere they may be referenced.
Its weak point is that other libraries using date/time system calls won't be mocked.
Thankfully this is rare.
It's also possible such python libraries can be added to the set mocked by time-machine.
One drawback is that it only works with CPython, so can't be used with other Python interpreters like PyPy.
However it may possible to extend it to support other interpreters through different mocking mechanisms.
Migrating from libfaketime or freezegun
=======================================
freezegun has a useful API, and python-libfaketime copies some of it, with a different function name.
time-machine also copies some of freezegun's API, in ``travel()``\'s ``destination``, and ``tick`` arguments, and the ``shift()`` method.
There are a few differences:
* time-machine's ``tick`` argument defaults to ``True``, because code tends to make the (reasonable) assumption that time progresses whilst running, and should normally be tested as such.
Testing with time frozen can make it easy to write complete assertions, but it's quite artificial.
Write assertions against time ranges, rather than against exact values.
* freezegun interprets dates and naive datetimes in the local time zone (including those parsed from strings with ``dateutil``).
This means tests can pass when run in one time zone and fail in another.
time-machine instead interprets dates and naive datetimes in UTC so they are fixed points in time.
Provide time zones where required.
* freezegun's ``tick()`` method has been implemented as ``shift()``, to avoid confusion with the ``tick`` argument.
It also requires an explicit delta rather than defaulting to 1 second.
* freezegun's ``tz_offset`` argument is not supported, since it only partially mocks the current time zone.
Time zones are more complicated than a single offset from UTC, and freezegun only uses the offset in ``time.localtime()``.
Instead, time-machine will mock the current time zone if you give it a ``datetime`` with a ``ZoneInfo`` timezone.
Some features aren't supported like the ``auto_tick_seconds`` argument.
These may be added in a future release.
If you are only fairly simple function calls, you should be able to migrate by replacing calls to ``freezegun.freeze_time()`` and ``libfaketime.fake_time()`` with ``time_machine.travel()``.
Raw data
{
"_id": null,
"home_page": null,
"name": "time-machine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "date, datetime, mock, test, testing, tests, time, warp",
"author": null,
"author_email": "Adam Johnson <me@adamj.eu>",
"download_url": "https://files.pythonhosted.org/packages/76/52/cfcf2de9300816ea35ccdfee7097d0226793516588423497c1ae35a75372/time_machine-2.14.2.tar.gz",
"platform": null,
"description": "============\ntime-machine\n============\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/time-machine/main.yml.svg?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/time-machine/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/time-machine/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/time-machine.svg?style=for-the-badge\n :target: https://pypi.org/project/time-machine/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nTravel through time in your tests.\n\nA quick example:\n\n.. code-block:: python\n\n import datetime as dt\n from zoneinfo import ZoneInfo\n import time_machine\n\n hill_valley_tz = ZoneInfo(\"America/Los_Angeles\")\n\n\n @time_machine.travel(dt.datetime(1985, 10, 26, 1, 24, tzinfo=hill_valley_tz))\n def test_delorean():\n assert dt.date.today().isoformat() == \"1985-10-26\"\n\nFor a bit of background, see `the introductory blog post <https://adamj.eu/tech/2020/06/03/introducing-time-machine/>`__ and `the benchmark blog post <https://adamj.eu/tech/2021/02/19/freezegun-versus-time-machine/>`__.\n\n----\n\n**Testing a Django project?**\nCheck out my book `Speed Up Your Django Tests <https://adamchainz.gumroad.com/l/suydt>`__ which covers loads of ways to write faster, more accurate tests.\nI created time-machine whilst writing the book.\n\n----\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n python -m pip install time-machine\n\nPython 3.8 to 3.13 supported.\nOnly CPython is supported at this time because time-machine directly hooks into the C-level API.\n\n\nUsage\n=====\n\nIf you\u2019re coming from freezegun or libfaketime, see also the below section on migrating.\n\n``travel(destination, *, tick=True)``\n-------------------------------------\n\n``travel()`` is a class that allows time travel, to the datetime specified by ``destination``.\nIt does so by mocking all functions from Python's standard library that return the current date or datetime.\nIt can be used independently, as a function decorator, or as a context manager.\n\n``destination`` specifies the datetime to move to.\nIt may be:\n\n* A ``datetime.datetime``.\n If it is naive, it will be assumed to have the UTC timezone.\n If it has ``tzinfo`` set to a |zoneinfo-instance|_, the current timezone will also be mocked.\n* A ``datetime.date``.\n This will be converted to a UTC datetime with the time 00:00:00.\n* A ``datetime.timedelta``.\n This will be interpreted relative to the current time.\n If already within a ``travel()`` block, the ``shift()`` method is easier to use (documented below).\n* A ``float`` or ``int`` specifying a `Unix timestamp <https://en.m.wikipedia.org/wiki/Unix_time>`__\n* A string, which will be parsed with `dateutil.parse <https://dateutil.readthedocs.io/en/stable/parser.html>`__ and converted to a timestamp.\n If the result is naive, it will be assumed to be local time.\n\n.. |zoneinfo-instance| replace:: ``zoneinfo.ZoneInfo`` instance\n.. _zoneinfo-instance: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo\n\nAdditionally, you can provide some more complex types:\n\n* A generator, in which case ``next()`` will be called on it, with the result treated as above.\n* A callable, in which case it will be called with no parameters, with the result treated as above.\n\n``tick`` defines whether time continues to \"tick\" after travelling, or is frozen.\nIf ``True``, the default, successive calls to mocked functions return values increasing by the elapsed real time *since the first call.*\nSo after starting travel to ``0.0`` (the UNIX epoch), the first call to any datetime function will return its representation of ``1970-01-01 00:00:00.000000`` exactly.\nThe following calls \"tick,\" so if a call was made exactly half a second later, it would return ``1970-01-01 00:00:00.500000``.\n\nMocked Functions\n^^^^^^^^^^^^^^^^\n\nAll datetime functions in the standard library are mocked to move to the destination current datetime:\n\n* ``datetime.datetime.now()``\n* ``datetime.datetime.utcnow()``\n* ``time.clock_gettime()`` (only for ``CLOCK_REALTIME``)\n* ``time.clock_gettime_ns()`` (only for ``CLOCK_REALTIME``)\n* ``time.gmtime()``\n* ``time.localtime()``\n* ``time.monotonic()`` (not a real monotonic clock, returns ``time.time()``)\n* ``time.monotonic_ns()`` (not a real monotonic clock, returns ``time.time_ns()``)\n* ``time.strftime()``\n* ``time.time()``\n* ``time.time_ns()``\n\nThe mocking is done at the C layer, replacing the function pointers for these built-ins.\nTherefore, it automatically affects everywhere those functions have been imported, unlike use of ``unittest.mock.patch()``.\n\nUsage with ``start()`` / ``stop()``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nTo use independently, create an instance, use ``start()`` to move to the destination time, and ``stop()`` to move back.\nFor example:\n\n.. code-block:: python\n\n import datetime as dt\n import time_machine\n\n traveller = time_machine.travel(dt.datetime(1985, 10, 26))\n traveller.start()\n # It's the past!\n assert dt.date.today() == dt.date(1985, 10, 26)\n traveller.stop()\n # We've gone back to the future!\n assert dt.date.today() > dt.date(2020, 4, 29)\n\n``travel()`` instances are nestable, but you'll need to be careful when manually managing to call their ``stop()`` methods in the correct order, even when exceptions occur.\nIt's recommended to use the decorator or context manager forms instead, to take advantage of Python features to do this.\n\nFunction Decorator\n^^^^^^^^^^^^^^^^^^\n\nWhen used as a function decorator, time is mocked during the wrapped function's duration:\n\n.. code-block:: python\n\n import time\n import time_machine\n\n\n @time_machine.travel(\"1970-01-01 00:00 +0000\")\n def test_in_the_deep_past():\n assert 0.0 < time.time() < 1.0\n\nYou can also decorate asynchronous functions (coroutines):\n\n.. code-block:: python\n\n import time\n import time_machine\n\n\n @time_machine.travel(\"1970-01-01 00:00 +0000\")\n async def test_in_the_deep_past():\n assert 0.0 < time.time() < 1.0\n\nBeware: time is a *global* state - `see below <#caveats>`__.\n\nContext Manager\n^^^^^^^^^^^^^^^\n\nWhen used as a context manager, time is mocked during the ``with`` block:\n\n.. code-block:: python\n\n import time\n import time_machine\n\n\n def test_in_the_deep_past():\n with time_machine.travel(0.0):\n assert 0.0 < time.time() < 1.0\n\nClass Decorator\n^^^^^^^^^^^^^^^\n\nOnly ``unittest.TestCase`` subclasses are supported.\nWhen applied as a class decorator to such classes, time is mocked from the start of ``setUpClass()`` to the end of ``tearDownClass()``:\n\n.. code-block:: python\n\n import time\n import time_machine\n import unittest\n\n\n @time_machine.travel(0.0)\n class DeepPastTests(TestCase):\n def test_in_the_deep_past(self):\n assert 0.0 < time.time() < 1.0\n\nNote this is different to ``unittest.mock.patch()``\\'s behaviour, which is to mock only during the test methods.\nFor pytest-style test classes, see the pattern `documented below <#pytest-plugin>`__.\n\nTimezone mocking\n^^^^^^^^^^^^^^^^\n\nIf the ``destination`` passed to ``time_machine.travel()`` or ``Coordinates.move_to()`` has its ``tzinfo`` set to a |zoneinfo-instance2|_, the current timezone will be mocked.\nThis will be done by calling |time-tzset|_, so it is only available on Unix.\nThe ``zoneinfo`` module is new in Python 3.8 - on older Python versions use the |backports-zoneinfo-package|_, by the original ``zoneinfo`` author.\n\n.. |zoneinfo-instance2| replace:: ``zoneinfo.ZoneInfo`` instance\n.. _zoneinfo-instance2: https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo\n\n.. |time-tzset| replace:: ``time.tzset()``\n.. _time-tzset: https://docs.python.org/3/library/time.html#time.tzset\n\n.. |backports-zoneinfo-package| replace:: ``backports.zoneinfo`` package\n.. _backports-zoneinfo-package: https://pypi.org/project/backports.zoneinfo/\n\n``time.tzset()`` changes the ``time`` module\u2019s `timezone constants <https://docs.python.org/3/library/time.html#timezone-constants>`__ and features that rely on those, such as ``time.localtime()``.\nIt won\u2019t affect other concepts of \u201cthe current timezone\u201d, such as Django\u2019s (which can be changed with its |timezone-override|_).\n\n.. |timezone-override| replace:: ``timezone.override()``\n.. _timezone-override: https://docs.djangoproject.com/en/stable/ref/utils/#django.utils.timezone.override\n\nHere\u2019s a worked example changing the current timezone:\n\n.. code-block:: python\n\n import datetime as dt\n import time\n from zoneinfo import ZoneInfo\n import time_machine\n\n hill_valley_tz = ZoneInfo(\"America/Los_Angeles\")\n\n\n @time_machine.travel(dt.datetime(2015, 10, 21, 16, 29, tzinfo=hill_valley_tz))\n def test_hoverboard_era():\n assert time.tzname == (\"PST\", \"PDT\")\n now = dt.datetime.now()\n assert (now.hour, now.minute) == (16, 29)\n\n``Coordinates``\n---------------\n\nThe ``start()`` method and entry of the context manager both return a ``Coordinates`` object that corresponds to the given \"trip\" in time.\nThis has a couple methods that can be used to travel to other times.\n\n``move_to(destination, tick=None)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n``move_to()`` moves the current time to a new destination.\n``destination`` may be any of the types supported by ``travel``.\n\n``tick`` may be set to a boolean, to change the ``tick`` flag of ``travel``.\n\nFor example:\n\n.. code-block:: python\n\n import datetime as dt\n import time\n import time_machine\n\n with time_machine.travel(0, tick=False) as traveller:\n assert time.time() == 0\n\n traveller.move_to(234)\n assert time.time() == 234\n\n``shift(delta)``\n^^^^^^^^^^^^^^^^\n\n``shift()`` takes one argument, ``delta``, which moves the current time by the given offset.\n``delta`` may be a ``timedelta`` or a number of seconds, which will be added to destination.\nIt may be negative, in which case time will move to an earlier point.\n\nFor example:\n\n.. code-block:: python\n\n import datetime as dt\n import time\n import time_machine\n\n with time_machine.travel(0, tick=False) as traveller:\n assert time.time() == 0\n\n traveller.shift(dt.timedelta(seconds=100))\n assert time.time() == 100\n\n traveller.shift(-dt.timedelta(seconds=10))\n assert time.time() == 90\n\npytest plugin\n-------------\n\ntime-machine also works as a pytest plugin.\nIt provides a function-scoped fixture called ``time_machine`` with methods ``move_to()`` and ``shift()``, which have the same signature as their equivalents in ``Coordinates``.\nThis can be used to mock your test at different points in time and will automatically be un-mock when the test is torn down.\n\nFor example:\n\n.. code-block:: python\n\n import datetime as dt\n\n\n def test_delorean(time_machine):\n time_machine.move_to(dt.datetime(1985, 10, 26))\n\n assert dt.date.today().isoformat() == \"1985-10-26\"\n\n time_machine.move_to(dt.datetime(2015, 10, 21))\n\n assert dt.date.today().isoformat() == \"2015-10-21\"\n\n time_machine.shift(dt.timedelta(days=1))\n\n assert dt.date.today().isoformat() == \"2015-10-22\"\n\nIf you are using pytest test classes, you can apply the fixture to all test methods in a class by adding an autouse fixture:\n\n.. code-block:: python\n\n import time\n\n import pytest\n\n\n class TestSomething:\n @pytest.fixture(autouse=True)\n def set_time(self, time_machine):\n time_machine.move_to(1000.0)\n\n def test_one(self):\n assert int(time.time()) == 1000.0\n\n def test_two(self, time_machine):\n assert int(time.time()) == 1000.0\n time_machine.move_to(2000.0)\n assert int(time.time()) == 2000.0\n\n``escape_hatch``\n----------------\n\nThe ``escape_hatch`` object provides functions to bypass time-machine.\nThese allow you to call the real datetime functions, without any mocking.\nIt also provides a way to check if time-machine is currently time travelling.\n\nThese capabilities are useful in rare circumstances.\nFor example, if you need to authenticate with an external service during time travel, you may need the real value of ``datetime.now()``.\n\nThe functions are:\n\n* ``escape_hatch.is_travelling() -> bool`` - returns ``True`` if ``time_machine.travel()`` is active, ``False`` otherwise.\n\n* ``escape_hatch.datetime.datetime.now()`` - wraps the real ``datetime.datetime.now()``.\n\n* ``escape_hatch.datetime.datetime.utcnow()`` - wraps the real ``datetime.datetime.utcnow()``.\n\n* ``escape_hatch.time.clock_gettime()`` - wraps the real ``time.clock_gettime()``.\n\n* ``escape_hatch.time.clock_gettime_ns()`` - wraps the real ``time.clock_gettime_ns()``.\n\n* ``escape_hatch.time.gmtime()`` - wraps the real ``time.gmtime()``.\n\n* ``escape_hatch.time.localtime()`` - wraps the real ``time.localtime()``.\n\n* ``escape_hatch.time.strftime()`` - wraps the real ``time.strftime()``.\n\n* ``escape_hatch.time.time()`` - wraps the real ``time.time()``.\n\n* ``escape_hatch.time.time_ns()`` - wraps the real ``time.time_ns()``.\n\nFor example:\n\n.. code-block:: python\n\n import time_machine\n\n\n with time_machine.travel(...):\n if time_machine.escape_hatch.is_travelling():\n print(\"We need to go back to the future!\")\n\n real_now = time_machine.escape_hatch.datetime.datetime.now()\n external_authenticate(now=real_now)\n\nCaveats\n=======\n\nTime is a global state.\nAny concurrent threads or asynchronous functions are also be affected.\nSome aren't ready for time to move so rapidly or backwards, and may crash or produce unexpected results.\n\nAlso beware that other processes are not affected.\nFor example, if you use SQL datetime functions on a database server, they will return the real time.\n\nComparison\n==========\n\nThere are some prior libraries that try to achieve the same thing.\nThey have their own strengths and weaknesses.\nHere's a quick comparison.\n\nunittest.mock\n-------------\n\nThe standard library's `unittest.mock <https://docs.python.org/3/library/unittest.mock.html>`__ can be used to target imports of ``datetime`` and ``time`` to change the returned value for current time.\nUnfortunately, this is fragile as it only affects the import location the mock targets.\nTherefore, if you have several modules in a call tree requesting the date/time, you need several mocks.\nThis is a general problem with unittest.mock - see `Why Your Mock Doesn't Work <https://nedbatchelder.com//blog/201908/why_your_mock_doesnt_work.html>`__.\n\nIt's also impossible to mock certain references, such as function default arguments:\n\n.. code-block:: python\n\n def update_books(_now=time.time): # set as default argument so faster lookup\n for book in books:\n ...\n\nAlthough such references are rare, they are occasionally used to optimize highly repeated loops.\n\nfreezegun\n---------\n\nSteve Pulec's `freezegun <https://github.com/spulec/freezegun>`__ library is a popular solution.\nIt provides a clear API which was much of the inspiration for time-machine.\n\nThe main drawback is its slow implementation.\nIt essentially does a find-and-replace mock of all the places that the ``datetime`` and ``time`` modules have been imported.\nThis gets around the problems with using unittest.mock, but it means the time it takes to do the mocking is proportional to the number of loaded modules.\nIn large projects, this can take several seconds, an impractical overhead for an individual test.\n\nIt's also not a perfect search, since it searches only module-level imports.\nSuch imports are definitely the most common way projects use date and time functions, but they're not the only way.\nfreezegun won\u2019t find functions that have been \u201chidden\u201d inside arbitrary objects, such as class-level attributes.\n\nIt also can't affect C extensions that call the standard library functions, including (I believe) Cython-ized Python code.\n\npython-libfaketime\n------------------\n\nSimon Weber's `python-libfaketime <https://github.com/simon-weber/python-libfaketime/>`__ wraps the `libfaketime <https://github.com/wolfcw/libfaketime>`__ library.\nlibfaketime replaces all the C-level system calls for the current time with its own wrappers.\nIt's therefore a \"perfect\" mock for the current process, affecting every single point the current time might be fetched, and performs much faster than freezegun.\n\nUnfortunately python-libfaketime comes with the limitations of ``LD_PRELOAD``.\nThis is a mechanism to replace system libraries for a program as it loads (`explanation <http://www.goldsborough.me/c/low-level/kernel/2016/08/29/16-48-53-the_-ld_preload-_trick/>`__).\nThis causes two issues in particular when you use python-libfaketime.\n\nFirst, ``LD_PRELOAD`` is only available on Unix platforms, which prevents you from using it on Windows.\n\nSecond, you have to help manage ``LD_PRELOAD``.\nYou either use python-libfaketime's ``reexec_if_needed()`` function, which restarts (*re-execs*) your test process while loading, or manually manage the ``LD_PRELOAD`` environment variable.\nNeither is ideal.\nRe-execing breaks anything that might wrap your test process, such as profilers, debuggers, and IDE test runners.\nManually managing the environment variable is a bit of overhead, and must be done for each environment you run your tests in, including each developer's machine.\n\ntime-machine\n------------\n\ntime-machine is intended to combine the advantages of freezegun and libfaketime.\nIt works without ``LD_PRELOAD`` but still mocks the standard library functions everywhere they may be referenced.\nIts weak point is that other libraries using date/time system calls won't be mocked.\nThankfully this is rare.\nIt's also possible such python libraries can be added to the set mocked by time-machine.\n\nOne drawback is that it only works with CPython, so can't be used with other Python interpreters like PyPy.\nHowever it may possible to extend it to support other interpreters through different mocking mechanisms.\n\nMigrating from libfaketime or freezegun\n=======================================\n\nfreezegun has a useful API, and python-libfaketime copies some of it, with a different function name.\ntime-machine also copies some of freezegun's API, in ``travel()``\\'s ``destination``, and ``tick`` arguments, and the ``shift()`` method.\nThere are a few differences:\n\n* time-machine's ``tick`` argument defaults to ``True``, because code tends to make the (reasonable) assumption that time progresses whilst running, and should normally be tested as such.\n Testing with time frozen can make it easy to write complete assertions, but it's quite artificial.\n Write assertions against time ranges, rather than against exact values.\n\n* freezegun interprets dates and naive datetimes in the local time zone (including those parsed from strings with ``dateutil``).\n This means tests can pass when run in one time zone and fail in another.\n time-machine instead interprets dates and naive datetimes in UTC so they are fixed points in time.\n Provide time zones where required.\n\n* freezegun's ``tick()`` method has been implemented as ``shift()``, to avoid confusion with the ``tick`` argument.\n It also requires an explicit delta rather than defaulting to 1 second.\n\n* freezegun's ``tz_offset`` argument is not supported, since it only partially mocks the current time zone.\n Time zones are more complicated than a single offset from UTC, and freezegun only uses the offset in ``time.localtime()``.\n Instead, time-machine will mock the current time zone if you give it a ``datetime`` with a ``ZoneInfo`` timezone.\n\nSome features aren't supported like the ``auto_tick_seconds`` argument.\nThese may be added in a future release.\n\nIf you are only fairly simple function calls, you should be able to migrate by replacing calls to ``freezegun.freeze_time()`` and ``libfaketime.fake_time()`` with ``time_machine.travel()``.\n",
"bugtrack_url": null,
"license": null,
"summary": "Travel through time in your tests.",
"version": "2.14.2",
"project_urls": {
"Changelog": "https://github.com/adamchainz/time-machine/blob/main/CHANGELOG.rst",
"Funding": "https://adamj.eu/books/",
"Repository": "https://github.com/adamchainz/time-machine"
},
"split_keywords": [
"date",
" datetime",
" mock",
" test",
" testing",
" tests",
" time",
" warp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f08962041cf0bd119c25841bdb858267da119b3e8ef0656170d100e7d42ce75a",
"md5": "dffb6821bc0815cdd2b62827c1406d2f",
"sha256": "1a6627ce920f1b4b73b2a4957e53f2740d684535af6924f62085005e6e3181cb"
},
"downloads": -1,
"filename": "time_machine-2.14.2-cp313-cp313-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "dffb6821bc0815cdd2b62827c1406d2f",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.8",
"size": 17249,
"upload_time": "2024-06-29T09:26:08",
"upload_time_iso_8601": "2024-06-29T09:26:08.840319Z",
"url": "https://files.pythonhosted.org/packages/f0/89/62041cf0bd119c25841bdb858267da119b3e8ef0656170d100e7d42ce75a/time_machine-2.14.2-cp313-cp313-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7652cfcf2de9300816ea35ccdfee7097d0226793516588423497c1ae35a75372",
"md5": "8231fda1f81c0cad968c4bf35c7d249f",
"sha256": "6e5150cdf1e128c4b3bea214204b4d7747456d9c7ce8e3d83c204e59f9640b72"
},
"downloads": -1,
"filename": "time_machine-2.14.2.tar.gz",
"has_sig": false,
"md5_digest": "8231fda1f81c0cad968c4bf35c7d249f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25017,
"upload_time": "2024-06-29T09:26:11",
"upload_time_iso_8601": "2024-06-29T09:26:11.385373Z",
"url": "https://files.pythonhosted.org/packages/76/52/cfcf2de9300816ea35ccdfee7097d0226793516588423497c1ae35a75372/time_machine-2.14.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-29 09:26:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "time-machine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "time-machine"
}
JSON
