fabulist module

(c) 2017 Martin Wendt; see https://github.com/mar10/fabulist Licensed under the MIT license: http://www.opensource.org/licenses/mit-license.php

class fabulist.fabulist.Fabulist[source]

Bases: object

Random string factory.

list_map

list – Dictionary with one _WordList entry per word-type.

lorem

fabulist.lorem_ipsum.LoremGenerator

generate_quotes(template, count=None, dedupe=False)[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, context=None)[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(“$%?!:,”)

get_lorem_paragraph(sentence_count=(2, 6), dialect='ipsum', entropy=2, keep_first=False, words_per_sentence=(3, 15))[source]

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=(3, 15), dialect='ipsum', entropy=3)[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.
get_lorem_text(para_count, dialect='ipsum', entropy=2, keep_first=False, words_per_sentence=(3, 15), sentences_per_para=(2, 6))[source]

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=None, dialect='ipsum', entropy=3, keep_first=False)[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=None, context=None)[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=None, context=None)[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)[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, modifiers=None, context=None)[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()[source]

Load all word lists into memory (lazy loading otherwise).

class fabulist.fabulist._WordList(path)[source]

Bases: object

Common base class for all word lists.

Note

This class is not instantiated directly, but provides common implementations for reading, writing and processing of word list data.

Parameters:path (str) – Location of dictionary csv file.
path

str – Location of dictionary csv file.

data

dict – Maps word lemmas to dicts of word data (i.e. word-forms).

key_list

list – List of all known word lemmas.

tag_map

dict – Maps tag names to sets of word lemmas.

add_entry(entry)[source]

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 = None
apply_macro(macro, entry)[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([])
csv_format = None
extra_modifiers = None
form_modifiers = None
get_random_entry(macro)[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=None)[source]

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)[source]

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()[source]

Update internal structures after entries have been added or modified.

word_type = None