fabulist module — fabulist 1.2.0 documentation

# 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`

  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)

    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)

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

    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)

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

    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)

    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)

    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)

    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)

    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)

    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`()

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

class `fabulist.fabulist.` `_WordList`(path)

  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)

    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

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

  `apply_macro`(macro, entry)

    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.

  `csv_format` = None

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

  `extra_modifiers` = None

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

  `form_modifiers` = None

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

  `get_random_entry`(macro)

    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)

    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)

    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`()

    Update internal structures after entries have been added or modified.

  `word_type` = None

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