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:

from evennia.utils import evmore

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

Where always_page 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

key = '__noinput_command'

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

auto_help = False

func()

Implement the command

help_category = 'general'

lock_storage = 'cmd:all();'

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

Bases: evennia.commands.command.Command

Override look to display window and prevent OOCLook from firing

key = 'look'

aliases = ['l']

auto_help = False

func()

Implement the command

help_category = 'general'

lock_storage = 'cmd:all();'

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

Bases: evennia.commands.cmdset.CmdSet

Stores the more command

key = 'more_commands'

priority = 110

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 input handler.

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 (backslash + f) format symbols, 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, any) – These will be passed on to the caller.msg method.

Examples

Basic use:

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

Paginated query data - this is an optimization to avoid fetching database data until it’s actually paged to.

from django.core.paginator import Paginator

query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)

Automatic split EvTable over multiple EvMore pages

table = EvMore(*header, table=tabledata)
EvMore(caller, table)

Every page a separate EvTable (optimization for very large data sets)

from evennia import EvTable, EvMore

class TableEvMore(EvMore):
    def init_pages(self, data):
        pages = # depends on data type
        super().init_pages(pages)

    def page_formatter(self, page):
        table = EvTable()

        for line in page:
            cols = # split raw line into columns
            table.add_row(*cols)

        return str(table)

TableEvMore(caller, pages)

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 (backslash + 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.

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.

Parameters

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

• text (str, EvTable or iterator) –

  The text or data to put under paging.

  • If a string, paginage normally. If this text contains one or more \f (backslash + f) format symbol, automatic pagination is 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 text is converted to an iterator, where each step is is expected to be a line in the final display, and each line will be run through repr().

• always_page (bool, optional) – If False, the pager will only kick in if text 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, justify long lines in output. Disable for fixed-format output, like tables.

• justify_kwargs (dict, bool or None, optional) – If given, this should be valid keyword arguments to the utils.justify() function. If False, no justification will be done.

• exit_on_lastpage (bool, optional) – Immediately exit pager when reaching the last page.

• use_evtable (bool, optional) – If True, each page will be rendered as an EvTable. For this to work, text must be an iterable, where each element is the table (list of list) to render on that page.

• evtable_args (tuple, optional) – The args to use for EvTable on each page.

• evtable_kwargs (dict, optional) – The kwargs to use for EvTable on each page (except table, which is supplied by EvMore per-page).

• kwargs (any, optional) – These will be passed on to the caller.msg method.