Numerous functions missing from the documentation/docs

[InconsolableCellist]

I was trying to use the reference section of the documentation to learn how to use floats, and I found numerous missing functions. As a brief example, from containers.py:

_Split:
is_modal
get_key_bindings
get_children

HSplit;
preferred_width
preferred_height
reset

VSplit:
preferred_width
preferred_height
reset

FloatContainer:
reset
preferred_width
write_to_screen
_draw_float
is_modal
get_key_bindings
get_children

Float:
get_width
get_height
__repr__

WindowRenderInfo
visible_line_to_input_line

ScrollOffsets:
top
bottom
left
right

Window:
reset
_write_to_screen_at_index
copy
_apply_style

Etc.

Some of these may be private or functionally equivalent to parent functions, but in those cases the docs should link to the parent functions, or at the very least link to the intended parent object, which currently isn't the case. Some of the above undocumented functions are also unique to the classes.

Trying to learn how to use a library when the reference docs can't be trusted to be complete is very frustrating. Specifically I wanted to know how to hide floats or dialogs, and I didn't know if a hide() function was missing because the docs are incomplete or because the function doesn't exist. It basically means I have to rely on examples and Google instead of what should be the most trustworthy source for information.

[jonathanslenders]

Hi @InconsolableCellist,

This is good feedback. I'm well aware that the documentation for building full screen applications is lacking. Plus, while more and more applications are built, we discover that better APIs are needed.

Regarding your question. show/hide methods don't exist. Instead, there is a ConditionalContainer that can conditionally hide or show something depending on a condition. See: https://python-prompt-toolkit.readthedocs.io/en/master/pages/reference.html#prompt_toolkit.layout.ConditionalContainer Check the filters documentation about how to build such a filter: https://python-prompt-toolkit.readthedocs.io/en/master/pages/advanced_topics/filters.html

If you want a show/hide method, this can be implemented as follows:

from prompt_toolkit.layout import ConditionalContainer, Container
from prompt_toolkit.filters import Condition

class ShowOrHideContainer(ConditionalContainer):
    """
    Wrap any other container object and make it possible to show or hide it.
    """
    def __init__(self, content: Container):
        self.visible = True

        @Condition
        def is_visible():
            return self.visible

        super().__init__(
            filter=is_visible,
            content=content)

    def show(self):
        self.visible = True

    def hide(self):
        self.visible = False

Usually, I think you don't need this kind of helper, as in practice, the condition is somewhere else already, and you want the reactivity of the filters and ConditionalContainer to do the job.

Feel free to open an issue if you have further questions. I can answer when I have time. The documentation should improve over time.

Cheers, Jonathan

[MrMino]

@InconsolableCellist @jonathanslenders For the record: I'm jumping around adding some of these docstrings as I go. When building my apps, my MO for gathering information has been so far: look at the reference, look at the code, search through github issues (in this order).

I doubt you can feasibly cover all of the usage in the docs. At some point you just get a feel for the library. As long as an API keeps its Halstead Complexity Measures in order, you'll be able to get intuitions for things pretty easily, and I suspect that prompt_toolkit does, because I was able to grasp most of it in less than a day.

That said, if you'd like, you can compile a list of methods that you're missing from the docs (in the order of subjective importance) for me, and I'll try and do my best to document them.