pyfyre.nodes package

class pyfyre.nodes.Button(onclick: Callable[[DOMEvent], None], children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <button>.

Parameters:: onclick – Called when this button is clicked.

pyfyre.nodes.E: alias of Element

class pyfyre.nodes.Element(tag_name: str, children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Node

Represents an HTML DOM element.

Parameters:

tag_name – HTML tag name of this element.
children – Builder for the children nodes of this element.
styles – CSS styling of this element. This will be combined into a single Style object. The styles are evaluated in order from left to right.
states – State dependencies of this object. If one of the state dependencies has changed its state, the update_dom method of this object will be called.
attrs – HTML attributes of this element.

tag_name

HTML tag name of this element.

Type:: str

children

Children nodes of this element. This is equal to the return of the children argument.

Type:: List[Node]

style

CSS styling of this element.

Type:: Style

states

State dependencies of this object. If one of the state dependencies has changed its state, the update_dom method of this object will be called.

Type:: List[StateDependency]

attrs

HTML attributes of this element.

Type:: Dict[str, str]

add_event_listener(event_type: str, callback: Callable[[DOMEvent], None]) → None: Calls the callback whenever the specified event_type is delivered to this element.

create_dom() → DOMNode

Create a new HTML DOM element from this object.

Returns:: Brython DOMNode type.

html() → str: HTML representation of this object.

is_void() → bool

Whether this element is a void or not based on its tag name.

More about void elements:: https://developer.mozilla.org/en-US/docs/Glossary/Void_element

update_attrs() → None: Update the attributes of the corresponding HTML DOM element of this object.

update_dom() → None: Update the corresponding HTML DOM element of this object. This rebuilds the children of this element recursively.

class pyfyre.nodes.FutureElement(tag_name: str, children: Callable[[], Awaitable[List[Node]]], *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Just like an Element, but the children returns an awaitable. That means the children builder of this element is asynchronous.

This class’s implementation is similar to asyncio.Future.

add_done_callback(callback: Callable[[FutureElement], None]) → None

Add a callback to be run when the Future is done.

The callback is called with the Future object as its only argument.

If the Future is already done when this method is called, the callback is called immediately.

cancel() → bool

Cancel the Future and call the callbacks.

Returns:: False, if the Future is already done or cancelled. Otherwise, change the Future’s state to cancelled, call the callbacks, and return True.

exception() → Optional[Exception]

Return the exception that was set on this Future.

Returns:

The exception (or None if no exception was set), only if the Future is done.

Raises:

FutureCancelled – If the Future has been cancelled.
FutureNoResult – If the Future isn’t done yet.

is_cancelled() → bool

Returns:: True if the Future was cancelled.

is_done() → bool

A Future is done if it was cancelled or if it has a result or an exception set with set_result() or set_exception() calls.

Returns:: True if the Future is done.

remove_done_callback(callback: Callable[[FutureElement], None]) → int

Remove the callback from the callbacks list.

Returns:: The number of callbacks removed, which is typically 1, unless the callback was added more than once.

result() → List[Node]

Return the result of the Future.

If the Future is done and has a result set by the set_result() method, the result value is returned.

Returns:

The result will be the children nodes of this element.

Raises:

Exception – If the Future is done and has an exception set by the set_exception() method, this method raises the exception.
FutureCancelled – If the Future has been cancelled.
FutureNoResult – If the Future’s result isn’t yet available.

set_exception(exception: Exception) → None

Mark the Future as done and set an exception.

Raises:: FutureAlreadyDone – If the Future is already done.

set_result(result: List[Node]) → None

Mark the Future as done and set its result.

Raises:: FutureAlreadyDone – If the Future is already done.

class pyfyre.nodes.FutureWidget(*, tag_name: str = 'div', styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: FutureElement, ABC

User-defined FutureElement class.

Inherit this class if you wish to define your own FutureElement class.

Example:

class MyFutureElement(FutureWidget):
    async def build(self) -> list[Node]:
        return await ...  # asynchronous operation

abstract async build() → List[Node]

Asynchronous builder for the children nodes of this Future element.

This is an abstract method so you must override this and define its implementation.

Error handling for the build method is currently not yet supported.

while_no_result() → List[Node]

Initial children builder for this element while the result of the Future is not yet ready.

You may override this method to customize your loading message.

Returns:: By default, a loading animation.

class pyfyre.nodes.Link(href: str, children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <a>.

Parameters:: href – Hyperlink of the page the link goes to.

href

Hyperlink of the page the link goes to.

Type:: str

is_internal() → bool: Whether the href is linked within the same domain.

property url: str: URL of the page the link goes to.

class pyfyre.nodes.ListBuilder(item_builder: Callable[[int], Optional[Node]], *, count: Optional[int] = None, max_height: str = '300px', render_batch: int = 10, render_interval: float = 0, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

A scrollable list of nodes that are created on demand.

This element is appropriate for lists with a large (or infinite) number of children because the builder is called only for those children that are actually visible.

Parameters:

item_builder – Builder for a child of this list. Called only with indices greater than or equal to zero and less than count. None can be returned in the builder to skip the current index.
count – Number of times this list will attempt to build a child. If None, infinite attempts will be made.
max_height – Maximum height of this element. A max-height CSS property is required to make a scrollable element.
render_batch – Number of children built at the same time when the user scrolls the list.
render_interval – Time interval in seconds between each batch of children build.

item_builder

Builder for a child of this list. Called only with indices greater than or equal to zero and less than count. None can be returned in the builder to skip the current index.

Type:: Callable[[int], Optional[Node]]

count

Number of times this list will attempt to build a child. If None, infinite attempts will be made.

Type:: Optional[int]

max_height

Maximum height of this element. A max-height CSS property is required to make a scrollable element.

Type:: str

render_batch

Number of children built at the same time when the user scrolls the list.

Type:: int

render_interval

Time interval in seconds between each batch of children build.

Type:: float

index

Current index of this list builder.

Type:: int

render_next_children() → bool

Build the next batch of children of this list.

Returns:: True if a new child is built. Otherwise, False.

class pyfyre.nodes.Node

Bases: ABC

Represents an HTML DOM node.

dom

Brython DOMNode type. The corresponding HTML DOM node of this object.

Type:: DOMNode

abstract create_dom() → DOMNode

abstract html() → str: HTML representation of this object.

abstract update_dom() → None

class pyfyre.nodes.RouterLink(href: str, children: Optional[Callable[[], List[Node]]] = None, *, arg: Optional[Any] = None, force_build: bool = True, styles: Optional[List[Style]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Link

Navigates to a different route inside the website as a single-page application.

Parameters:

arg – The argument that will be passed in to the route builder.
force_build – Whether to call the route builder even if it is already called before. By default, called route builders are cached.

pyfyre.nodes.Text: alias of TextNode

class pyfyre.nodes.TextInput(children: Optional[Callable[[], List[Node]]] = None, *, placeholder: str = '', multiline: bool = False, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <input> or <textarea> depending on the multiline argument.

Parameters:

placeholder – Placeholder text of this input.
multiline – Whether this text input is multiline or not.

set_value(value: Any) → None: Set the value of this text input.

property value: str: Value of this text input.

class pyfyre.nodes.TextNode(*values: Union[State[Any], Any])

Bases: Node

Represents an HTML DOM text node.

Parameters:: *values – Value of the text. You can pass in a State object to automatically update the value of the text when the state dependency has changed its state.

create_dom() → DOMNode

Create a new HTML DOM text node from this object.

Returns:: Brython DOMNode type.

html() → str: HTML representation of this object.

property value: str: Value of the text.

class pyfyre.nodes.Widget(*, tag_name: str = 'div', styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element, ABC

User-defined Element class.

Inherit this class if you wish to define your own Element class.

Example:

class MyElement(Widget):
    def build(self) -> list[Node]:
        return [Element("p", lambda: [Text("Hello, World!")])]

abstract build() → List[Node]

Builder for the children nodes of this element.

This is an abstract method so you must override this and define its implementation.

on_build_error(exc_type: Type[Exception], exc_value: Exception, exc_traceback: TracebackType) → List[Node]

Error handler for the build method.

This replaces the build method as the children builder for this element if an error occurred inside the build method.

You may override this method to customize your error message.

Parameters:

exc_type – Type of the exception.
exc_value – The exception itself.
exc_traceback – Traceback object which typically encapsulates the call stack at the point where the exception last occurred.

Returns:

By default, a simple error message on production environment and a traceback message on development environment.

Submodules

pyfyre.nodes.base module

pyfyre.nodes.base.E: alias of Element

class pyfyre.nodes.base.Element(tag_name: str, children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Node

Represents an HTML DOM element.

Parameters:

tag_name – HTML tag name of this element.
children – Builder for the children nodes of this element.
styles – CSS styling of this element. This will be combined into a single Style object. The styles are evaluated in order from left to right.
states – State dependencies of this object. If one of the state dependencies has changed its state, the update_dom method of this object will be called.
attrs – HTML attributes of this element.

tag_name

HTML tag name of this element.

Type:: str

children

Children nodes of this element. This is equal to the return of the children argument.

Type:: List[Node]

style

CSS styling of this element.

Type:: Style

states

State dependencies of this object. If one of the state dependencies has changed its state, the update_dom method of this object will be called.

Type:: List[StateDependency]

attrs

HTML attributes of this element.

Type:: Dict[str, str]

add_event_listener(event_type: str, callback: Callable[[DOMEvent], None]) → None: Calls the callback whenever the specified event_type is delivered to this element.

create_dom() → DOMNode

Create a new HTML DOM element from this object.

Returns:: Brython DOMNode type.

html() → str: HTML representation of this object.

is_void() → bool

Whether this element is a void or not based on its tag name.

More about void elements:: https://developer.mozilla.org/en-US/docs/Glossary/Void_element

update_attrs() → None: Update the attributes of the corresponding HTML DOM element of this object.

update_dom() → None: Update the corresponding HTML DOM element of this object. This rebuilds the children of this element recursively.

class pyfyre.nodes.base.Node

Bases: ABC

Represents an HTML DOM node.

dom

Brython DOMNode type. The corresponding HTML DOM node of this object.

Type:: DOMNode

abstract create_dom() → DOMNode

abstract html() → str: HTML representation of this object.

abstract update_dom() → None

pyfyre.nodes.base.Text: alias of TextNode

class pyfyre.nodes.base.TextNode(*values: Union[State[Any], Any])

Bases: Node

Represents an HTML DOM text node.

Parameters:: *values – Value of the text. You can pass in a State object to automatically update the value of the text when the state dependency has changed its state.

create_dom() → DOMNode

Create a new HTML DOM text node from this object.

Returns:: Brython DOMNode type.

html() → str: HTML representation of this object.

property value: str: Value of the text.

pyfyre.nodes.buttons module

class pyfyre.nodes.buttons.Button(onclick: Callable[[DOMEvent], None], children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <button>.

Parameters:: onclick – Called when this button is clicked.

pyfyre.nodes.futures module

class pyfyre.nodes.futures.FutureElement(tag_name: str, children: Callable[[], Awaitable[List[Node]]], *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Just like an Element, but the children returns an awaitable. That means the children builder of this element is asynchronous.

This class’s implementation is similar to asyncio.Future.

add_done_callback(callback: Callable[[FutureElement], None]) → None

Add a callback to be run when the Future is done.

The callback is called with the Future object as its only argument.

If the Future is already done when this method is called, the callback is called immediately.

cancel() → bool

Cancel the Future and call the callbacks.

Returns:: False, if the Future is already done or cancelled. Otherwise, change the Future’s state to cancelled, call the callbacks, and return True.

exception() → Optional[Exception]

Return the exception that was set on this Future.

Returns:

The exception (or None if no exception was set), only if the Future is done.

Raises:

FutureCancelled – If the Future has been cancelled.
FutureNoResult – If the Future isn’t done yet.

is_cancelled() → bool

Returns:: True if the Future was cancelled.

is_done() → bool

A Future is done if it was cancelled or if it has a result or an exception set with set_result() or set_exception() calls.

Returns:: True if the Future is done.

remove_done_callback(callback: Callable[[FutureElement], None]) → int

Remove the callback from the callbacks list.

Returns:: The number of callbacks removed, which is typically 1, unless the callback was added more than once.

result() → List[Node]

Return the result of the Future.

If the Future is done and has a result set by the set_result() method, the result value is returned.

Returns:

The result will be the children nodes of this element.

Raises:

Exception – If the Future is done and has an exception set by the set_exception() method, this method raises the exception.
FutureCancelled – If the Future has been cancelled.
FutureNoResult – If the Future’s result isn’t yet available.

set_exception(exception: Exception) → None

Mark the Future as done and set an exception.

Raises:: FutureAlreadyDone – If the Future is already done.

set_result(result: List[Node]) → None

Mark the Future as done and set its result.

Raises:: FutureAlreadyDone – If the Future is already done.

pyfyre.nodes.inputs module

class pyfyre.nodes.inputs.TextInput(children: Optional[Callable[[], List[Node]]] = None, *, placeholder: str = '', multiline: bool = False, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <input> or <textarea> depending on the multiline argument.

Parameters:

placeholder – Placeholder text of this input.
multiline – Whether this text input is multiline or not.

set_value(value: Any) → None: Set the value of this text input.

property value: str: Value of this text input.

pyfyre.nodes.links module

class pyfyre.nodes.links.Link(href: str, children: Optional[Callable[[], List[Node]]] = None, *, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

Represents an HTML <a>.

Parameters:: href – Hyperlink of the page the link goes to.

href

Hyperlink of the page the link goes to.

Type:: str

is_internal() → bool: Whether the href is linked within the same domain.

property url: str: URL of the page the link goes to.

class pyfyre.nodes.links.RouterLink(href: str, children: Optional[Callable[[], List[Node]]] = None, *, arg: Optional[Any] = None, force_build: bool = True, styles: Optional[List[Style]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Link

Navigates to a different route inside the website as a single-page application.

Parameters:

arg – The argument that will be passed in to the route builder.
force_build – Whether to call the route builder even if it is already called before. By default, called route builders are cached.

pyfyre.nodes.lists module

class pyfyre.nodes.lists.ListBuilder(item_builder: Callable[[int], Optional[Node]], *, count: Optional[int] = None, max_height: str = '300px', render_batch: int = 10, render_interval: float = 0, styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element

A scrollable list of nodes that are created on demand.

This element is appropriate for lists with a large (or infinite) number of children because the builder is called only for those children that are actually visible.

Parameters:

item_builder – Builder for a child of this list. Called only with indices greater than or equal to zero and less than count. None can be returned in the builder to skip the current index.
count – Number of times this list will attempt to build a child. If None, infinite attempts will be made.
max_height – Maximum height of this element. A max-height CSS property is required to make a scrollable element.
render_batch – Number of children built at the same time when the user scrolls the list.
render_interval – Time interval in seconds between each batch of children build.

item_builder

Builder for a child of this list. Called only with indices greater than or equal to zero and less than count. None can be returned in the builder to skip the current index.

Type:: Callable[[int], Optional[Node]]

count

Number of times this list will attempt to build a child. If None, infinite attempts will be made.

Type:: Optional[int]

max_height

Maximum height of this element. A max-height CSS property is required to make a scrollable element.

Type:: str

render_batch

Number of children built at the same time when the user scrolls the list.

Type:: int

render_interval

Time interval in seconds between each batch of children build.

Type:: float

index

Current index of this list builder.

Type:: int

render_next_children() → bool

Build the next batch of children of this list.

Returns:: True if a new child is built. Otherwise, False.

pyfyre.nodes.widgets module

class pyfyre.nodes.widgets.FutureWidget(*, tag_name: str = 'div', styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: FutureElement, ABC

User-defined FutureElement class.

Inherit this class if you wish to define your own FutureElement class.

Example:

class MyFutureElement(FutureWidget):
    async def build(self) -> list[Node]:
        return await ...  # asynchronous operation

abstract async build() → List[Node]

Asynchronous builder for the children nodes of this Future element.

This is an abstract method so you must override this and define its implementation.

Error handling for the build method is currently not yet supported.

while_no_result() → List[Node]

Initial children builder for this element while the result of the Future is not yet ready.

You may override this method to customize your loading message.

Returns:: By default, a loading animation.

class pyfyre.nodes.widgets.Widget(*, tag_name: str = 'div', styles: Optional[List[Style]] = None, states: Optional[List[StateDependency]] = None, attrs: Optional[Dict[str, str]] = None)

Bases: Element, ABC

User-defined Element class.

Inherit this class if you wish to define your own Element class.

Example:

class MyElement(Widget):
    def build(self) -> list[Node]:
        return [Element("p", lambda: [Text("Hello, World!")])]

abstract build() → List[Node]

Builder for the children nodes of this element.

This is an abstract method so you must override this and define its implementation.

on_build_error(exc_type: Type[Exception], exc_value: Exception, exc_traceback: TracebackType) → List[Node]

Error handler for the build method.

This replaces the build method as the children builder for this element if an error occurred inside the build method.

You may override this method to customize your error message.

Parameters:

exc_type – Type of the exception.
exc_value – The exception itself.
exc_traceback – Traceback object which typically encapsulates the call stack at the point where the exception last occurred.

Returns:

By default, a simple error message on production environment and a traceback message on development environment.