0
# FreezeGun
1

2
FreezeGun is a Python testing library that allows your tests to travel through time by mocking datetime and time functions. It freezes calls to datetime.datetime.now(), datetime.datetime.utcnow(), datetime.date.today(), time.time(), time.localtime(), time.gmtime(), time.strftime(), time.monotonic(), and time.perf_counter() to return consistent, predictable values during test execution.
3

4
## Package Information
5

6
- **Package Name**: freezegun
7
- **Language**: Python
8
- **Installation**: `pip install freezegun`
9
- **Requirements**: Python 3.8+, python-dateutil >= 2.7
10

11
## Core Imports
12

13
```python
14
from freezegun import freeze_time, configure
15
```
16

17
Note: Only `freeze_time` and `configure` are officially exported. Other components can be accessed from internal modules but are not part of the guaranteed public API:
18

19
```python
20
# Internal API access (not guaranteed stable)
21
from freezegun.api import FakeDate, FakeDatetime, get_current_time
22
from freezegun.config import reset_config
23
```
24

25
## Basic Usage
26

27
```python
28
from freezegun import freeze_time
29
import datetime
30

31
# As a decorator
32
@freeze_time("2012-01-14")
33
def test_datetime():
34
    assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)
35

36
# As a context manager
37
def test_context_manager():
38
    with freeze_time("2012-01-14"):
39
        assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)
40
    # Time is unfrozen outside the context
41

42
# Manual start/stop
43
def test_manual():
44
    freezer = freeze_time("2012-01-14 12:00:01")
45
    freezer.start()
46
    assert datetime.datetime.now() == datetime.datetime(2012, 1, 14, 12, 0, 1)
47
    freezer.stop()
48
```
49

50
## Architecture
51

52
FreezeGun works by monkey-patching Python's time and datetime modules at runtime. It replaces standard time functions with fake implementations that return frozen values, while preserving original functionality for restoration when freezing stops. The library uses three time factory patterns:
53

54
- **FrozenDateTimeFactory**: Returns a static frozen time
55
- **TickingDateTimeFactory**: Time advances with real-world time passage
56
- **StepTickTimeFactory**: Time advances by specified intervals automatically
57

58
This approach ensures comprehensive time mocking across the entire Python environment while maintaining compatibility with existing codebases.
59

60
## Capabilities
61

62
### Time Freezing Decorator/Context Manager
63

64
Main functionality for freezing time during test execution. Can be used as a decorator, context manager, or manually controlled.
65

66
```python { .api }
67
def freeze_time(
68
    time_to_freeze: Optional[_Freezable] = None,
69
    tz_offset: Union[int, datetime.timedelta] = 0,
70
    ignore: Optional[List[str]] = None,
71
    tick: bool = False,
72
    as_arg: bool = False,
73
    as_kwarg: str = '',
74
    auto_tick_seconds: float = 0,
75
    real_asyncio: bool = False
76
) -> _freeze_time:
77
    """
78
    Freezes time for testing purposes.
79

80
    Args:
81
        time_to_freeze: The datetime to freeze time at (see _Freezable type for supported formats)
82
        tz_offset: Timezone offset in hours or timedelta
83
        ignore: List of module names to ignore during freezing
84
        tick: If True, time advances with real-world time
85
        as_arg: Pass time factory as first argument to decorated function
86
        as_kwarg: Pass time factory as named keyword argument
87
        auto_tick_seconds: Automatically advance time by this interval
88
        real_asyncio: Allow asyncio event loops to see real monotonic time
89

90
    Returns:
91
        _freeze_time: Time freezer instance that can be used as decorator or context manager
92
    """
93
```
94

95
### Freeze Time Context Manager Class
96

97
The class returned by `freeze_time()` that provides context manager and decorator functionality.
98

99
```python { .api }
100
class _freeze_time:
101
    """
102
    A class to freeze time for testing purposes.
103
    
104
    This class can be used as a context manager or a decorator to freeze time
105
    during the execution of a block of code or a function.
106
    """
107
    
108
    def __init__(
109
        self,
110
        time_to_freeze_str: Optional[_Freezable],
111
        tz_offset: Union[int, datetime.timedelta],
112
        ignore: List[str],
113
        tick: bool,
114
        as_arg: bool,
115
        as_kwarg: str,
116
        auto_tick_seconds: float,
117
        real_asyncio: Optional[bool],
118
    ): ...
119
    
120
    def start(self) -> Union[StepTickTimeFactory, TickingDateTimeFactory, FrozenDateTimeFactory]:
121
        """
122
        Starts freezing time and returns the time factory.
123
        
124
        Returns:
125
            Time factory instance for controlling frozen time
126
        """
127
    
128
    def stop(self) -> None:
129
        """Stops freezing time and restores the original time functions."""
130
    
131
    def __enter__(self) -> Union[StepTickTimeFactory, TickingDateTimeFactory, FrozenDateTimeFactory]:
132
        """Context manager entry point. Calls start()."""
133
    
134
    def __exit__(self, *args: Any) -> None:
135
        """Context manager exit point. Calls stop()."""
136
    
137
    def __call__(self, func: Union[Type[T], Callable]) -> Union[Type[T], Callable]:
138
        """
139
        Decorator functionality for functions, methods, and classes.
140
        
141
        Args:
142
            func: Function, method, or class to decorate
143
            
144
        Returns:
145
            Decorated callable with frozen time behavior
146
        """
147
    
148
    def decorate_class(self, klass: Type[T]) -> Type[T]:
149
        """Decorates a class to freeze time during its execution."""
150
    
151
    def decorate_callable(self, func: Callable) -> Callable:
152
        """Decorates a callable to freeze time during its execution."""
153
    
154
    def decorate_coroutine(self, coroutine: Callable) -> Callable:
155
        """Decorates a coroutine to freeze time during its execution."""
156
```
157

158
### Time Factory Classes
159

160
Time factory classes control how frozen time behaves during test execution.
161

162
```python { .api }
163
class FrozenDateTimeFactory:
164
    """Factory for static frozen time that doesn't advance."""
165
    
166
    def __init__(self, time_to_freeze: datetime.datetime): ...
167
    
168
    def __call__(self) -> datetime.datetime:
169
        """Returns the frozen datetime."""
170
    
171
    def tick(self, delta: Union[datetime.timedelta, float] = datetime.timedelta(seconds=1)) -> datetime.datetime:
172
        """
173
        Advances frozen time by the specified delta.
174
        
175
        Args:
176
            delta: Time delta to advance (timedelta or seconds as float/int)
177
            
178
        Returns:
179
            datetime.datetime: New frozen time after advancement
180
        """
181
    
182
    def move_to(self, target_datetime: _Freezable) -> None:
183
        """
184
        Moves frozen time to a specific target datetime.
185
        
186
        Args:
187
            target_datetime: Target time to move to (see _Freezable type for supported formats)
188
        """
189

190
class TickingDateTimeFactory:
191
    """Factory for time that advances with real-world time passage."""
192
    
193
    def __init__(self, time_to_freeze: datetime.datetime, start: datetime.datetime): ...
194
    
195
    def __call__(self) -> datetime.datetime:
196
        """Returns frozen time plus elapsed real time since start."""
197
    
198
    def tick(self, delta: Union[datetime.timedelta, float] = datetime.timedelta(seconds=1)) -> datetime.datetime:
199
        """Advances the base frozen time by delta."""
200
    
201
    def move_to(self, target_datetime: _Freezable) -> None:
202
        """Moves base frozen time to target, resets real time tracking."""
203

204
class StepTickTimeFactory:
205
    """Factory for time that automatically advances by fixed intervals."""
206
    
207
    def __init__(self, time_to_freeze: datetime.datetime, step_width: float): ...
208
    
209
    def __call__(self) -> datetime.datetime:
210
        """Returns current time and advances by step_width."""
211
    
212
    def tick(self, delta: Optional[Union[datetime.timedelta, float]] = None) -> datetime.datetime:
213
        """
214
        Advances time by delta or step_width if delta is None.
215
        
216
        Args:
217
            delta: Time to advance (defaults to step_width)
218
            
219
        Returns:
220
            datetime.datetime: New time after advancement
221
        """
222
    
223
    def update_step_width(self, step_width: float) -> None:
224
        """
225
        Updates the automatic advancement interval.
226
        
227
        Args:
228
            step_width: New step width in seconds
229
        """
230
    
231
    def move_to(self, target_datetime: _Freezable) -> None:
232
        """Moves to target datetime."""
233
```
234

235
### Fake Date and DateTime Classes
236

237
Replacement classes for Python's built-in date and datetime that provide frozen behavior.
238

239
```python { .api }
240
class FakeDate:
241
    """Replacement for datetime.date with frozen behavior."""
242
    
243
    def __init__(self, year: int, month: int, day: int): ...
244
    
245
    @classmethod
246
    def today(cls) -> 'FakeDate':
247
        """Returns the current frozen date."""
248
    
249
    def __add__(self, other: datetime.timedelta) -> 'FakeDate':
250
        """Add timedelta to date."""
251
    
252
    def __sub__(self, other: Union['FakeDate', datetime.timedelta]) -> Union['FakeDate', datetime.timedelta]:
253
        """Subtract date or timedelta from date."""
254
    
255
    # Class attributes
256
    min: 'FakeDate'  # Minimum representable date
257
    max: 'FakeDate'  # Maximum representable date
258

259
class FakeDatetime:
260
    """Replacement for datetime.datetime with frozen behavior."""
261
    
262
    def __init__(self, year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, tzinfo: Optional[datetime.tzinfo] = None): ...
263
    
264
    @classmethod
265
    def now(cls, tz: Optional[datetime.tzinfo] = None) -> 'FakeDatetime':
266
        """Returns the current frozen datetime."""
267
    
268
    @classmethod
269
    def utcnow(cls) -> 'FakeDatetime':
270
        """Returns the current frozen UTC datetime."""
271
    
272
    @classmethod
273
    def today(cls) -> 'FakeDatetime':
274
        """Returns the current frozen date as datetime."""
275
    
276
    @classmethod
277
    def fromtimestamp(cls, t: float, tz: Optional[datetime.tzinfo] = None) -> 'FakeDatetime':
278
        """Creates datetime from timestamp using frozen timezone offset."""
279
    
280
    def date(self) -> FakeDate:
281
        """Returns the date portion as FakeDate."""
282
    
283
    def timestamp(self) -> float:
284
        """Returns POSIX timestamp respecting frozen time."""
285
    
286
    def astimezone(self, tz: Optional[datetime.tzinfo] = None) -> 'FakeDatetime':
287
        """Returns timezone-aware datetime."""
288
    
289
    def __add__(self, other: datetime.timedelta) -> 'FakeDatetime':
290
        """Add timedelta to datetime."""
291
    
292
    def __sub__(self, other: Union['FakeDatetime', datetime.timedelta]) -> Union['FakeDatetime', datetime.timedelta]:
293
        """Subtract datetime or timedelta from datetime."""
294
    
295
    @property
296
    def nanosecond(self) -> int:
297
        """Nanosecond component (0 if not supported)."""
298
    
299
    # Class attributes
300
    min: 'FakeDatetime'  # Minimum representable datetime
301
    max: 'FakeDatetime'  # Maximum representable datetime
302
```
303

304
### Configuration
305

306
Global configuration for FreezeGun behavior across all freeze operations.
307

308
```python { .api }
309
def configure(
310
    default_ignore_list: Optional[List[str]] = None,
311
    extend_ignore_list: Optional[List[str]] = None
312
) -> None:
313
    """
314
    Configure global FreezeGun settings.
315
    
316
    Args:
317
        default_ignore_list: Replace default ignore list with these modules
318
        extend_ignore_list: Add these modules to default ignore list
319
        
320
    Raises:
321
        ConfigurationError: If both parameters are provided
322
    """
323

324
def reset_config() -> None:
325
    """Reset configuration to default settings."""
326

327
class Settings:
328
    """Global settings container."""
329
    def __init__(self, default_ignore_list: Optional[List[str]] = None): ...
330
    
331
    default_ignore_list: List[str]  # Modules to ignore during freezing
332

333
class ConfigurationError(Exception):
334
    """Raised when configuration parameters conflict."""
335
```
336

337
### Utility Functions
338

339
Helper functions for time manipulation and type conversion.
340

341
```python { .api }
342
def get_current_time() -> datetime.datetime:
343
    """
344
    Returns the current frozen time.
345
    
346
    Returns:
347
        datetime.datetime: Current frozen datetime
348
        
349
    Raises:
350
        IndexError: If no time is currently frozen
351
    """
352

353
def convert_to_timezone_naive(time_to_freeze: datetime.datetime) -> datetime.datetime:
354
    """
355
    Converts timezone-aware datetime to naive UTC datetime.
356
    
357
    Args:
358
        time_to_freeze: Input datetime (may be timezone-aware)
359
        
360
    Returns:
361
        datetime.datetime: Naive UTC datetime
362
    """
363

364
def datetime_to_fakedatetime(datetime: datetime.datetime) -> FakeDatetime:
365
    """
366
    Converts standard datetime to FakeDatetime.
367
    
368
    Args:
369
        datetime: Standard datetime object
370
        
371
    Returns:
372
        FakeDatetime: Equivalent FakeDatetime instance
373
    """
374

375
def date_to_fakedate(date: datetime.date) -> FakeDate:
376
    """
377
    Converts standard date to FakeDate.
378
    
379
    Args:
380
        date: Standard date object
381
        
382
    Returns:
383
        FakeDate: Equivalent FakeDate instance
384
    """
385
```
386

387
### Type Definitions
388

389
```python { .api }
390
from typing import Union, Optional, List, Callable, Iterator, Type, Any
391
import types
392
import datetime
393

394
_Freezable = Union[
395
    str,  # "2020-01-01", "2020-01-01 12:30:45"
396
    datetime.datetime,  # Specific datetime object
397
    datetime.date,  # Date (time set to midnight)
398
    datetime.timedelta,  # Relative to current time
399
    types.FunctionType,  # Function returning datetime
400
    Callable[[], Union[str, datetime.datetime, datetime.date, datetime.timedelta]],  # Callable returning datetime
401
    Iterator[datetime.datetime]  # Generator yielding datetime values
402
]
403
```
404

405
### Package Metadata
406

407
```python { .api }
408
__version__: str = '1.5.5'  # Package version
409
__title__: str = 'freezegun'  # Package title
410
__author__: str = 'Steve Pulec'  # Package author
411
__license__: str = 'Apache License 2.0'  # Package license
412
__copyright__: str = 'Copyright 2012 Steve Pulec'  # Copyright notice
413
```
414

415
### Constants
416

417
```python { .api }
418
DEFAULT_IGNORE_LIST: List[str]  # Default modules ignored during freezing: [
419
    'nose.plugins', 'six.moves', 'django.utils.six.moves', 'google.gax',
420
    'threading', 'multiprocessing', 'queue', 'selenium', '_pytest.terminal.',
421
    '_pytest.runner.', 'gi', 'prompt_toolkit'
422
]
423

424
settings: Settings  # Global settings instance
425
```
426

427
## Usage Examples
428

429
### Advanced Time Control
430

431
```python
432
from freezegun import freeze_time
433
import datetime
434

435
# Ticking time - advances with real time
436
@freeze_time("2020-01-01", tick=True)
437
def test_ticking():
438
    start = datetime.datetime.now()
439
    time.sleep(1)
440
    end = datetime.datetime.now()
441
    assert end > start  # Time has advanced
442

443
# Auto-tick time - advances automatically
444
@freeze_time("2020-01-01", auto_tick_seconds=1)
445
def test_auto_tick():
446
    time1 = datetime.datetime.now()
447
    time2 = datetime.datetime.now()
448
    # time2 is 1 second after time1
449

450
# Manual time control
451
with freeze_time("2020-01-01") as frozen_time:
452
    assert datetime.datetime.now() == datetime.datetime(2020, 1, 1)
453
    
454
    # Advance time manually
455
    frozen_time.tick(delta=datetime.timedelta(days=1))
456
    assert datetime.datetime.now() == datetime.datetime(2020, 1, 2)
457
    
458
    # Jump to specific time
459
    frozen_time.move_to("2020-06-15 14:30:00")
460
    assert datetime.datetime.now() == datetime.datetime(2020, 6, 15, 14, 30)
461
```
462

463
### Timezone Handling
464

465
```python
466
from freezegun import freeze_time
467
import datetime
468

469
# Timezone offset
470
@freeze_time("2020-01-01 12:00:00", tz_offset=-5)
471
def test_timezone():
472
    # UTC time is frozen at 12:00:00
473
    assert datetime.datetime.utcnow() == datetime.datetime(2020, 1, 1, 12, 0, 0)
474
    # Local time shows 07:00:00 (UTC-5)
475
    assert datetime.datetime.now() == datetime.datetime(2020, 1, 1, 7, 0, 0)
476

477
# Using timedelta for offset
478
@freeze_time("2020-01-01", tz_offset=datetime.timedelta(hours=3))
479
def test_timedelta_offset():
480
    # Local time is 3 hours ahead of UTC
481
    pass
482
```
483

484
### Class and Method Decoration
485

486
```python
487
from freezegun import freeze_time
488
import unittest
489
import datetime
490

491
# Class decorator - freezes for all test methods
492
@freeze_time("2020-01-01")
493
class TestTimeTravel(unittest.TestCase):
494
    def test_method_one(self):
495
        assert datetime.datetime.now().year == 2020
496
    
497
    def test_method_two(self):  
498
        assert datetime.datetime.now().month == 1
499

500
# Method decorator with time factory injection
501
class TestWithFactory(unittest.TestCase):
502
    @freeze_time("2020-01-01", as_kwarg='frozen_time')
503
    def test_with_factory_kwarg(self, frozen_time):
504
        assert datetime.datetime.now() == datetime.datetime(2020, 1, 1)
505
        
506
        # Use the factory to control time
507
        frozen_time.tick(datetime.timedelta(days=5))
508
        assert datetime.datetime.now() == datetime.datetime(2020, 1, 6)
509
    
510
    @freeze_time("2020-01-01", as_arg=True)  
511
    def test_with_factory_arg(self, frozen_time):
512
        # frozen_time is passed as first argument
513
        frozen_time.move_to("2020-12-31")
514
        assert datetime.datetime.now().month == 12
515
```
516

517
### Configuration and Module Ignoring
518

519
```python
520
from freezegun import freeze_time, configure
521

522
# Configure globally
523
configure(extend_ignore_list=['my_module', 'another_module'])
524

525
# Or per freeze operation
526
@freeze_time("2020-01-01", ignore=['requests', 'urllib3'])
527
def test_with_ignored_modules():
528
    # Time is frozen except in requests and urllib3 modules
529
    pass
530

531
# Reset configuration
532
from freezegun.config import reset_config
533
reset_config()
534
```
535

536
### Dynamic Time Generation
537

538
```python
539
from freezegun import freeze_time
540
import datetime
541

542
# Using a function
543
def get_test_time():
544
    return datetime.datetime(2020, 6, 15, 10, 30, 0)
545

546
@freeze_time(get_test_time)
547
def test_function_time():
548
    assert datetime.datetime.now() == datetime.datetime(2020, 6, 15, 10, 30, 0)
549

550
# Using a generator
551
def time_generator():
552
    base = datetime.datetime(2020, 1, 1)
553
    for i in range(10):
554
        yield base + datetime.timedelta(days=i)
555

556
time_gen = time_generator()
557

558
@freeze_time(time_gen)
559
def test_generator_time():
560
    # Uses next value from generator
561
    pass
562
```