Full API Documentation

This full API documentation is provided for those who want to understand the internals of Drafter and potentially contribute to the project. If you are looking for user documentation, please refer to the Student Documentation.

get_main_server() → Server

Gets the main server. This is useful for testing purposes.

Returns:

The main server

get_server_setting(key, default=None, server=MAIN_SERVER)

Gets a setting from the server’s configuration. If the setting is not found, the default value is returned.

Parameters:

  • key – The key to look up in the configuration

  • default – The default value to return if the key is not found

  • server – The server to look up the setting in (defaults to the MAIN_SERVER)

Returns:

The value of the setting, or the default value if not found

set_main_server(server: Server)

Sets the main server to the given server. This is useful for testing purposes.

Parameters:

server – The server to set as the main server

Returns:

None

start_server(initial_state=None, server: Server = MAIN_SERVER, skip=False, **kwargs)

Starts the server with the given initial state and configuration. If the server is set to skip, it will not start. Additional keyword arguments will be passed to the server’s run method, and therefore to Bottle. This can be used to control things like the port.

Parameters:

  • initial_state – The initial state to start the server with

  • server – The server to run on, defaulting to MAIN_SERVER

  • skip – If True, the server will not start; this is useful for running tests headlessly

  • kwargs – Additional keyword arguments to pass to the server’s run method. See below.

Returns:

None

Keyword Arguments:

  • port (int) – The port to run the server on. Defaults to 8080

class BakeryTestCase(args: tuple, kwargs: dict, result: Any, line: int, caller: str)
assert_equal(*args, **kwargs)

Pointless definition of assert_equal to avoid errors

diff_tests(left, right, left_name, right_name)

Compare two strings and show the differences in a table.

route(url: Callable | str | None = None, server: Server | None = None)

Main function to add a new route to the server. Recommended to use as a decorator. Once added, the route will be available at the given URL; the function name will be used if no URL is provided. When you go to the URL, the function will be called and its return value will be displayed.

Parameters:

  • url – The URL to add the route to. If None, the function name will be used.

  • server – The server to add the route to. Defaults to the main server.

Returns:

The modified route function.

class Page(state, content=None)

A page is a collection of content to be displayed to the user. This content has two critical parts:

  • The state, which is the current value of the backend server for this user’s session. This is used to restore the state of the page when the user navigates back to it. Typically, this will be a dataclass or a dictionary, but could also be a list, primitive value, or even None.

  • The content, which is a list of strings and components that will be rendered to the user.

The content of a page can be any combination of strings and components. Strings will be rendered as paragraphs, while components will be rendered as their respective HTML. Components should be classes that inherit from drafter.components.PageContent. If the content is not a list, a ValueError will be raised.

Parameters:

  • state – The state of the page. If only one argument is provided, this will default to be None.

  • content – The content of the page. Must always be provided as a list of strings and components.

make_reset_button() → str

Creates a reset button that has the “reset” icon and title text that says “Resets the page to its original state.”. Simply links to the “–reset” URL.

Returns:

A string of HTML representing the reset button.

render_content(current_state, configuration: ServerConfiguration) → str

Renders the content of the page to HTML. This will include the state of the page, if it is restorable. Users should not call this method directly; it will be called on their behalf by the server.

Parameters:

  • current_state – The current state of the server. This will be used to restore the page if needed.

  • configuration – The configuration of the server. This will be used to determine how the page is rendered.

Returns:

A string of HTML representing the content of the page.

verify_content(server) → bool

Verifies that the content of the page is valid. This will check that all links are valid and that all components are valid. This is not meant to be called by the user; it will be called by the server.

Parameters:

server – The server to verify the content against.

Returns:

True if the content is valid, False otherwise.

class ConversionRecord(parameter: str, value: Any, expected_type: Any, converted_value: Any)
class UnchangedRecord(parameter: str, value: Any, expected_type: Any = None)
class VisitedPage(url: str, function: Callable, arguments: str, status: str, button_pressed: str, original_page_content: Optional[str] = None, old_state: Any = None, started: datetime.datetime = <factory>, stopped: Optional[datetime.datetime] = None)
add_website_css(selector: str, css: str | None = None)

Adds additional CSS content to the website. This is useful for adding custom CSS to the website, either for specific selectors or for general styles. If you only provide one parameter, it will be wrapped in <style> tags. If you provide both parameters, they will be used to create a CSS rule; the first parameter is the CSS selector, and the second parameter is the CSS content that will be wrapped in {}.

Parameters:

  • selector – The CSS selector to apply the CSS to, or the CSS content if the second parameter is None.

  • css – The CSS content to apply to the selector.

add_website_header(header: str)

Adds additional header content to the website. This is useful for adding custom CSS or JavaScript to the website, or other arbitrary header tags like meta tags.

Parameters:

header – The raw header content to add. This will not be wrapped in additional tags.

default_index(state) → Page

The default index page for the website. This will show a simple “Hello world!” message. You should not modify or use this function; instead, create your own index page.

deploy_site(image_folder='images')

Deploys the website with the given image folder. This will set the production flag to True and turn off debug information, too.

Parameters:

image_folder – The folder where images are stored.

hide_debug_information()

Hides debug information from the website, so that it will not appear. Useful for deployed websites.

set_website_framed(framed: bool)

Sets whether the website should be framed or not. If you are deploying the website, then this would be a common thing to set to False.

Parameters:

framed – Whether the website should be framed or not.

set_website_style(style: str | None)

Sets the style of the website. This is a string that will be used to determine the CSS style of the website from the available styles (e.g., skeleton, bootstrap). This list will be expanded in the future.

Parameters:

style – The style of the website.

set_website_title(title: str)

Sets the title of the website, as it appears in the browser tab.

Parameters:

title – The title of the website.

show_debug_information()

Shows debug information on the website. Useful for development.

class DebugInformation(page_history: List[Tuple[drafter.history.VisitedPage, Any]], state: Any, routes: Dict[str, Callable], conversion_record: List[drafter.history.ConversionRecord], configuration: drafter.configuration.ServerConfiguration)

TODO: Custom Error pages Shareable link to get a link to the current page Download/upload state button

class ServerConfiguration(host: str = 'localhost', port: int = 8080, debug: bool = True, backend: str = 'bottle', reloader: bool = False, skip: bool = False, title: str = 'Drafter Website', framed: bool = True, skulpt: bool = False, style: str = 'skeleton', additional_header_content: ~typing.List[str] = <factory>, additional_css_content: ~typing.List[str] = <factory>, src_image_folder: str = '', save_uploaded_files: bool = True, deploy_image_path: str = 'images')

Configuration for the server.

class Argument(name: str, value: Any, **kwargs)
Box

alias of Div

class BulletedList(items: List[Any], **kwargs)
class Button(text: str, url: str, arguments=None, **kwargs)
class CheckBox(name: str, default_value: bool = False, **kwargs)
class Div(*args, **kwargs)
Division

alias of Div

class Download(text: str, filename: str, content: str, content_type: str = 'text/plain')
class FileUpload(name: str, accept: str | List[str] | None = None, **kwargs)

A file upload component that allows users to upload files to the server.

This works by creating a hidden input field that stores the file data as a JSON string. That input is sent, but the file data is not sent directly.

The accept field can be used to specify the types of files that can be uploaded. It accepts either a literal string (e.g. “image/*”) or a list of strings (e.g. [“image/png”, “image/jpeg”]). You can either provide MIME types, extensions, or extensions without a period (e.g., “png”, “.jpg”).

To have multiple files uploaded, use the multiple attribute, which will cause the corresponding parameter to be a list of files.

class Header(body: str, level: int = 1)
class HorizontalRule
class Image(url: str, width=None, height=None, **kwargs)
class LineBreak
class MatPlotLibPlot(extra_matplotlib_settings=None, close_automatically=True, **kwargs)
class NumberedList(items: List[Any], **kwargs)
class PageContent

Base class for all content that can be added to a page. This class is not meant to be used directly, but rather to be subclassed by other classes. Critically, each subclass must implement a __str__ method that returns the HTML representation.

Under most circumstances, a string value can be used in place of a PageContent object (in which case we say it is a Content type). However, the PageContent object allows for more customization and control over the content.

Ultimately, the PageContent object is converted to a string when it is rendered.

This class also has some helpful methods for verifying URLs and handling attributes/styles.

Picture

alias of Image

class Pre(*args, **kwargs)
PreformattedText

alias of Pre

class Row(*args, **kwargs)
class SelectBox(name: str, options: List[str], default_value: str | None = None, **kwargs)
class Span(*args, **kwargs)
SubmitButton

alias of Button

class Table(rows: List[List[str]], header=None, **kwargs)
class Text(body: str, **kwargs)
class TextArea(name: str, default_value: str | None = None, **kwargs)
class TextBox(name: str, default_value: str | None = None, kind: str = 'text', **kwargs)

TODO: - [ ] indent - [ ] center - [ ] Superscript, subscript - [ ] border/margin/padding (all sides)

float_left(component: PageContent) → PageContent

Floats the component to the left.

Parameters:

component – The component to float left

Returns:

Returns the original component (updated)

float_right(component: PageContent | str) → PageContent

Floats the component to the right.

Parameters:

component – The component to float right

Returns:

Returns the original component (updated)

update_attr(component: PageContent | str, attr: str, value: str) → PageContent

Updates the attribute of a component, returning the component (allowing you to chain calls). The attr property should match the HTML attribute name.

Example attributes include: - id - class - title

Parameters:

  • component – The component to update

  • attr – The name of the attribute to change

  • value – The value to set the attribute to (should be a string).

Returns:

Returns the original component (updates its values)

update_style(component: PageContent | str, style: str, value: str) → PageContent

Updates the style of a component, returning the component (allowing you to chain calls). The style property should match the CSS property name. Remember to include units in the value if they are expected!

Example style properties include: - color - background-color - font-size

Parameters:

  • component – The component to update

  • style – The name of the style property to change

  • value – The value to set the style property to (should be a string).

Returns:

Returns the original component (updates its values)