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'

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

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'

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'

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

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'

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

survey.routines.select(*args, reply=<function _select_reply>, **kwargs)

Use an Select widget.

The default hint shows available controls.

All widget and start() arguments are valid.

🎨 Theme with 'routines.select'

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

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>, **kwargs)

Use an Basket widget.

The default hint shows available controls.

All widget and start() arguments are valid.

🎨 Theme with 'routines.basket'

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

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'

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

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'

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

Parameters:

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

• end (str) – Appended to the end of the final value.

• re (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) – Prepended to the final value.

• mark_color (str) – Used to color info.mark with.

Additional arguments are passed to text().

🎨 Theme with printers.info.

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

Print a value denoting success.

Parameters:

• values – Same as text.value.

• mark (str) – Prepended to the final value.

• mark_color (str) – Used to color info.mark with.

Additional arguments are passed to text().

🎨 Theme with printers.done.

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

Print a value denoting failure.

Parameters:

• values – Same as text.value.

• mark (str) – Prepended to the final value.

• mark_color (str) – Used to color info.mark with.

Additional arguments are passed to text().

🎨 Theme with printers.fail.

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[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.

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[MultiLineProgressControl]) – The controls to manage.

• width (int) – The default width for each line.

• empty (str) – The rune to fill empty space with.

• prefix_wall (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

property controls: List[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

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

Parameters:

• total (Union[int, float]) – The maximum expected amount of the internal value.

• value (Union[int, float]) – The initial value.

• runes (List[str]) – The runes to cycle through for subdivisions of a character.

• color (Optional[str]) – The color of the line.

• suffix (Union[str, Callable[[MultiLineProgressControl], 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 (Union[str, Callable[[MultiLineProgressControl], str], None]) – Used after the value has reached the total instead of the suffix.

• denominate (Optional[Callable[[Union[int, float]], Tuple[float, str]]]) –

  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

property total: int | float

The total value.

property value: int | float

The current value.

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 (Union[int, float]) – The amount to move it by.

get_line(width)

Get the current line text.

Parameters:

width (int) – The maximum amount of allowed characters.

Return type:

str

get_info()

Get the current info text.

Will be an empty string if the internal deque is empty

Return type:

str

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

Bases: MultiLineProgress

A simple line progress with one internal control.

Parameters:

total (Union[int, 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

classmethod from_iterable(iterable, *args, total=None, count=None, **kwargs)

Yields values from the iterable and displays the progress to completion.

Parameters:

• iterable (Container) – The iterable to yield values from.

• total (Union[int, float, None]) – The total of the iterable if it cannot be determined directly from it.

• count (Optional[Callable[[Any], int]]) – Can be used to specify by how much to increase the internal value per yield (default: 1).

Raises:

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 (Union[int, 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

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

exception survey.widgets.Escape

Bases: 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

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 (Optional[Callable[[Tuple[EventType, Event], Union[Text, Escape, Control, Sequence]], None]]) – Used as handle.Handle.callback.

• delegate (Optional[Callable[[Event], bool]]) – Used with (event) and decides whether to continue the invokation.

• validate (Optional[Callable[[Any], None]]) – Used with (result) upon submission, forbidden by raising Abort.

property mutate

The underlying mutate.

resolve()

Get the resolved value.

invoke(event, info)

Invoke the underlying handle.

Parameters:

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

• info (Union[Text, Escape, Control, Sequence]) – Contains details used during the operation.

Note

If delegate is provided and returns False, nothing happens.

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:

Optional[Tuple[List[List[str]], Optional[List[int]]]]

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) – Whether the body should start on a separate line during use.

• multi_aft (bool) – Whether the reply should start on a separate line.

• widget (Widget) – The widget to use.

• show (Optional[str]) – Printed before anything else (uncontrollable).

• mark (Optional[str]) – Prepended to the show.

• info (Union[str, List[List[str]], Callable[[Any], Tuple[List[List[str]], List[int]]], None]) – The info for the stage. If callable, takes (widget, event_name, event_info).

• info_parse (bool) – Whether info is given (or, if callable returns) as a str or (lines, point).

• hint (Union[str, List[List[str]], Callable[[Any], Tuple[List[List[str]], List[int]]], None]) – The hint for the stage. If callable, takes (widget, event_name, event_info).

• hint_parse (bool) – Whether hint is given (or, if callable returns) as a str or (lines, point).

• site (str) – Can be 'info' or 'body' to place the cursor on the info or widget body respectively.

• reply (Optional[Callable[[Widget, Any], str]]) – 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[List[str]]) – Same as mutates.Text.lines.

• point (List[int]) – Same as mutates.Text.point.

• multi (bool) – Whether to support multiple lines. If so, leaving 2 empty lines submits.

• callback (Optional[Callable[[Tuple[EventType, Event], Union[Text, Escape, Control, Sequence]], None]]) – Same as Widget.callback.

• delegate (Optional[Callable[[Event], bool]]) – Same as Widget.delegate.

• validate (Optional[Callable[[Any], None]]) – Same as Widget.validate.

• funnel_enter (Optional[Callable[[List[List[str]], List[int]], None]]) – Same as visuals.Text.funnel_enter.

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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.

Parameters:

• value (str) – Converted into BaseText.lines.

• index (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 or float.

Parameters:

• value (int) – Converted into Input.value.

• decimal (bool) – Whether to allow (finite) decimal values.

• zfill (int) – Amount of 0-fill to have.

• invalid_value_message (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.

Parameters:

• rune (str) – The rune to replace all others with.

• color (Optional[int]) – 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[str]) – The possible options. Attempting to insert a rune that does not lead to an option is forbidden.

• transform (Optional[Callable[[str], str]]) – 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[str, Any]) – The possible options and their respective values.

• default (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>, 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 (Optional[Callable[[List[List[str]], Any], Optional[int]]]) – Same as mutates.Mesh.score.

• create (Optional[Callable[[Tuple[int, int]], Optional[Any]]]) – Same as mutates.Mesh.create.

• tiles (Dict[Tuple[int, int], Any]) – Same as mutates.Mesh.tiles. Values should be Widget instances.

• point (List[int]) – Same as mutates.Mesh.point.

• clean (Optional[int]) – Same as mutates.Mesh.clean.

• scout (Optional[Callable[[Tuple[int, int]], bool]]) – Same as mutates.Mesh.scout.

• rigid (bool) – Same as mutates.Mesh.rigid.

• focus (Union[bool, Callable[[Event], bool]]) – When 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 (Optional[Callable[[Tuple[EventType, Event], Union[Text, Escape, Control, Sequence]], None]]) – Same as Widget.callback.

• delegate (Optional[Callable[[Event], bool]]) – Same as Widget.delegate.

• validate (Optional[Callable[[Any], None]]) – Same as Widget.validate.

• escapable (bool) – Same as Widget.escapable.

• funnel_enter (Optional[Callable[[Dict[Tuple[int, int], Tuple[List[List[str]], List[int]]], List[int]], None]]) – Same as visuals.Mesh.funnel_enter.

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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 (the pointed index).

Parameters:

• axis (int) – Denotes the axis across which movement is allowed.

• tiles (Union[List[Widget], Dict[Tuple[int, int], Any]]) – Same as BaseMesh.tiles, but it can be any iterable.

• index (int) – Used as the axisth element of BaseMesh.point.

• label (Optional[Callable[[int], str]]) – Used as (index, tile) and returns a label to place on the right.

• view_max (Optional[int]) – Maximum amount of elemnts visible at once.

• focus_color (Optional[str]) – The color to paint the current tile with.

• focus_mark (Optional[str]) – The rune to prepend to the current tile.

• evade_color (Optional[str]) – The color to paint the non-current tiles with.

• evade_mark (Optional[str]) – The rune to prepend to the non-current tiles.

• fill (bool) – Whether to fill empty room.

• delimit (Optional[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[str]) – Converted into BaseList.tiles.

• create (Optional[Callable[[Tuple[int, int]], str]]) – 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[str]) – Converted into BaseList.tiles.

• active (List[int]) – Indexes that should be selected from the start.

• positive_mark (str) – Prepended to all selected options.

• negative_mark (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 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 (the pointed value).

Parameters:

• value (Union[int, float]) – Initial value.

• rate (Union[int, float]) – Rate to move by.

• decimal (Optional[bool]) – Whether to only allow float or int.

• convert (Optional[Callable[[Union[int, float]], Union[int, float]]]) – 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 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 object.

Parameters:

• value (Optional[datetime]) – Initial value.

• attrs (List[str]) – The datetime attributes used.

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

• date_delimit (str) – Separator for date parts.

• time_delimit (str) – Separator for time parts.

• part_delimit (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’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 (Union[str, Callable[[str], 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, Enum

Denotes the type of alignment.

start = 'start'

left or top

end = 'end'

right or bottom

center = 'center'

middle

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) – The minimum length of each line.

• rune (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) – The minimum amount lines.

• rune (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) – 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) – 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[[], Tuple[int, 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) – The additional length of the longest line, applied as minimum to all.

• rune (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) – The additional amount lines.

• rune (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) – Used on the first line.

• rune_bottom (str) – Used on the last line.

• rune_left (str) – Used on the first rune of each line.

• rune_right (str) – Used on the last rune of each line.

• rune_top_left (str) – Used on the first rune of the first line.

• rune_top_right (str) – Used on the last rune of the first line.

• rune_bottom_left (str) – Used on the first rune of the last line.

• rune_bottom_right (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) – The color to paint with.

'The quic k brown fox'
'jumps ov|er the lazy dog'
'and fall s on its face'

>>> text_paint('')

# 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[[List[List[str]], List[int]], None]) – The function called.

• check (Optional[Callable[[Tuple[int, int], List[List[List[str]]], List[int]], bool]]) – Used as (spot, tile) -> bool to denote whether the specific tile gets ignored.

• aware (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) – The axis considered for the operation.

• text (str) – The text to insert.

survey.funnels.mesh_focal(function)

Call a function on each tile of the mesh, with a 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 (Optional[str]) – The color used for the pointed tile.

• evade_color (Optional[str]) – 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) – The rune for the pointed tile.

• evade_rune (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) – The axis considered for the operation.

• size (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) – The axis considered for the operation.

• size (int) – The minimum amount of tiles.

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

• fill (Callable[[Tuple[int, int]], List[List[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) – The rune used when vertical growing each tile.

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

• tile_rune_horizontal (str) – The rune used when horizontal growing each tile.

• tile_min_vertical (int) – The minimum vertical size of each tile.

• tile_min_horizontal (int) – The minimum horizontal size of each tile.

• push_top (int) – The additional amount of horizontal groups of tiles injected over the final square.

• push_bottom (int) – The additional amount of horizontal groups of tiles injected under the final square.

• push_left (int) – The additional amount of vertical groups of tiles injected left of the final square.

• push_right (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[str, str]) – The collection of runes used for drawing around each tile.

• runes_color (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) – The axis along which to add headers.

• get (Callable[[int], List[List[str]]]) – Used as (index) -> lines on each row or column for fetching its header.

• just (Optional[JustType]) – Denotes justification to align with. Default is left/top.

• skip (int) – The amount of rows or columns to ignore at the beginning of the operation.

• min (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) – The axis to flip.

survey.funnels.line_delimit(text)

Insert text between tiles.

Parameters:

text (str) – The text to insert.

Colors

Utilities for dealing with ANSI 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

survey.colors.basic(fg=None, bg=None)

Get a basic ansi color by path (4 bit docs).

Parameters:

• fg (Optional[str]) – The foreground color.

• bg (Optional[str]) – The background color.

Return type:

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

Parameters:

• part (str) – The color in [0, 255] range.

• layer (str) – Whether it’s foreground ('fg') or background ('bg').

Return type:

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

Parameters:

• part_r (int) – The red component.

• part_g (int) – The green component.

• part_b (int) – The blue component.

Parma layer:

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

Return type:

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

class survey.mutates.Mutate

Bases: 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[int]) – The manipulating point.

property point: List[int]

The internal point.

move(instructions)

Move according to the instructions given.

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

Return type:

None

class survey.mutates.Text(lines, point)

Bases: Mutate

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

Parameters:

• lines (List[List[str]]) – The manipulating list of lines.

• point (List[int]) – The point for the cursor.

property lines: List[List[str]]

The current lines.

property point: List[int]

The current cursor’s point.

insert(runes)

Insert text at the current cursor position and move it accordingly.

Parameters:

runes (List[str]) – The runes to insert.

move_y(size)

Move the cursor verticaly, wrapping to the max width of the new line as necessary.

Parameters:

size (int) – The amount of lines to move by.

move_x(size)

Move the cursor horizontally, wrapping to the next or last line as necessary.

Parameters:

size (int) – The amount of runes to move by.

delete(size)

Delete ahead of the cursor, including newlines.

Parameters:

size (int) – The amount of runes to delete.

newline()

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

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

Bases: Mutate

A mutate for a collection of tiles.

Parameters:

• score (Optional[Callable[[List[List[str]], Any], Optional[int]]]) – Used during searching to determine the order at which each spot’s tile should be shown, if at all.

• scout (Optional[Callable[[Tuple[int, int]], bool]]) – Determines whether a spot is valid to move to.

• rigid (bool) – Whether to not allow wraping around when moving toward the edge.

• create (Optional[Callable[[Tuple[int, int]], Optional[Any]]]) – Used for creating tiles for new spots. Can return None to prevent creation.

• tiles (Dict[Tuple[int, int], Any]) – The manipulating tiles.

• point (List[int]) – The point for the cursor.

property search_point: Tuple[int, int]

The search mutate’s cursor’s point.

Should always be at the end of the search_line.

property search_lines: List[List[str]]

The search mutate’s lines.

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

property search_line: List[str]

The search mutate’s current line.

Tile creation is only possible when this is empty.

property vision: Dict[Tuple[int, int], Tuple[int, int]]

A mapping of currently visible spots to the real ones they correspond to.

property point: List[int]

The current cursor’s point.

property vis_spot: Tuple[int, int]

The current vision spot. Simply a tuple of point.

property cur_spot: Tuple[int, int]

The current real spot, accounting for vision.

property cur_tile

The current tile.

insert(spot)

Attempt to insert a tile.

Parameters:

spot (Tuple[int, int]) – The spot to insert the tile at.

Return type:

Optional[Any]

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

delete(spot)

Attempt to delete a tile

Parameters:

spot (Tuple[int, int]) – The spot to delete the tile from.

Return type:

Optional[Any]

If one exists, it is returned.

move(direction)

Move the cursor to the nearest tile.

Parameters:

direction (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.

search_insert(runes)

Insert text to the search line, and filter or displace tiles accordingly.

Parameters:

runes (List[str]) – The runes to insert.

search_delete(size)

Delete from the search line, and filter or displace tiles accordingly.

Parameters:

size (int) – The amount of runes to delete.

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

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

Parameters:

• get (Callable[[bool, bool], Tuple[Any]]) – Used for fetching the data. The arguments have the same meaning as in get().

• funnel_enter (Optional[Callable[[Any], None]]) – Used for mutating the data in-place before turning into lines and point.

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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) – Whether to use funnel_enter.

• leave (bool) – Whether to use funnel_leave.

Return type:

Optional[Tuple[List[List[str]], Optional[List[int]]]]

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[[bool, bool], Tuple[List[List[str]], List[int]]]) – Used for fetching data.

• funnel_enter (Optional[Callable[[List[List[str]], List[int]], None]]) – Used for mutating data in-place before turning into (lines, point).

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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[[bool, bool], Tuple[Dict[Tuple[int, int], Tuple[List[List[str]], List[int]]], List[int]]]) – Used for fetching (tiles, point).

• funnel_enter (Optional[Callable[[Dict[Tuple[int, int], Tuple[List[List[str]], List[int]]], List[int]], None]]) – Used for mutating (tiles, point) in-place before turning into (lines, point).

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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[[bool, bool], Tuple[Dict[Tuple[int, int], Tuple[List[List[str]], List[int]]], List[int]]]) – Used for fetching (tiles, point).

• funnel_enter (Optional[Callable[[Dict[Tuple[int, int], Tuple[List[List[str]], List[int]]], List[int]], None]]) – Used for mutating (tiles, point) in-place before turning into (lines, point).

• funnel_leave (Optional[Callable[[List[List[str]], Optional[List[int]]], 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(value)

Bases: str, Enum

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

exception survey.handle.Abort

Bases: Exception

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

class survey.handle.Handle(*args, unsafe=False, callback=None)

Bases: object

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

Parameters:

• unsafe (bool) – Whether KeyError should be surfaced when an invoke is missing.

• callback (Optional[Callable[[Tuple[EventType, Event], Union[Text, Escape, Control, Sequence]], 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.Cursor(intel)

Bases: object

Emulates the on-screen cursor.

Note

Coordinates here are 1-offset indexes, meaning they start from 1. The position of the cursor on the top-left-most of the screen is (1, 1).

Parma intel:

Used for fetching parsed items from input and sending to output.

io = IO(sys.stdin, sys.stdout)
intel = Intel(io)
cursor = Cursor(intel)
location = cursor.locate()

property hidden

A context manager for hiding the cursor.

with cursor.hidden:
    ...

up(size=None)

Move up. No effect if at the edge of the screen.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

down(size=None)

Move down. No effect if at the edge of the screen.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

left(size=None)

Move left. No effect if at the edge of the screen.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

right(size=None)

Move right. No effect if at the edge of the screen.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

goto(x=None)

Move absolutely on line.

Parameters:

x (Optional[int]) – The absolute coordinate to move to. System default is usually 1.

last(size=None)

Move up at line start.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

next(size=None)

Move down at line start.

Parameters:

size (Optional[int]) – The amount of lines to move by. System default is usually 1.

move(y=None, x=None)

Move absolutely on screen.

Parameters:

• y (Optional[int]) – The absolute vertical coordinate to move to. System default is usually 1.

• x (Optional[int]) – The absolute horizontal coordiante to move to. System default is usually 1.

clear(mode=None)

Clear the screen.

Parameters:

mode (Optional[ClearMode]) – Denotes which part of the screen to clear. System default is usually ClearMode.right.

erase(mode=None)

Erase the line.

Parameters:

mode (Optional[EraseMode]) – Denotes which part of the screen to clear. System default is usually EraseMode.right.

save()

Save the current position. Consequent uses will overwrite previous ones.

load()

Move to the last-saved position. Consequent uses will have the same result.

hide()

Become invisible.

show()

Become visible.

locate()

Get the current absolute vertical and horizontal coordinates.

Return type:

Tuple[int, int]

Returns:

(vertical, horizontal)

measure()

Get the maximum possible vertical and horizontal coordinates.

Return type:

Tuple[int, int]

Returns:

(vertical, horizontal)

class survey.core.ClearMode

Bases: 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

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.Source(callback, intel)

Bases: object

Translates incoming ANSI sequences to events and calls back with relevant information.

Parameters:

• callback (Callable[[Event, Union[Text, Escape, Control, Sequence]], None]) – Called with (name, info) upon receiving and translating.

• intel (Intel) – Used for receiving from input.

listen()

Begin listening for events.

class survey.core.Event

Bases: str, Enum

Names for received events.

insert = 'insert'

arrow_left = 'arrow_left'

arrow_right = 'arrow_right'

arrow_up = 'arrow_up'

arrow_down = 'arrow_down'

delete_left = 'delete_left'

delete_right = 'delete_right'

escape = 'escape'

indent = 'indent'

enter = 'enter'

class survey.core.Render(cursor)

Bases: object

Assists with printing text in a predictible way.

Note

In contrast to how Cursor works, point coordinates here are 0-offset indexes.

Parameters:

• cursor (Cursor) – Used for moving and clearing.

• intel – Used for sending to the output.

io = IO(sys.stdin, sys.stdout)
intel = Intel(io)
cursor = Cursor(intel)
render = Render(cursor, intel)
# draw "Hello\nWorld" and place cursor between "r" and "l".
render.draw([['H', 'e', 'l', 'l', 'o'], ['W', 'o', 'r', 'l', 'd']], [1, 3])

property cursor: Cursor

The cursor used for positioning the cursor and fetching coordinate information.

property memory: List[int] | None

The last initial cursor position.

draw(lines, point=None, *, clean=True, learn=True)

Draw lines and place the cursor among them.

Parameters:

• lines (List[List[str]]) – The lines to draw.

• point (Optional[List[int]]) – The coordiantes among the lines to place the cursor.

• clean (bool) – Whether to clear the rest of the screen after drawing the lines.

• learn (bool) – Whether to keep track of the initial cursor position.

back()

Move the cursor to the position it was before drawing.

class survey.core.Screen(render)

Bases: object

Encapsulates the visualization logic.

Parameters:

• render (Render) – Used for drawing and cursor placement.

• cursor – Used for hidding the cursor between draws.

print(sketch, re, *, clean=True, learn=True)

Fetch drawing information and use it to print.

Parameters:

• sketch (Callable[[], Tuple[List[List[str]], Optional[List[int]]]]) – Used after potentially placing the cursor to its initial position. Should return (lines, point) used for drawing.

• re (bool) – Whether to return the cursor to its initial position before attempting to draw.

• clean (bool) – Same as Render.draw.clean.

• learn (bool) – Same as Render.draw.learn.

The reason a callable is required instead of (lines, point), is to allow the original cursor information to be true on every call.

class survey.core.Handle(intel)

Bases: object

Encapsulates the invokation loop logic.

start(invoke)

Start the invokation loop.

This will use Source.listen() until Terminate is raised.

Parameters:

invoke (Callable[[str, Union[Text, Escape, Control, Sequence]], None]) – Used as Source.callback callback.

exception survey.core.Terminate

Bases: Exception

Signals the invokation loop to stop.

class survey.core.Console(handle, screen)

Bases: object

Standardizes interaction with the IO into a wait-receive-invoke loop.

Parameters:

• handle (Handle) – Used for the invokation loop.

• screen (Screen) – Used for visualizing.

property handle: Handle

The internal handle.

start(sketch, invoke)

Creates an invokation-visualization loop.

1. sketch is used for the initial print.

2. invoke is used once input is received.

3. sketch is used for the updated print.

4. Repeat from step 2 until handle.Terminate gets raised.

Parameters:

• sketch (Callable[[], Tuple[List[List[str]], Optional[List[int]]]]) – Used for visualizing.

• invoke (Callable[[str, Union[Text, Escape, Control, Sequence]], None]) – Called upon receiving info from the IO.

exception survey.core.SkipDraw

Bases: Exception

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

ansi

class survey.core.ansi.Text(rune)

Bases: tuple

Non-ANSI text.

rune

Alias for field number 0

class survey.core.ansi.Control(rune)

Bases: tuple

ANSI control code (wiki).

rune

Alias for field number 0

class survey.core.ansi.Escape(rune)

Bases: tuple

ANSI escape sequence (wiki).

rune

Alias for field number 0

class survey.core.ansi.Sequence(rune, args, trail)

Bases: tuple

ANSI control sequence (wiki).

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[[], str]) – Used whenever an additional character is needed, may return an empty string.

Return type:

Union[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) – Its iter(...).__next__ method is used as parse.get.

Return type:

Union[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

survey.core.ansi.get_control(code, *args, private=False)

Get the control sequence of code with args.

Return type:

str