faker.providers.misc

Subpackages

Package Contents

Classes

BaseProvider

Provider

Attributes

TypesSpec

localized

exception faker.providers.misc.UnsupportedFeature(msg: str, name: str)

Bases: BaseFakerException

The requested feature is not available on this system.

class faker.providers.misc.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.misc.TypesSpec
faker.providers.misc.localized = True
class faker.providers.misc.Provider(generator: Any)

Bases: faker.providers.BaseProvider

boolean(chance_of_getting_true: int = 50) bool

Generate a random boolean value based on chance_of_getting_true.

Sample

chance_of_getting_true=25

Sample

chance_of_getting_true=50

Sample

chance_of_getting_true=75

null_boolean() Optional[bool]

Generate None, True, or False, each with equal probability.

binary(length: int = 1 * 1024 * 1024) bytes

Generate a random binary blob of length bytes.

If this faker instance has been seeded, performance will be signficiantly reduced, to conform to the seeding.

Sample

length=64

md5(raw_output: bool = False) Union[bytes, str]

Generate a random MD5 hash.

If raw_output is False (default), a hexadecimal string representation of the MD5 hash will be returned. If True, a bytes object representation will be returned instead.

Sample

raw_output=False

Sample

raw_output=True

sha1(raw_output: bool = False) Union[bytes, str]

Generate a random SHA-1 hash.

If raw_output is False (default), a hexadecimal string representation of the SHA-1 hash will be returned. If True, a bytes object representation will be returned instead.

Sample

raw_output=False

Sample

raw_output=True

sha256(raw_output: bool = False) Union[bytes, str]

Generate a random SHA-256 hash.

If raw_output is False (default), a hexadecimal string representation of the SHA-256 hash will be returned. If True, a bytes object representation will be returned instead.

Sample

raw_output=False

Sample

raw_output=True

uuid4(cast_to: Optional[Union[Callable[[uuid.UUID], str], Callable[[uuid.UUID], bytes]]] = str) Union[bytes, str, uuid.UUID]

Generate a random UUID4 object and cast it to another type if specified using a callable cast_to.

By default, cast_to is set to str.

May be called with cast_to=None to return a full-fledged UUID.

Sample

Sample

cast_to=None

password(length: int = 10, special_chars: bool = True, digits: bool = True, upper_case: bool = True, lower_case: bool = True) str

Generate a random password of the specified length.

The arguments special_chars, digits, upper_case, and lower_case control what category of characters will appear in the generated password. If set to True (default), at least one character from the corresponding category is guaranteed to appear. Special characters are characters from !@#$%^&*()_+, digits are characters from 0123456789, and uppercase and lowercase characters are characters from the ASCII set of letters.

Sample

length=12

Sample

length=40, special_chars=False, upper_case=False

zip(uncompressed_size: int = 65536, num_files: int = 1, min_file_size: int = 4096, compression: Optional[str] = None) bytes

Generate a bytes object containing a random valid zip archive file.

The number and sizes of files contained inside the resulting archive can be controlled using the following arguments:

  • uncompressed_size - the total size of files before compression, 16 KiB by default

  • num_files - the number of files archived in resulting zip file, 1 by default

  • min_file_size - the minimum size of each file before compression, 4 KiB by default

No compression is used by default, but setting compression to one of the values listed below will use the corresponding compression type.

  • 'bzip2' or 'bz2' for BZIP2

  • 'lzma' or 'xz' for LZMA

  • 'deflate', 'gzip', or 'gz' for GZIP

Sample

uncompressed_size=256, num_files=4, min_file_size=32

Sample

uncompressed_size=256, num_files=32, min_file_size=4, compression=’bz2’

tar(uncompressed_size: int = 65536, num_files: int = 1, min_file_size: int = 4096, compression: Optional[str] = None) bytes

Generate a bytes object containing a random valid tar file.

The number and sizes of files contained inside the resulting archive can be controlled using the following arguments:

  • uncompressed_size - the total size of files before compression, 16 KiB by default

  • num_files - the number of files archived in resulting zip file, 1 by default

  • min_file_size - the minimum size of each file before compression, 4 KiB by default

No compression is used by default, but setting compression to one of the values listed below will use the corresponding compression type.

  • 'bzip2' or 'bz2' for BZIP2

  • 'lzma' or 'xz' for LZMA

  • 'gzip' or 'gz' for GZIP

Sample

uncompressed_size=256, num_files=4, min_file_size=32

Sample

uncompressed_size=256, num_files=32, min_file_size=4, compression=’bz2’

image(size: Tuple[int, int] = (256, 256), image_format: str = 'png', hue: Optional[Union[int, Sequence[int], str]] = None, luminosity: Optional[str] = None) bytes

Generate an image and draw a random polygon on it using the Python Image Library. Without it installed, this provider won’t be functional. Returns the bytes representing the image in a given format.

The argument size must be a 2-tuple containing (width, height) in pixels. Defaults to 256x256.

The argument image_format can be any valid format to the underlying library like 'tiff', 'jpeg', 'pdf' or 'png' (default). Note that some formats need present system libraries prior to building the Python Image Library. Refer to https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html for details.

The arguments hue and luminosity are the same as in the color provider and are simply forwarded to it to generate both the background and the shape colors. Therefore, you can ask for a “dark blue” image, etc.

Sample

size=(2, 2), hue=’purple’, luminosity=’bright’, image_format=’pdf’

Sample

size=(16, 16), hue=[90,270], image_format=’ico’

dsv(dialect: str = 'faker-csv', header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False, **fmtparams: Any) str

Generate random delimiter-separated values.

This method’s behavior share some similarities with csv.writer. The dialect and **fmtparams arguments are the same arguments expected by csv.writer to control its behavior, and instead of expecting a file-like object to where output will be written, the output is controlled by additional keyword arguments and is returned as a string.

The dialect argument defaults to 'faker-csv' which is the name of a csv.excel subclass with full quoting enabled.

The header argument expects a list or a tuple of strings that will serve as the header row if supplied. The data_columns argument expects a list or a tuple of string tokens, and these string tokens will be passed to pystr_format() for data generation. Argument Groups are used to pass arguments to the provider methods. Both header and data_columns must be of the same length.

Example:

fake.set_arguments(‘top_half’, {‘min_value’: 50, ‘max_value’: 100}) fake.dsv(data_columns=(‘{{ name }}’, ‘{{ pyint:top_half }}’))

The num_rows argument controls how many rows of data to generate, and the include_row_ids argument may be set to True to include a sequential row ID column.

Sample

dialect=’excel’, data_columns=(‘{{name}}’, ‘{{address}}’)

Sample

dialect=’excel-tab’, data_columns=(‘{{name}}’, ‘{{address}}’), include_row_ids=True

Sample

data_columns=(‘{{name}}’, ‘{{address}}’), num_rows=5, delimiter=’$’

csv(header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False) str

Generate random comma-separated values.

For more information on the different arguments of this method, please refer to dsv() which is used under the hood.

Sample

data_columns=(‘{{name}}’, ‘{{address}}’), num_rows=10, include_row_ids=False

Sample

header=(‘Name’, ‘Address’, ‘Favorite Color’), data_columns=(‘{{name}}’, ‘{{address}}’, ‘{{safe_color_name}}’), num_rows=10, include_row_ids=True

tsv(header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False) str

Generate random tab-separated values.

For more information on the different arguments of this method, please refer to dsv() which is used under the hood.

Sample

data_columns=(‘{{name}}’, ‘{{address}}’), num_rows=10, include_row_ids=False

Sample

header=(‘Name’, ‘Address’, ‘Favorite Color’), data_columns=(‘{{name}}’, ‘{{address}}’, ‘{{safe_color_name}}’), num_rows=10, include_row_ids=True

psv(header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False) str

Generate random pipe-separated values.

For more information on the different arguments of this method, please refer to dsv() which is used under the hood.

Sample

data_columns=(‘{{name}}’, ‘{{address}}’), num_rows=10, include_row_ids=False

Sample

header=(‘Name’, ‘Address’, ‘Favorite Color’), data_columns=(‘{{name}}’, ‘{{address}}’, ‘{{safe_color_name}}’), num_rows=10, include_row_ids=True

json_bytes(data_columns: Optional[List] = None, num_rows: int = 10, indent: Optional[int] = None, cls: Optional[Type[json.JSONEncoder]] = None) bytes

Generate random JSON structure and return as bytes.

For more information on the different arguments of this method, refer to json() which is used under the hood.

json(data_columns: Optional[List] = None, num_rows: int = 10, indent: Optional[int] = None, cls: Optional[Type[json.JSONEncoder]] = None) str

Generate random JSON structure values.

Using a dictionary or list of records that is passed as data_columns, define the structure that is used to build JSON structures. For complex data structures it is recommended to use the dictionary format.

Data Column Dictionary format:

{‘key name’: ‘definition’}

The definition can be ‘provider’, ‘provider:argument_group’, tokenized ‘string {{ provider:argument_group }}’ that is passed to the python provider method pystr_format() for generation, or a fixed ‘@word’. Using Lists, Tuples, and Dicts as a definition for structure.

Example:

fake.set_arguments(‘top_half’, {‘min_value’: 50, ‘max_value’: 100}) fake.json(data_columns={‘Name’: ‘name’, ‘Score’: ‘pyint:top_half’})

Data Column List format:

[(‘key name’, ‘definition’, {‘arguments’})]

With the list format the definition can be a list of records, to create a list within the structure data. For literal entries within the list, set the ‘field_name’ to None.

Parameters
  • data_columns (dict) – specification for the data structure

  • num_rows (int) – number of rows the returned

  • indent (int) – number of spaces to indent the fields

  • cls (json.JSONEncoder) – optional json encoder to use for non-standard objects such as datetimes

Returns

Serialized JSON data

Return type

str

Sample

data_columns={‘Spec’: @1.0.1’, ‘ID’: ‘pyint’, ‘Details’: {‘Name’: ‘name’, ‘Address’: ‘address’}}, num_rows=2

Sample

data_columns={‘Candidates’: [‘name’, ‘name’, ‘name’]}, num_rows=1

Sample

data_columns=[(‘Name’, ‘name’), (‘Points’, ‘pyint’, {‘min_value’: 50, ‘max_value’: 100})], num_rows=1

xml(nb_elements: int = 10, variable_nb_elements: bool = True, value_types: Optional[faker.providers.python.TypesSpec] = None, allowed_types: Optional[faker.providers.python.TypesSpec] = None) str

Returns some XML.

Nb_elements

number of elements for dictionary

Variable_nb_elements

is use variable number of elements for dictionary

Value_types

type of dictionary values

Note: this provider required xmltodict library installed

fixed_width(data_columns: Optional[list] = None, num_rows: int = 10, align: str = 'left') str

Generate random fixed width values.

Using a list of tuple records that is passed as data_columns, that defines the structure that will be generated. Arguments within the record are provider specific, and should be a dictionary that will be passed to the provider method.

Data Column List format

[(‘field width’, ‘definition’, {‘arguments’})]

The definition can be ‘provider’, ‘provider:argument_group’, tokenized ‘string {{ provider:argument_group }}’ that is passed to the python provider method pystr_format() for generation, or a fixed ‘@word’. Using Lists, Tuples, and Dicts as a definition for structure.

Argument Groups can be used to pass arguments to the provider methods, but will override the arguments supplied in the tuple record.

Example:

fake.set_arguments(‘top_half’, {‘min_value’: 50, ‘max_value’: 100}) fake.fixed_width(data_columns=[(20, ‘name’), (3, ‘pyint:top_half’)])

Parameters
  • data_columns (list) – specification for the data structure

  • num_rows (int) – number of rows the generator will yield

  • align (str) – positioning of the value. (left, middle, right)

Returns

Serialized Fixed Width data

Return type

str

Sample

data_columns=[(20, ‘name’), (3, ‘pyint’, {‘min_value’: 50, ‘max_value’: 100})], align=’right’, num_rows=2

_value_format_selection(definition: str, **kwargs: Any) Union[int, str]

Formats the string in different ways depending on its contents.

The return can be the @word’ itself, a ‘{{ token }}’ passed to PyStr, or a ‘provider:argument_group’ format field that returns potentially a non-string type.

This ensures that Numbers, Boolean types that are generated in the JSON structures in there proper type, and not just strings.