SURVEY(1)

NAME
survey - survey 5.4.2 ✨ A simple library for creating beautiful interactive prompts.

    pip install survey

FEATURES

•   Pythonic: Friendly interface built around simple functions.

•   Lightweight: No external depencencies for any operating system.

•   Adaptable: Works with any string formatting and window size.

•   Extensive: Packed with tweaks and features for any situation.

•   Complete: Supports Windows 10 (Anniversary Update and up).

SHOWCASE
[image: Cybersecurity Rotuine] [image] Cybersecurity Inspector Prompting Routine.UNINDENT [image: TribalWars Map] [image] Map Traversal of en130.tribalswars.net.UNINDENT

  Reference

The specifics of the library.

  Routines

Functions that use Widgets within a stage.get visual and respond with the formated result, before returning it upon submission.

survey.routines.input(*args, reply=<function _input_reply>, **kwargs)
    Use an Input widget.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.input' [image]

        value = survey.routines.input('ping? ')
        print(f'Answered {value}.')
    [image]

        limit = 50
        def info(widget, name, info):
            result = widget.resolve().rstrip('\n')
            remain = limit - len(result)
            if remain < 0:
                raise survey.widgets.Abort('no characters left')
            return str(remain)
        value = survey.routines.input('Limited Message: ', multi = True, info = info)
        print(f'Answered with {len(value)} characters.')

survey.routines.conceal(*args, reply=<function _conceal_reply>, **kwargs)
    Use an Conceal widget.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.conceal' [image]

        value = survey.routines.conceal('Password: ')
        print(f'Answered {value}.')

survey.routines.numeric(*args, reply=<function _numeric_reply>, **kwargs)
    Use an Count widget.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.numeric' [image]

        value = survey.routines.numeric('Price: ')
        print(f'Answered {value}.')
    [image]

        value = survey.routines.numeric('Age: ', decimal = False)
        print(f'Answered {value}.')

survey.routines.inquire(*args, default_color=<fg:cyan>, reply=<function _inquire_reply>, **kwargs)
    Use an Inquire widget.

Parameters

•   options -- The keys are used as widgets.Inquire.options. The resolving key's value is returned.

•   default_color -- Used in the default hint for signifying the default value. The default value must be part of options' values.

    All other widget and start() arguments are valid.

    🎨 Theme with 'routines.inquire' [image]

        value = survey.routines.inquire('Save? ', default = True)
        print(f'Answered {value}.')

survey.routines.select(*args, reply=<function _select_reply>, insearch_color=<fg:red>, **kwargs)
    Use an Select widget.

Parameters
    insearch_color -- Color for when _widgets.BaseMesh.permit is True and the search is invalid or incosequential.

    The default hint shows available controls.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.select' [image]

        colors = ('red', 'green', 'blue', 'pink', 'silver', 'magenta')
        index = survey.routines.select('Pick a color: ', options = colors)
        print(f'Answered {index}.')
    [image]

        names = map(''.join, itertools.combinations('AXBYCZ', 3))
        index = survey.routines.select('Favorite names? ',  options = names,  focus_mark = '~ ',  evade_color = survey.colors.basic('yellow'))
        print(f'Answered {index}.')

survey.routines.basket(*args, reply=<function _basket_reply>, insearch_color=<fg:red>, **kwargs)
    Use an Basket widget.

Parameters
    insearch_color -- Color for when _widgets.BaseMesh.permit is True and the search is invalid or incosequential.

    The default hint shows available controls.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.basket' [image]

        days = ('Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday')
        indexes = survey.routines.basket('Favourite days? ', options = days)
        print(f'Answered {indexes}.')
    [image]

        names = tuple(map(''.join, itertools.combinations('AXBYCZ', 3)))
        def scout(spot):
            index = spot[0]
            name = names[index]
            return not 'C' in name
        index = survey.routines.basket('Favorite names? ', options = names, scout = scout,  evade_mark = '__', focus_color = survey.colors.basic('magenta'), positive_mark = 'O ', negative_mark = 'X ')
        print(f'Answered {index}.')

survey.routines.datetime(*args, reply=<function _datetime_reply>, **kwargs)
    Use an DateTime widget.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.datetime' [image]

        datetime = survey.routines.datetime('Schedule At: ')
        print(f'Answered {datetime}.')
    [image]

        datetime = survey.routines.datetime('Meeting Time: ', attrs = ('hour', 'minute'))
        print(f'Answered {datetime}.')

survey.routines.form(*args, reply=<function _form_reply>, **kwargs)
    Use an Form widget.

    The default hint shows available controls, including of focused widgets.

    All widget and start() arguments are valid.

    🎨 Theme with 'routines.form' [image]

        form = {
            'name': survey.widgets.Input(),
            'price': survey.widgets.Count(),
            'type': survey.widgets.Select(options = ('food', 'stationary', 'tobacco', 'literature'))
        }
        data = survey.routines.form('Item Data: ', form = form)

  Printers

Functions that print to the console with optional sentiment using marks.

survey.printers.text(*values, sep=' ', end='\\n', re=False)
    Print a plain value. Works similar to print() <https://docs.python.org/3/library/functions.html#print>.

Parameters

•   values -- Used to create the final value by mapping all with str() and concatenating with text.sep.

•   end (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Appended to the end of the final value.

•   re (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to return the cursor to the last saved position before printing.

survey.printers.info(*values, mark='!', mark_color=<fg:cyan>, **kwargs)
    Print a value denoting information.

Parameters

•   values -- Same as text.value.

•   mark (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Prepended to the final value.

•   mark_color (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used to color info.mark with.

    Additional arguments are passed to text().

    🎨 Theme with printers.info. [image]

survey.printers.done(*values, mark='✔', mark_color=<fg:green>, **kwargs)
    Print a value denoting success.

Parameters

•   values -- Same as text.value.

•   mark (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Prepended to the final value.

•   mark_color (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used to color info.mark with.

    Additional arguments are passed to text().

    🎨 Theme with printers.done. [image]

survey.printers.fail(*values, mark='✘', mark_color=<fg:red>, **kwargs)
    Print a value denoting failure.

Parameters

•   values -- Same as text.value.

•   mark (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Prepended to the final value.

•   mark_color (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used to color info.mark with.

    Additional arguments are passed to text().

    🎨 Theme with printers.fail. [image]

  Graphics

Classes for printing data that can change over time.

class survey.graphics.SpinProgress(*args, runes=('|', '/', '—', '\\\\'), **kwargs)
    Bases: Graphic

    A spinner indicating work of undeterminable size.

Parameters
    runes (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The characters to cycle through on every print.

        state = None
        with survey.graphics.SpinProgress(prefix = 'Loading ', suffix = lambda self: state, epilogue = 'Done!') as progress:
            for state in (state, ' calculating...', ' molding...', ' redering...'):
                time.sleep(2)

    🎨 Theme with graphics.SpinProgress. [image]

class survey.graphics.MultiLineProgress(controls, *args, width=50, empty=' ', prefix=<function _get_MultiLineProgress_prefix>, suffix=<function _get_MultiLineProgress_suffix>, prefix_wall='|', suffix_wall='|', **kwargs)
    Bases: Graphic

    A manager for progress controls.

Parameters

•   controls (List <https://docs.python.org/3/library/typing.html#typing.List>[MultiLineProgressControl]) -- The controls to manage.

•   width (int <https://docs.python.org/3/library/functions.html#int>) -- The default width for each line.

•   empty (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune to fill empty space with.

•   prefix_wall (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Added before the line.

•   prefix_wall -- Added after the line.

        total = 1600
        controls = [
            survey.graphics.MultiLineProgressControl(total, color = survey.colors.basic('blue' ), epilogue = 'done!'),
            survey.graphics.MultiLineProgressControl(total, color = survey.colors.basic('red'  )),
            survey.graphics.MultiLineProgressControl(total, color = survey.colors.basic('green'), epilogue = lambda context: 'dynamic done!')
        ]
        # lower-index controls take longer to iterate, but speed up as the higher-index controls complete
        with survey.graphics.MultiLineProgress(controls, prefix = 'Loading '):
            for _ in range(total):
                for index, control in enumerate(controls, start = 1):
                    if control.value >= total:
                        continue
                    for _ in range(index):
                        control.move(1)
                        time.sleep(0.01)

    🎨 Theme with graphics.MultiLineProgress [image]

property controls: List <https://docs.python.org/3/library/typing.html#typing.List>[MultiLineProgressControl <#survey.graphics.MultiLineProgressControl>]
    The internal controls.

    Can be modified in any way at any time.

class survey.graphics.MultiLineProgressControl(total, value=0, runes=('━',), color=None, suffix='{value}/{total}{total_unit} {speed}{speed_unit}/s {remain}', epilogue=None, denominate=None)
    Bases: object <https://docs.python.org/3/library/functions.html#object>

    A line indicating the progress of work of a certain size.

Parameters

•   total (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- The maximum expected amount of the internal value.

•   value (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- The initial value.

•   runes (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The runes to cycle through for subdivisions of a character.

•   color (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The color of the line.

•   suffix (str <https://docs.python.org/3/library/stdtypes.html#str> | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[MultiLineProgressControl], str <https://docs.python.org/3/library/stdtypes.html#str>]) --

    Added after the line. The following placeholders may be used:

•   value is the current value.

•   total is total.

•   total_unit is from denominate on total.

•   speed is the known moving rate of the value.

•   speed_unit is from denominate on speed.

•   remain is the known time left until completion.

•   elapse is the time spent since the first move.

•   epilogue (str <https://docs.python.org/3/library/stdtypes.html#str> | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[MultiLineProgressControl], str <https://docs.python.org/3/library/stdtypes.html#str>]) -- Used after the value has reached the total instead of the suffix.

•   denominate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[float <https://docs.python.org/3/library/functions.html#float>, str <https://docs.python.org/3/library/stdtypes.html#str>]] | None <https://docs.python.org/3/library/constants.html#None>) --

    Used to determine the desired denomination of the value (and speed) and its respective unit.

    For example, if speed is '1000 KB/s', then denominate(1000) may return (1000, 'MB') so that speed is shown as 1000/1000 -> '1 MB/s'

    🎨 Theme with .graphics.MultiLineProgressControl

get_info()
    Get the current info text.

    Will be an empty string if the internal deque is empty

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

get_line(width)
    Get the current line text.

Parameters
    width (int <https://docs.python.org/3/library/functions.html#int>) -- The maximum amount of allowed characters.

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

property init_time
    The time spot of the first value.

property last_time
    The time spot of the final value.

move(size)
    Move the internal value.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- The amount to move it by.

property total: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>
    The total value.

property value: int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>
    The current value.

class survey.graphics.LineProgress(total, *args, **kwargs)
    Bases: MultiLineProgress

    A simple line progress with one internal control.

Parameters
    total (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- The total expected value.

        total = 1600
        numbers = list(range(total))
        for number in survey.graphics.LineProgress.from_iterable(numbers, prefix = 'Loading ', epilogue = 'done!'):
            time.sleep(0.01)

        total = 1600
        numbers = list(range(total))
        with survey.graphics.LineProgress(len(numbers), prefix = 'Loading ', epilogue = 'done!') as progress:
            for number in numbers:
                time.sleep(0.01)
                progress.move(1)

    🎨 Theme with graphics.LineProgress [image]

classmethod from_iterable(iterable, *args, total=None, count=None, **kwargs)
    Yields values from the iterable and displays the progress to completion.

Parameters

•   iterable (Container <https://docs.python.org/3/library/collections.abc.html#collections.abc.Container>) -- The iterable to yield values from.

•   total (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float> | None <https://docs.python.org/3/library/constants.html#None>) -- The total of the iterable if it cannot be determined directly from it.

•   count (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>) -- Can be used to specify by how much to increase the internal value per yield (default: 1).

Raises
    TypeError <https://docs.python.org/3/library/exceptions.html#TypeError> -- The iterable does not implement __len__ and total has not been used.

classmethod from_response(response, *args, **kwargs)
    Yields chunks of data as received from the response.

move(size)
    Move the underlying control's value.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- Same as MultiLineProgressControl.move.

  Widgets

Combinations of Mutates, Visuals and Handle to create interactive units that can be resolved into expected values.

exception survey.widgets.Abort(text, **info_kwargs)
    Bases: InfoErrorMixin, Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Raised when an invokation needs to stop. May include a message.

exception survey.widgets.Escape
    Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Raised when the users pressed the Esc button.

class survey.widgets.Widget(mutate, visual, callback=None, delegate=None, validate=None, escapable=False)
    Bases: object <https://docs.python.org/3/library/functions.html#object>

    A team of mutate, handle and visual working together.

Parameters

•   mutate (Mutate) -- The underlying mutate for changing data.

•   visual (Visual) -- The underlying visual for fetching drawing information.

•   callback (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[EventType, Event], Text | Escape | Control | Sequence], None <https://docs.python.org/3/library/constants.html#None>]) -- Used as handle.Handle.callback.

•   delegate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Event], bool <https://docs.python.org/3/library/functions.html#bool>]) -- Used with (event) and decides whether to continue the invokation.

•   validate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], None <https://docs.python.org/3/library/constants.html#None>]) -- Used with (result) upon submission, forbidden by raising Abort.

invoke(event, info)
    Invoke the underlying handle.

Parameters

•   event (Event) -- Dictates the type of operation.

•   info (Text | Escape | Control | Sequence) -- Contains details used during the operation.

    Note: If delegate is provided and returns False, nothing happens.

property mutate
    The underlying mutate.

resolve()
    Get the resolved value.

sketch(*args, **kwargs)
    Get the lines and point used for rendering the widget's state.

    Additional arguments are passed to the underlying Visual.get() method.

Return type
    Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>

Returns
    The (lines, point) that can be used to draw.

survey.widgets.start(multi_pre, multi_aft, widget, show=None, mark='? ', mark_color=<fg:yellow>, info=None, info_parse=True, hint=None, hint_parse=True, site='body', reply=None)
    Start a widget and return its resolve result upon submission.

Parameters

•   multi_pre (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether the body should start on a separate line during use.

•   multi_aft (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether the reply should start on a separate line.

•   widget (Widget) -- The widget to use.

•   show (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- Printed before anything else (uncontrollable).

•   mark (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- Prepended to the show.

•   info (str <https://docs.python.org/3/library/stdtypes.html#str> | List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]] | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]] | None <https://docs.python.org/3/library/constants.html#None>) -- The info for the stage. If callable, takes (widget, event_name, event_info).

•   info_parse (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether info is given (or, if callable returns) as a str <https://docs.python.org/3/library/stdtypes.html#str> or (lines, point).

•   hint (str <https://docs.python.org/3/library/stdtypes.html#str> | List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]] | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]] | None <https://docs.python.org/3/library/constants.html#None>) -- The hint for the stage. If callable, takes (widget, event_name, event_info).

•   hint_parse (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether hint is given (or, if callable returns) as a str <https://docs.python.org/3/library/stdtypes.html#str> or (lines, point).

•   site (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Can be 'info' or 'body' to place the cursor on the info or widget body respectively.

•   reply (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Widget, Any <https://docs.python.org/3/library/typing.html#typing.Any>], str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>) -- Called upon successful submission with (widget, result). Should return a class:str that is used as a response.

Parm mark_color
    The color to paint mark with.

class survey.widgets.BaseText(lines, point, multi=False, callback=None, delegate=None, validate=None, escapable=False, funnel_enter=None, funnel_leave=None)
    Bases: Widget

    Base for text-like widgets.

Parameters

•   lines (List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]) -- Same as mutates.Text.lines.

•   point (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- Same as mutates.Text.point.

•   multi (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to support multiple lines. If so, leaving 2 empty lines submits.

•   callback (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[EventType, Event], Text | Escape | Control | Sequence], None <https://docs.python.org/3/library/constants.html#None>]) -- Same as Widget.callback.

•   delegate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Event], bool <https://docs.python.org/3/library/functions.html#bool>]) -- Same as Widget.delegate.

•   validate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], None <https://docs.python.org/3/library/constants.html#None>]) -- Same as Widget.validate.

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as visuals.Text.funnel_enter.

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as visuals.Text.funnel_leave.

class survey.widgets.Input(*args, value=auto, index=auto, **kwargs)
    Bases: BaseText

    A text editor.

    It resolves into a str <https://docs.python.org/3/library/stdtypes.html#str>.

Parameters

•   value (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Converted into BaseText.lines.

•   index (int <https://docs.python.org/3/library/functions.html#int>) -- Where to place in the cursor in relation to its position along the continous text. Converted into BaseText.point.

    Arguments directly passed to super-class:

•   lines - Created from value.

•   point - Created from index.

    🎨 Theme with 'widgets.Input'.

class survey.widgets.Numeric(*args, value=auto, decimal=False, zfill=0, invalid_value_message='invalid {name}', **kwargs)
    Bases: Input

    A text editor that only allows submission with numeric values.

    It resolves into a int <https://docs.python.org/3/library/functions.html#int> or float <https://docs.python.org/3/library/functions.html#float>.

Parameters

•   value (int <https://docs.python.org/3/library/functions.html#int>) -- Converted into Input.value.

•   decimal (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to allow (finite) decimal values.

•   zfill (int <https://docs.python.org/3/library/functions.html#int>) -- Amount of 0-fill to have.

•   invalid_value_message (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used as template to raise Abort when the value is invalid.

    Arguments directly passed to super-class:

•   value - Created from value.

    🎨 Theme with 'widgets.Numeric'.

class survey.widgets.Conceal(*args, rune='*', color=None, **kwargs)
    Bases: Input

    A text editor that replaces all characters with a rune.

    It resolves into a str <https://docs.python.org/3/library/stdtypes.html#str>.

Parameters

•   rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune to replace all others with.

•   color (int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>) -- The color to paint the rune with.

    🎨 Theme with 'widgets.Conceal'.

class survey.widgets.AutoSubmit(options, *args, transform=<method 'lower' of 'str' objects>, **kwargs)
    Bases: AutoSubmitBase

    A text editor that submits upon insertion of a valid option.

    Resolves into the respective option.

Parameters

•   options (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The possible options. Attempting to insert a rune that does not lead to an option is forbidden.

•   transform (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[str <https://docs.python.org/3/library/stdtypes.html#str>], str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used on all options and the current value when comparing.

    Arguments directly passed to super-class:

•   evaluate - Created using options.

•   validate - Created using options.

    🎨 Theme with 'widgets.AutoSubmit'.

class survey.widgets.Inquire(*args, options={'n': False, 'y': True}, default=<object object>, **kwargs)
    Bases: AutoSubmit

    A text editor that submits upon insertion of a valid option.

    Resolves into the value of the matching option.

Parameters

•   options (Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[str <https://docs.python.org/3/library/stdtypes.html#str>, Any <https://docs.python.org/3/library/typing.html#typing.Any>]) -- The possible options and their respective values.

•   default (Any <https://docs.python.org/3/library/typing.html#typing.Any>) -- Used instead when attempting to submit without an option.

    Arguments directly passed to super-class:

•   options - Created using options and default.

    🎨 Theme with 'widgets.Inquire'.

class survey.widgets.BaseMesh(tiles=auto, point=auto, create=None, search=<function fuzzy>, permit=False, clean=False, scout=None, rigid=False, focus=False, callback=None, delegate=None, validate=None, escapable=True, funnel_enter=None, funnel_leave=None)
    Bases: Widget

    A mesh traverser.

Parameters

•   search (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], Any <https://docs.python.org/3/library/typing.html#typing.Any>], int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as mutates.Mesh.score.

•   create (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as mutates.Mesh.create.

•   tiles (Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Any <https://docs.python.org/3/library/typing.html#typing.Any>]) -- Same as mutates.Mesh.tiles. Values should be Widget instances.

•   point (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- Same as mutates.Mesh.point.

•   clean (int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>) -- Same as mutates.Mesh.clean.

•   scout (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], bool <https://docs.python.org/3/library/functions.html#bool>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as mutates.Mesh.scout.

•   rigid (bool <https://docs.python.org/3/library/functions.html#bool>) -- Same as mutates.Mesh.rigid.

•   focus (bool <https://docs.python.org/3/library/functions.html#bool> | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Event], bool <https://docs.python.org/3/library/functions.html#bool>]) -- When bool <https://docs.python.org/3/library/functions.html#bool>, it is used as the initial focus state. The state can be set to True with Event.indent while unfocused, and to False by submitting the focused tile. When Callable, it is used on each invokation to determine whether to delegate it to the currently pointed-at tile instead.

•   callback (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[EventType, Event], Text | Escape | Control | Sequence], None <https://docs.python.org/3/library/constants.html#None>]) -- Same as Widget.callback.

•   delegate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Event], bool <https://docs.python.org/3/library/functions.html#bool>]) -- Same as Widget.delegate.

•   validate (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], None <https://docs.python.org/3/library/constants.html#None>]) -- Same as Widget.validate.

•   escapable (bool <https://docs.python.org/3/library/functions.html#bool>) -- Same as Widget.escapable.

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as visuals.Mesh.funnel_enter.

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as visuals.Mesh.funnel_leave.

class survey.widgets.BaseList(*args, axis=0, tiles=auto, index=0, label=None, view_max=7, focus_color=<fg:cyan>, focus_mark='> ', evade_color=None, evade_mark=' ', fill=True, delimit=None, **kwargs)
    Bases: BaseMesh

    Base for list-like widgets.

    Resolves to a int <https://docs.python.org/3/library/functions.html#int> (the pointed index).

Parameters

•   axis (int <https://docs.python.org/3/library/functions.html#int>) -- Denotes the axis across which movement is allowed.

•   tiles (List <https://docs.python.org/3/library/typing.html#typing.List>[Widget] | Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Any <https://docs.python.org/3/library/typing.html#typing.Any>]) -- Same as BaseMesh.tiles, but it can be any iterable.

•   index (int <https://docs.python.org/3/library/functions.html#int>) -- Used as the axisth element of BaseMesh.point.

•   label (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[int <https://docs.python.org/3/library/functions.html#int>], str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used as (index, tile) and returns a label to place on the right.

•   view_max (int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>) -- Maximum amount of elemnts visible at once.

•   focus_color (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The color to paint the current tile with.

•   focus_mark (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The rune to prepend to the current tile.

•   evade_color (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The color to paint the non-current tiles with.

•   evade_mark (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The rune to prepend to the non-current tiles.

•   fill (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to fill empty room.

•   delimit (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune inserted between tiles.

    Arguments directly passed to super-class:

•   tiles - Created using tiles.

•   point - Created using index.

    Warning: For the sake of matching each spot's index to it's axis-th value, vertical movement and vision are adjusted so that indexes increment downward instead of upward (which is how BaseMesh behaves normally).

class survey.widgets.Select(*args, options=auto, create=None, Option=<class 'survey._widgets.Input'>, **kwargs)
    Bases: BaseList

    A single-option selector.

Parameters

•   options (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- Converted into BaseList.tiles.

•   create (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], str <https://docs.python.org/3/library/stdtypes.html#str>] | None <https://docs.python.org/3/library/constants.html#None>) -- Same as BaseMesh.create, except returned values are converted to widgets.

•   Option (Input) -- Used to convert options and create results to tiles.

    Arguments directly passed to super-class:

•   tiles - Created using options.

•   create - Created using create.

•   focus - Set to a Callable that delegates no events.

•   delimit - Defaults to ' ' when BaseList.axis is set to 1.

    Arguments used for Option:

•   value - Set to each option upon creation.

    🎨 Theme with 'widgets.Select'.

class survey.widgets.Basket(*args, options=auto, active=auto, positive_mark='[X]', negative_mark='[ ]', Option=<class 'survey._widgets.Input'>, Stamp=<class 'survey._widgets.Select'>, **kwargs)
    Bases: BaseList

    A multi-item selector.

Parameters

•   options (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- Converted into BaseList.tiles.

•   active (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- Indexes that should be selected from the start.

•   positive_mark (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Prepended to all selected options.

•   negative_mark (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Prepended to all non-selected options.

•   Option (Input) -- Used to convert options to tiles.

•   Stamp (Select) -- Used to convert positive_mark or negative_mark to tiles.

    Arguments directly passed to super-class:

•   tiles - Created using options.

•   focus - Set to a Callable that delegates arrow events based on axis.

•   delimit - Defaults to ' ' when BaseList.axis is set to 1

    Arguments used for Option:

•   value - Set to each option upon creation.

    Arguments used for Stamp:

•   axis - Set to to the opposite of BaseList.axis.

•   options - Set to a tuple <https://docs.python.org/3/library/stdtypes.html#tuple> of negative_mark and positive_mark

•   index - Set to either 0 or 1 depending on whether the option's index is in active.

•   view_max - Set to 1.

•   focus_color - Set to None.

•   callback - Set to a Callable that handles multi-switching of marks.

    🎨 Theme with 'widgets.Basket'.

class survey.widgets.Count(*args, value=0, rate=1, decimal=None, convert=None, Numeric=<class 'survey._widgets.Numeric'>, **kwargs)
    Bases: BaseList

    An editable counter.

    Resolves to an int <https://docs.python.org/3/library/functions.html#int> (the pointed value).

Parameters

•   value (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- Initial value.

•   rate (int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>) -- Rate to move by.

•   decimal (bool <https://docs.python.org/3/library/functions.html#bool> | None <https://docs.python.org/3/library/constants.html#None>) -- Whether to only allow float <https://docs.python.org/3/library/functions.html#float> or int <https://docs.python.org/3/library/functions.html#int>.

•   convert (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>], int <https://docs.python.org/3/library/functions.html#int> | float <https://docs.python.org/3/library/functions.html#float>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used with (value) before creating a new widget.

•   Numeric (Numeric) -- Used to convert each value into a widget.

    Arguments directly passed to super-class:

•   axis - Set to 0.

•   index - Set to 0 (value is used as an offset).

•   clean - Set to True.

•   create - Created from value, rate, decimal and convert.

•   focus - Set to a Callable that delegates insert and delete_left.

•   focus_mark - Set to a None.

    Arguments used for Numeric:

•   value - Set to each numeric value upon creation.

•   decimal - Set to float <https://docs.python.org/3/library/functions.html#float> unless decimal specifies otherwise.

    🎨 Theme with 'widgets.Count'.

class survey.widgets.DateTime(*args, value=None, attrs=('day', 'month', 'year', 'hour', 'minute'), Chron=<class 'survey._widgets.Count'>, date_delimit='/', time_delimit=':', part_delimit=' ', **kwargs)
    Bases: BaseList

    A datetime picker.

    Resolves to datetime.datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime> object.

Parameters

•   value (datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime>) -- Initial value.

•   attrs (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The datetime attributes used.

•   Chron (Count) -- Used to convert value to tiles.

•   date_delimit (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Separator for date parts.

•   time_delimit (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Separator for time parts.

•   part_delimit (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Separator for the date and time parts.

    Arguments directly passed to super-class:

•   axis - Set to 1.

•   tiles - Created from value's attributes using attrs and Chron.

•   focus - Set to a Callable that delegates arrow_up, arrow_down, insert and delete_left.

    Arguments used for Chron:

•   value - Set to each numeric value for each part.

•   decimal - Set to False.

•   convert - Set to a Callable that returns the rolling datetime.datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime>'s value after attempting to set it.

•   Numeric - Set to a partial Numeric (see later for arguments).

•   focus_color - Set to None.

    Arguments used for Chron's Numeric:

•   zfill - Set to the maximum amount of digits for the respective part.

    🎨 Theme with 'widgets.DateTime'.

class survey.widgets.Form(*args, form={}, Field=<class 'survey._widgets.Input'>, delimit=':', **kwargs)
    Bases: BaseList

    A multi-item form.

Parameters

•   form -- A mapping of field: editable widget pairs.

•   Field -- Used to convert form keys to tiles.

•   delimit -- Placed between fields and widgets.

    Arguments directly passed to super-class:

•   axis - Set to 1

•   tiles - Created using form.

•   focus_color - Set to None.

•   evade_color - Set to None.

    Arguments used for Field:

•   value - Set to each pair's field.

•   funnel_leave - Set to a Callable that aligns with others fields and includes delimit.

    🎨 Theme with 'widgets.Form'.

  Theme

Themeing is essentially changing the default values for elligible callables.

Look for the "🎨 Theme with" sections to see which functions are subject to themeing.

survey.theme.use(theme)
    Use the theme where applicable. This overrides any subsequent themes.

    A theme is a collection of default arguments for specified functions.

        with theme.use({'printers.info': {'mark_color': colors.basic('magenta')}}):
            with theme.use({'printers.done': {'mark_color': colors.basic('yellow')}}):
                survey.printers.info('example')
                survey.printers.done('example')

    On the above example, only the marker of info will be painted magenta.

survey.theme.get()
    Get the current theme, with all subsequent values attached to it.

  Funnels

Functions that can be used for changing the way data appears upon printing.

Specifically, they are meant to be passed to funnel_enter or funnel_leave. All text_ funnels can be used for the latter, while anythign else should be used former the former.

survey.funnels.text_replace(rune)
    Replace every line element.

Parameters
    rune (str <https://docs.python.org/3/library/stdtypes.html#str> | Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[str <https://docs.python.org/3/library/stdtypes.html#str>], str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The rune to replace with, or a function that takes the current rune and returns the replacement.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_replace('*')
        '******** ***********'
        '********|***************'
        '******** *************'

class survey.funnels.JustType
    Bases: str <https://docs.python.org/3/library/stdtypes.html#str>, Enum <https://docs.python.org/3/library/enum.html#enum.Enum>

    Denotes the type of alignment.

center = 'center'
    middle

start = 'start'
    left or top

end = 'end'
    right or bottom

survey.funnels.text_min_horizontal(just, size, rune)
    Ensure each line is at least of a certain length, aligned accordingly using a rune.

Parameters

•   just (JustType) -- Denotes justification to align with.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum length of each line.

•   rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used to fill empty space.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_min_horizontal(JustType.center, 25, ' ')
        '   The qu ick brown fox   '
        ' jumps ov|er the lazy dog '
        '  and fal ls on its face  '

survey.funnels.text_min_vertical(just, size, rune)
    Ensure there is at least a certain amount of lines, aligned accordingly using a rune.

Parameters

•   just (JustType) -- Denotes justification to align with.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum amount lines.

•   rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used to create lines to fill empty space.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_min_vertical(JustType.end, 5, '~')
        '~~~~~~~~ ~~~~~~~~~~~~~~~'
        '~~~~~~~~ ~~~~~~~~~~~~~~~'
        'The quic k brown fox    '
        'jumps ov|er the lazy dog'
        'and fall s on its face  '

survey.funnels.text_max_horizontal(size)
    Ensure each line is at most a certain size, ensuring the cursor is visible.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The maximum length of each line.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_max_horizontal(10)
        ' quic k bro'
        'ps ov|er th'
        ' fall s on '

survey.funnels.text_max_vertical(size)
    Ensure there is at most a certain amount of lines, ensuring the cursor is visible.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The maximum amount of lines.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_max_vertical(1)
        'jumps ov|er the lazy dog'

survey.funnels.text_max_dynamic(get)
    A combination of text_max_horizontal() and text_max_vertical().

Parameters
    get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]]) -- Should return an iterable with each function's size on their axis index.

survey.funnels.text_bloat_horizontal(just, size, rune)
    Increase each line's length to a certain size, aligned by an axis using a rune.

Parameters

•   just (JustType) -- Denotes justification to align with.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The additional length of the longest line, applied as minimum to all.

•   rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used to fill empty space.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_bloat_horizontal(JustType.start, 2, '%')
        'The quic k brown fox%%%%%%'
        'jumps ov|er the lazy dog%%'
        'and fall s on its face%%%%'

survey.funnels.text_bloat_vertical(just, size, rune)
    Increase the amount of lines lines to a certain size, aligned by an axis using a rune.

Parameters

•   just (JustType) -- Denotes justification to align with.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The additional amount lines.

•   rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used to create lines to fill empty space.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_bloat_vertical(JustType.center, 2, '%')
        '%%%%%%%% %%%%%%%%%%%%%%%'
        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        '%%%%%%%% %%%%%%%%%%%%%%%'

survey.funnels.text_block(rune_top, rune_bottom, rune_left, rune_right, rune_top_left, rune_top_right, rune_bottom_left, rune_bottom_right)
    Surround the lines by overwriting with the respective runes. Any of them can be None to ignore.

Parameters

•   rune_top (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the first line.

•   rune_bottom (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the last line.

•   rune_left (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the first rune of each line.

•   rune_right (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the last rune of each line.

•   rune_top_left (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the first rune of the first line.

•   rune_top_right (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the last rune of the first line.

•   rune_bottom_left (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the first rune of the last line.

•   rune_bottom_right (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used on the last rune of the last line.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_block('-', '-', '|', '|', '/', '\', '\', '/')
        '/----------------------\'
        '|umps ov|er the lazy do|'
        '\----------------------/'

    Use text_bloat_vertical(JustType.center, 2, ' ') and text_bloat_horizontal(JustType.center, 2, ' ') before this to avoid content overwrite.

survey.funnels.text_paint(color)
    Paint each rune of each line.

Parameters
    color (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The color to paint with.

        'The quic k brown fox'
        'jumps ov|er the lazy dog'
        'and fall s on its face'
        >>> text_paint('[36m')
        # The same, but in light blue.

survey.funnels.mesh_delegate(function, check=None, aware=False)
    Call a function on each tile of the mesh.

Parameters

•   function (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>]) -- The function called.

•   check (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], bool <https://docs.python.org/3/library/functions.html#bool>]) -- Used as (spot, tile) -> bool to denote whether the specific tile gets ignored.

•   aware (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to prepend the tile's spot to the function's arguments.

survey.funnels.mesh_delimit(axis, text)
    Insert text between tiles.

Parameters

•   axis (int <https://docs.python.org/3/library/functions.html#int>) -- The axis considered for the operation.

•   text (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The text to insert.

survey.funnels.mesh_focal(function)
    Call a function on each tile of the mesh, with a bool <https://docs.python.org/3/library/functions.html#bool> denoting whether it's the pointed tile prepended in the arguments.

Parameters
    function -- The function called.

survey.funnels.mesh_light(focus_color=None, evade_color=None)
    Paint the mesh's tiles depending on whether they are pointed.

Parameters

•   focus_color (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The color used for the pointed tile.

•   evade_color (str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None>) -- The color used for the other tiles.

survey.funnels.mesh_point(focus_rune, evade_rune)
    Prepend a rune to the pointed tile's first line and another to all others.

    All other lines have empty characters prepended to align with the first.

Parameters

•   focus_rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune for the pointed tile.

•   evade_rune (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune for the other tiles.

survey.funnels.mesh_max(axis, size)
    Ensure there is most of a certain amount of tiles along an certain axis.

Parameters

•   axis (int <https://docs.python.org/3/library/functions.html#int>) -- The axis considered for the operation.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The maximum amount of tiles.

survey.funnels.mesh_min(axis, size, just=JustType.start, fill=<function <lambda>>)
    Ensure there is most of a certain amount of tiles along an certain axis, aligned accordingly by filling with new tiles.

Parameters

•   axis (int <https://docs.python.org/3/library/functions.html#int>) -- The axis considered for the operation.

•   size (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum amount of tiles.

•   just (JustType) -- Denotes justification to align with.

•   fill (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]]) -- Used as (spot) -> lines to fill empty space.

survey.funnels.mesh_grid_fill(tile_just_vertical=JustType.start, tile_rune_vertical=' ', tile_just_horizontal=JustType.start, tile_rune_horizontal=' ', tile_min_vertical=0, tile_min_horizontal=0, push_top=0, push_bottom=0, push_left=0, push_right=0)
    Fill missing spots within a square so that all rows and columns align.

    For that to happen, tiles may need to grow to adjust for the size of others in each axis.

Parameters

•   tile_just_vertical (JustType) -- Denotes vertical justfication for growing each tile.

•   tile_rune_vertical (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used when vertical growing each tile.

•   tile_just_horizontal (JustType) -- Denotes horizontal justfication for growing each tile.

•   tile_rune_horizontal (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The rune used when horizontal growing each tile.

•   tile_min_vertical (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum vertical size of each tile.

•   tile_min_horizontal (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum horizontal size of each tile.

•   push_top (int <https://docs.python.org/3/library/functions.html#int>) -- The additional amount of horizontal groups of tiles injected over the final square.

•   push_bottom (int <https://docs.python.org/3/library/functions.html#int>) -- The additional amount of horizontal groups of tiles injected under the final square.

•   push_left (int <https://docs.python.org/3/library/functions.html#int>) -- The additional amount of vertical groups of tiles injected left of the final square.

•   push_right (int <https://docs.python.org/3/library/functions.html#int>) -- The additional amount of vertical groups of tiles injected right of the final square.

survey.funnels.mesh_grid(runes={'bottom_left': '└', 'bottom_right': '┘', 'cross': '┼', 'cross_bottom': '┴', 'cross_left': '├', 'cross_right': '┤', 'cross_top': '┬', 'horizontal': '─', 'top_left': '┌', 'top_right': '┐', 'vertical': '│'}, runes_color=<fg:black.lite>, **fill_kwargs)
    Turns a mesh into a grid using.

Parameters

•   runes (Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[str <https://docs.python.org/3/library/stdtypes.html#str>, str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The collection of runes used for drawing around each tile.

•   runes_color (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Used to paint all provided grid runes.

    Additional arguments get passed to mesh_grid_fill() before the operation.

survey.funnels.mesh_head(axis, get, just=None, skip=0, min=0)
    Add headers to the mesh.

Parameters

•   axis (int <https://docs.python.org/3/library/functions.html#int>) -- The axis along which to add headers.

•   get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[int <https://docs.python.org/3/library/functions.html#int>], List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]]) -- Used as (index) -> lines on each row or column for fetching its header.

•   just (JustType | None <https://docs.python.org/3/library/constants.html#None>) -- Denotes justification to align with. Default is left/top.

•   skip (int <https://docs.python.org/3/library/functions.html#int>) -- The amount of rows or columns to ignore at the beginning of the operation.

•   min (int <https://docs.python.org/3/library/functions.html#int>) -- The minimum amount of headers to be added. Can be used to avoid possible gaps.

        mesh_head(0, lambda index: [list(str(index))], min = 10)
        # skip is used to prevent adding a header for the headers row.
        mesh_head(1, lambda index: [list(str(index))], min = 10, skip = 1)

survey.funnels.mesh_flip(axis)
    Flip a mesh's axis.

Parameters
    axis (int <https://docs.python.org/3/library/functions.html#int>) -- The axis to flip.

survey.funnels.line_delimit(text)
    Insert text between tiles.

Parameters
    text (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The text to insert.

  Colors

Utilities for dealing with ANSI Colors <https://en.wikipedia.org/wiki/ANSI_escape_code#Colors>.

survey.colors.style(name)
    Get an ansi style by name.

        faint = colors.style('faint')

    The following styles are available: reset, strong, faint, italic, underline, slow_blink, rapid_blink, reverse, conceal, strike, underline_double, reset_intensity, reset_italic, reset_underline, reset_blink, reset_reverse, reset_conceal, reset_strike, reset_fg_color, reset_bg_color

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

survey.colors.basic(fg=None, bg=None)
    Get a basic ansi color by path (4 bit docs <https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit>).

Parameters

•   fg (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The foreground color.

•   bg (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The background color.

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

        fg_lite_blue = basic('blue.lite')
        fg_dark_green = basic('green.dark')
        bg_lite_yellow = basic(bg = 'yellow') # .lite can be ommited
        bg_dark_red_fg_dark_cyan = basic(fg = 'red.dark', bg = 'cyan.dark')

survey.colors.standard(part, layer='fg')
    Get a standard ansi color by value (8 bit docs <https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit>).

Parameters

•   part (str <https://docs.python.org/3/library/stdtypes.html#str>) -- The color in [0, 255] range.

•   layer (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Whether it's foreground ('fg') or background ('bg').

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

        fg_blue = standard(4)
        fg_pink = standard(225)
        bg_cyan = standard(6, 'bg')

survey.colors.full(part_r, part_g, part_b, layer='fg')
    Get a full rgb ansi color by the respective values (224 bit docs <https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit>).

Parameters

•   part_r (int <https://docs.python.org/3/library/functions.html#int>) -- The red component.

•   part_g (int <https://docs.python.org/3/library/functions.html#int>) -- The green component.

•   part_b (int <https://docs.python.org/3/library/functions.html#int>) -- The blue component.

Parma layer
    Whether it's foreground ('fg') or background ('bg').

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

        fg_steel = full(113, 121, 126)
        bg_brick = fill(170, 74, 68, 'bg')

  Mutates

Classes for changing data in-place in ways that emulate commonly-used interfaces.

exception survey.mutates.Error(text, **info_kwargs)
    Bases: InfoErrorMixin, Exception <https://docs.python.org/3/library/exceptions.html#Exception>

class survey.mutates.Mutate
    Bases: ABC <https://docs.python.org/3/library/abc.html#abc.ABC>

    Base class for mutates. They emulate the behavior of common data manipulators.

get_state()
    Get a copy of the current state.

set_state(state)
    Restore the current state to the one provided.

class survey.mutates.Cursor(point)
    Bases: Mutate

    A mutate for a point representing a position in space.

Parameters
    point (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- The manipulating point.

move(instructions)
    Move according to the instructions given.

    Each instruction should be of (index, new_coordinate) form.

Return type
    None <https://docs.python.org/3/library/constants.html#None>

property point: List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]
    The internal point.

class survey.mutates.Text(lines, point)
    Bases: Mutate

    A mutate for a block of text and a cursor among it.

Parameters

•   lines (List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]) -- The manipulating list of lines.

•   point (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- The point for the cursor.

delete(size)
    Delete ahead of the cursor, including newlines.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The amount of runes to delete.

insert(runes)
    Insert text at the current cursor position and move it accordingly.

Parameters
    runes (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The runes to insert.

property lines: List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]
    The current lines.

move_x(size)
    Move the cursor horizontally, wrapping to the next or last line as necessary.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The amount of runes to move by.

move_y(size)
    Move the cursor verticaly, wrapping to the max width of the new line as necessary.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The amount of lines to move by.

newline()
    Insert a new line under the cursor, cutting the current one as necessary.

property point: List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]
    The current cursor's point.

class survey.mutates.Mesh(score, scout, rigid, permit, create, clean, tiles, point, *args, **kwargs)
    Bases: Mutate

    A mutate for a collection of tiles.

Parameters

•   score (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], Any <https://docs.python.org/3/library/typing.html#typing.Any>], int <https://docs.python.org/3/library/functions.html#int> | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used during searching to determine the order at which each spot's tile should be shown, if at all.

•   scout (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], bool <https://docs.python.org/3/library/functions.html#bool>] | None <https://docs.python.org/3/library/constants.html#None>) -- Determines whether a spot is valid to move to.

•   rigid (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to not allow wraping around when moving toward the edge.

•   permit (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to allow invalid runes to be added to the search lines.

•   create (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]], Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for creating tiles for new spots. Can return None to prevent creation.

•   tiles (Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Any <https://docs.python.org/3/library/typing.html#typing.Any>]) -- The manipulating tiles.

•   point (List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]) -- The point for the cursor.

property cur_spot: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]
    The current real spot, accounting for vision.

property cur_tile
    The current tile.

delete(spot)
    Attempt to delete a tile

Parameters
    spot (Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]) -- The spot to delete the tile from.

Return type
    Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None>

    If one exists, it is returned.

insert(spot)
    Attempt to insert a tile.

Parameters
    spot (Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]) -- The spot to insert the tile at.

Return type
    Any <https://docs.python.org/3/library/typing.html#typing.Any> | None <https://docs.python.org/3/library/constants.html#None>

    If one already exists or gets created, it is returned.

move(direction)
    Move the cursor to the nearest tile.

Parameters
    direction (int <https://docs.python.org/3/library/functions.html#int>) -- The direction to move toward in circular [-90, +180] degrees.

    If none exists toward the specified direction, attempt again by wrapping around the other side.

property point: List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]
    The current cursor's point.

search_delete(size)
    Delete from the search line, and filter or displace tiles accordingly.

Parameters
    size (int <https://docs.python.org/3/library/functions.html#int>) -- The amount of runes to delete.

property search_ignore_index
    The current search ignore index.

search_insert(runes)
    Insert text to the search line, and filter or displace tiles accordingly.

Parameters
    runes (List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]) -- The runes to insert.

property search_line: List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]
    The search mutate's current line.

    Tile creation is only possible when this is empty.

property search_lines: List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]]
    The search mutate's lines.

    Only one line will be in use at any given time.

property search_point: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]
    The search mutate's cursor's point.

    Should always be at the end of the search_line.

property vis_spot: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]
    The current vision spot. Simply a tuple of point.

property vision: Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]]
    A mapping of currently visible spots to the real ones they correspond to.

  Visuals

Visuals guide the rendering of data in predictible ways.

Classes for transforming specific-structure data into a form that be used by to print to the console while maintaining proper cursor position.

Most accept data structured in similar ways to how it is used in :class`~.mutate.Mutate`s.

class survey.visuals.Visual(get, funnel_enter=None, funnel_leave=None)
    Bases: ABC <https://docs.python.org/3/library/abc.html#abc.ABC>

    Base class for transformers of data into lines and point for rendering.

Parameters

•   get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[bool <https://docs.python.org/3/library/functions.html#bool>, bool <https://docs.python.org/3/library/functions.html#bool>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[Any <https://docs.python.org/3/library/typing.html#typing.Any>]]) -- Used for fetching the data. The arguments have the same meaning as in get().

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Any <https://docs.python.org/3/library/typing.html#typing.Any>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating the data in-place before turning into lines and point.

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating the resulting lines and point in-place after transforming the data.

get(enter=True, leave=True)
    Fetches and transforms the data.

Parameters

•   enter (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to use funnel_enter.

•   leave (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether to use funnel_leave.

Return type
    Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>

Returns
    The final lines and point.

class survey.visuals.Text(get, funnel_enter=None, funnel_leave=None)
    Bases: Visual

    Transforms lines and point into... lines and cursor point.

Parameters

•   get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[bool <https://docs.python.org/3/library/functions.html#bool>, bool <https://docs.python.org/3/library/functions.html#bool>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]]) -- Used for fetching data.

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating data in-place before turning into (lines, point).

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating the resulting (lines, point) in-place after transforming data.

classmethod link(lines, point, *args, **kwargs)
    Use this if (lines, point) are expected to be mutated in-place over their life time.

class survey.visuals.Mesh(get, funnel_enter=None, funnel_leave=None)
    Bases: Visual

    Transforms mesh tiles and point into lines and cursor point.

Parameters

•   get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[bool <https://docs.python.org/3/library/functions.html#bool>, bool <https://docs.python.org/3/library/functions.html#bool>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]]) -- Used for fetching (tiles, point).

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating (tiles, point) in-place before turning into (lines, point).

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating the resulting (lines, point) in-place after transforming (tiles, point).

•   tiles is {spot: tile, ...}

•   spot is (y, x)

•   tile is (lines, point)

classmethod link(tiles, point, *args, **kwargs)
    Use this if (tiles, point) are expected to be mutated in-place over their life time.

•   tiles is {spot: get, ...}

•   spot is (y, x)

•   get is like get() and returns (lines, point)

class survey.visuals.Line(get, funnel_enter=None, funnel_leave=None)
    Bases: Visual

    Transforms a list of tiles and point into lines and cursor point.

Parameters

•   get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[bool <https://docs.python.org/3/library/functions.html#bool>, bool <https://docs.python.org/3/library/functions.html#bool>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]]) -- Used for fetching (tiles, point).

•   funnel_enter (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Dict <https://docs.python.org/3/library/typing.html#typing.Dict>[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>]], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating (tiles, point) in-place before turning into (lines, point).

•   funnel_leave (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[List <https://docs.python.org/3/library/typing.html#typing.List>[List <https://docs.python.org/3/library/typing.html#typing.List>[str <https://docs.python.org/3/library/stdtypes.html#str>]], List <https://docs.python.org/3/library/typing.html#typing.List>[int <https://docs.python.org/3/library/functions.html#int>] | None <https://docs.python.org/3/library/constants.html#None>], None <https://docs.python.org/3/library/constants.html#None>] | None <https://docs.python.org/3/library/constants.html#None>) -- Used for mutating the resulting (lines, point) in-place after transforming (tiles, point).

•   tiles is [get, ...]

•   get is like get() and return (lines, point)

classmethod link(tiles, point, *args, **kwargs)
    Use this if (tiles, point) are expected to be mutated in-place over their life time.

•   tiles is [get, ...]

•   get is like get()

  Handle

Handling incoming events and their information by delegating to functions that can handle them.

class survey.handle.EventType(*values)
    Bases: str <https://docs.python.org/3/library/stdtypes.html#str>, Enum <https://docs.python.org/3/library/enum.html#enum.Enum>

    Flags whether the event is called back before or after invokation.

exception survey.handle.Abort
    Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Can be raised during a callback with EventType.enter to prevent invokation.

class survey.handle.Handle(*args, unsafe=False, callback=None)
    Bases: object <https://docs.python.org/3/library/functions.html#object>

    Used for holding and calling "control" functions that determine action for each _core.Event.

Parameters

•   unsafe (bool <https://docs.python.org/3/library/functions.html#bool>) -- Whether KeyError <https://docs.python.org/3/library/exceptions.html#KeyError> should be surfaced when an invoke is missing.

•   callback (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[EventType, Event], Text | Escape | Control | Sequence], None <https://docs.python.org/3/library/constants.html#None>]) -- Called before and after invokation with Event.enter. and Event.leave prepended in the arguments respectively.

add(control)
    Add a control.

invoke(event, *args)
    Invoke a control if it exists.

  Core

The internal tools of the library.

class survey.core.IO(i, o, *args, **kwargs)
    Bases: BaseIO

    Manages the input and output buffers.

        io = IO(sys.stdin, sys.stdout)
        with io:
            rune = io.recv()
            io.send('You pressed ' + rune)

class survey.core.ClearMode
    Bases: IntEnum <https://docs.python.org/3/library/enum.html#enum.IntEnum>

    Denotes how the cursor clears the screen.

right = 0
    Clear all runes right-and-down of the cursor.

left = 1
    Clear all runes left-and-up of the cursor.

full = 2
    Clear all runes.

extend = 3
    Clear all runes and delete scrollback lines.

class survey.core.EraseMode
    Bases: IntEnum <https://docs.python.org/3/library/enum.html#enum.IntEnum>

    Denotes how the cursor erases the line.

right = 0
    Erase all visible runes right of the cursor.

left = 1
    Erase all visible runes left of the cursor.

full = 2
    Erase all visible runes.

class survey.core.Event
    Bases: str <https://docs.python.org/3/library/stdtypes.html#str>, Enum <https://docs.python.org/3/library/enum.html#enum.Enum>

    Names for received events.

exception survey.core.Terminate
    Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Signals the invokation loop to stop.

exception survey.core.SkipDraw
    Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Signals the invokation loop to not skip drawing for the current turn.

  ansi

class survey.core.ansi.Text(rune)
    Bases: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>

rune
    Alias for field number 0

class survey.core.ansi.Control(rune)
    Bases: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>

rune
    Alias for field number 0

class survey.core.ansi.Escape(rune)
    Bases: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>

rune
    Alias for field number 0

class survey.core.ansi.Sequence(rune, args, trail)
    Bases: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>

args
    Alias for field number 1

rune
    Alias for field number 0

trail
    Alias for field number 2

survey.core.ansi.parse(get)
    Parse an incoming series of characters into their ANSI representation.

Parameters
    get (Callable <https://docs.python.org/3/library/typing.html#typing.Callable>[[], str <https://docs.python.org/3/library/stdtypes.html#str>]) -- Used whenever an additional character is needed, may return an empty string.

Return type
    Text | Escape | Control | Sequence

Returns
    Encapsulates resulting ANSI information.

survey.core.ansi.parse_iterable(iterable)
    Same as parse(), except accepts an iterable.

Parameters
    iterable (Iterable <https://docs.python.org/3/library/typing.html#typing.Iterable>) -- Its iter(...).__next__ method is used as parse.get.

Return type
    Text | Escape | Control | Sequence

Returns
    Same as in parse().

survey.core.ansi.get_escape(code, *args)
    Get the escape sequence of code with args.

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

survey.core.ansi.get_control(code, *args, private=False)
    Get the control sequence of code with args.

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

Author
Exahilosys

Copyright
2023, Exahilosys