faker.providers.misc
¶
Subpackages¶
Package Contents¶
Classes¶
Attributes¶
- 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'¶
- __use_weighting__ = False¶
- language_locale_codes¶
- random_int(min: int = 0, max: int = 9999, step: int = 1) int ¶
Generate a random integer between two integers
min
andmax
inclusive while observing the providedstep
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_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
isNone
(default), its value will be set to a random integer from 1 to 9.If
fix_len
isFalse
(default), all integers that do not exceed the number ofdigits
can be generated.If
fix_len
isTrue
, only integers with the exact number ofdigits
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_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_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
toFalse
for random sampling with replacement, and setunique
toTrue
for random sampling without replacement.If
length
is set toNone
or is omitted,length
will be set to a random integer from 1 to the size ofelements
.The value of
length
cannot be greater than the number of objects inelements
ifunique
is set toTrue
.The value of
elements
can be any sequence type (list
,tuple
,set
,string
, etc) or anOrderedDict
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 ifunique
is set toFalse
. 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
andlength
arguments, please refer torandom_elements()
which is used under the hood with theunique
argument explicitly set toFalse
.- 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 torandom_elements()
which is used under the hood with theunique
argument set toFalse
and thelength
argument set to1
.- 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
andlength
arguments, please refer torandom_elements()
which is used under the hood with theunique
argument explicitly set toTrue
.- 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
isFalse
(default), allow generation up to 140% ofnumber
. IfTrue
, upper bound generation is capped at 100%.If
ge
isFalse
(default), allow generation down to 60% ofnumber
. IfTrue
, lower bound generation is capped at 100%.If a numerical value for
min
is provided, generated values less thanmin
will be clamped atmin
.If a numerical value for
max
is provided, generated values greater thanmax
will be clamped atmax
.If both
le
andge
areTrue
, the value ofnumber
will automatically be returned, regardless of the values supplied formin
andmax
.
- 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()
, andrandom_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 fromletters
.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 andlexify()
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 toTrue
, 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
- 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
isFalse
(default), a hexadecimal string representation of the MD5 hash will be returned. IfTrue
, abytes
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
isFalse
(default), a hexadecimal string representation of the SHA-1 hash will be returned. IfTrue
, abytes
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
isFalse
(default), a hexadecimal string representation of the SHA-256 hash will be returned. IfTrue
, abytes
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 tostr
.May be called with
cast_to=None
to return a full-fledgedUUID
.- 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
, andlower_case
control what category of characters will appear in the generated password. If set toTrue
(default), at least one character from the corresponding category is guaranteed to appear. Special characters are characters from!@#$%^&*()_+
, digits are characters from0123456789
, 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 defaultnum_files
- the number of files archived in resulting zip file, 1 by defaultmin_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 defaultnum_files
- the number of files archived in resulting zip file, 1 by defaultmin_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
andluminosity
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
. Thedialect
and**fmtparams
arguments are the same arguments expected bycsv.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 acsv.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. Thedata_columns
argument expects a list or a tuple of string tokens, and these string tokens will be passed topystr_format()
for data generation. Argument Groups are used to pass arguments to the provider methods. Bothheader
anddata_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 theinclude_row_ids
argument may be set toTrue
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
- 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
- Returns
Serialized Fixed Width data
- Return type
- 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.