fabulist module¶

class AdjList(path: str)[source]¶

Bases: _WordList

Implement a collection of adjectives.

Parameters:: path (str) – Path to CSV source file (loaded on demand or when _WordList.load()) is called.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

The entry argument should have the same keys as the current CSV file format (see csv_format). If entry values are omitted or None, they are passed to _process_entry() in order to compute a default. If entry values are set to False, they are considered ‘not available’. For example There is no plural form of ‘information’.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = frozenset({'an', 'antonym', 'comp', 'lemma', 'super'})¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({'comp', 'super'})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma', 'comp', 'super', 'antonym', 'tags')¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = frozenset({'an'})¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = frozenset({'antonym', 'comp', 'lemma', 'super'})¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

The resulting CSV file has the format as defined in csv_format. For better compression, word forms that are computable are stored as empty strings (‘’). Comments from the original file are retained at the top.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = 'adj'¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

class AdvList(path: str)[source]¶

Bases: _WordList

Implement a collection of adverbs.

Parameters:: path (str) – Path to CSV source file (loaded on demand or when _WordList.load()) is called.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = frozenset({'an', 'antonym', 'comp', 'lemma', 'super'})¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({'comp', 'super'})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma', 'comp', 'super', 'antonym', 'tags')¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = frozenset({'an'})¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = frozenset({'antonym', 'comp', 'lemma', 'super'})¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = 'adv'¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

exception ApplyTemplateError[source]¶

Bases: RuntimeError

Raised when a template could not be resolved.

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

class Fabulist[source]¶

Bases: object

Random string factory.

list_map¶

Dictionary with one _WordList entry per word-type.

Type:: list

lorem¶

Type:: fabulist.lorem_ipsum.LoremGenerator

generate_quotes(template: str | list[str], *, count: int | None = None, dedupe: bool | None = False) → Iterator[str][source]¶

Return a generator for random strings.

Parameters:

template (str | str[]) – A string template with embedded macros, e.g. “Hello $(name:mr)!”. If a list of strings are passed, a random template is chosen.
count (int, optional) – Number of results to generate. Pass None for infinite. Default: None.
dedupe (bool | set, optional) – Pass True to prevent duplicate results. If a set instance is passed, it will be used to add and check for generated entries. Default: False.

Yields:

str – Random variants of template.

get_choice(modifiers: str, *, context: dict | None = None) → str[source]¶

Return a random entry from a list of values.

Parameters:

modifiers (str) – Additional modifiers, separated by ‘:’. Only one modifier is accepted with a comma separated list of choices. If a single string is passed (i.e. no comma), one random character is returned. Use a backslash to escape comma or colons.
context (dict, optional) – Used internally to cache template results for back-references.

Returns:

str – A randomly selected value.

Examples

fab.get_choice(“foo,bar,baz”) fab.get_choice(“$%?!”) fab.get_choice(“$%?!:,”)

Return one random paragraph.

See also fabulist.lorem_ipsum.LoremGenerator for more flexible and efficient generators (accessible as Fabulist.lorem).

Parameters:

sentence_count (int or tuple(min, max)) – Number of sentences. Default: (2, 6).
dialect (str, optional) – For example “ipsum”, “pulp”, “trappatoni”. Pass None to pick a random dialect. Default: “ipsum” (i.e. lorem-ipsum).
entropy (int) – 0: iterate sentences from original text 1: pick a random paragraph, then use it literally 2: pick a random sentence, then use it literally 3: pick random words Default: 2.
keep_first (bool, optional) – Always return the first sentence as first result. Default: False.
words_per_sentence (int or tuple(min, max), optional) – Number of words per sentence. This argument is only used for entropy=3. Default: (3, 15).

Returns:

str – One paragraph made of random sentences.

get_lorem_sentence(word_count: int | tuple[int, int] | None = (3, 15), *, dialect: str | None = 'ipsum', entropy: int | None = 3) → str[source]¶

Return one random sentence.

See also fabulist.lorem_ipsum.LoremGenerator for more flexible and efficient generators (accessible as Fabulist.lorem).

Parameters:

word_count (int or tuple(min, max), optional) – Tuple with (min, max) number of words per sentence. This argument is only used for entropy=3. Default: (3, 15).
dialect (str, optional) – For example “ipsum”, “pulp”, “trappatoni”. Pass None to pick a random dialect. Default: “ipsum” (i.e. lorem-ipsum).
entropy (int) – 0: use first sentence from original text 1: pick a random paragraph, then use the first sentence 2: pick a random sentence 3: mix random words Default: 3.

Returns:

str – One random sentence.

Generate a number of paragraphs, made up from random sentences.

Paragraphs are seperated by newline.

See also fabulist.lorem_ipsum.LoremGenerator for more flexible and efficient generators (accessible as Fabulist.lorem).

Parameters:

para_count (int or tuple(min, max)) – Number of paragraphs.
dialect (str, optional) – For example “ipsum”, “pulp”, “trappatoni”. Pass None to pick a random dialect. Default: “ipsum”.
keep_first (bool, optional) – Always return the first sentence as first result. Default: False.
entropy (int) – 0: iterate sentences from original text 1: pick a random paragraph, then use it literally 2: pick a random sentence, then use it literally 3: pick random words Default: 2.
words_per_sentence (tuple(int, int), optional) – Tuple with (min, max) number of words per sentence. This argument is only used for entropy=3. Default: (3, 15).
sentences_per_para (tuple(int, int), optional) – Tuple with (min, max) number of sentences per paragraph. Default: (2, 6).

Returns:

str – Text made of one or more paragraphs.

get_lorem_words(count: int | None = None, *, dialect: str | None = 'ipsum', entropy: int | None = 3, keep_first: bool | None = False) → list[str][source]¶

Return a list of random words.

See also fabulist.lorem_ipsum.LoremGenerator for more flexible and efficient generators (accessible as Fabulist.lorem).

Parameters:

count (int, optional) – Number of words. Pass None for infinite. Default: None.
dialect (str, optional) – For example “ipsum”, “pulp”, “trappatoni”. Pass None to pick a random dialect. Default: “ipsum” (i.e. lorem-ipsum).
entropy (int, optional) – 0: iterate words from original text 1: pick a random paragraph, then use it literally 2: pick a random sentence, then use it literally 3: pick random words Default: 3.
keep_first (bool, optional) – Always return the words of the first sentence as first result. Default: False.

Returns:

list[str]

get_name(modifiers: str | None = None, *, context: dict | None = None) → str[source]¶

Return a single name string.

This is a convenience variant of get_word() with word_type=”name”.

Parameters:

modifiers (str, optional) – Additional modifiers, separated by ‘:’. Default: “”.
context (dict, optional) – Used internally to cache template results for back-references.

Returns:

str – A random name of the requested form.

get_number(modifiers: str | None = None, *, context: dict | None = None) → str[source]¶

Return a string-formatted random number.

Parameters:

modifiers (str) – Additional modifiers, separated by ‘:’. Only one modifier is accepted with a comma separated list of min, max, and width. Example: “0,99,2”.
context (dict, optional) – Used internally to cache template results for back-references.

Returns:

str – A random number matching in the requested range.

Examples

fab.get_number(“0,999,3”)

get_quote(template: str | list[str]) → str[source]¶

Return a single random string.

This is a convenience variant of generate_quotes().

Parameters:: template (str | str[]) – A string template with embedded macros, e.g. “Hello $(name:mr)!”. If a list of strings are passed, a random template is chosen.
Returns:: str – A random variant of template.

get_word(word_type: str, modifiers: str | None = None, *, context: dict | None = None) → str[source]¶

Return a random word.

Parameters:

word_type (str) – For example ‘adj’, ‘adv’, ‘name’, ‘noun’, ‘verb’.
modifiers (str, optional) – Additional modifiers, separated by ‘:’. Default: “”.
context (dict, optional) – Used internally to cache template results for back-references.

Returns:

str – A random word of the requested type and form.

load() → None[source]¶: Load all word lists into memory (lazy loading otherwise).

class FirstnameList(path: str)[source]¶

Bases: _WordList

List of first names, tagged by gender.

Internally used by NameList, not intended to be instantiated directly.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = None¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma', 'tags')¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = None¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = None¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None[source]¶: Update internal structures after entries have been added or modified.

word_type: str = None¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

class LastnameList(path: str)[source]¶

Bases: _WordList

List of last names.

Note

Internally used by NameList, not intended to be instantiated directly.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = None¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma',)¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = None¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = None¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = None¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

class Macro(word_type: str, modifiers: str, word_list: _WordList)[source]¶

Bases: object

Parses and represents a macro with type, modifiers, tags, and references.

Note

Internal use only.

Parameters:

word_type (str) – The word type, e.g. “adj”, “noun”, …
modifiers (str) – E.g. “plural:an”
word_list (_WordList) – The associated _WordList instance, e.g. AdvList for word_type adj.

Examples

$(TYPE:MODS:#foo|bar:=NUM)

word_type¶: lowercase word type (‘adv’, ‘adj’, …)

class NameList(path: str)[source]¶

Bases: _WordList

Implement a virtual collection of person names.

Internally uses FirstnameList and LastnameList to generate different variants.

Parameters:: path (str) – Path to CSV source file (loaded on demand or when _WordList.load()) is called.

firstname_list¶

Type:: list[FirstnameList]

lastname_list¶

Type:: list[LastnameList]

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = frozenset({'first', 'last', 'middle', 'mr'})¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str[source]¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = None¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = frozenset({'first', 'last', 'middle', 'mr'})¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = frozenset({})¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str][source]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None[source]¶: Load and add list of entries from text file.

middle_initials: str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'¶

middle_name_probability: float = 0.5¶

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = 'name'¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

class NounList(path: str)[source]¶

Bases: _WordList

Implement a collection of nouns.

Parameters:: path (str) – Path to CSV source file (loaded on demand or when _WordList.load()) is called.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = frozenset({'an', 'lemma', 'plural'})¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({'plural'})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma', 'plural', 'tags')¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = frozenset({'an'})¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = frozenset({'lemma', 'plural'})¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = 'noun'¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

TWordListEntry¶

A dictionary with a ‘lemma’ and additional values, depending on the wordlist type.

alias of dict[str, str]

class VerbList(path: str)[source]¶

Bases: _WordList

Implement a collection of verbs.

Parameters:: path (str) – Path to CSV source file (loaded on demand or when _WordList.load()) is called.

add_entry(entry: dict[str, str]) → None¶

Add a single entry to the word list.

Callers should also call update_data() later, to make sure that key_list is up-to-date.

Parameters:: entry (dict) – Word data.

all_modifiers: frozenset = frozenset({'an', 'ing', 'lemma', 'past', 'pp', 's'})¶

Set of all supported modifiers (word-form and additional). Set by derived classes.

Type:: frozenset

apply_macro(macro: Macro, entry: dict[str, str]) → str¶

Return a word-form for an entry dict, according to macro modifiers.

Parameters:

macro (Macro) – The parsed macro instance.
entry (dict) – Dict of word forms as stored in data.

Returns:

str – The requested word form.

computable_modifiers: frozenset = frozenset({'ing', 'pp', 's'})¶

Set of word forms that can potentially be computed from a lemma (e.g. {‘ing’, ‘s’, …}). Set by derived classes.

Type:: frozenset

csv_format: tuple = ('lemma', 'past', 'pp', 's', 'ing', 'tags')¶

Ordered list of CSV file columns (e.g. (‘lemma’, ‘plural’, ‘tags’)). Set by derived classes.

Type:: tuple

extra_modifiers: frozenset = frozenset({'an'})¶

Set of supported additional modifiers (e.g. {‘an’}). Set by derived classes.

Type:: frozenset

form_modifiers: frozenset = frozenset({'ing', 'lemma', 'past', 'pp', 's'})¶

Set of supported word form modifiers (e.g. {‘plural’}). Set by derived classes.

Type:: frozenset

get_random_entry(macro: Macro) → dict[str, str]¶

Return a random entry dict, according to modifiers.

Parameters:: macro (Macro) – A parsed template macro.
Returns:: dict – A random entry from key_list.

load(path: str | None = None) → None¶

Load and add list of entries from text file.

Normally, we don’t have to call this method explicitly, because entries are loaded lazily on demand. It may be useful however to add supplemental word lists however.

This method also calls update_data().

Parameters:: path (str, optional) – path to CSV file. Defaults to path.

save_as(path: str) → None¶

Write current data to a text file.

Parameters:: path (str) – path to CSV file.

update_data() → None¶: Update internal structures after entries have been added or modified.

word_type: str = 'verb'¶

Type of word list (e.g. ‘adj’, ‘adv’, …). Set by derived classes.

Type:: str

get_default_word_form(word_form: str, lemma: str, entry: dict[str, str]) → str[source]¶

Use standard rules to compute a word form for a given lemma.

Parameters:

word_form (str) – Requested word form, e.g. ‘plural’, ‘ing’, …
lemma (str) – The word’s base form.
entry (dict) – Word’s data as stored in _WordList.data.

Returns:

str – The computed word form.