faker.providers.misc.en_US

Package Contents

Classes

MiscProvider

Provider

class faker.providers.misc.en_US.MiscProvider(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.

class faker.providers.misc.en_US.Provider(generator: Any)

Bases: faker.providers.misc.Provider