almanac.pages

class AbstractPage(path: Union[str, almanac.pages.page_path.PagePath])

Bases: abc.ABC

The base abstract page interface.

property children

The immediate children of this page.

abstract get_prompt() → str

Return the prompt text for this page.

This is what is shown on the application’s current line, acting as the input prompt.

abstract property help_text

The help text about this page.

Think of this as a static explanation about the page type’s role within the greater application, rather than reflecting the current state of this particular page.

abstract property info_text

The info text about this page.

Think of this as a more dynamic output (in contrast to help_text()), which reflect the current state of this page.

property parent

The parent page of this page.

property path

This page’s path.

class DirectoryPage(path: Union[str, almanac.pages.page_path.PagePath])

Bases: almanac.pages.abstract_page.AbstractPage

A page that holds references to other pages.

get_prompt() → str

Return the prompt text for this page.

This is what is shown on the application’s current line, acting as the input prompt.

property help_text

The help text about this page.

Think of this as a static explanation about the page type’s role within the greater application, rather than reflecting the current state of this particular page.

property info_text

The info text about this page.

Think of this as a more dynamic output (in contrast to help_text()), which reflect the current state of this page.

class PageNavigator(*args, **kwds)

Bases: collections.abc.MutableMapping, typing.Generic

Encapsulation of page navigation and history logic.

add_directory_page(path: Union[str, almanac.pages.page_path.PagePath]) → almanac.pages.directory_page.DirectoryPage

Add a directory page at the specified path.

This method is only used for adding pages that do not already exist. It will also create any intermediate directories within the path that do not already exist.

Returns

The created DirectoryPage.

Raises

BlockedPageOverwriteError – If an existing page would be overwritten by the operation.

>>> from almanac import PageNavigator
>>> p = PageNavigator()
>>> p.add_directory_page('/a_page')
<DirectoryPage [/a_page]>
>>> print(p)
/
/a_page
>>> p.add_directory_page('/a_page/and/some/others')
<DirectoryPage [/a_page/and/some/others]>
>>> print(p)
/
/a_page
/a_page/and
/a_page/and/some
/a_page/and/some/others

back() → None

Move backward in the page history.

change_directory(destination: Union[str, almanac.pages.page_path.PagePath]) → None

Change the current directory of this navigator.

Parameters

destination – The page to change to, which will be exploded into an absolute path.

Raises

• NoSuchPageError – If the specified destination is invalid or does not exist.

• OutOfBoundsPageError – If the specified destination attempts to go above the root directory.

• PathSyntaxError – If a syntactical error occured during the path parsing.

property current_page

The current page within this navigator.

property directory_page_cls

The class used to create new directory pages.

explode(path: Union[str, almanac.pages.page_path.PagePath]) → str

Parse a user-specified path into an absolute path.

Parameters

path – The path to explode (i.e., expand . and ..) into an absolute path. If this is not an absolute path, the navigator’s current path will be used as the starting point.

Returns

The exploded absolute path. This value is not guaranteed to exist within this PageNavigator.

Raises

OutOfBoundsPageError – If invalid parent directors are referenced via the .. operator.

forward() → None

Move forward in the page history.

match(pattern: str) → Iterable[almanac.pages.abstract_page.AbstractPage]

Match stored pages against fnmatch patterns.

property root_page

The root page within this navigator.

set_page(key: Union[str, almanac.pages.page_path.PagePath], value: almanac.pages.abstract_page.AbstractPage, allow_overwrite: bool = True) → None

class PagePath(path: Union[str, almanac.pages.page_path.PagePath])

Bases: object

An encapsulation of an absolute pseudo-filesystem path.

static assert_absolute_path(path: Union[str, almanac.pages.page_path.PagePath]) → None

Assert that the specified path is absolut.

Raises

PathSyntaxError – If the path is not absolute.

property parent_dirs

All parent directory paths of this path.

>>> from almanac import PagePath
>>> print('\n'.join(PagePath('/a/b/c/d/e').parent_dirs))
/
/a
/a/b
/a/b/c
/a/b/c/d

property path

The string path wrapped in this instance.

property segments

The path segments of this class.

>>> from almanac import PagePath
>>> PagePath('/a/b/c').segments
('/', 'a', 'b', 'c')
>>> PagePath('/').segments
('/',)