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 to8080
- 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])¶
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: list[str] = <factory>, additional_css_content: 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)¶
- 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)¶
- 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 Link(text: str, url: str, arguments=None, **kwargs)¶
- 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 aContent
type). However, thePageContent
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.
- class Pre(*args, **kwargs)¶
- class Row(*args, **kwargs)¶
- class SelectBox(name: str, options: list[str], default_value: str | None = None, **kwargs)¶
- class Span(*args, **kwargs)¶
- 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 thevalue
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)