faker.providers.date_time
¶
Subpackages¶
faker.providers.date_time.ar_AA
faker.providers.date_time.ar_EG
faker.providers.date_time.az_AZ
faker.providers.date_time.bn_BD
faker.providers.date_time.cs_CZ
faker.providers.date_time.da_DK
faker.providers.date_time.de_AT
faker.providers.date_time.de_DE
faker.providers.date_time.el_GR
faker.providers.date_time.en_PH
faker.providers.date_time.en_US
faker.providers.date_time.es
faker.providers.date_time.es_AR
faker.providers.date_time.es_CL
faker.providers.date_time.es_ES
faker.providers.date_time.fil_PH
faker.providers.date_time.fr_CA
faker.providers.date_time.fr_FR
faker.providers.date_time.hi_IN
faker.providers.date_time.hr_HR
faker.providers.date_time.hu_HU
faker.providers.date_time.hy_AM
faker.providers.date_time.id_ID
faker.providers.date_time.it_IT
faker.providers.date_time.ja_JP
faker.providers.date_time.ko_KR
faker.providers.date_time.nl_NL
faker.providers.date_time.no_NO
faker.providers.date_time.pl_PL
faker.providers.date_time.pt_BR
faker.providers.date_time.pt_PT
faker.providers.date_time.ro_RO
faker.providers.date_time.ru_RU
faker.providers.date_time.sk_SK
faker.providers.date_time.sl_SI
faker.providers.date_time.ta_IN
faker.providers.date_time.th_TH
faker.providers.date_time.tl_PH
faker.providers.date_time.tr_TR
faker.providers.date_time.zh_CN
faker.providers.date_time.zh_TW
Package Contents¶
Classes¶
Functions¶
|
|
|
|
|
Unless the current_date is February 29th, it is fine to just subtract years. |
|
Attributes¶
- class faker.providers.date_time.Country¶
- faker.providers.date_time.DateParseType¶
- class faker.providers.date_time.BaseProvider(generator: Any)¶
- __provider__ = 'base'¶
- __use_weighting__ = False¶
- language_locale_codes¶
- random_int(min: int = 0, max: int = 9999, step: int = 1) int ¶
Generate a random integer between two integers
min
andmax
inclusive while observing the providedstep
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_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
isNone
(default), its value will be set to a random integer from 1 to 9.If
fix_len
isFalse
(default), all integers that do not exceed the number ofdigits
can be generated.If
fix_len
isTrue
, only integers with the exact number ofdigits
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_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_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
toFalse
for random sampling with replacement, and setunique
toTrue
for random sampling without replacement.If
length
is set toNone
or is omitted,length
will be set to a random integer from 1 to the size ofelements
.The value of
length
cannot be greater than the number of objects inelements
ifunique
is set toTrue
.The value of
elements
can be any sequence type (list
,tuple
,set
,string
, etc) or anOrderedDict
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 ifunique
is set toFalse
. 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
andlength
arguments, please refer torandom_elements()
which is used under the hood with theunique
argument explicitly set toFalse
.- 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 torandom_elements()
which is used under the hood with theunique
argument set toFalse
and thelength
argument set to1
.- 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
andlength
arguments, please refer torandom_elements()
which is used under the hood with theunique
argument explicitly set toTrue
.- 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
isFalse
(default), allow generation up to 140% ofnumber
. IfTrue
, upper bound generation is capped at 100%.If
ge
isFalse
(default), allow generation down to 60% ofnumber
. IfTrue
, lower bound generation is capped at 100%.If a numerical value for
min
is provided, generated values less thanmin
will be clamped atmin
.If a numerical value for
max
is provided, generated values greater thanmax
will be clamped atmax
.If both
le
andge
areTrue
, the value ofnumber
will automatically be returned, regardless of the values supplied formin
andmax
.
- 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()
, andrandom_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 fromletters
.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 andlexify()
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 toTrue
, 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).
- 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_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 byprecision
.distrib
is a callable that accepts<datetime>
and returns<value>
- 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 ¶