Metadata-Version: 2.1
Name: time-machine
Version: 1.0.0
Summary: Warp time
Home-page: https://github.com/adamchainz/time-machine
Author: Adam Johnson
Author-email: me@adamj.eu
License: ISC License
Project-URL: Changelog, https://github.com/adamchainz/time-machine/blob/master/HISTORY.rst
Project-URL: Twitter, https://twitter.com/adamchainz
Description: ============
        time-machine
        ============
        
        .. image:: https://github.com/adamchainz/time-machine/workflows/CI/badge.svg?branch=master
           :target: https://github.com/adamchainz/time-machine/actions?workflow=CI
        
        .. image:: https://coveralls.io/repos/adamchainz/time-machine/badge.svg
          :target: https://coveralls.io/r/adamchainz/time-machine
        
        .. image:: https://img.shields.io/pypi/v/time-machine.svg
           :target: https://pypi.python.org/pypi/time-machine
        
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
           :target: https://github.com/python/black
        
        Travel through time in your tests.
        
        A quick example:
        
        .. code-block:: python
        
            import datetime as dt
            import time_machine
        
            @time_machine.travel("1955-11-05 01:22")
            def test_delorean():
                assert dt.date.today().isoformat() == "1955-11-05"
        
        Installation
        ============
        
        Use **pip**:
        
        .. code-block:: sh
        
            python -m pip install time-machine
        
        Python 3.6 to 3.8 supported (CPython only).
        
        Usage
        =====
        
        ``travel(destination, *, tick=True, tz_offset=None)``
        -----------------------------------------------------
        
        ``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.
        * A ``datetime.date``.
          This will be converted to a UTC datetime with the time 00:00:00.
        * 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.
        
        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``.
        
        ``tz_offset`` allows you to offset the given destination.
        It may be a ``timedelta`` or a number of seconds, which will be added to destination.
        It may be negative.
        
        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.gmtime()``
        * ``time.localtime()``
        * ``time.clock_gettime()`` (only for ``CLOCK_REALTIME``)
        * ``time.clock_gettime_ns()`` (only for ``CLOCK_REALTIME``)
        * ``time.strftime()``
        * ``time.time()``
        * ``time.time_ns()``
        
        This 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 and 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(1955, 11, 5))
            traveller.start()
            # It's the past!
            assert dt.date.today() == dt.date(1955, 11, 5)
            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
        
        This also works for 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
        
        Context Manager
        ^^^^^^^^^^^^^^^
        
        When used as a context manager, time is mocked during the ``with`` block:
        
        .. code-block:: python
        
            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.
        
        Caveats
        ^^^^^^^
        
        Time is global state.
        Any concurrent threads or async 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 datetime functions in a client/server database they will still 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 this is rare, it's often used to optimize repeat 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.
        
        Also, it can't affect C extensions that call the standard library functions, including Cython-ized Python code.
        
        Additionally, it has the same problem that it can't mock function default arguments and some other references.
        
        python-libfaketime
        ------------------
        
        Simon Weber's `python-libfaketime <https://github.com/simon-weber/python-libfaketime/>`__ wraps the ``LD_PRELOAD`` library `libfaketime <https://github.com/wolfcw/libfaketime>`__.
        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 it comes with the limitations of ``LD_PRELOAD`` (`explanation <http://www.goldsborough.me/c/low-level/kernel/2016/08/29/16-48-53-the_-ld_preload-_trick/>`__).
        First, this is only available on Unix platforms, which prevents it from working on Windows.
        Seccond, you either use its ``reexec_if_needed()`` function, which restarts (re-execs) your tests' process once while loading, or manually manage the ``LD_PRELOAD`` environment variable (everywhere you run your tests).
        Re-execing breaks profilers, use of ``python -m pdb`` and similar, and other things that might wrap your test process.
        Manually managing the environment variable is a bit of overhead for each environment you want to run your tests in.
        
        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``, ``tick``, and ``tz_offset`` arguments.
        There is one difference - time-machine's ``tick`` argument defaults to ``True``, because code tends to make the (reasonable) assumption that time progresses between function calls, and should normally be tested as such.
        
        Some arguments aren't supported like ``auto_tick_seconds``, or the ``move_to()`` and ``tick()`` methods.
        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()``.
        
Keywords: time,warp
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
