API Reference

This page contains the API reference for Randum’s main classes and modules.

Randum Class

class randum.Randum(locale: str | Sequence[str] | dict[str, int | float] | None = None, providers: list[str] | None = None, generator: Generator | None = None, includes: list[str] | None = None, use_weighting: bool = True, **config: Any)

Bases: object

Proxy class capable of supporting multiple locales

cache_pattern: Pattern = re.compile('^_cached_\\w*_mapping$')

generator_attrs = ['_Generator__config', '_Generator__format_token', '_global_seed', '_is_seeded', 'add_provider', 'del_arguments', 'format', 'get_arguments', 'get_formatter', 'get_providers', 'parse', 'provider', 'set_arguments', 'set_formatter']

property unique: UniqueProxy

property optional: OptionalProxy

classmethod seed(seed: int | float | str | bytes | bytearray | None = None) → None

Hashables the shared random.Random object across all factories

Parameters:

seed – seed value

seed_instance(seed: int | float | str | bytes | bytearray | None = None) → None

Creates and seeds a new random.Random object for each factory

Parameters:

seed – seed value

seed_locale(locale: str, seed: int | float | str | bytes | bytearray | None = None) → None

Creates and seeds a new random.Random object for the factory of the specified locale

Parameters:

• locale – locale string

• seed – seed value

property random: Random

Proxies random getter calls

In single locale mode, this will be proxied to the random getter of the only internal Generator object. Subclasses will have to implement desired behavior in multiple locale mode.

property locales: list[str]

property weights: list[int | float] | None

property factories: list[Generator | Randum]

items() → list[tuple[str, Generator | Randum]]

Factory

class randum.factory.Factory

Bases: object

classmethod create(locale: str | None = None, providers: List[str] | None = None, generator: Generator | None = None, includes: List[str] | None = None, use_weighting: bool = True, **config: Any) → Generator

Generator

class randum.generator.Generator(**config: Dict)

Bases: object

add_provider(provider: BaseProvider | Type[BaseProvider]) → None

provider(name: str) → BaseProvider | None

get_providers() → List[BaseProvider]

Returns added providers.

property random: Random

seed_instance(seed: int | float | str | bytes | bytearray | None = None) → Generator

Calls random.seed

classmethod seed(seed: int | float | str | bytes | bytearray | None = None) → None

format(formatter: str, *args: Any, **kwargs: Any) → str

This is a secure way to make a fake from another Provider.

get_formatter(formatter: str) → Callable

set_formatter(name: str, formatter: Callable) → None

This method adds a provider method to generator. Override this method to add some decoration or logging stuff.

set_arguments(group: str, argument: str, value: Any | None = None) → None

Creates an argument group, with an individual argument or a dictionary of arguments. The argument groups is used to apply arguments to tokens, when using the generator.parse() method. To further manage argument groups, use get_arguments() and del_arguments() methods.

generator.set_arguments(‘small’, ‘max_value’, 10) generator.set_arguments(‘small’, {‘min_value’: 5, ‘max_value’: 10})

get_arguments(group: str, argument: str | None = None) → Any

Get the value of an argument configured within a argument group, or the entire group as a dictionary. Used in conjunction with the set_arguments() method.

generator.get_arguments(‘small’, ‘max_value’) generator.get_arguments(‘small’)

del_arguments(group: str, argument: str | None = None) → Any

Delete an argument from an argument group or the entire argument group. Used in conjunction with the set_arguments() method.

generator.del_arguments(‘small’) generator.del_arguments(‘small’, ‘max_value’)

parse(text: str) → str

Replaces tokens like ‘{{ tokenName }}’ or ‘{{tokenName}}’ in a string with the result from the token method call. Arguments can be parsed by using an argument group. For more information on the use of argument groups, please refer to the set_arguments() method.

Example:

generator.set_arguments(‘red_rgb’, {‘hue’: ‘red’, ‘color_format’: ‘rgb’}) generator.set_arguments(‘small’, ‘max_value’, 10)

generator.parse(‘{{ color:red_rgb }} - {{ pyint:small }}’)

Providers

class randum.providers.BaseProvider(generator: Any)

Bases: object

language_locale_codes = {'aa': ('DJ', 'ER', 'ET'), 'af': ('ZA',), 'ak': ('GH',), 'am': ('ET',), 'an': ('ES',), 'apn': ('IN',), 'ar': ('AE', 'BH', 'DJ', 'DZ', 'EG', 'EH', 'ER', 'IL', 'IN', 'IQ', 'JO', 'KM', 'KW', 'LB', 'LY', 'MA', 'MR', 'OM', 'PS', 'QA', 'SA', 'SD', 'SO', 'SS', 'SY', 'TD', 'TN', 'YE'), 'as': ('IN',), 'ast': ('ES',), 'ayc': ('PE',), 'az': ('AZ', 'IN'), 'be': ('BY',), 'bem': ('ZM',), 'ber': ('DZ', 'MA'), 'bg': ('BG',), 'bhb': ('IN',), 'bho': ('IN',), 'bn': ('BD', 'IN'), 'bo': ('CN', 'IN'), 'br': ('FR',), 'brx': ('IN',), 'bs': ('BA',), 'byn': ('ER',), 'ca': ('AD', 'ES', 'FR', 'IT'), 'ce': ('RU',), 'ckb': ('IQ',), 'cmn': ('TW',), 'crh': ('UA',), 'cs': ('CZ',), 'csb': ('PL',), 'cv': ('RU',), 'cy': ('GB',), 'da': ('DK',), 'de': ('AT', 'BE', 'CH', 'DE', 'LI', 'LU'), 'doi': ('IN',), 'dv': ('MV',), 'dz': ('BT',), 'el': ('GR', 'CY'), 'en': ('AG', 'AU', 'BD', 'BW', 'CA', 'DK', 'GB', 'HK', 'IE', 'IN', 'NG', 'NZ', 'PH', 'PK', 'SG', 'US', 'ZA', 'ZM', 'ZW', 'KE'), 'eo': ('US',), 'es': ('AR', 'BO', 'CL', 'CO', 'CR', 'CU', 'DO', 'EC', 'ES', 'GT', 'HN', 'MX', 'NI', 'PA', 'PE', 'PR', 'PY', 'SV', 'US', 'UY', 'VE'), 'et': ('EE',), 'eu': ('ES', 'FR'), 'fa': ('IR',), 'ff': ('SN',), 'fi': ('FI',), 'fil': ('PH',), 'fo': ('FO',), 'fr': ('CA', 'CH', 'FR', 'LU'), 'fur': ('IT',), 'fy': ('NL', 'DE'), 'ga': ('IE',), 'gd': ('GB',), 'gez': ('ER', 'ET'), 'gl': ('ES',), 'gu': ('IN',), 'gv': ('GB',), 'ha': ('NG',), 'hak': ('TW',), 'he': ('IL',), 'hi': ('IN',), 'hne': ('IN',), 'hr': ('HR',), 'hsb': ('DE',), 'ht': ('HT',), 'hu': ('HU',), 'hy': ('AM',), 'ia': ('FR',), 'id': ('ID',), 'ig': ('NG',), 'ik': ('CA',), 'is': ('IS',), 'it': ('CH', 'IT'), 'iu': ('CA',), 'iw': ('IL',), 'ja': ('JP',), 'ka': ('GE',), 'kk': ('KZ',), 'kl': ('GL',), 'km': ('KH',), 'kn': ('IN',), 'ko': ('KR',), 'kok': ('IN',), 'ks': ('IN',), 'ku': ('TR',), 'kw': ('GB',), 'ky': ('KG',), 'lb': ('LU',), 'lg': ('UG',), 'li': ('BE', 'NL'), 'lij': ('IT',), 'ln': ('CD',), 'lo': ('LA',), 'lt': ('LT',), 'lv': ('LV',), 'lzh': ('TW',), 'mag': ('IN',), 'mai': ('IN',), 'mg': ('MG',), 'mhr': ('RU',), 'mi': ('NZ',), 'mk': ('MK',), 'ml': ('IN',), 'mn': ('MN',), 'mni': ('IN',), 'mr': ('IN',), 'ms': ('MY',), 'mt': ('MT',), 'my': ('MM',), 'nan': ('TW',), 'nb': ('NO',), 'nds': ('DE', 'NL'), 'ne': ('NP',), 'nhn': ('MX',), 'niu': ('NU', 'NZ'), 'nl': ('AW', 'BE', 'NL'), 'nn': ('NO',), 'nr': ('ZA',), 'nso': ('ZA',), 'oc': ('FR',), 'om': ('ET', 'KE'), 'or': ('IN',), 'os': ('RU',), 'pa': ('IN', 'PK'), 'pap': ('AN', 'AW', 'CW'), 'pl': ('PL',), 'ps': ('AF',), 'pt': ('BR', 'PT'), 'quz': ('PE',), 'raj': ('IN',), 'ro': ('RO',), 'ru': ('RU', 'UA'), 'rw': ('RW',), 'sa': ('IN',), 'sat': ('IN',), 'sc': ('IT',), 'sd': ('IN', 'PK'), 'se': ('NO',), 'shs': ('CA',), 'si': ('LK',), 'sid': ('ET',), 'sk': ('SK',), 'sl': ('SI',), 'so': ('DJ', 'ET', 'KE', 'SO'), 'sq': ('AL', 'ML'), 'sr': ('ME', 'RS'), 'ss': ('ZA',), 'st': ('ZA',), 'sv': ('FI', 'SE'), 'sw': ('KE', 'TZ'), 'szl': ('PL',), 'ta': ('IN', 'LK'), 'tcy': ('IN',), 'te': ('IN',), 'tg': ('TJ',), 'th': ('TH',), 'the': ('NP',), 'ti': ('ER', 'ET'), 'tig': ('ER',), 'tk': ('TM',), 'tl': ('PH',), 'tn': ('ZA',), 'tr': ('CY', 'TR'), 'ts': ('ZA',), 'tt': ('RU',), 'ug': ('CN',), 'uk': ('UA',), 'unm': ('US',), 'ur': ('IN', 'PK'), 'uz': ('UZ',), 've': ('ZA',), 'vi': ('VN',), 'wa': ('BE',), 'wae': ('CH',), 'wal': ('ET',), 'wo': ('SN',), 'xh': ('ZA',), 'yi': ('US',), 'yo': ('NG',), 'yue': ('HK',), 'zh': ('CN', 'HK', 'SG', 'TW'), 'zu': ('ZA',)}

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() → 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() → 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: 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.

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: 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
)

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

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

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

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

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

Sample:

text=’Random Identifier: ??????????’

Sample:

text=’Random Identifier: ??????????’, letters=’ABCDE’

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.

Sample:

letters=’ABCDE’

Sample:

text=’Product Number: ????-########’

Sample:

text=’Product Number: ????-########’, letters=’ABCDE’

Sample:

text=’Order: ##??-$’

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

class randum.providers.DynamicProvider(provider_name: str, elements: List | None = None, generator: Any | None = None)

Bases: BaseProvider

add_element(element: str) → None

Add new element.

get_random_value(use_weighting: bool = True) → Any

Returns a random value for this provider.

Parameters:

use_weighting – boolean option to use weighting. Defaults to True

Exceptions

exception randum.exceptions.BaseFakerException

Bases: Exception

The base exception for all Faker exceptions.

exception randum.exceptions.UniquenessException

Bases: BaseFakerException

To avoid infinite loops, after a certain number of attempts, the “unique” attribute of the Proxy will throw this exception.

exception randum.exceptions.UnsupportedFeature(msg: str, name: str)

Bases: BaseFakerException

The requested feature is not available on this system.