`faker.providers`¶

class faker.providers.BaseProvider(generator: Any)¶

Bases: object

bothify(text: str = '## ??', letters: str = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ') → 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.bothify(letters='ABCDE')
...
'66 AC'
'87 DC'
'75 EB'
'82 CB'
'19 CE'

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.bothify(text='Product Number: ????-########')
...
'Product Number: EwLn-66048764'
'Product Number: TZMj-82421948'
'Product Number: BuNO-41157815'
'Product Number: afUz-38778408'
'Product Number: KopZ-09753513'

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.bothify(text='Product Number: ????-########', letters='ABCDE')
...
'Product Number: DCEB-66048764'
'Product Number: EBCA-82421948'
'Product Number: EBED-15781565'
'Product Number: AEDC-78408016'
'Product Number: EDAA-35139332'

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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.hexify(text='MAC Address: ^^:^^:^^:^^:^^:^^')
...
'MAC Address: cd:18:fc:9f:b6:49'
'MAC Address: 43:84:93:2a:f3:bd'
'MAC Address: a6:fe:81:02:c0:fa'
'MAC Address: 7a:26:77:4e:22:af'
'MAC Address: 39:93:a6:9e:2c:a7'

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.hexify(text='MAC Address: ^^:^^:^^:^^:^^:^^', upper=True)
...
'MAC Address: CD:18:FC:9F:B6:49'
'MAC Address: 43:84:93:2A:F3:BD'
'MAC Address: A6:FE:81:02:C0:FA'
'MAC Address: 7A:26:77:4E:22:AF'
'MAC Address: 39:93:A6:9E:2C:A7'

language_code() → str¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.language_code()
...
'mg'
'mt'
'az'
'hy'
'ro'

lexify(text: str = '????', letters: str = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ') → 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.lexify(text='Random Identifier: ??????????')
...
'Random Identifier: yWAcqGFzYt'
'Random Identifier: EwLnGisiWg'
'Random Identifier: NZqITZMjtg'
'Random Identifier: UeRvEJgwBu'
'Random Identifier: NOnJECHqdZ'

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.lexify(text='Random Identifier: ??????????', letters='ABCDE')
...
'Random Identifier: DDACEDDCDC'
'Random Identifier: EBEBCBAECE'
'Random Identifier: EBCAACDEAC'
'Random Identifier: DCEBEDDECA'
'Random Identifier: EAADAEDCBC'

locale() → str¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.locale()
...
'mg_MG'
'az_IN'
'ro_RO'
'mn_MN'
'os_RU'

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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.numerify(text='Intel Core i%-%%##K vs AMD Ryzen % %%##X')
...
'Intel Core i9-8766K vs AMD Ryzen 5 8604X'
'Intel Core i5-3293K vs AMD Ryzen 5 9382X'
'Intel Core i8-9241K vs AMD Ryzen 6 7615X'
'Intel Core i8-9593K vs AMD Ryzen 1 9187X'
'Intel Core i8-6416K vs AMD Ryzen 6 2409X'

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.numerify(text='!!! !!@ !@! !@@ @!! @!@ @@! @@@')
...
'68 672 9 8 72 488 1 16'
'1 9 1 8 681 83 1 8'
'  828 6 9 72 35 7'
'   4 11 2 2 63'
'0 352 93 7 6 5 28 13'

random_choices(elements: Collection[str] | Collection[T] | OrderedDict[T, float] = ('a', 'b', 'c'), length: int | None = 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_choices(elements=('a', 'b', 'c', 'd'))
...
['d', 'b', 'b', 'c']
['d', 'd', 'd', 'b']
['c', 'b']
['c']
['b', 'c']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_choices(elements=('a', 'b', 'c', 'd'), length=10)
...
['d', 'd', 'b', 'b', 'c', 'b', 'd', 'b', 'b', 'c']
['d', 'c', 'b', 'd', 'c', 'b', 'd', 'd', 'd', 'd']
['b', 'c', 'd', 'c', 'b', 'a', 'b', 'c', 'd', 'd']
['b', 'd', 'b', 'd', 'c', 'a', 'c', 'b', 'd', 'c']
['a', 'b', 'd', 'a', 'b', 'd', 'a', 'c', 'a', 'd']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_choices(elements=OrderedDict([("a", 0.45), ("b", 0.35), ("c", 0.15), ("d", 0.05), ]))
...
['b', 'a', 'a', 'b']
['c', 'c', 'd', 'a']
['b', 'a']
['b']
['d', 'b', 'b']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_choices(elements=OrderedDict([("a", 0.45), ("b", 0.35), ("c", 0.15), ("d", 0.05), ]), length=20)
...
['c', 'b', 'a', 'a', 'b', 'a', 'b', 'a', 'b', 'b', 'c', 'b', 'a', 'b', 'b', 'a', 'c', 'd', 'c', 'c']
['a', 'b', 'c', 'b', 'b', 'a', 'a', 'b', 'c', 'd', 'b', 'c', 'a', 'c', 'b', 'a', 'b', 'a', 'c', 'b']
['a', 'b', 'c', 'a', 'a', 'c', 'a', 'b', 'a', 'd', 'c', 'a', 'a', 'a', 'b', 'c', 'a', 'b', 'b', 'b']
['c', 'b', 'd', 'b', 'b', 'a', 'b', 'a', 'b', 'a', 'a', 'a', 'b', 'b', 'b', 'a', 'b', 'c', 'c', 'c']
['c', 'c', 'b', 'a', 'b', 'a', 'c', 'c', 'c', 'b', 'c', 'b', 'b', 'b', 'd', 'c', 'b', 'a', 'b', 'b']

random_digit() → int¶

Generate a random digit (0 to 9).

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_digit()
...
6
6
0
4
8

random_digit_above_two() → int¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_digit_above_two()
...
8
8
2
6
9

random_digit_not_null() → int¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_digit_not_null()
...
7
7
1
5
9

random_digit_not_null_or_empty() → 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_digit_not_null_or_empty()
...
7
''
9
7
8

random_digit_or_empty() → 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_digit_or_empty()
...
6
''
8
6
7

random_element(elements: Collection[str] | Collection[T] | OrderedDict[T, float] = ('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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_element(elements=('a', 'b', 'c', 'd'))
...
'd'
'd'
'a'
'c'
'd'

>>> Faker.seed(0)
>>> for _ in range(10):
...     fake.random_element(elements=OrderedDict([("a", 0.45), ("b", 0.35), ("c", 0.15), ("d", 0.05), ]))
...
'c'
'b'
'a'
'a'
'b'
'a'
'b'
'a'
'b'
'b'

random_elements(elements: Collection[str] | Collection[T] | OrderedDict[T, float] = ('a', 'b', 'c'), length: int | None = None, unique: bool = False, use_weighting: bool | None = 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
)

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=('a', 'b', 'c', 'd'), unique=False)
...
['d', 'b', 'b', 'c']
['d', 'd', 'd', 'b']
['c', 'b']
['c']
['b', 'c']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=('a', 'b', 'c', 'd'), unique=True)
...
['d', 'a', 'b', 'c']
['c', 'b', 'd', 'a']
['c', 'a']
['c']
['c', 'a']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=('a', 'b', 'c', 'd'), length=10, unique=False)
...
['d', 'd', 'b', 'b', 'c', 'b', 'd', 'b', 'b', 'c']
['d', 'c', 'b', 'd', 'c', 'b', 'd', 'd', 'd', 'd']
['b', 'c', 'd', 'c', 'b', 'a', 'b', 'c', 'd', 'd']
['b', 'd', 'b', 'd', 'c', 'a', 'c', 'b', 'd', 'c']
['a', 'b', 'd', 'a', 'b', 'd', 'a', 'c', 'a', 'd']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=('a', 'b', 'c', 'd'), length=4, unique=True)
...
['d', 'b', 'a', 'c']
['d', 'b', 'c', 'a']
['c', 'd', 'a', 'b']
['c', 'a', 'd', 'b']
['b', 'd', 'a', 'c']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=OrderedDict([("a", 0.45), ("b", 0.35), ("c", 0.15), ("d", 0.05), ]), length=20, unique=False)
...
['c', 'b', 'a', 'a', 'b', 'a', 'b', 'a', 'b', 'b', 'c', 'b', 'a', 'b', 'b', 'a', 'c', 'd', 'c', 'c']
['a', 'b', 'c', 'b', 'b', 'a', 'a', 'b', 'c', 'd', 'b', 'c', 'a', 'c', 'b', 'a', 'b', 'a', 'c', 'b']
['a', 'b', 'c', 'a', 'a', 'c', 'a', 'b', 'a', 'd', 'c', 'a', 'a', 'a', 'b', 'c', 'a', 'b', 'b', 'b']
['c', 'b', 'd', 'b', 'b', 'a', 'b', 'a', 'b', 'a', 'a', 'a', 'b', 'b', 'b', 'a', 'b', 'c', 'c', 'c']
['c', 'c', 'b', 'a', 'b', 'a', 'c', 'c', 'c', 'b', 'c', 'b', 'b', 'b', 'd', 'c', 'b', 'a', 'b', 'b']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_elements(elements=OrderedDict([("a", 0.45), ("b", 0.35), ("c", 0.15), ("d", 0.05), ]), unique=True)
...
['b', 'a', 'c', 'd']
['c', 'b', 'd', 'a']
['b', 'a']
['b']
['d', 'b', 'a']

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).

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_int(min=0, max=15)
...
12
13
1
8
15

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_int(min=0, max=15, step=3)
...
9
9
0
6
12

random_letter() → str¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_letter()
...
'y'
'W'
'A'
'c'
'q'

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

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_letters(length=10)
...
['R', 'N', 'v', 'n', 'A', 'v', 'O', 'p', 'y', 'E']
['V', 'A', 'o', 'N', 'G', 'n', 'V', 'Z', 'Q', 'U']
['q', 'L', 'U', 'J', 'y', 'f', 'w', 'F', 'V', 'Y']
['y', 'S', 'n', 'P', 'C', 'a', 'L', 'u', 'Q', 'I']
['a', 'z', 'T', 'm', 'q', 'T', 'j', 'D', 'm', 'Y']

random_lowercase_letter() → str¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_lowercase_letter()
...
'm'
'y'
'n'
'b'
'i'

random_number(digits: int | None = 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_number(fix_len=False)
...
7056020
4
521760889
5088743
48056573

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_number(fix_len=True)
...
8056020
5
621760889
6088743
58056573

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_number(digits=3)
...
864
394
776
911
430

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_number(digits=3, fix_len=False)
...
864
394
776
911
430

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_number(digits=3, fix_len=True)
...
964
494
876
530
141

random_sample(elements: Collection[str] | Collection[T] | OrderedDict[T, float] = ('a', 'b', 'c'), length: int | None = 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_sample(elements=('a', 'b', 'c', 'd', 'e', 'f'))
...
['d', 'a', 'c', 'f']
['d', 'c', 'f', 'b']
['b', 'e', 'f', 'd', 'a']
['e']
['e', 'f', 'b']

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_sample(elements=('a', 'b', 'c', 'd', 'e', 'f'), length=3)
...
['d', 'f', 'a']
['c', 'e', 'd']
['d', 'c', 'f']
['c', 'e', 'b']
['e', 'b', 'c']

random_uppercase_letter() → str¶

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

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.random_uppercase_letter()
...
'M'
'Y'
'N'
'B'
'I'

randomize_nb_elements(number: int = 10, le: bool = False, ge: bool = False, min: int | None = None, max: int | None = 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.

Examples:

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=100)
...
109
113
65
93
125

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=100, ge=True)
...
124
126
102
116
132

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=100, ge=True, min=120)
...
124
126
120
120
132

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=100, le=True)
...
84
86
62
76
92

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=100, le=True, max=80)
...
80
80
62
76
80

>>> Faker.seed(0)
>>> for _ in range(5):
...     fake.randomize_nb_elements(number=79, le=True, ge=True, min=80)
...
79
79
79
79
79

`faker.providers`¶

Table of Contents

Previous topic

Next topic

This Page

faker.providers¶

`faker.providers`¶