faker.providers.date_time

Subpackages

Package Contents

Classes

Country

BaseProvider

Provider

Functions

datetime_to_timestamp(→ int)

timestamp_to_datetime(→ datetime.datetime)

change_year(→ datetime.date)

Unless the current_date is February 29th, it is fine to just subtract years.

convert_timestamp_to_datetime(→ datetime.datetime)

Attributes

DateParseType

ElementsType

localized

timedelta_pattern

class faker.providers.date_time.Country
name: str
timezones: Sequence[str]
alpha_2_code: str
alpha_3_code: str
continent: str
capital: str
faker.providers.date_time.DateParseType
class faker.providers.date_time.BaseProvider(generator: Any)
__provider__ = 'base'
__lang__: Optional[str]
__use_weighting__ = False
language_locale_codes
locale() str

Generate a random underscored i18n locale code (e.g. en_US).

language_code() str

Generate a random i18n language code (e.g. en).

random_int(min: int = 0, max: int = 9999, step: int = 1) int

Generate a random integer between two integers min and max inclusive while observing the provided step value.

This method is functionally equivalent to randomly sampling an integer from the sequence range(min, max + 1, step).

Sample

min=0, max=15

Sample

min=0, max=15, step=3

random_digit() int

Generate a random digit (0 to 9).

random_digit_not_null() int

Generate a random non-zero digit (1 to 9).

random_digit_above_two() int

Generate a random digit above value two (2 to 9).

random_digit_or_empty() Union[int, str]

Generate a random digit (0 to 9) or an empty string.

This method will return an empty string 50% of the time, and each digit has a 1/20 chance of being generated.

random_digit_not_null_or_empty() Union[int, str]

Generate a random non-zero digit (1 to 9) or an empty string.

This method will return an empty string 50% of the time, and each digit has a 1/18 chance of being generated.

random_number(digits: Optional[int] = None, fix_len: bool = False) int

Generate a random integer according to the following rules:

  • If digits is None (default), its value will be set to a random integer from 1 to 9.

  • If fix_len is False (default), all integers that do not exceed the number of digits can be generated.

  • If fix_len is True, only integers with the exact number of digits can be generated.

Sample

fix_len=False

Sample

fix_len=True

Sample

digits=3

Sample

digits=3, fix_len=False

Sample

digits=3, fix_len=True

random_letter() str

Generate a random ASCII letter (a-z and A-Z).

random_letters(length: int = 16) Sequence[str]

Generate a list of random ASCII letters (a-z and A-Z) of the specified length.

Sample

length=10

random_lowercase_letter() str

Generate a random lowercase ASCII letter (a-z).

random_uppercase_letter() str

Generate a random uppercase ASCII letter (A-Z).

random_elements(elements: ElementsType[T] = ('a', 'b', 'c'), length: Optional[int] = None, unique: bool = False, use_weighting: Optional[bool] = None) Sequence[T]

Generate a list of randomly sampled objects from elements.

Set unique to False for random sampling with replacement, and set unique to True for random sampling without replacement.

If length is set to None or is omitted, length will be set to a random integer from 1 to the size of elements.

The value of length cannot be greater than the number of objects in elements if unique is set to True.

The value of elements can be any sequence type (list, tuple, set, string, etc) or an OrderedDict type. If it is the latter, the keys will be used as the objects for sampling, and the values will be used as weighted probabilities if unique is set to False. For example:

# Random sampling with replacement
fake.random_elements(
    elements=OrderedDict([
        ("variable_1", 0.5),        # Generates "variable_1" 50% of the time
        ("variable_2", 0.2),        # Generates "variable_2" 20% of the time
        ("variable_3", 0.2),        # Generates "variable_3" 20% of the time
        ("variable_4": 0.1),        # Generates "variable_4" 10% of the time
    ]), unique=False
)

# Random sampling without replacement (defaults to uniform distribution)
fake.random_elements(
    elements=OrderedDict([
        ("variable_1", 0.5),
        ("variable_2", 0.2),
        ("variable_3", 0.2),
        ("variable_4": 0.1),
    ]), unique=True
)
Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’), unique=False

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’), unique=True

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’), length=10, unique=False

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’), length=4, unique=True

Sample
elements=OrderedDict([

(“a”, 0.45), (“b”, 0.35),

(“c”, 0.15), (“d”, 0.05),

]), length=20, unique=False

Sample
elements=OrderedDict([

(“a”, 0.45), (“b”, 0.35), (“c”, 0.15), (“d”, 0.05),

]), unique=True

random_choices(elements: ElementsType[T] = ('a', 'b', 'c'), length: Optional[int] = None) Sequence[T]

Generate a list of objects randomly sampled from elements with replacement.

For information on the elements and length arguments, please refer to random_elements() which is used under the hood with the unique argument explicitly set to False.

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’)

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’), length=10

Sample
elements=OrderedDict([

(“a”, 0.45), (“b”, 0.35), (“c”, 0.15), (“d”, 0.05),

])

Sample
elements=OrderedDict([

(“a”, 0.45), (“b”, 0.35), (“c”, 0.15), (“d”, 0.05),

]), length=20

random_element(elements: ElementsType[T] = ('a', 'b', 'c')) T

Generate a randomly sampled object from elements.

For information on the elements argument, please refer to random_elements() which is used under the hood with the unique argument set to False and the length argument set to 1.

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’)

Sample size=10
elements=OrderedDict([

(“a”, 0.45), (“b”, 0.35), (“c”, 0.15), (“d”, 0.05),

])

random_sample(elements: ElementsType[T] = ('a', 'b', 'c'), length: Optional[int] = None) Sequence[T]

Generate a list of objects randomly sampled from elements without replacement.

For information on the elements and length arguments, please refer to random_elements() which is used under the hood with the unique argument explicitly set to True.

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘f’)

Sample

elements=(‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘f’), length=3

randomize_nb_elements(number: int = 10, le: bool = False, ge: bool = False, min: Optional[int] = None, max: Optional[int] = None) int

Generate a random integer near number according to the following rules:

  • If le is False (default), allow generation up to 140% of number. If True, upper bound generation is capped at 100%.

  • If ge is False (default), allow generation down to 60% of number. If True, lower bound generation is capped at 100%.

  • If a numerical value for min is provided, generated values less than min will be clamped at min.

  • If a numerical value for max is provided, generated values greater than max will be clamped at max.

  • If both le and ge are True, the value of number will automatically be returned, regardless of the values supplied for min and max.

Sample

number=100

Sample

number=100, ge=True

Sample

number=100, ge=True, min=120

Sample

number=100, le=True

Sample

number=100, le=True, max=80

Sample

number=79, le=True, ge=True, min=80

numerify(text: str = '###') str

Generate a string with each placeholder in text replaced according to the following rules:

  • Number signs (‘#’) are replaced with a random digit (0 to 9).

  • Percent signs (‘%’) are replaced with a random non-zero digit (1 to 9).

  • Dollar signs (‘$’) are replaced with a random digit above two (2 to 9).

  • Exclamation marks (‘!’) are replaced with a random digit or an empty string.

  • At symbols (‘@’) are replaced with a random non-zero digit or an empty string.

Under the hood, this method uses random_digit(), random_digit_not_null(), random_digit_or_empty(), and random_digit_not_null_or_empty() to generate the random values.

Sample

text=’Intel Core i%-%%##K vs AMD Ryzen % %%##X’

Sample

text=’!!! !!@ !@! !@@ @!! @!@ @@! @@@’

lexify(text: str = '????', letters: str = string.ascii_letters) str

Generate a string with each question mark (‘?’) in text replaced with a random character from letters.

By default, letters contains all ASCII letters, uppercase and lowercase.

Sample

text=’Random Identifier: ??????????’

Sample

text=’Random Identifier: ??????????’, letters=’ABCDE’

bothify(text: str = '## ??', letters: str = string.ascii_letters) str

Generate a string with each placeholder in text replaced according to the following rules:

  • Number signs (‘#’) are replaced with a random digit (0 to 9).

  • Question marks (‘?’) are replaced with a random character from letters.

By default, letters contains all ASCII letters, uppercase and lowercase.

Under the hood, this method uses numerify() and and lexify() to generate random values for number signs and question marks respectively.

Sample

letters=’ABCDE’

Sample

text=’Product Number: ????-########’

Sample

text=’Product Number: ????-########’, letters=’ABCDE’

hexify(text: str = '^^^^', upper: bool = False) str

Generate a string with each circumflex (‘^’) in text replaced with a random hexadecimal character.

By default, upper is set to False. If set to True, output will be formatted using uppercase hexadecimal characters.

Sample

text=’MAC Address: ^^:^^:^^:^^:^^:^^’

Sample

text=’MAC Address: ^^:^^:^^:^^:^^:^^’, upper=True

faker.providers.date_time.ElementsType
faker.providers.date_time.localized = True
faker.providers.date_time.datetime_to_timestamp(dt: Union[datetime.date, datetime.datetime]) int
faker.providers.date_time.timestamp_to_datetime(timestamp: Union[int, float], tzinfo: Optional[datetime.tzinfo]) datetime.datetime
faker.providers.date_time.change_year(current_date: datetime.date, year_diff: int) datetime.date

Unless the current_date is February 29th, it is fine to just subtract years. If it is a leap day, and we are rolling back to a non-leap year, it will cause a ValueError. Since this is relatively uncommon, just catch the error and roll forward to March 1

current_date: date object year_diff: int year delta value, positive or negative

exception faker.providers.date_time.ParseError

Bases: ValueError

Inappropriate argument value (of correct type).

faker.providers.date_time.timedelta_pattern: str = ''
class faker.providers.date_time.Provider(generator: Any)

Bases: faker.providers.BaseProvider

centuries: faker.providers.ElementsType[str] = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X', 'XI', 'XII', 'XIII', 'XIV', 'XV',...
countries
regex
unix_time(end_datetime: Optional[faker.typing.DateParseType] = None, start_datetime: Optional[faker.typing.DateParseType] = None) int

Get a timestamp between January 1, 1970 and now, unless passed explicit start_datetime or end_datetime values.

Example

1061306726

time_delta(end_datetime: Optional[faker.typing.DateParseType] = None) datetime.timedelta

Get a timedelta object

date_time(tzinfo: Optional[datetime.tzinfo] = None, end_datetime: Optional[faker.typing.DateParseType] = None) datetime.datetime

Get a datetime object for a date between January 1, 1970 and now

Parameters

tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘2005-08-16 20:39:21’)

Returns

datetime

date_time_ad(tzinfo: Optional[datetime.tzinfo] = None, end_datetime: Optional[faker.typing.DateParseType] = None, start_datetime: Optional[faker.typing.DateParseType] = None) datetime.datetime

Get a datetime object for a date between January 1, 001 and now

Parameters

tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘1265-03-22 21:15:52’)

Returns

datetime

iso8601(tzinfo: Optional[datetime.tzinfo] = None, end_datetime: Optional[faker.typing.DateParseType] = None, sep: str = 'T', timespec: str = 'auto') str

Get a timestamp in ISO 8601 format (or one of its profiles).

Parameters
  • tzinfo – timezone, instance of datetime.tzinfo subclass

  • sep – separator between date and time, defaults to ‘T’

  • timespec – format specifier for the time part, defaults to ‘auto’ - see datetime.isoformat() documentation

Example

‘2003-10-21T16:05:52+0000’

date(pattern: str = '%Y-%m-%d', end_datetime: Optional[faker.typing.DateParseType] = None) str

Get a date string between January 1, 1970 and now.

Parameters

pattern – Format of the date (year-month-day by default)

Example

‘2008-11-27’

Returns

Date

date_object(end_datetime: Optional[datetime.datetime] = None) datetime.date

Get a date object between January 1, 1970 and now

Example

datetime.date(2016, 9, 20)

time(pattern: str = '%H:%M:%S', end_datetime: Optional[faker.typing.DateParseType] = None) str

Get a time string (24h format by default)

Parameters

pattern – format

Example

‘15:02:34’

time_object(end_datetime: Optional[faker.typing.DateParseType] = None) datetime.time

Get a time object

Example

datetime.time(15, 56, 56, 772876)

classmethod _parse_start_datetime(value: Optional[faker.typing.DateParseType]) int
classmethod _parse_end_datetime(value: Optional[faker.typing.DateParseType]) int
classmethod _parse_date_string(value: str) Dict[str, float]
classmethod _parse_timedelta(value: Union[datetime.timedelta, str, float]) Union[float, int]
classmethod _parse_date_time(value: faker.typing.DateParseType, tzinfo: Optional[datetime.tzinfo] = None) int
classmethod _parse_date(value: faker.typing.DateParseType) datetime.date
date_time_between(start_date: faker.typing.DateParseType = '-30y', end_date: faker.typing.DateParseType = 'now', tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Get a datetime object based on a random date between two given dates. Accepts date strings that can be recognized by strtotime().

Parameters
  • start_date – Defaults to 30 years ago

  • end_date – Defaults to “now”

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘1999-02-02 11:42:52’)

Returns

datetime

date_between(start_date: faker.typing.DateParseType = '-30y', end_date: faker.typing.DateParseType = 'today') datetime.date

Get a Date object based on a random date between two given dates. Accepts date strings that can be recognized by strtotime().

Parameters
  • start_date – Defaults to 30 years ago

  • end_date – Defaults to “today”

Example

Date(‘1999-02-02’)

Returns

Date

future_datetime(end_date: faker.typing.DateParseType = '+30d', tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Get a datetime object based on a random date between 1 second form now and a given date. Accepts date strings that can be recognized by strtotime().

Parameters
  • end_date – Defaults to “+30d”

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘1999-02-02 11:42:52’)

Returns

datetime

future_date(end_date: faker.typing.DateParseType = '+30d', tzinfo: Optional[datetime.tzinfo] = None) datetime.date

Get a Date object based on a random date between 1 day from now and a given date. Accepts date strings that can be recognized by strtotime().

Parameters
  • end_date – Defaults to “+30d”

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

dtdate(‘2030-01-01’)

Returns

dtdate

past_datetime(start_date: faker.typing.DateParseType = '-30d', tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Get a datetime object based on a random date between a given date and 1 second ago. Accepts date strings that can be recognized by strtotime().

Parameters
  • start_date – Defaults to “-30d”

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘1999-02-02 11:42:52’)

Returns

datetime

past_date(start_date: faker.typing.DateParseType = '-30d', tzinfo: Optional[datetime.tzinfo] = None) datetime.date

Get a Date object based on a random date between a given date and 1 day ago. Accepts date strings that can be recognized by strtotime().

Parameters
  • start_date – Defaults to “-30d”

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

dtdate(‘1999-02-02’)

Returns

dtdate

date_time_between_dates(datetime_start: Optional[faker.typing.DateParseType] = None, datetime_end: Optional[faker.typing.DateParseType] = None, tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Takes two datetime objects and returns a random datetime between the two given datetimes. Accepts datetime objects.

Parameters
  • datetime_start – datetime

  • datetime_end – datetime

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘1999-02-02 11:42:52’)

Returns

datetime

date_between_dates(date_start: Optional[faker.typing.DateParseType] = None, date_end: Optional[faker.typing.DateParseType] = None) datetime.date

Takes two Date objects and returns a random date between the two given dates. Accepts Date or datetime objects

Parameters
  • date_start – Date

  • date_end – Date

Returns

Date

date_time_this_century(before_now: bool = True, after_now: bool = False, tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Gets a datetime object for the current century.

Parameters
  • before_now – include days in current century before today

  • after_now – include days in current century after today

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘2012-04-04 11:02:02’)

Returns

datetime

date_time_this_decade(before_now: bool = True, after_now: bool = False, tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Gets a datetime object for the decade year.

Parameters
  • before_now – include days in current decade before today

  • after_now – include days in current decade after today

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘2012-04-04 11:02:02’)

Returns

datetime

date_time_this_year(before_now: bool = True, after_now: bool = False, tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Gets a datetime object for the current year.

Parameters
  • before_now – include days in current year before today

  • after_now – include days in current year after today

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘2012-04-04 11:02:02’)

Returns

datetime

date_time_this_month(before_now: bool = True, after_now: bool = False, tzinfo: Optional[datetime.tzinfo] = None) datetime.datetime

Gets a datetime object for the current month.

Parameters
  • before_now – include days in current month before today

  • after_now – include days in current month after today

  • tzinfo – timezone, instance of datetime.tzinfo subclass

Example

datetime(‘2012-04-04 11:02:02’)

Returns

datetime

date_this_century(before_today: bool = True, after_today: bool = False) datetime.date

Gets a Date object for the current century.

Parameters
  • before_today – include days in current century before today

  • after_today – include days in current century after today

Example

Date(‘2012-04-04’)

Returns

Date

date_this_decade(before_today: bool = True, after_today: bool = False) datetime.date

Gets a Date object for the decade year.

Parameters
  • before_today – include days in current decade before today

  • after_today – include days in current decade after today

Example

Date(‘2012-04-04’)

Returns

Date

date_this_year(before_today: bool = True, after_today: bool = False) datetime.date

Gets a Date object for the current year.

Parameters
  • before_today – include days in current year before today

  • after_today – include days in current year after today

Example

Date(‘2012-04-04’)

Returns

Date

date_this_month(before_today: bool = True, after_today: bool = False) datetime.date

Gets a Date object for the current month.

Parameters
  • before_today – include days in current month before today

  • after_today – include days in current month after today

Example

dtdate(‘2012-04-04’)

Returns

dtdate

time_series(start_date: faker.typing.DateParseType = '-30d', end_date: faker.typing.DateParseType = 'now', precision: Optional[float] = None, distrib: Optional[Callable[[datetime.datetime], float]] = None, tzinfo: Optional[datetime.tzinfo] = None) Iterator[Tuple[datetime.datetime, Any]]

Returns a generator yielding tuples of (<datetime>, <value>).

The data points will start at start_date, and be at every time interval specified by precision. distrib is a callable that accepts <datetime> and returns <value>

am_pm() str
day_of_month() str
day_of_week() str
month() str
month_name() str
year() str
century() str
Example

‘XVII’

timezone() str
pytimezone(*args: Any, **kwargs: Any) Optional[datetime.tzinfo]

Generate a random timezone (see faker.timezone for any args) and return as a python object usable as a tzinfo to datetime or other fakers.

Example

faker.pytimezone()

Returns

dateutil.tz.tz.tzfile

date_of_birth(tzinfo: Optional[datetime.tzinfo] = None, minimum_age: int = 0, maximum_age: int = 115) datetime.date

Generate a random date of birth represented as a Date object, constrained by optional miminimum_age and maximum_age parameters.

Parameters
  • tzinfo – Defaults to None.

  • minimum_age – Defaults to 0.

  • maximum_age – Defaults to 115.

Example

Date(‘1979-02-02’)

Returns

Date

faker.providers.date_time.convert_timestamp_to_datetime(timestamp: Union[int, float], tzinfo: datetime.tzinfo) datetime.datetime