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

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

    - 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'

        >>> Faker.seed(0)
        >>> for _ in range(5):
        ...     fake.bothify(text='Order: ##??-$')
        ...
        'Order: 66qG-2'
        'Order: 76Ew-6'
        'Order: 93si-4'
        'Order: 19IT-6'
        'Order: 92gU-6'

  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[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[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[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[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