faker.providers.lorem

Subpackages

Package Contents

Classes

BaseProvider

Provider

Implement default lorem provider for Faker.

Attributes

localized

default_locale

class faker.providers.lorem.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.lorem.localized = True
faker.providers.lorem.default_locale = 'la'
class faker.providers.lorem.Provider(generator: Any)

Bases: faker.providers.BaseProvider

Implement default lorem provider for Faker.

Important

The default locale of the lorem provider is la. When using a locale without a localized lorem provider, the la lorem provider will be used, so generated words will be in pseudo-Latin. The locale used for the standard provider docs was en_US, and en_US has a localized lorem provider which is why the samples here show words in American English.

word_connector = ' '
sentence_punctuation = '.'
words(nb: int = 3, part_of_speech: Optional[str] = None, ext_word_list: Optional[Sequence[str]] = None, unique: bool = False) List[str]

Generate a tuple of words.

The nb argument controls the number of words in the resulting list, and if ext_word_list is provided, words from that list will be used instead of those from the locale provider’s built-in word list.

If unique is True, this method will return a list containing unique words. Under the hood, |random_sample| will be used for sampling without replacement. If unique is False, |random_choices| is used instead, and the list returned may contain duplicates.

part_of_speech is a parameter that defines to what part of speech the returned word belongs. If ext_word_list is not None, then part_of_speech is ignored. If the value of part_of_speech does not correspond to an existent part of speech according to the set locale, then an exception is raised.

Warning

Depending on the length of a locale provider’s built-in word list or on the length of ext_word_list if provided, a large nb can exhaust said lists if unique is True, raising an exception.

Sample

Sample

nb=5

Sample

nb=5, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

Sample

nb=4, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’], unique=True

word(part_of_speech: Optional[str] = None, ext_word_list: Optional[Sequence[str]] = None) str

Generate a word.

This method uses |words| under the hood with the nb argument set to 1 to generate the result.

Sample

Sample

ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

sentence(nb_words: int = 6, variable_nb_words: bool = True, ext_word_list: Optional[Sequence[str]] = None) str

Generate a sentence.

The nb_words argument controls how many words the sentence will contain, and setting variable_nb_words to False will generate the exact amount, while setting it to True (default) will generate a random amount (+/-40%, minimum of 1) using |randomize_nb_elements|.

Under the hood, |words| is used to generate the words, so the argument ext_word_list works in the same way here as it would in that method.

Sample

nb_words=10

Sample

nb_words=10, variable_nb_words=False

Sample

nb_words=10, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

Sample

nb_words=10, variable_nb_words=True, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

sentences(nb: int = 3, ext_word_list: Optional[Sequence[str]] = None) List[str]

Generate a list of sentences.

This method uses |sentence| under the hood to generate sentences, and the nb argument controls exactly how many sentences the list will contain. The ext_word_list argument works in exactly the same way as well.

Sample

Sample

nb=5

Sample

nb=5, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

paragraph(nb_sentences: int = 3, variable_nb_sentences: bool = True, ext_word_list: Optional[Sequence[str]] = None) str

Generate a paragraph.

The nb_sentences argument controls how many sentences the paragraph will contain, and setting variable_nb_sentences to False will generate the exact amount, while setting it to True (default) will generate a random amount (+/-40%, minimum of 1) using |randomize_nb_elements|.

Under the hood, |sentences| is used to generate the sentences, so the argument ext_word_list works in the same way here as it would in that method.

Sample

nb_sentences=5

Sample

nb_sentences=5, variable_nb_sentences=False

Sample

nb_sentences=5, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

Sample

nb_sentences=5, variable_nb_sentences=False, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

paragraphs(nb: int = 3, ext_word_list: Optional[Sequence[str]] = None) List[str]

Generate a list of paragraphs.

This method uses |paragraph| under the hood to generate paragraphs, and the nb argument controls exactly how many sentences the list will contain. The ext_word_list argument works in exactly the same way as well.

Sample

nb=5

Sample

nb=5, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

text(max_nb_chars: int = 200, ext_word_list: Optional[Sequence[str]] = None) str

Generate a text string.

The max_nb_chars argument controls the approximate number of characters the text string will have, and depending on its value, this method may use either |words|, |sentences|, or |paragraphs| for text generation. The ext_word_list argument works in exactly the same way it would in any of those methods.

Sample

max_nb_chars=20

Sample

max_nb_chars=80

Sample

max_nb_chars=160

Sample

ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]

texts(nb_texts: int = 3, max_nb_chars: int = 200, ext_word_list: Optional[Sequence[str]] = None) List[str]

Generate a list of text strings.

The nb_texts argument controls how many text strings the list will contain, and this method uses |text| under the hood for text generation, so the two remaining arguments, max_nb_chars and ext_word_list will work in exactly the same way as well.

Sample

nb_texts=5

Sample

nb_texts=5, max_nb_chars=50

Sample

nb_texts=5, max_nb_chars=50, ext_word_list=[‘abc’, ‘def’, ‘ghi’, ‘jkl’]