Reference
The specifics of the library.
Routines
Functions that use Widget
s 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()
.
- survey.printers.info(*values, mark='!', mark_color=<fg:cyan>, **kwargs)
Print a value denoting information.
- Parameters:
values – Same as
text.value
.mark_color (
str
) – Used to colorinfo.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_color (
str
) – Used to colorinfo.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_color (
str
) – Used to colorinfo.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.
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.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.runes (
List
[str
]) – The runes to cycle through for subdivisions of a character.suffix (
Union
[str
,Callable
[[MultiLineProgressControl
],str
]]) –Added after the line. The following placeholders may be used:
value
is the current value.total
istotal
.total_unit
is fromdenominate
ontotal
.speed
is the known moving rate of the value.speed_unit
is fromdenominate
onspeed
.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'
, thendenominate(1000)
may return(1000, 'MB')
so that speed is shown as1000/1000 -> '1 MB/s'
🎨 Theme with
.graphics.MultiLineProgressControl
- 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.
- get_line(width)
Get the current line text.
- class survey.graphics.LineProgress(total, *args, **kwargs)
Bases:
MultiLineProgress
A simple line progress with one internal control.
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.
- classmethod from_response(response, *args, **kwargs)
Yields chunks of data as received from the response.
Widgets
Combinations of Mutate
s, Visual
s 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.
- 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:
visual (
Visual
) – The underlying visual for fetching drawing information.callback (
Optional
[Callable
[[Tuple
[EventType
,Event
],Union
[Text
,Escape
,Control
,Sequence
]],None
]]) – Used ashandle.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 raisingAbort
.
- property mutate
The underlying mutate.
- resolve()
Get the resolved value.
- 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.show (
Optional
[str
]) – Printed before anything else (uncontrollable).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
) – Whetherinfo
is given (or, if callable returns) as astr
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
) – Whetherhint
is given (or, if callable returns) as astr
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 asmutates.Text.lines
.point (
List
[int
]) – Same asmutates.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 asWidget.callback
.delegate (
Optional
[Callable
[[Event
],bool
]]) – Same asWidget.delegate
.validate (
Optional
[Callable
[[Any
],None
]]) – Same asWidget.validate
.funnel_enter (
Optional
[Callable
[[List
[List
[str
]],List
[int
]],None
]]) – Same asvisuals.Text.funnel_enter
.funnel_leave (
Optional
[Callable
[[List
[List
[str
]],Optional
[List
[int
]]],None
]]) – Same asvisuals.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 intoBaseText.lines
.index (
int
) – Where to place in the cursor in relation to its position along the continous text. Converted intoBaseText.point
.
Arguments directly passed to super-class:
🎨 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
orfloat
.- Parameters:
value (
int
) – Converted intoInput.value
.invalid_value_message (
str
) – Used as template to raiseAbort
when the value is invalid.
Arguments directly passed to super-class:
🎨 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:
🎨 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:
Arguments directly passed to super-class:
🎨 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:
Arguments directly passed to super-class:
🎨 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 asmutates.Mesh.score
.create (
Optional
[Callable
[[Tuple
[int
,int
]],Optional
[Any
]]]) – Same asmutates.Mesh.create
.tiles (
Dict
[Tuple
[int
,int
],Any
]) – Same asmutates.Mesh.tiles
. Values should beWidget
instances.point (
List
[int
]) – Same asmutates.Mesh.point
.clean (
Optional
[int
]) – Same asmutates.Mesh.clean
.scout (
Optional
[Callable
[[Tuple
[int
,int
]],bool
]]) – Same asmutates.Mesh.scout
.rigid (
bool
) – Same asmutates.Mesh.rigid
.focus (
Union
[bool
,Callable
[[Event
],bool
]]) – Whenbool
, it is used as the initial focus state. The state can be set toTrue
withEvent.indent
while unfocused, and toFalse
by submitting the focused tile. WhenCallable
, 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 asWidget.callback
.delegate (
Optional
[Callable
[[Event
],bool
]]) – Same asWidget.delegate
.validate (
Optional
[Callable
[[Any
],None
]]) – Same asWidget.validate
.escapable (
bool
) – Same asWidget.escapable
.funnel_enter (
Optional
[Callable
[[Dict
[Tuple
[int
,int
],Tuple
[List
[List
[str
]],List
[int
]]],List
[int
]],None
]]) – Same asvisuals.Mesh.funnel_enter
.funnel_leave (
Optional
[Callable
[[List
[List
[str
]],Optional
[List
[int
]]],None
]]) – Same asvisuals.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 asBaseMesh.tiles
, but it can be any iterable.index (
int
) – Used as theaxis
th element ofBaseMesh.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.
Arguments directly passed to super-class:
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 howBaseMesh
behaves normally).
- class survey.widgets.Select(*args, options=auto, create=None, Option=<class 'survey._widgets.Input'>, **kwargs)
Bases:
BaseList
A single-option selector.
- Parameters:
Arguments directly passed to super-class:
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 intoBaseList.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.Stamp (
Select
) – Used to convertpositive_mark
ornegative_mark
to tiles.
Arguments directly passed to super-class:
focus
- Set to aCallable
that delegates arrow events based on axis.delimit
- Defaults to' '
whenBaseList.axis
is set to1
Arguments used for
Option
:value
- Set to each option upon creation.
Arguments used for
Stamp
:axis
- Set to to the opposite ofBaseList.axis
.options
- Set to atuple
ofnegative_mark
andpositive_mark
index
- Set to either0
or1
depending on whether the option’s index is inactive
.view_max
- Set to1
.focus_color
- Set toNone
.callback
- Set to aCallable
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:
Arguments directly passed to super-class:
Arguments used for
Numeric
:🎨 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:
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 to1
.tiles
- Created fromvalue
’s attributes usingattrs
andChron
.focus
- Set to aCallable
that delegatesarrow_up
,arrow_down
,insert
anddelete_left
.
Arguments used for
Chron
:value
- Set to each numeric value for each part.decimal
- Set toFalse
.convert
- Set to aCallable
that returns the rollingdatetime.datetime
’s value after attempting to set it.Numeric
- Set to a partialNumeric
(see later for arguments).focus_color
- Set toNone
.
Arguments used for
Chron
’sNumeric
: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:
Arguments directly passed to super-class:
axis
- Set to1
focus_color
- Set toNone
.evade_color
- Set toNone
.
Arguments used for
Field
:value
- Set to each pair’s field.funnel_leave
- Set to aCallable
that aligns with others fields and includesdelimit
.
🎨 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
-
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:
'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:
'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.
'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.
'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()
andtext_max_vertical()
.
- 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:
'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:
'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_bottom (
str
) – Used on the last 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, ' ')
andtext_bloat_horizontal(JustType.center, 2, ' ')
before this to avoid content overwrite.
- survey.funnels.text_paint(color)
Paint each rune of each line.
'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
[[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’sspot
to the function’s arguments.
- survey.funnels.mesh_delimit(axis, text)
Insert text between tiles.
- 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.
- 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
fill
ing with new tiles.
- 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:
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:
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)
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:
- survey.colors.basic(fg=None, bg=None)
Get a basic ansi color by path (4 bit docs).
- Parameters:
- Return type:
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:
- Return type:
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:
- Parma layer:
Whether it’s foreground (
'fg'
) or background ('bg'
).- Return type:
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.
- 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.
- class survey.mutates.Text(lines, point)
Bases:
Mutate
A mutate for a block of text and a cursor among it.
- Parameters:
- insert(runes)
Insert text at the current cursor position and move it accordingly.
- move_y(size)
Move the cursor verticaly, wrapping to the max width of the new line as necessary.
- move_x(size)
Move the cursor horizontally, wrapping to the next or last line as necessary.
- delete(size)
Delete ahead of the cursor, including newlines.
- 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 returnNone
to prevent creation.tiles (
Dict
[Tuple
[int
,int
],Any
]) – The manipulating tiles.
- 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 cur_tile
The current tile.
- insert(spot)
Attempt to insert a tile.
If one already exists or gets created, it is returned.
- delete(spot)
Attempt to delete a tile
If one exists, it is returned.
- move(direction)
Move the cursor to the nearest tile.
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.
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 inget()
.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.
- 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 fetchingdata
.funnel_enter (
Optional
[Callable
[[List
[List
[str
]],List
[int
]],None
]]) – Used for mutatingdata
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 transformingdata
.
- 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)
- 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 likeget()
and return(lines, point)
Handle
Handling incoming events and their information by delegating to functions that can handle them.
- class survey.handle.EventType(value)
-
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.
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()
A context manager for hiding the cursor.
with cursor.hidden: ...
- up(size=None)
Move up. No effect if at the edge of the screen.
- down(size=None)
Move down. No effect if at the edge of the screen.
- left(size=None)
Move left. No effect if at the edge of the screen.
- right(size=None)
Move right. No effect if at the edge of the screen.
- goto(x=None)
Move absolutely on line.
- last(size=None)
Move up at line start.
- next(size=None)
Move down at line start.
- move(y=None, x=None)
Move absolutely on screen.
- clear(mode=None)
Clear the screen.
- Parameters:
mode (
Optional
[ClearMode
]) – Denotes which part of the screen to clear. System default is usuallyClearMode.right
.
- erase(mode=None)
Erase the line.
- Parameters:
mode (
Optional
[EraseMode
]) – Denotes which part of the screen to clear. System default is usuallyEraseMode.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.
- 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:
- listen()
Begin listening for events.
- class survey.core.Event
-
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.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.
- draw(lines, point=None, *, clean=True, learn=True)
Draw lines and place the cursor among them.
- back()
Move the cursor to the position it was before drawing.
- class survey.core.Screen(render)
Bases:
object
Encapsulates the visualization logic.
- Parameters:
- 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 asRender.draw.clean
.learn (
bool
) – Same asRender.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.Console(handle, screen)
Bases:
object
Standardizes interaction with the IO into a wait-receive-invoke loop.
- start(sketch, invoke)
Creates an invokation-visualization loop.
sketch
is used for the initial print.invoke
is used once input is received.sketch
is used for the updated print.Repeat from step 2 until
handle.Terminate
gets raised.
- exception survey.core.SkipDraw
Bases:
Exception
Signals the invokation loop to not skip drawing for the current turn.
ansi
- 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.
- survey.core.ansi.get_escape(code, *args)
Get the escape sequence of
code
withargs
.- Return type: