evennia.contrib.utils.random_string_generator.random_string_generator

Pseudo-random generator and registry

Evennia contribution - Vincent Le Goff 2017

This contrib can be used to generate pseudo-random strings of information with specific criteria. You could, for instance, use it to generate phone numbers, license plate numbers, validation codes, non-sensivite passwords and so on. The strings generated by the generator will be stored and won’t be available again in order to avoid repetition. Here’s a very simple example:

from evennia.contrib.utils.random_string_generator import RandomStringGenerator
# Create a generator for phone numbers
phone_generator = RandomStringGenerator("phone number", r"555-[0-9]{3}-[0-9]{4}")
# Generate a phone number (555-XXX-XXXX with X as numbers)
number = phone_generator.get()
# **number** will contain something like: "555-981-2207"
# If you call **phone_generator.get**, it won't give the same anymore.phone_generator.all()
# Will return a list of all currently-used phone numbers
phone_generator.remove("555-981-2207")
# The number can be generated again

To use it, you will need to:

1. Import the RandomStringGenerator class from the contrib.

2. Create an instance of this class taking two arguments: - The name of the gemerator (like “phone number”, “license plate”…). - The regular expression representing the expected results.

3. Use the generator’s all, get and remove methods as shown above.

To understand how to read and create regular expressions, you can refer to [the documentation on the re module](https://docs.python.org/2/library/re.html). Some examples of regular expressions you could use:

• r”555-d{3}-d{4}”: 555, a dash, 3 digits, another dash, 4 digits.

• r”[0-9]{3}[A-Z][0-9]{3}”: 3 digits, a capital letter, 3 digits.

• r”[A-Za-z0-9]{8,15}”: between 8 and 15 letters and digits.

• …

Behind the scenes, a script is created to store the generated information for a single generator. The RandomStringGenerator object will also read the regular expression you give to it to see what information is required (letters, digits, a more restricted class, simple characters…)… More complex regular expressions (with branches for instance) might not be available.

exception evennia.contrib.utils.random_string_generator.random_string_generator.RejectedRegex

Bases: RuntimeError

The provided regular expression has been rejected.

More details regarding why this error occurred will be provided in the message. The usual reason is the provided regular expression is not specific enough and could lead to inconsistent generating.

exception evennia.contrib.utils.random_string_generator.random_string_generator.ExhaustedGenerator

Bases: RuntimeError

The generator hasn’t any available strings to generate anymore.

class evennia.contrib.utils.random_string_generator.random_string_generator.RandomStringGeneratorScript(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

The global script to hold all generators.

It will be automatically created the first time generate is called on a RandomStringGenerator object.

at_script_creation()

Hook called when the script is created.

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.contrib.utils.random_string_generator.random_string_generator.RandomStringGeneratorScript'

typename = 'RandomStringGeneratorScript'

class evennia.contrib.utils.random_string_generator.random_string_generator.RandomStringGenerator(name, regex)

Bases: object

A generator class to generate pseudo-random strings with a rule.

The “rule” defining what the generator should provide in terms of string is given as a regular expression when creating instances of this class. You can use the all method to get all generated strings, the get method to generate a new string, the remove method to remove a generated string, or the clear method to remove all generated strings.

Bear in mind, however, that while the generated strings will be stored to avoid repetition, the generator will not concern itself with how the string is stored on the object you use. You probably want to create a tag to mark this object. This is outside of the scope of this class.

script = None

__init__(name, regex)

Create a new generator.

Parameters

• name (str) – name of the generator to create.

• regex (str) – regular expression describing the generator.

Notes

name should be an explicit name. If you use more than one generator in your game, be sure to give them different names. This name will be used to store the generated information in the global script, and in case of errors.

The regular expression should describe the generator, what it should generate: a phone number, a license plate, a password or something else. Regular expressions allow you to use pretty advanced criteria, but be aware that some regular expressions will be rejected if not specific enough.

Raises

• RejectedRegex – the provided regular expression couldn’t be

• accepted as a valid generator description. –

all()

Return all generated strings for this generator.

Returns

strings (list of strr) – the list of strings that are already used. The strings that were generated first come first in the list.

get(store=True, unique=True)

Generate a pseudo-random string according to the regular expression.

Parameters

• store (bool, optional) – store the generated string in the script.

• unique (bool, optional) – keep on trying if the string is already used.

Returns

The newly-generated string.

Raises

ExhaustedGenerator – if there’s no available string in this generator.

Note

Unless asked explicitly, the returned string can’t repeat itself.

remove(element)

Remove a generated string from the list of stored strings.

Parameters

element (str) – the string to remove from the list of generated strings.

Raises

ValueError – the specified value hasn’t been generated and is not present.

Note

The specified string has to be present in the script (so has to have been generated). It will remove this entry from the script, so this string could be generated again by calling the get method.

clear()

Clear the generator of all generated strings.