pages.py

Submodule containing the factories & page objects to create Tembo pages.

Page

Abstract Page class.

This interface is used to define a Page object.

A Page represents a note/page that will be saved to disk.

Abstract

This object is an abstract base class and should be implemented for each Page type.

path: pathlib.Path property readonly

When implemented this should return the full path of the page including the filename.

Returns:

Type	Description
pathlib.Path	the path as a Path object.

Abstract

This property is abstract and should be implemented for each Page type.

__init__(self, path, page_content) special

When implemented this should initalise a Page object.

Parameters:

Name	Type	Description	Default
path	pathlib.Path	the full path of the page including the filename as a Path.	required
page_content	str	the contents of the page.	required

Abstract

This method is abstract and should be implemented for each Page type.

Source code in tembo/journal/pages.py

@abstractmethod
def __init__(self, path: pathlib.Path, page_content: str) -> None:
    """
    When implemented this should initalise a Page object.

    Args:
        path (pathlib.Path): the full path of the page including the filename as a
            [Path][pathlib.Path].
        page_content (str): the contents of the page.

    !!! abstract
    This method is abstract and should be implemented for each `Page` type.
    """
    raise NotImplementedError

save_to_disk(self)

When implemented this should save the page to disk.

Returns:

Type	Description
tembo.utils.Success	A Tembo Success object.

Abstract

This method is abstract and should be implemented for each Page type.

Source code in tembo/journal/pages.py

@abstractmethod
def save_to_disk(self) -> tembo.utils.Success:
    """
    When implemented this should save the page to disk.

    Returns:
        tembo.utils.Success: A Tembo [Success][tembo.utils.__init__.Success] object.

    !!! abstract
    This method is abstract and should be implemented for each `Page` type.
    """
    raise NotImplementedError

PageCreator

A PageCreator factory base class.

This factory should implement methods to create Page objects.

Abstract

This factory is an abstract base class and should be implemented for each Page type.

The private methods

• _check_base_path_exists()
• _convert_base_path_to_path()
• _load_template()

are not abstract and are shared between all Page types.

options: PageCreatorOptions property readonly

When implemented this should return the PageCreatorOptions on the class.

Returns:

Type	Description
PageCreatorOptions	the instance of PageCreatorOptions set on the class.

Abstract

This method is abstract and should be implemented for each Page type.

__init__(self, options) special

When implemented this should initialise the PageCreator factory.

Parameters:

Name	Type	Description	Default
options	PageCreatorOptions	An instance of PageCreatorOptions	required

Abstract

This method is abstract and should be implemented for each Page type.

Source code in tembo/journal/pages.py

@abstractmethod
def __init__(self, options: PageCreatorOptions) -> None:
    """
    When implemented this should initialise the `PageCreator` factory.

    Args:
        options (PageCreatorOptions): An instance of
            [PageCreatorOptions][tembo.journal.pages.PageCreatorOptions]

    !!! abstract
    This method is abstract and should be implemented for each
    [Page][tembo.journal.pages.Page] type.
    """
    raise NotImplementedError

create_page(self)

When implemented this should create a Page object.

Returns:

Type	Description
Page	an implemented instance of Page such as ScopedPage.

Abstract

This method is abstract and should be implemented for each Page type.

Source code in tembo/journal/pages.py

@abstractmethod
def create_page(self) -> Page:
    """
    When implemented this should create a `Page` object.

    Returns:
        Page: an implemented instance of [Page][tembo.journal.pages.Page] such as
            [ScopedPage][tembo.journal.pages.ScopedPage].

    !!! abstract
    This method is abstract and should be implemented for each
    [Page][tembo.journal.pages.Page] type.
    """
    raise NotImplementedError

PageCreatorOptions dataclass

Options dataclass to create a Page.

This is passed to an implemented instance of PageCreator

Attributes:

Name	Type	Description
base_path	str	The base path.
page_path	str	The path of the page relative to the base path.
filename	str	The filename of the page.
extension	str	The extension of the page.
name	str	The name of the scope.
user_input	Collection[str] | None	User input tokens.
example	str | None	User example command.
template_path	str | None	The path which contains the templates. This should be the full path and not relative to the base path.
template_filename	str | None	The template filename with extension relative to the template path.

ScopedPage (Page)

A page that uses substitute tokens.

Attributes:

Name	Type	Description
path	pathlib.Path	a Path object of the page's filepath including the filename.
page_content	str	the content of the page from the template.

path: pathlib.Path property readonly

Return the full path of the page.

Returns:

Type	Description
pathlib.path	The full path of the page as a Path object.

__init__(self, path, page_content) special

Initalise a scoped page object.

Parameters:

Name	Type	Description	Default
path	pathlib.Path	a Path object of the page's filepath including the filename.	required
page_content	str	the content of the page from the template.	required

Source code in tembo/journal/pages.py

def __init__(self, path: pathlib.Path, page_content: str) -> None:
    """
    Initalise a scoped page object.

    Args:
        path (pathlib.Path): a [Path][pathlib.Path] object of the page's filepath including
            the filename.
        page_content (str): the content of the page from the template.
    """
    self._path = path
    self.page_content = page_content

__str__(self) special

Return a str representation of a ScopedPage.

Examples:

>>> str(ScopedPage(Path("/home/bob/tembo/meetings/my_meeting_0.md"), ""))
ScopedPage("/home/bob/tembo/meetings/my_meeting_0.md")

Returns:

Type	Description
str	The ScopedPage as a str.

Source code in tembo/journal/pages.py

def __str__(self) -> str:
    """
    Return a `str` representation of a `ScopedPage`.

    Examples:
        ```
        >>> str(ScopedPage(Path("/home/bob/tembo/meetings/my_meeting_0.md"), ""))
        ScopedPage("/home/bob/tembo/meetings/my_meeting_0.md")
        ```

    Returns:
        str: The `ScopedPage` as a `str`.
    """
    return f'ScopedPage("{self.path}")'

save_to_disk(self)

Save the scoped page to disk and write the page_content.

Exceptions:

Type	Description
exceptions.ScopedPageAlreadyExists	If the page already exists a ScopedPageAlreadyExists exception is raised.

Returns:

Type	Description
tembo.utils.Success	A Success with the path of the ScopedPage as the message.

Source code in tembo/journal/pages.py

def save_to_disk(self) -> tembo.utils.Success:
    """
    Save the scoped page to disk and write the `page_content`.

    Raises:
        exceptions.ScopedPageAlreadyExists: If the page already exists a
            [ScopedPageAlreadyExists][tembo.exceptions.ScopedPageAlreadyExists] exception
            is raised.

    Returns:
        tembo.utils.Success: A [Success][tembo.utils.__init__.Success] with the path of the
            ScopedPage as the message.
    """
    # create the parent directories
    scoped_page_file = pathlib.Path(self.path)
    scoped_page_file.parents[0].mkdir(parents=True, exist_ok=True)
    if scoped_page_file.exists():
        raise exceptions.ScopedPageAlreadyExists(f"{self.path} already exists")
    with scoped_page_file.open("w", encoding="utf-8") as scoped_page:
        scoped_page.write(self.page_content)
    return tembo.utils.Success(str(self.path))

ScopedPageCreator (PageCreator)

Factory to create a scoped page.

Attributes:

Name	Type	Description
base_path	str	base path of tembo.
page_path	str	path of the page relative to the base path.
filename	str	filename relative to the page path.
extension	str	extension of file.

options: PageCreatorOptions property readonly

Return the PageCreatorOptions instance set on the factory.

Returns:

Type	Description
PageCreatorOptions	An instance of PageCreatorOptions.

__init__(self, options) special

Initialise a ScopedPageCreator factory.

Parameters:

Name	Type	Description	Default
options	PageCreatorOptions	An instance of PageCreatorOptions.	required

Source code in tembo/journal/pages.py

def __init__(self, options: PageCreatorOptions) -> None:
    """
    Initialise a `ScopedPageCreator` factory.

    Args:
        options (PageCreatorOptions): An instance of
            [PageCreatorOptions][tembo.journal.pages.PageCreatorOptions].
    """
    self._all_input_tokens: list[str] = []
    self._options = options

create_page(self)

Create a ScopedPage object.

This method will

• Check the base_path exists
• Verify the input tokens match the number defined in the config.yml
• Substitue the input tokens in the filepath
• Load the template contents and substitue the input tokens

Exceptions:

Type	Description
exceptions.MismatchedTokenError	Raises MismatchedTokenError if the number of input tokens does not match the number of unique input tokens defined.
exceptions.BasePathDoesNotExistError	Raises BasePathDoesNotExistError if the base path does not exist.
exceptions.TemplateFileNotFoundError	Raises TemplateFileNotFoundError if the template file is specified but not found.

Returns:

Type	Description
Page	A ScopedPage object using the PageCreatorOptions.

Source code in tembo/journal/pages.py

def create_page(self) -> Page:
    """
    Create a [ScopedPage][tembo.journal.pages.ScopedPage] object.

    This method will

    - Check the `base_path` exists
    - Verify the input tokens match the number defined in the `config.yml`
    - Substitue the input tokens in the filepath
    - Load the template contents and substitue the input tokens

    Raises:
        exceptions.MismatchedTokenError: Raises
            [MismatchedTokenError][tembo.exceptions.MismatchedTokenError] if the number of
            input tokens does not match the number of unique input tokens defined.
        exceptions.BasePathDoesNotExistError: Raises
            [BasePathDoesNotExistError][tembo.exceptions.BasePathDoesNotExistError] if the
            base path does not exist.
        exceptions.TemplateFileNotFoundError: Raises
            [TemplateFileNotFoundError][tembo.exceptions.TemplateFileNotFoundError] if the
            template file is specified but not found.


    Returns:
        Page: A [ScopedPage][tembo.journal.pages.ScopedPage] object using the
            `PageCreatorOptions`.
    """
    try:
        self._check_base_path_exists()
    except exceptions.BasePathDoesNotExistError as base_path_does_not_exist_error:
        raise base_path_does_not_exist_error
    self._all_input_tokens = self._get_input_tokens()
    try:
        self._verify_input_tokens()
    except exceptions.MismatchedTokenError as mismatched_token_error:
        raise mismatched_token_error

    path = self._convert_base_path_to_path()
    path = pathlib.Path(self._substitute_tokens(str(path)))

    try:
        template_contents = self._load_template()
    except exceptions.TemplateFileNotFoundError as template_not_found_error:
        raise template_not_found_error
    if self.options.template_filename is not None:
        template_contents = self._substitute_tokens(template_contents)

    return ScopedPage(path, template_contents)