CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-time-machine

Travel through time in your tests.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Time Machine

A Python library for mocking time in tests, enabling developers to travel through time to create deterministic tests for time-sensitive code. Time Machine patches Python's time and datetime functions at the C level for high performance and comprehensive coverage.

Package Information

  • Package Name: time-machine
  • Language: Python
  • Installation: pip install time-machine
  • Python Version: 3.9+

Core Imports

import time_machine

Common usage pattern:

from time_machine import travel

Basic Usage

import time_machine
from datetime import datetime, timezone

# Context manager usage
with time_machine.travel(datetime(2023, 1, 1, 12, 0, 0, tzinfo=timezone.utc)):
    print(datetime.now())  # Prints 2023-01-01 12:00:00

# Decorator usage
@time_machine.travel("2023-01-01 12:00 UTC")
def test_something():
    assert datetime.now().year == 2023

# Moving through time during travel
with time_machine.travel(0) as traveller:
    print(datetime.now())  # 1970-01-01 00:00:00
    traveller.shift(3600)  # Add 1 hour
    print(datetime.now())  # 1970-01-01 01:00:00
    traveller.move_to("2023-01-01")
    print(datetime.now())  # 2023-01-01 00:00:00

Architecture

Time Machine operates by patching Python's time-related functions at the C extension level:

  • C Extension: _time_machine.c provides low-level patching of time functions
  • Coordinates System: Manages time travel state with support for nested time travel
  • Escape Hatch: Provides access to real time functions during time travel
  • Pytest Integration: Automatic fixture and marker support for seamless test integration

The patching system ensures that all time-related functions (time.time(), datetime.now(), etc.) return consistent mocked values during time travel, with support for both static time (tick=False) and advancing time (tick=True).

Capabilities

Core Time Travel

Primary time travel functionality using the travel class as a context manager or decorator. Supports various destination formats including timestamps, datetime objects, ISO strings, and relative time deltas.

class travel:
    def __init__(self, destination: DestinationType, *, tick: bool = True): ...
    def start(self) -> Coordinates: ...
    def stop(self) -> None: ...
    def __enter__(self) -> Coordinates: ...
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
    async def __aenter__(self) -> Coordinates: ...
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: ...
class Coordinates:
    def time(self) -> float: ...
    def time_ns(self) -> int: ...
    def shift(self, delta: dt.timedelta | int | float) -> None: ...
    def move_to(self, destination: DestinationType, tick: bool | None = None) -> None: ...

Core Time Travel

Pytest Integration

Seamless integration with pytest through fixtures, markers, and automatic test discovery. Provides both imperative and declarative approaches to time travel in tests.

class TimeMachineFixture:
    def move_to(self, destination: DestinationType, tick: bool | None = None) -> None: ...
    def shift(self, delta: dt.timedelta | int | float) -> None: ...
    def stop(self) -> None: ...
@pytest.fixture(name="time_machine")
def time_machine_fixture(request: pytest.FixtureRequest) -> Generator[TimeMachineFixture, None, None]: ...

Pytest Integration

Escape Hatch

Access to real time functions during time travel for testing time-dependent operations that need actual system time, such as performance measurements or external API calls.

class _EscapeHatch:
    def is_travelling(self) -> bool: ...
    time: _EscapeHatchTime
    datetime: _EscapeHatchDatetime
escape_hatch: _EscapeHatch

Escape Hatch

CLI Migration Tool

Command-line tool for migrating test code from freezegun to time-machine, automatically rewriting imports and function calls.

def main(argv: Sequence[str] | None = None) -> int: ...
def migrate_files(files: list[str]) -> int: ...
def migrate_file(filename: str) -> int: ...

CLI Migration Tool

Type Definitions

DestinationBaseType = Union[
    int,                    # Unix timestamp
    float,                  # Unix timestamp with fractional seconds
    dt.datetime,           # Datetime object (timezone-aware recommended)
    dt.timedelta,          # Relative time from current time
    dt.date,               # Date (converted to midnight UTC)
    str,                   # ISO 8601 datetime string
]

DestinationType = Union[
    DestinationBaseType,
    Callable[[], DestinationBaseType],                    # Function returning destination
    Generator[DestinationBaseType, None, None],          # Generator yielding destinations
]

_TimeTuple = tuple[int, int, int, int, int, int, int, int, int]  # Time tuple format used by time functions

Constants

NANOSECONDS_PER_SECOND: int = 1_000_000_000
SYSTEM_EPOCH_TIMESTAMP_NS: int  # System epoch timestamp in nanoseconds (Windows compatibility)
escape_hatch: _EscapeHatch
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/time-machine@2.19.x
Publish Source
CLI
Badge
tessl/pypi-time-machine badge