Home

Napolitan is a lightweight, user-friendly library for creating custom elements with a simple API for PyScript. It uses a declarative approach for easy component structure definition and updates only changed parts of the DOM for efficiency. It works with both Pyodide and MicroPython, using only the language features and built-in libraries supported by both, intentionally avoiding certain modules like typing and metaclasses. Based on Web Components, probably, Napolitan works with any PyScript, JavaScript, or TypeScript framework.

Quick Look¶

Example: Counter (Not Styled)¶

PythonHTMLResult

from napolitan.core import Component, Attr, customElement
from napolitan.livingstandard import div, button


@customElement("my-counter-not-styled")
class Counter(Component):

    count = Attr(int, 0)

    def render(self):
        return div()(
            button(onclick=self.increment)("Increment"),
            self.count,
            button(onclick=self.decrement)("Decrement"),
        )

    def increment(self, _):
        self.count += 1

    def decrement(self, _):
        self.count -= 1

<my-counter-not-styled count="0"></my-counter-not-styled>

Example: Counter (Styled using Shoelace)¶

Info

"+" annotations in this example explain each part of the code well, so could please click "+" if you want to know the details.

PythonHTMLResult

from napolitan.core import Component, Attr, customElement
from napolitan.livingstandard import div, span
from napolitan.shoelace import button, button_group, icon, card


@customElement("my-counter")  #Register the component with the name my-counter as a custom element.

class Counter(Component): #Define the Counter class that extends the Component class.


    count = Attr(int, 0) #Define a count attrerty with a default value of 0.
    The Attr class is used to define a attrerty of the component.
    The Attr class takes two arguments: the type of the attrerty and the default value.
    my-counter custom element can be used with the count attribute.
    If you want to use the count as an internal state, you can define it using State class instead of using Attr class. If you use State class, the count will not be related to the count attribute of the my-counter custom element.


    @staticmethod
    def style(): #Define the style method to return the CSS styles for the component.

        return """
        .counter {
            --padding: 1rem;
            --border-color: #1E2129;
        }
        .count {
            font-size: 3rem;
            font-weight: bold;
            color: #1E2129;
            display: flex;
            justify-content: center;
        }
        """

    def render(self): #Define the render method to return the HTML structure of the component.
    Napolitan provides some sets of helper functions to create DOM elements and factory class to create a helper function for any DOM element as well. Here, sl_card, sl_button, sl_button_group, and sl_icon are helper functions to create Shoelace components. Napolitan currently provides a set of helper functions to create Shoelace components, HTML Living Standard elements, and Nord components. And also, you can use HTML tags text directly to create DOM elements, please refer to examples directory in the Napolitan repository, if you are interested in that.

        return card(cls="counter")(
            span(cls="count")(self.count),
            div(slot="footer", cls="footer")(
                button_group(label="btns")(
                    button(variant="primary", onclick=self.increment)( #Add an event listener to the + button click to call the increment method.

                        icon(name="plus-lg")
                    ),
                    button(variant="primary", onclick=self.decrement)( #Add an event listener to the - button click to call the decrement method.

                        icon(name="dash-lg")
                    ),
                )
            ),
        )

    def increment(self, e): #Define the increment method to increment the count attrerty.
    When count attrerty is updated, the only count span will be re-rendered automatically.

        self.count += 1

    def decrement(self, e): #Define the decrement method to decrement the count attrerty.
    When count attrerty is updated, the only count span will be re-rendered automatically.

        self.count -= 1

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.15.0/cdn/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.15.0/cdn/shoelace.js"></script>
<script type="mpy" src="examples/counter.py" config="examples/pyscript.toml"></script>
<my-counter count="10"></my-counter>

Example: Counter (Used `listen` decorator for event handling)¶

PythonHTMLResult

from napolitan.core import Component, Attr, customElement, track_method_calls, listen
from napolitan.livingstandard import div, span
from napolitan.shoelace import sl_button, sl_button_group, sl_icon, sl_card


@customElement("my-counter-use-listen")
class Counter(Component):

    count = Attr(int, 0)

    @staticmethod
    def style():
        return """
        :host {
            display: flex;
            width: fit-content;
            height: fit-content;
        }
        .counter {
            --padding: 1rem;
            --border-color: #1E2129;
        }
        .count {
            font-size: 3rem;
            font-weight: bold;
            color: #1E2129;
            display: flex;
            justify-content: center;
        }
        .counter [slot='footer'] {
            display: flex;
            justify-content: center;
        }
        """

    def render(self):
        return sl_card(cls="counter")(
            span(cls="count")(self.count),
            div(slot="footer")(
                sl_button_group(label="btns")(
                    sl_button(cls="inc", variant="primary")(
                        sl_icon(name="plus-lg"),
                    ),
                    sl_button(cls="dec", variant="primary")(
                        sl_icon(name="dash-lg")
                    ),
                )
            ),
        )

    @listen("click", ".inc")
    def increment(self, e):
        self.count += 1

    @listen("click", ".dec")
    def decrement(self, e):
        self.count -= 1

<script type="mpy" src="examples/counter_use_listen.py" config="examples/pyscript.toml"></script>
<my-counter-use-listen count="20"></my-counter-use-listen>

Home

Quick Look¶

Example: Counter (Not Styled)¶

Example: Counter (Styled using Shoelace)¶

Example: Counter (Used listen decorator for event handling)¶

Example: Counter (Used `listen` decorator for event handling)¶