evennia.utils.evmore

EvMore - pager mechanism

This is a pager for displaying long texts and allows stepping up and down in the text (the name comes from the traditional ‘more’ unix command).

To use, simply pass the text through the EvMore object:

from evennia.utils.evmore import EvMore

text = some_long_text_output()
EvMore(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

One can also use the convenience function msg from this module to avoid having to set up the EvMenu object manually:

from evennia.utils import evmore

text = some_long_text_output()
evmore.msg(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

The always_page argument decides if the pager is used also if the text is not long enough to need to scroll, session is used to determine which session to relay to and justify_kwargs are kwargs to pass to utils.utils.justify in order to change the formatting of the text. The remaining **kwargs will be passed on to the caller.msg() construct every time the page is updated.

---

class evennia.utils.evmore.CmdMore(**kwargs)

Bases: evennia.commands.command.Command

Manipulate the text paging. Catch no-input with aliases.

key = '__noinput_command'

aliases = ['top', 'e', 'n', 'end', 't', 'abort', 'next', 'a', 'p', 'previous', 'quit', 'q']

auto_help = False

func()

Implement the command

help_category = 'general'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'top e n end t abort next a p previous quit q', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' top e n end t abort next a p previous quit q', 'tags': '', 'text': '\n Manipulate the text paging. Catch no-input with aliases.\n '}

class evennia.utils.evmore.CmdMoreExit(**kwargs)

Bases: evennia.commands.command.Command

Any non-more command will exit the pager.

key = '__nomatch_command'

func()

Exit pager and re-fire the failed command.

aliases = []

help_category = 'general'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'general', 'key': '__nomatch_command', 'no_prefix': ' ', 'tags': '', 'text': '\n Any non-more command will exit the pager.\n\n '}

class evennia.utils.evmore.CmdSetMore(cmdsetobj=None, key=None)

Bases: evennia.commands.cmdset.CmdSet

Stores the more command

key = 'more_commands'

priority = 110

mergetype = 'Replace'

at_cmdset_creation()

Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

path = 'evennia.utils.evmore.CmdSetMore'

evennia.utils.evmore.queryset_maxsize(qs)

class evennia.utils.evmore.EvMore(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Bases: object

The main pager object

__init__(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Initialization of the EvMore pager.

Parameters

• caller (Object or Account) – Entity reading the text.

• inp (str, EvTable, Paginator or iterator) –

  The text or data to put under paging.

  • If a string, paginage normally. If this text contains one or more \f format symbol, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

  • If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

  • Otherwise inp is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

• always_page (bool, optional) – If False, the pager will only kick in if inp is too big to fit the screen.

• session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

• justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if inp is an EvTable.

• justify_kwargs (dict, optional) – Keywords for the justify function. Used only if justify is True. If this is not set, default arguments will be used.

• exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

• exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

• kwargs (any, optional) – These will be passed on to the caller.msg method. Notably, one can pass additional outputfuncs this way. There is one special kwarg: - text_kwargs - extra kwargs to pass with the text outputfunc, e.g. text_kwargs={“type”: “help”} would result to each page being sent to msg as text=(pagetxt, {“type”: “help”}).

Examples

super_long_text = " ... "
EvMore(caller, super_long_text)

Paginator

from django.core.paginator import Paginator
query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)

Every page an EvTable

from evennia import EvTable
def _to_evtable(page):
    table = ... # convert page to a table
    return EvTable(*headers, table=table, ...)
EvMore(caller, pages, page_formatter=_to_evtable)

display(show_footer=True)

Pretty-print the page.

page_top()

Display the top page

page_end()

Display the bottom page.

page_next()

Scroll the text to the next page. Quit if already at the end of the page.

page_back()

Scroll the text back up, at the most to the top.

page_quit(quiet=False)

Quit the pager

start()

Starts the pagination

paginator_index(pageno)

Paginate to specific, known index

paginator_slice(pageno)

Paginate by slice. This is done with an eye on memory efficiency (usually for querysets); to avoid fetching all objects at the same time.

paginator_django(pageno)

Paginate using the django queryset Paginator API. Note that his is indexed from 1.

init_evtable(table)

The input is an EvTable.

init_queryset(qs)

The input is a queryset

init_django_paginator(pages)

The input is a django Paginator object.

init_iterable(inp)

The input is something other than a string - convert to iterable of strings

init_f_str(text)

The input contains f markers. We use f to indicate the user wants to enforce their line breaks on their own. If so, we do no automatic line-breaking/justification at all.

Parameters

text (str) – The string to format with f-markers.

init_str(text)

The input is a string

init_pages(inp)

Initialize the pagination. By default, will analyze input type to determine how pagination automatically.

Parameters

inp (any) – Incoming data to be paginated. By default, handles pagination of strings, querysets, django.Paginator, EvTables and any iterables with strings.

Notes

If overridden, this method must perform the following actions:

• read and re-store self._data (the incoming data set) if needed for pagination to work.

• set self._npages to the total number of pages. Default is 1.

• set self._paginator to a callable that will take a page number 1…N and return the data to display on that page (not any decorations or next/prev buttons). If only wanting to change the paginator, override self.paginator instead.

• set self._page_formatter to a callable that will receive the page from self._paginator and format it with one element per line. Default is str. Or override self.page_formatter directly instead.

By default, helper methods are called that perform these actions depending on supported inputs.

paginator(pageno)

Paginator. The data operated upon is in self._data.

Parameters

pageno (int) – The page number to view, from 0…N-1

Returns

str –

The page to display (without any decorations, those are added

by EvMore).

page_formatter(page)

Page formatter. Every page passes through this method. Override it to customize behavior per-page. A common use is to generate a new EvTable for every page (this is more efficient than to generate one huge EvTable across many pages and feed it into EvMore all at once).

Parameters

page (any) – A piece of data representing one page to display. This must

Returns

str –

A ready-formatted page to display. Extra footer with help about

switching to the next/prev page will be added automatically

evennia.utils.evmore.msg(caller, text='', always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=True, **kwargs)

EvMore-supported version of msg, mimicking the normal msg method.

Initialization of the EvMore pager.

Parameters

• caller (Object or Account) – Entity reading the text.

• inp (str, EvTable, Paginator or iterator) –

  The text or data to put under paging.

  • If a string, paginage normally. If this text contains one or more \f format symbol, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

  • If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

  • Otherwise inp is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

• always_page (bool, optional) – If False, the pager will only kick in if inp is too big to fit the screen.

• session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

• justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if inp is an EvTable.

• justify_kwargs (dict, optional) – Keywords for the justify function. Used only if justify is True. If this is not set, default arguments will be used.

• exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

• exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

• kwargs (any, optional) – These will be passed on to the caller.msg method. Notably, one can pass additional outputfuncs this way. There is one special kwarg: - text_kwargs - extra kwargs to pass with the text outputfunc, e.g. text_kwargs={“type”: “help”} would result to each page being sent to msg as text=(pagetxt, {“type”: “help”}).

Examples

super_long_text = " ... "
EvMore(caller, super_long_text)

Paginator

from django.core.paginator import Paginator
query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)

Every page an EvTable

from evennia import EvTable
def _to_evtable(page):
    table = ... # convert page to a table
    return EvTable(*headers, table=table, ...)
EvMore(caller, pages, page_formatter=_to_evtable)