DEV Community: Flet

Creating realtime chat app in Python with Flutter UI

Flet — Tue, 07 Feb 2023 20:17:59 +0000

In this tutorial we are going to create a trivial in-memory Chat app with Flutter UI in Python using Flet framework. This app could be a good starting point to creating your own more complex and useful projects.

In this tutorial you will learn how to:

Create your first Flet app
Add page controls and handle events
Broadcast messages using built-in PubSub library
Use AlertDialog control for accepting user name
Enhance user interface with re-usable controls
Deploy the app as a web app

The complete application will look like this:

You can play with a live demo here.

The full code for the chat app can be found here.

Getting started with Flet

To create a Flet web app you don't need to know HTML, CSS or JavaScript, but you do need a basic knowledge of Python and object-oriented programming.

Flet requires Python 3.7 or above. To create a Flet app in Python, you need to install flet module first:

pip install flet

Note: upgrading Flet
To upgrade flet module, run:
pip install flet --upgrade

Create hello.py with the following contents:

import flet as ft

def main(page: ft.Page):
    page.add(ft.Text(value="Hello, world!"))

ft.app(target=main)

Run this app and you will see a new window with a greeting:

Adding page controls and handling events

To start, we want to be able to take user input (chat message) and show messages history on the screen. The layout for this step could look like this:

To implement this layout we will be using these Flet controls:

Column - a container to display chat messages (Text controls) vertically.
Text - chat message displayed in the chat Column.
TextField - input control used for taking new message input from the user.
ElevatedButton - "Send" button that will add new message to the chat Column.
Row - a container to display TextField and ElevatedButton horizontally.

Create chat.py with the following contents:

import flet as ft

def main(page: ft.Page):
    chat = ft.Column()
    new_message = ft.TextField()

    def send_click(e):
        chat.controls.append(ft.Text(new_message.value))
        new_message.value = ""
        page.update()

    page.add(
        chat, ft.Row(controls=[new_message, ft.ElevatedButton("Send", on_click=send_click)])
    )

ft.app("chat", target=main, view=ft.WEB_BROWSER)

When user clicks on the "Send" button, it triggers on_click event which calls send_click method. send_click then adds new Text control to the list of Column controls and clears new_message TextField value.

Important
After any properties of a control are updated, an update() method of the control (or its parent control) should be called for the update to take effect.

Chat app now looks like this:

Broadcasting chat messages

In the previous step we have created a simple web app that takes input from the user and displays chats messages on the screen. If you open this app in two web browser tabs, it will create two app sessions. Each session will have its own list of messages.

To build a realtime chat app, you need to somehow pass the messages between chat app sessions. When a user sends a message, it should be broadcasted to all other app sessions and displayed on their pages.

Flet provides a simple built-in PubSub mechanism for asynchronous communication between page sessions.

First, we need subscribe the user to receive broadcast messages:

    page.pubsub.subscribe(on_message)

pubsub.subsribe() method will add current app session to the list of subscribers. It accepts handler as an argument, that will later be called at the moment a publisher calls pubsub.send_all() method.

In the handler we will be adding new message (Text) to the list of chat controls:

    def on_message(message: Message):
        chat.controls.append(ft.Text(f"{message.user}: {message.text}"))
        page.update()

Finally, you need to call pubsub.send_all() method when the user clicks on "Send" button:

    def send_click(e):
        page.pubsub.send_all(Message(user=page.session_id, text=new_message.value))
        new_message.value = ""
        page.update()

    page.add(chat, ft.Row([new_message, ft.ElevatedButton("Send", on_click=send_click)]))

pubsub.send_all() will call the on_message() and pass on the Message object down to it.

Here is the full code for this step:

import flet as ft

class Message():
    def __init__(self, user: str, text: str):
        self.user = user
        self.text = text

def main(page: ft.Page):

    chat = ft.Column()
    new_message = ft.TextField()

    def on_message(message: Message):
        chat.controls.append(ft.Text(f"{message.user}: {message.text}"))
        page.update()

    page.pubsub.subscribe(on_message)

    def send_click(e):
        page.pubsub.send_all(Message(user=page.session_id, text=new_message.value))
        new_message.value = ""
        page.update()

    page.add(chat, ft.Row([new_message, ft.ElevatedButton("Send", on_click=send_click)]))

ft.app(target=main, view=ft.WEB_BROWSER)

User name dialog

Chat app that you have created in the previous step has basic functionality needed to exchange messages between user sessions. It is not very user-friendly though, since it shows session_id that sent a message, which doesn't tell much about who you are communicating with.

Let's improve our app to show user name instead of session_id for each message. To capture user name, we will be using AlertDialog control. Let's add it to the page:

    user_name = ft.TextField(label="Enter your name")

    page.dialog = ft.AlertDialog(
        open=True,
        modal=True,
        title=ft.Text("Welcome!"),
        content=ft.Column([user_name], tight=True),
        actions=[ft.ElevatedButton(text="Join chat", on_click=join_click)],
        actions_alignment="end",
    )

Note
A dialog will be opened on the start of the program since we have set its open property to True.

When the user clicks on "Join chat" button, it will call join_click method that should send a message to all subscribers, informing them that the user has joined the chat. This message should look different from the regular chat message, for example, like this:

Let's add message_type property to the Message class to differentiate between login and chat messages:

class Message():
    def __init__(self, user: str, text: str, message_type: str):
        self.user = user
        self.text = text
        self.message_type = message_type

We will be checking message_type in on_message method:

def on_message(message: Message):
    if message.message_type == "chat_message":
        chat.controls.append(ft.Text(f"{message.user}: {message.text}"))
    elif message.message_type == "login_message":
        chat.controls.append(
            ft.Text(message.text, italic=True, color=ft.colors.BLACK45, size=12)
        )
    page.update()

Messages of "login_message" and "chat_message" types will now be sent on two events: when user joins the chat and when user sends a message.

Let's create join_click method:

def join_click(e):
    if not user_name.value:
        user_name.error_text = "Name cannot be blank!"
        user_name.update()
    else:
        page.session.set("user_name", user_name.value)
        page.dialog.open = False
        page.pubsub.send_all(Message(user=user_name.value, text=f"{user_name.value} has joined the chat.", message_type="login_message"))
        page.update()

We used page session storage to store user_name for its future use in send_click method to send chat messages.

Note
User name dialog will close as soon as we set its open property to False and call update() method.

Finally, let's update send_click method to use user_name that we previously saved using page.session:

def send_click(e):

page.pubsub.send_all(Message(user=page.session.get('user_name'), text=new_message.value, message_type="chat_message"))
    new_message.value = ""
    page.update()

The full code for this step can be found here.

Enhancing user interface

Chat app that you have created in the previous step already serves its purpose of exchanging messages between users with basic login functionality.

Before moving on to deploying your app, we suggest adding some extra features to it that will improve user experience and make the app look more professional.

Re-usable user controls

You may want to show messages in a different format, like this:

Chat message will now be a Row containing CircleAvatar with username initials and Column that contains two Text controls: user name and message text.

We will need to show quite a few chat messages in the chat app, so it makes sense to create your own reusable control. Lets create a new ChatMessage class that will inherit from Row.

When creating an instance of ChatMessage class, we will pass a Message object as an argument and then ChatMessage will display itself based on message.user_name and message.text:

class ChatMessage(ft.Row):
    def __init__(self, message: Message):
        super().__init__()
        self.vertical_alignment="start"
        self.controls=[
                ft.CircleAvatar(
                    content=ft.Text(self.get_initials(message.user_name)),
                    color=ft.colors.WHITE,
                    bgcolor=self.get_avatar_color(message.user_name),
                ),
                ft.Column(
                    [
                        ft.Text(message.user_name, weight="bold"),
                        ft.Text(message.text, selectable=True),
                    ],
                    tight=True,
                    spacing=5,
                ),
            ]

    def get_initials(self, user_name: str):
        return user_name[:1].capitalize()

    def get_avatar_color(self, user_name: str):
        colors_lookup = [
            ft.colors.AMBER,
            ft.colors.BLUE,
            ft.colors.BROWN,
            ft.colors.CYAN,
            ft.colors.GREEN,
            ft.colors.INDIGO,
            ft.colors.LIME,
            ft.colors.ORANGE,
            ft.colors.PINK,
            ft.colors.PURPLE,
            ft.colors.RED,
            ft.colors.TEAL,
            ft.colors.YELLOW,
        ]
        return colors_lookup[hash(user_name) % len(colors_lookup)]

ChatMessage control extracts initials and algorithmically derives avatar color from a username.
Later, if you decide to improve control layout or its logic, it won't affect the rest of the program - that's the power of encapsulation!

Laying out controls

Now you can use your brand new ChatMessage to build a better layout for the chat app:

Instances of ChatMessage will be created instead of plain Text chat messages in on_message method:

    def on_message(message: Message):
        if message.message_type == "chat_message":
            m = ChatMessage(message)
        elif message.message_type == "login_message":
            m = ft.Text(message.text, italic=True, color=ft.colors.BLACK45, size=12)
        chat.controls.append(m)
        page.update()

Other improvements suggested with the new layout are:

ListView instead of Column for displaying messages, to be able to scroll through the messages later
Container for displayng border around ListView
IconButton instead of ElevatedButton to send messages
Use of expand property for controls to fill available space

Here is how you can implement this layout:

    # Chat messages
    chat = ft.ListView(
        expand=True,
        spacing=10,
        auto_scroll=True,
    )

    # A new message entry form
    new_message = ft.TextField(
        hint_text="Write a message...",
        autofocus=True,
        shift_enter=True,
        min_lines=1,
        max_lines=5,
        filled=True,
        expand=True,
        on_submit=send_message_click,
    )

    # Add everything to the page
    page.add(
        ft.Container(
            content=chat,
            border=ft.border.all(1, ft.colors.OUTLINE),
            border_radius=5,
            padding=10,
            expand=True,
        ),
        ft.Row(
            [
                new_message,
                ft.IconButton(
                    icon=ft.icons.SEND_ROUNDED,
                    tooltip="Send message",
                    on_click=send_message_click,
                ),
            ]
        ),
    )

The full code for this step can be found here.

This is the final version of the chat app for the purpose of this tutorial. Below you can read more about the enhancements that we have made.

Keyboard support

Focusing input controls

All data entry controls have autofocus property which when set to True moves initial focus to the control. If there is more than one control on a page with autofocus set, then the first one added to the page will get focus.

We set autofocus=True on a username TextField inside a dialog and then on a TextField for entering chat message to set initial focus on it when the dialog is closed.

When a user click "Send" button or presses Enter to submit a chat message, TextField loses focus.
To programmatically set control focus we used TextField.focus() method.

Submitting forms on `Enter`

It's so tempting to submit forms with just pushing Enter button on the keyboard! Type your name in the dialog, hit Enter, type a new message, hit Enter, type another, hit Enter - no mouse involved at all! 🚀

Flet has support for that by providing TextField.on_submit event handler which fires when a user press Enter button while the focus is on the TextField.

Entering multiline messages

What about multiline TextFields where Enter must advance a cursor to the next line? We've got that covered too! TextField control has shift_enter property which when set to True enables Discord-like behaviour: to get to a new line user presses Shift+Enter while hitting just Enter submits a form.

Animated scrolling to the last message

Noticed a nice animation of scrolling to the last message in a chat window? It could be enabled by setting ListView.auto_scroll property to True. The top most Page class, being a scrollable container itself, also supports auto_scroll.

Page title

Final touch - page title that could be changed as simply as:

page.title = "Flet Chat"
page.update()

Deploying the app

Congratulations! You have created your Chat app in Python with Flet, and it looks awesome!

Now it's time to share your app with the world!

Follow these instructions to deploy your Flet app as a web app to Fly.io or Replit.

What's next

There are plenty of features we could implement to improve this chat app:

Disconnect, reconnect, session timeout
Upload/download images
Authentication, avatars
Using database for the storage
Chat channels, topics
Full-text search
Emojis, markdown
Bots
Mobile app

Please let us know if you would like to contribute to the app/tutorial and share it with other Flet developers.

Summary

In this tutorial, you have learnt how to:

Create a simple Flet app;
Add page controls and handle events;
Use built in PubSub library;
User AlertDialog for entering user name;
Build page layout with reusable controls;
Deploy your Flet app to the web;

For further reading you can explore controls and examples repository.

We would love to hear your feedback! Please drop us an email, join the discussion on Discord, follow on Twitter.

Create Solitaire game with Python and Flet - Part 1

Flet — Wed, 18 Jan 2023 19:22:45 +0000

In this tutorial we will show you step-by-step creation of a famous Klondike solitaire game in Python with Flet. As an inspiration, we looked at this online game: https://www.solitr.com/

This tutorial is aimed at beginner/intermediate level Python developers who have basic knowledge of Python and object oriented programming.

Here you can see the final result that you are going to achieve with Flet and this tutorial: https://solitaire-part1.fly.dev/#/

We have broken down the game implementation into the following steps:

Getting started with Flet
Proof of concept app for draggable cards
Fanned card piles
Solitaire setup
Solitaire rules
Winning the game
Deploying the app
Summary

In the Part 2 (will be covered in the next tutorial) we'll be adding Appbar with options to start new game, view game rules and change game settings.

Getting started with Flet

To create a Flet web app you don't need to know HTML, CSS or JavaScript, but you do need a basic knowledge of Python and object-oriented programming.

Flet requires Python 3.7 or above. To create a web app in Python with Flet, you need to install flet module first:

pip install flet

To start, let's create a simple hello-world app.

Create hello.py with the following contents:

import flet as ft

def main(page: ft.Page):
    page.add(ft.Text(value="Hello, world!"))

ft.app(target=main)

Run this app and you will see a new window with a greeting:

Proof of concept app for draggable cards

For the proof of concept, we will only be using three types of Flet controls:

Stack - will be used as a parent control for absolute positioning of slots and cards.
GestureDetector - the card that will be moved within the Stack.
Container - the slot where the card will be dropped. Also will be used as content for the GestureDetector.

We have broken down the proof of concept app into four easy steps, so that after each step you have a complete short program to run and test.

Step 1: Drag the card around

In this step we will create a Stack (Solitaire game field) and a GestureDetector (Solitaire card). The card will then be added to the list of the Stack controls. top and left properties of the card are used for absolute positioning of the card in the Stack.

import flet as ft

def main(page: ft.Page):

   card = ft.GestureDetector(
       left=0,
       top=0,
       content=ft.Container(bgcolor=ft.colors.GREEN, width=70, height=100),
   )   

   page.add(ft.Stack(controls=[card], width=1000, height=500))

ft.app(target=main)

Run the app to see the the card added to the stack:

To be able to move the card, we'll create a drag method that will be called in on_pan_update event of GestureDetector, which happens every drag_interval while the user drags the card with their mouse.

To show the card movement, we’ll be updating the card’s top and left properties in the drag method each time the on_pan_update event happens.

Below is the simplest code for dragging GestureDetector in Stack:

import flet as ft

# Use of GestureDetector for with on_pan_update event for dragging card
# Absolute positioning of controls within stack

def main(page: ft.Page):

   def drag(e: ft.DragUpdateEvent):
       e.control.top = max(0, e.control.top + e.delta_y)
       e.control.left = max(0, e.control.left + e.delta_x)
       e.control.update()

   card = ft.GestureDetector(
       mouse_cursor=ft.MouseCursor.MOVE,
       drag_interval=5,
       on_pan_update=drag,
       left=0,
       top=0,
       content=ft.Container(bgcolor=ft.colors.GREEN, width=70, height=100),
   )   

   page.add(ft.Stack(controls=[card], width=1000, height=500))

ft.app(target=main)

Now you can see the card moving:

Important
After any properties of a control are updated, an update() method of the control (or its parent control) should be called for the update to take effect.

Step 2: Drop the card in the slot or bounce it back

The goal of this step is to be able to drop a card into a slot if it is close enough and bounce it back if it’s not.

Let’s create a Container control that will be a slot to which we’ll be dropping the card:

slot = ft.Container(
    width=70, height=100, left=200, top=0, border=ft.border.all(1)
    )
page.add(ft.Stack(controls = [slot, card], width=1000, height=500))

on_pan_end event of the card is called when the card is dropped:

card = ft.GestureDetector(
    mouse_cursor=ft.MouseCursor.MOVE,
    drag_interval=5,
    on_pan_update=drag,
    on_pan_end=drop,
    left=0,
    top=0,
    content=ft.Container(bgcolor=ft.colors.GREEN, width=70, height=100),
)

On this event, we’ll call drop method to check if the card is close enough to the slot (let’s say it’s closer than 20px to the slot), and place it there:

def drop(e: ft.DragEndEvent):
    if (
        abs(e.control.top - slot.top) < 20
        and abs(e.control.left - slot.left) < 20
    ):
        place(e.control, slot)
    e.control.update()

def place(card, slot):
    """place card to the slot"""
    card.top = slot.top
    card.left = slot.left
    page.update()

Now, if the card is not close enough, we need to bounce it back to its original position, which we don’t know at the moment, since the card’s top and left properties were changed on on_pan_update event.

Let’s create a Solitaire class object to remember the original position of the card when on_pan_start event of the card is called:

class Solitaire:
   def __init__(self):
       self.start_top = 0
       self.start_left = 0

solitaire = Solitaire()

def start_drag(e: ft.DragStartEvent):
   solitaire.start_top = e.control.top
   solitaire.start_left = e.control.left
   e.control.update()

Now let’s update on_pan_end event with the option to bounce card back:

def bounce_back(game, card):
    """return card to its original position"""
    card.top = game.start_top
    card.left = game.start_left
    page.update()

def drop(e: ft.DragEndEvent):
    if (
        abs(e.control.top - slot.top) < 20
        and abs(e.control.left - slot.left) < 20
    ):
        place(e.control, slot)

    else:
        bounce_back(solitaire, e.control)

    e.control.update()

The full code for this step can be found here.

Step 3: Adding a second card

Eventually, we’ll need 52 cards to play the game. For our proof of concept, let’s add a second card:

   card2 = ft.GestureDetector(
       mouse_cursor=ft.MouseCursor.MOVE,
       drag_interval=5,
       on_pan_start=start_drag,
       on_pan_update=drag,
       on_pan_end=drop,
       left=100,
       top=0,
       content=ft.Container(bgcolor=ft.colors.YELLOW, width=70, height=100),
   )

   controls = [slot, card1, card2]
   page.add(ft.Stack(controls=controls, width=1000, height=500))

Now, if you run the app with the two cards, you will notice that when you move the cards around, the yellow card (card2) is moving as expected, but the green the card (card1) is moving under the yellow card.

It happens because card2 is added to the list of stack controls after card1. To fix this problem, we need to move the draggable card to the top of the list of controls on on_pan_start event:

def move_on_top(card, controls):
    """Moves draggable card to the top of the stack"""
    controls.remove(card)
    controls.append(card)
    page.update()

def start_drag(e: ft.DragStartEvent):
    move_on_top(e.control, controls)
    solitaire.start_top = e.control.top
    solitaire.start_left = e.control.left

Now the two cards can be dragged without issues:

The full code for this step can be found here.

Step 4: Adding more slots

As a final step for the proof of concept app, let’s create two more slots:

slot0 = ft.Container(
    width=70, height=100, left=0, top=0, border=ft.border.all(1)
)

slot1 = ft.Container(
    width=70, height=100, left=200, top=0, border=ft.border.all(1)
)

slot2 = ft.Container(
    width=70, height=100, left=300, top=0, border=ft.border.all(1)
)

slots = [slot0, slot1, slot2]

When creating new cards, we will not specify their top and left position now, but instead, will place them to the slot0:

# deal cards
place(card1, slot0)
place(card2, slot0)

on_pan_end event, where we check if a card is close to a slot, we will now go through the list of slots to find where the card should be dropped:

def drop(e: ft.DragEndEvent):
    for slot in slots:
        if (
            abs(e.control.top - slot.top) < 20
        and abs(e.control.left - slot.left) < 20
        ):
            place(e.control, slot)
            e.control.update()
            return

    bounce_back(solitaire, e.control)
    e.control.update()

As a result, the two cards can be dragged between the three slots:

The full code for this step can be found here.

Congratulations on completing the proof of concept app for the Solitaire game! Now you can work with GestureDetector to move cards inside Stack and place them to certain Containers, which is a great part of the game to begin with.

Fanned card piles

In the proof of concept app we have accomplished the task of dropping a card to a slot in proximity or bounce it back. If there is already a card in that slot, the new card is placed on top of it, covering it completely.

In the Solitaire game, if there is already a card in a tableau slot, you want to place the draggable card a bit lower, so that you can see the previous card too, and if there are two cards, even lower. Those are called “fanned piles”.

Then, we want to be able to pick a card from the fanned pile that is not the top card of the pile and drag the card together with all the cards below it:

To be able to do that, it would be useful to have the information about the pile of cards in the slot from which the card is dragged, as well as in the slot to which it is being dropped. Let’s restructure our program and get it ready for the implementation of the fanned piles.

Slot, Card and Solitaire classes

A slot could have a pile property that would hold a list of cards that were placed there. Now the slot is a Container control object, and we can’t add any new properties to it. Let’s create a new Slot class that will inherit from Container and add a pile property to it:

SLOT_WIDTH = 70
SLOT_HEIGHT = 100

import flet as ft

class Slot(ft.Container):
   def __init__(self, top, left):
       super().__init__()
       self.pile=[]
       self.width=SLOT_WIDTH
       self.height=SLOT_HEIGHT
       self.left=left
       self.top=top
       self.border=ft.border.all(1)

Similarly to the Slot class, let’s create a new Card class with slot property to remember in which slot it resides. It will inherit from GestureDetector and we’ll move all card-related methods to it:

CARD_WIDTH = 70
CARD_HEIGTH = 100
DROP_PROXIMITY = 20

import flet as ft

class Card(ft.GestureDetector):
   def __init__(self, solitaire, color):
       super().__init__()
       self.slot = None
       self.mouse_cursor=ft.MouseCursor.MOVE
       self.drag_interval=5
       self.on_pan_start=self.start_drag
       self.on_pan_update=self.drag
       self.on_pan_end=self.drop
       self.left=None
       self.top=None
       self.solitaire = solitaire
       self.color = color
       self.content=ft.Container(bgcolor=self.color, width=CARD_WIDTH, height=CARD_HEIGTH)

   def move_on_top(self):
       """Moves draggable card to the top of the stack"""
       self.solitaire.controls.remove(self)
       self.solitaire.controls.append(self)
       self.solitaire.update()

   def bounce_back(self):
       """Returns card to its original position"""
       self.top = self.slot.top
       self.left = self.slot.left
       self.update()

   def place(self, slot):
       """Place card to the slot"""
       self.top = slot.top
       self.left = slot.left

   def start_drag(self, e: ft.DragStartEvent):
       self.move_on_top()
       self.update()

   def drag(self, e: ft.DragUpdateEvent):
       self.top = max(0, self.top + e.delta_y)
       self.left = max(0, self.left + e.delta_x)
       self.update()

   def drop(self, e: ft.DragEndEvent):
       for slot in self.solitaire.slots:
           if (
               abs(self.top - slot.top) < DROP_PROXIMITY
           and abs(self.left - slot.left) < DROP_PROXIMITY
         ):
               self.place(slot)
               self.update()
               return

       self.bounce_back()
       self.update()

Note
Since each card has slot property now, there is no need to remember start_left and start_top position of the draggable card in Solitaire class anymore, because we can just bounce it back to it’s slot.

Let’s update Solitaire class to inherit from Stack, and move the creation of cards and slots there:

SOLITAIRE_WIDTH = 1000
SOLITAIRE_HEIGHT = 500

import flet as ft
from slot import Slot
from card import Card

class Solitaire(ft.Stack):
   def __init__(self):
       super().__init__()
       self.controls = []
       self.slots = []
       self.cards = []
       self.width = SOLITAIRE_WIDTH
       self.height = SOLITAIRE_HEIGHT

   def did_mount(self):
       self.create_card_deck()
       self.create_slots()
       self.deal_cards()

   def create_card_deck(self):
       card1 = Card(self, color="GREEN")
       card2 = Card(self, color="YELLOW")
       self.cards = [card1, card2]

   def create_slots(self):
       self.slots.append(Slot(top=0, left=0))
       self.slots.append(Slot(top=0, left=200))
       self.slots.append(Slot(top=0, left=300))
       self.controls.extend(self.slots)
       self.update()

   def deal_cards(self):
       self.controls.extend(self.cards)
       for card in self.cards:
           card.place(self.slots[0])
       self.update()

Note
If you try to call create_slots(), create_card_deck() and deal_cards() methods in __init__() method of the Solitaire class, it will cause an error Control must be added to the page first. To fix this, we create slots and cards inside the did_mount() method, which happens immediately after the stack is added to the page.

Our main program will be very simple now:

import flet as ft
from solitaire import Solitaire

def main(page: ft.Page):

   solitaire = Solitaire()

   page.add(solitaire)

ft.app(target=main)

You can find the full source code for this step here. It works exactly the same way as the proof of concept app, but re-written with the new classes to be ready for adding more complex functionality to it.

Placing card with offset

When the card is being placed to a slot in the card.place() method, we need to do three things:

Remove the card from its original slot, if it exists
Change card’s slot to the new slot
Add the card to the new slot’s pile

def place(self, slot):
    # remove card from it's original slot, if exists
    if self.slot is not None:
        self.slot.pile.remove(self)

    # change card's slot to a new slot
    self.slot = slot

    # add card to the new slot's pile
    slot.pile.append(self)

When updating card’s top and left position, left should remain the same, but top will depend on the length of the new slot’s pile:

    self.top = slot.top + len(slot.pile) * CARD_OFFSET
    self.left = slot.left

Now the cards are placed with offset, which gives us the fanned pile look:

Drag pile of cards

If you try to drag the card from the bottom of the pile now, it will look like this:

To fix this problem, we need to update all the methods that work with the draggable card to work with the draggable pile instead.

Let’s create get_draggable_pile() method that will return list of cards that need to be dragged together, starting with the card you picked:

def get_draggable_pile(self):
    """returns list of cards that will be dragged together, starting with the current card"""
    if self.slot is not None:
        return self.slot.pile[self.slot.pile.index(self):]
    return [self]

Then, we’ll update move_on_top() method:

def move_on_top(self):
    """Brings draggable card pile to the top of the stack"""
    for card in draggable_pile:
        self.solitaire.controls.remove(card)
        self.solitaire.controls.append(card)
    self.solitaire.update()

Additionally, we need to update drag() method to go through the draggable pile and update positions of all the cards being dragged:

def drag(self, e: ft.DragUpdateEvent):
    draggable_pile = self.get_draggable_pile()
    for card in draggable_pile:
        card.top = max(0, self.top + e.delta_y) + draggable_pile.index(card) * CARD_OFFSET
        card.left = max(0, self.left + e.delta_x)
        card.update()

Also, we need to update place() method to place place the draggable pile to the slot:

def place(self, slot):
    """Place draggable pile to the slot"""
    draggable_pile = self.get_draggable_pile()

    for card in draggable_pile:
        card.top = slot.top + len(slot.pile) * CARD_OFFSET
        card.left = slot.left

        # remove card from it's original slot, if exists
        if card.slot is not None:
            card.slot.pile.remove(card)

        # change card's slot to a new slot
        card.slot = slot

        # add card to the new slot's pile
        slot.pile.append(card)

    self.solitaire.update()

Finally, if no slot in proximity is found, we need to bounce the whole pile back to its original position:

def bounce_back(self):
    """Returns draggable pile to its original position"""
    draggable_pile = self.get_draggable_pile()
    for card in draggable_pile:
        card.top = card.slot.top + card.slot.pile.index(card) * CARD_OFFSET
        card.left = card.slot.left
    self.solitaire.update()

The full source code of this step can be found here. Now we can drag and drop cards in fanned piles, which means we are ready for the real deal!

Solitaire setup

Let’s take a look at the wikipedia article about Klondike (solitaire):

Klondike is played with a standard 52-card deck.

After shuffling, a tableau of seven fanned piles of cards is laid from left to right. From left to right, each pile contains one more card than the last. The first and left-most pile contains a single upturned card, the second pile contains two cards, the third pile contains three cards, the fourth pile contains four cards, the fifth pile contains five cards, the sixth pile contains six cards, and the seventh pile contains seven cards. The topmost card of each pile is turned face up. The remaining cards form the stock and are placed facedown at the upper left of the layout.

The four foundations (light rectangles in the upper right of the figure) are built up by suit from Ace (low in this game) to King, and the tableau piles can be built down by alternate colors.

We will now work on this setup step by step.

Create card deck

The first step is to create a full deck of cards in Solitaire class. Each card should have a suit property (hearts, diamonds, clubs and spades) and a rank property (from Ace to King). For the suit, its color is important, because tableau piles are built by alternate colors.

For the rank, its value is important, because foundations are built from the lowest (Ace) to the highest (King) rank value.

In solitaire.py, create Suite and Rank classes:

class Suite:
    def __init__(self, suite_name, suite_color):
        self.name = suite_name
        self.color = suite_color

class Rank:
    def __init__(self, card_name, card_value):
        self.name = card_name
        self.value = card_value

Now, in the Card class, instead of accepting the color as an argument, we’ll be accepting suite and rank in __init__(). Additionally, we’ll add face_up property to the card and the Container will now has image of the back of the card as its content:

class Card(ft.GestureDetector):
    def __init__(self, solitaire, suite, rank):
        super().__init__()
        self.mouse_cursor=ft.MouseCursor.MOVE
        self.drag_interval=5
        self.on_pan_start=self.start_drag
        self.on_pan_update=self.drag
        self.on_pan_end=self.drop
        self.suite=suite
        self.rank=rank
        self.face_up=False
        self.top=None
        self.left=None
        self.solitaire = solitaire
        self.slot = None
        self.content=ft.Container(
            width=CARD_WIDTH,
            height=CARD_HEIGTH,
            border_radius = ft.border_radius.all(6),
            content=ft.Image(src="card_back.png"))

All the images for the face up cards, as well as card back are stored in the images folder in the same directory as main.py.

Important
For the reference to the image file to work, we need to specify the folder were it resides in the assets_dir in main.py:
ft.app(target=main, assets_dir="images")

Finally, in solitaire.create_card_deck() we'll create lists of suites and ranks and then the 52-card deck:

def create_card_deck(self):
    suites = [
        Suite("hearts", "RED"),
        Suite("diamonds", "RED"),
        Suite("clubs", "BLACK"),
        Suite("spades", "BLACK"),
    ]
    ranks = [
        Rank("Ace", 1),
        Rank("2", 2),
        Rank("3", 3),
        Rank("4", 4),
        Rank("5", 5),
        Rank("6", 6),
        Rank("7", 7),
        Rank("8", 8),
        Rank("9", 9),
        Rank("10", 10),
        Rank("Jack", 11),
        Rank("Queen", 12),
        Rank("King", 13),
    ]

    self.cards = []

    for suite in suites:
        for rank in ranks:
            self.cards.append(Card(solitaire=self, suite=suite, rank=rank))

The card deck is ready to be dealt, and now we need to create the layout for it.

Create slots

Klondike solitaire game layout should look like this:

Let’s create all those slots in solitaire.create_slots():

def create_slots(self):

    self.stock = Slot(top=0, left=0, border=ft.border.all(1))
    self.waste = Slot(top=0, left=100, border=None)

    self.foundations = []
    x = 300
    for i in range(4):
        self.foundations.append(Slot(top=0, left=x, border=ft.border.all(1, "outline")))
        x += 100

    self.tableau = []
    x = 0
    for i in range(7):
        self.tableau.append(Slot(top=150, left=x, border=None))
        x += 100

    self.controls.append(self.stock)
    self.controls.append(self.waste)
    self.controls.extend(self.foundations)
    self.controls.extend(self.tableau)
    self.update()

Note
Some slots should have visible border and some shouldn’t, so we added border to the list of arguments for the creation of Slot objects.

Deal cards

Let's start with shuffling the cards and adding them to the list of controls:

def deal_cards(self):
    random.shuffle(self.cards)
    self.controls.extend(self.cards)
    self.update()

Then we'll deal the cards to the tableau piles from left to right so that each pile contains one more card than the last, and place the remaining cards to the stock pile:

def deal_cards(self):
    random.shuffle(self.cards)
    self.controls.extend(self.cards)

    # deal to tableau
    first_slot = 0
    remaining_cards = self.cards

    while first_slot < len(self.tableau):
        for slot in self.tableau[first_slot:]:
            top_card = remaining_cards[0]
            top_card.place(slot)
            remaining_cards.remove(top_card)
        first_slot +=1

    # place remaining cards to stock pile
    for card in remaining_cards:
        card.place(self.stock)

    self.update()

Let’s run the program and see where we are at now:

Cards in stock were placed in a fanned pile in the same manner as to the tableau, but they should have been placed to a regular pile instead. To fix this problem, let’s add this condition to the card.place() method:

def place(self, slot):
    """Place draggable pile to the slot"""
    if slot in self.solitaire.tableau:
        self.top = slot.top + len(slot.pile) * self.solitaire.card_offset
    else:
        self.top = slot.top
    self.left = slot.left

Now the cards are only placed in fanned piles to tableau:

If you try moving the cards around now, the program won’t work. The reason for this is that in the card.drop() method iterates through list of slots which we don’t have now.

Let’s update the method to go separately through foundations and tableau:

def drop(self, e: ft.DragEndEvent):
    for slot in self.solitaire.tableau:
        if (
            abs(self.top - (slot.top + len(slot.pile) * CARD_OFFSET)) < DROP_PROXIMITY
        and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
            self.place(slot)
            self.update()
            return

    for slot in self.solitaire.foundations:
        if (
            abs(self.top - slot.top) < DROP_PROXIMITY
        and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
            self.place(slot)
            self.update()
            return

    self.bounce_back()
    self.update()

Reveal top cards in tableau piles

Now we have the correct game setup and as a last touch we need to reveal the topmost cards in tableau piles.

In Slot class, create a get_top_card() method:

def get_top_card(self):
    if len(self.pile) > 0:
        return self.pile[-1]

In Card class, create turn_face_up() method:

def turn_face_up(self):
    self.face_up = True
    self.content.content.src=
f"/images/{self.rank.name}_{self.suite.name}.svg"
    self.update()

Finally, reveal the topmost cards in the solitaire.deal_cards():

for slot in self.tableau:
    slot.get_top_card().turn_face_up()
    self.update()

Let’s see how it looks now:

The full source code for this step can be found here.

Congratulations on completing the Solitaire game setup! You’ve created a full 52-card deck, built layout with stock, waste, foundations and tableau piles, dealt the cards and revealed the top cards in tableau. Let’s move on to the next item on our todo list, which is Solitaire Rules.

Solitaire rules

If you run your current version of Solitaire, you’ll notice that you can do some crazy things with your cards:

Now it is time to implement some rules.

General rules

Currently, we can move any card, but only face-up cards should be allowed to be moved. Let’s add this check in start_drag, drag and drop methods of the card:

def start_drag(self, e: ft.DragStartEvent):
    if self.face_up:
        self.move_on_top()
        self.update()

def drag(self, e: ft.DragUpdateEvent):
    if self.face_up:
        draggable_pile = self.get_draggable_pile()
        for card in draggable_pile:
            card.top = max(0, self.top + e.delta_y) + draggable_pile.index(card) * CARD_OFFSET
            card.left = max(0, self.left + e.delta_x)
            card.update()

def drop(self, e: ft.DragEndEvent):
    if self.face_up:
        for slot in self.solitaire.tableau:
            if (
                abs(self.top - (slot.top + len(slot.pile) * CARD_OFFSET)) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
                self.place(slot)
                self.update()
                return

        for slot in self.solitaire.foundations:
            if (
                    abs(self.top - slot.top) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
                self.place(slot)
                self.update()
                return

    self.bounce_back()
    self.update()

Now let’s specify click method for the on_tap event of the card to reveal the card if you click on a faced-down top card in a tableau pile:

def click(self, e):
    if self.slot in self.solitaire.tableau:
        if not self.face_up and self == self.slot.get_top_card():
            self.turn_face_up()
            self.update()

Let's check how it works:

Foundations rules

At the moment we can place fanned piles to foundations, which shouldn’t be allowed. Let’s check the draggable pile length to fix it:

def drop(self, e: ft.DragEndEvent):
    for slot in self.solitaire.tableau:
        if (
            abs(self.top - (slot.top + len(slot.pile) * CARD_OFFSET)) < DROP_PROXIMITY
        and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
            self.place(slot)
            self.update()
            return

    if len(self.get_draggable_pile()) == 1:
        for slot in self.solitaire.foundations:
            if (
                abs(self.top - slot.top) < DROP_PROXIMITY
        and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
                self.place(slot)
                self.update()
                return

    self.bounce_back()
    self.update()

Then, of course, not any card can be placed to a foundation. According to the rules, a foundation should start with an Ace and then the cards of the same suite can be placed on top of it to build a pile form Ace to King.

Let’s add these rules to Solitaire class:

def check_foundations_rules(self, card, slot):
    top_card = slot.get_top_card()
    if top_card is not None:
        return (
            card.suite.name == top_card.suite.name
            and card.rank.value - top_card.rank.value == 1
        )
    else:
        return card.rank.name == "Ace"

We’ll check this rule in drop() method before placing a card to a foundation:

def drop(self, e: ft.DragEndEvent):
    if self.face_up:
        for slot in self.solitaire.tableau:
            if (
                abs(self.top - (slot.top + len(slot.pile) * CARD_OFFSET)) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ):
                self.place(slot)
                self.update()
                return

        if len(self.get_draggable_pile()) == 1:
            for slot in self.solitaire.foundations:
                if (
                    abs(self.top - slot.top) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ) and self.solitaire.check_foundations_rules(self, slot):
                    self.place(slot)
                    self.update()
                    return

        self.bounce_back()
        self.update()

As a final touch for foundations rules, let’s implement doubleclick method for on_double_tap event of a card. It will be checking if the faced-up card fits into any of the foundations and place it there:

   def doubleclick(self, e):
       if self.face_up:
           self.move_on_top()
           for slot in self.solitaire.foundations:
               if self.solitaire.check_foundations_rules(self, slot):
                   self.place(slot)
                   self.page.update()
                   return

Tableau rules

Finally, let's implement the rules to build tableau piles down from King to Ace by alternating suite color. Additionally, only King can be placed to an empty tableau slot.

Let’s add these rules for Solitaire class:

def check_tableau_rules(self, card, slot):
    top_card = slot.get_top_card()
    if top_card is not None:
        return (
            card.suite.color != top_card.suite.color
            and top_card.rank.value - card.rank.value == 1
            and top_card.face_up
        )
    else:
        return card.rank.name == "King"

Similarly to the foundations rules, we’ll check tableau rules before placing a card to a tableau pile:

def drop(self, e: ft.DragEndEvent):
    if self.face_up:
        for slot in self.solitaire.tableau:
            if (
                abs(self.top - (slot.top + len(slot.pile) * CARD_OFFSET)) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ) and self.solitaire.check_tableau_rules(self, slot):
                self.place(slot)
                self.update()
                return

        if len(self.get_draggable_pile()) == 1:
            for slot in self.solitaire.foundations:
                if (
                    abs(self.top - slot.top) < DROP_PROXIMITY
            and abs(self.left - slot.left) < DROP_PROXIMITY
        ) and self.solitaire.check_foundations_rules(self, slot):
                    self.place(slot)
                    self.update()
                    return

        self.bounce_back()
        self.update()

Stock and waste

To properly play Solitaire game right now, we are missing the remaining cards that are piled in the stock.

Let’s update click() method of the card to go through the stock pile and place the cards to waste as we go:

def click(self, e):
    if self.slot in self.solitaire.tableau:
        if not self.face_up and self == self.slot.get_top_card():
            self.turn_face_up()
            self.update()
    elif self.slot == self.solitaire.stock:
        self.move_on_top()
        self.place(self.solitaire.waste)
        self.turn_face_up()
        self.solitaire.update()

That’s it! Now you can properly play Solitaire game, but it is very difficult to win the game if you cannot pass though the waste again. Let’s implement click method that will be called in on_click event of the stock slot to go through the stock pile again:

class Slot(ft.Container):
   def __init__(self, solitaire, top, left, border):
       super().__init__()
       self.pile=[]
       self.width=SLOT_WIDTH
       self.height=SLOT_HEIGHT
       self.left=left
       self.top=top
       self.on_click=self.click
       self.solitaire=solitaire
       self.border=border
       self.border_radius = ft.border_radius.all(6)

   def click(self, e):
       if self == self.solitaire.stock:
           self.solitaire.restart_stock()

restart_stock() method in Solitaire class will place all the cards from waste to stock again:

def restart_stock(self):
    while len(self.waste.pile) > 0:
        card = self.waste.get_top_card()
        card.turn_face_down()
        card.move_on_top()
        card.place(self.stock)   
    self.update

For card.place() method to work properly with the cards from stock and waste, we’ve added a condition to card.get_draggable_pile(), so that it returns the top card only and not the whole pile:

def get_draggable_pile(self):
    """returns list of cards that will be dragged together, starting with the current card"""
    if self.slot is not None and self.slot != self.solitaire.stock and self.slot != self.solitaire.waste:
        return self.slot.pile[self.slot.pile.index(self):]
    return [self]

All done! The full source code for this step can be found here.

Let’s move on to the last step of the game itself - detecting the situation when you have won.

Winning the game

According to wikipedia, some suggest the chances of winning the Klondike solitaire game as being 1 in 30 games.

Knowing that the chances of winning are quite low, we should plan on showing the user something exciting when that finally happens.

First, let’s add a check for the winning condition to Solitaire class. If all four foundations contain total of 52 cards, then you have won:

def check_win(self):
    cards_num = 0
    for slot in self.foundations:
        cards_num += len(slot.pile)
    if cards_num == 52:
        return True
    return False

We’ll be checking if this condition is true each time a card is placed to a foundation:

def place(self, slot):
    """Place draggable pile to the slot"""

    draggable_pile = self.get_draggable_pile()

    for card in draggable_pile:
        if slot in self.solitaire.tableau:
            card.top = slot.top + len(slot.pile) * CARD_OFFSET
        else:
            card.top = slot.top
        card.left = slot.left

        # remove card from it's original slot, if exists
        if card.slot is not None:
            card.slot.pile.remove(card)

        # change card's slot to a new slot
        card.slot = slot

        # add card to the new slot's pile
        slot.pile.append(card)

    if self.solitaire.check_win():
        self.solitaire.winning_sequence()

    self.solitaire.update()

Finally, if the winning condition is met, it will trigger a winning sequence involving position animation:

def winning_sequence(self):
    for slot in self.foundations:   
        for card in slot.pile:
            card.animate_position=1000
            card.move_on_top()
            card.top = random.randint(0, SOLITAIRE_HEIGHT)
            card.left = random.randint(0, SOLITAIRE_WIDTH)
            self.update()
    self.controls.append(ft.AlertDialog(title=ft.Text(
"Congratulations! You won!"), open=True))

As you can imagine, it took me a while before I could win the game and take this video, but here it is:

Wow! We did it. You can find the full source code for the Part 1 of the Solitaire game here.

In Part 2 we will be adding top menu with options to restart the game, view game rules and change game settings such as waste size, number of passes through the waste and card back image.

Now, as we have a decent desktop version of the game, let’s deploy it as a web app to share with your friends and colleagues.

Deploying the app

Congratulations! You have created your Solitaire game app in Python with Flet, and it looks awesome!

Now it's time to share your app with the world!

Follow these instructions to deploy your Flet app as a web app to Fly.io or Replit.

Summary

In this tutorial, you have learnt how to:

Create a simple Flet app;
Drag and drop cards with GestureDetector;
Create your own classes that inherit from Flet controls;
Design UI layout using absolute positioning of controls in Stack;
Implement implicit animations;
Deploy your Flet app to the web;

For further reading you can explore controls and examples repository.

We would love to hear your feedback! Please join the discussion on Discord or follow us on Twitter.

Create 2-in-1 web and desktop app in Python without knowledge of HTML/CSS/JavaScript

Flet — Thu, 30 Jun 2022 20:35:38 +0000

In this tutorial we will show you, step-by-step, how to create a ToDo web app in Python using Flet framework and then share it on the internet. The app is a single-file console program of just 180 lines (formatted!) of Python code, yet it is a multi-session, modern single-page application with rich, responsive UI:

You can see the live demo here.

We chose a ToDo app for the tutorial, because it covers all of the basic concepts you would need to create any web app: building a page layout, adding controls, handling events, displaying and editing lists, making reusable UI components, and deployment/packaging options.

The tutorial consists of the following steps:

Getting started with Flet
Adding page controls and handling events
View, edit and delete list items
Filtering list items
Final touches
Deploying a web app
Packaging as a desktop app

Getting started with Flet

To write a Flet web app you don't need to know HTML, CSS or JavaScript, but you do need a basic knowledge of Python and object-oriented programming.

Flet requires Python 3.7 or above. To create a web app in Python with Flet, you need to install flet module first:

pip install flet

To start, let's create a simple hello-world app.

Create hello.py with the following contents:

import flet
from flet import Page, Text

def main(page: Page):
    page.add(Text(value="Hello, world!"))

flet.app(target=main)

Run this app and you will see a new window with a greeting:

Adding page controls and handling events

Now we're ready to create a multi-user ToDo app.

To start, we'll need a TextField for entering a task name, and an "+" FloatingActionButton with an event handler that will display a Checkbox with a new task.

Create todo.py with the following contents:

import flet
from flet import Checkbox, FloatingActionButton, Page, TextField, icons

def main(page: Page):
    def add_clicked(e):
        page.add(Checkbox(label=new_task.value))
        new_task.value = ""
        page.update()

    new_task = TextField(hint_text="Whats needs to be done?")

    page.add(new_task, FloatingActionButton(icon=icons.ADD, on_click=add_clicked))

flet.app(target=main)

Run the app and you should see a page like this:

Page layout

Now let's make the app look nice! We want the entire app to be at the top center of the page, taking up 600 px width. The TextField and the "+" button should be aligned horizontally, and take up full app width:

Row is a control that is used to lay its children controls out horizontally on a page. Column is a control that is used to lay its children controls out vertically on a page.

Replace todo.py contents with the following:

import flet
from flet import Checkbox, Column, FloatingActionButton, Page, Row, TextField, icons


def main(page: Page):
    def add_clicked(e):
        tasks_view.controls.append(Checkbox(label=new_task.value))
        new_task.value = ""
        view.update()

    new_task = TextField(hint_text="Whats needs to be done?", expand=True)
    tasks_view = Column()
    view = Column(
        width=600,
        controls=[
            Row(
                controls=[
                    new_task,
                    FloatingActionButton(icon=icons.ADD, on_click=add_clicked),
                ],
            ),
            tasks_view,
        ],
    )

    page.horizontal_alignment = "center"
    page.add(view)

flet.app(target=main)

Run the app and you should see a page like this:

Reusable UI components

While we could continue writing our app in the main function, the best practice would be to create a reusable UI component. Imagine you are working on an app header, a side menu, or UI that will be a part of a larger project. Even if you can't think of such uses right now, we still recommend creating all your web apps with composability and reusability in mind.

To make a reusable ToDo app component, we are going to encapsulate its state and presentation logic in a separate class:

import flet
from flet import Checkbox, Column, FloatingActionButton, Page, Row, TextField, UserControl, icons

class TodoApp(UserControl):
    def build(self):
        self.new_task = TextField(hint_text="Whats needs to be done?", expand=True)
        self.tasks = Column()

        # application's root control (i.e. "view") containing all other controls
        return Column(
            width=600,
            controls=[
                Row(
                    controls=[
                        self.new_task,
                        FloatingActionButton(icon=icons.ADD, on_click=self.add_clicked),
                    ],
                ),
                self.tasks,
            ],
        )

    def add_clicked(self, e):
        self.tasks.controls.append(Checkbox(label=self.new_task.value))
        self.new_task.value = ""
        self.update()


def main(page: Page):
    page.title = "ToDo App"
    page.horizontal_alignment = "center"
    page.update()

    # create application instance
    todo = TodoApp()

    # add application's root control to the page
    page.add(todo)

flet.app(target=main)

Read more about [creating user controls](https://flet.dev/docs/getting-started/python#user-controls).

Try something:
Try adding two TodoApp components to the page:

# create application instance
app1 = TodoApp()
app2 = TodoApp()

# add application's root control to the page
page.add(app1, app2)

View, edit and delete list items

In the previous step, we created a basic ToDo app with task items shown as checkboxes. Let's improve the app by adding "Edit" and "Delete" buttons next to a task name. The "Edit" button will switch a task item to edit mode.

Each task item is represented by two rows: display_view row with Checkbox, "Edit" and "Delete" buttons and edit_view row with TextField and "Save" button. view column serves as a container for both display_view and edit_view rows.

Before this step, the code was short enough to be fully included in the tutorial. Going forward, we will be highlighting only the changes introduced in a step.

Copy the entire code for this step from here. Below we will explain the changes we've done to implement view, edit, and delete tasks.

To encapsulate task item views and actions, we introduced a new Task class:

class Task(UserControl):
    def __init__(self, task_name):
        super().__init__()
        self.task_name = task_name

    def build(self):
        self.display_task = Checkbox(value=False, label=self.task_name)
        self.edit_name = TextField(expand=1)

        self.display_view = Row(
            alignment="spaceBetween",
            vertical_alignment="center",
            controls=[
                self.display_task,
                Row(
                    spacing=0,
                    controls=[
                        IconButton(
                            icon=icons.CREATE_OUTLINED,
                            tooltip="Edit To-Do",
                            on_click=self.edit_clicked,
                        ),
                        IconButton(
                            icons.DELETE_OUTLINE,
                            tooltip="Delete To-Do",
                            on_click=self.delete_clicked,
                        ),
                    ],
                ),
            ],
        )

        self.edit_view = Row(
            visible=False,
            alignment="spaceBetween",
            vertical_alignment="center",
            controls=[
                self.edit_name,
                IconButton(
                    icon=icons.DONE_OUTLINE_OUTLINED,
                    icon_color=colors.GREEN,
                    tooltip="Update To-Do",
                    on_click=self.save_clicked,
                ),
            ],
        )
        return Column(controls=[self.display_view, self.edit_view])

    def edit_clicked(self, e):
        self.edit_name.value = self.display_task.label
        self.display_view.visible = False
        self.edit_view.visible = True
        self.update()

    def save_clicked(self, e):
        self.display_task.label = self.edit_name.value
        self.display_view.visible = True
        self.edit_view.visible = False
        self.update()

Additionally, we changed TodoApp class to create and hold Task instances when the "Add" button is clicked:

class TodoApp(UserControl):
    def build(self):
        self.new_task = TextField(hint_text="Whats needs to be done?", expand=True)
        self.tasks = Column()
        # ...

    def add_clicked(self, e):
        task = Task(self.new_task.value, self.task_delete)
        self.tasks.controls.append(task)
        self.new_task.value = ""
        self.update()

For "Delete" task operation, we implemented task_delete() method in TodoApp class which accepts task control instance as a parameter:

class TodoApp(UserControl):
    # ...
    def task_delete(self, task):
        self.tasks.controls.remove(task)
        self.update()

Then, we passed a reference to task_delete method into Task constructor and called it on "Delete" button event handler:

class Task(UserControl):
    def __init__(self, task_name, task_delete):
        super().__init__()
        self.task_name = task_name
        self.task_delete = task_delete

        # ...        

    def delete_clicked(self, e):
        self.task_delete(self)

Run the app and try to edit and delete tasks:

Filtering list items

We already have a functional ToDo app where we can create, edit, and delete tasks. To be even more productive, we want to be able to filter tasks by their status.

Copy the entire code for this step from here. Below we will explain the changes we've done to implement filtering.

Tabs control is used to display filter:

from flet import Tabs, Tab

# ...

class TodoApp(UserControl):
    def __init__(self):
        self.tasks = []
        self.new_task = TextField(hint_text="Whats needs to be done?", expand=True)
        self.tasks = Column()

        self.filter = Tabs(
            selected_index=0,
            on_change=self.tabs_changed,
            tabs=[Tab(text="all"), Tab(text="active"), Tab(text="completed")],
        )

        self.view = Column(
            width=600,
            controls=[
                Row(
                    controls=[
                        self.new_task,
                        FloatingActionButton(icon=icons.ADD, on_click=self.add_clicked),
                    ],
                ),
                Column(
                    spacing=25,
                    controls=[
                        self.filter,
                        self.tasks,
                    ],
                ),
            ],
        )

To display different lists of tasks depending on their statuses, we could maintain three lists with "All", "Active" and "Completed" tasks. We, however, chose an easier approach where we maintain the same list and only change a task's visibility depending on its status.

In TodoApp class we overrided update() method which iterates through all the tasks and updates their visible property depending on the status of the task:

class TodoApp(UserControl):

    # ...

    def update(self):
        status = self.filter.tabs[self.filter.selected_index].text
        for task in self.tasks.controls:
            task.visible = (
                status == "all"
                or (status == "active" and task.completed == False)
                or (status == "completed" and task.completed)
            )
        super().update()

Filtering should occur when we click on a tab or change a task status. TodoApp.update() method is called when Tabs selected value is changed or Task item checkbox is clicked:

class TodoApp(UserControl):

    # ...

    def tabs_changed(self, e):
        self.update()

class Task(UserControl):
    def __init__(self, task_name, task_status_change, task_delete):
        super().__init__()
        self.completed = False
        self.task_name = task_name
        self.task_status_change = task_status_change
        self.task_delete = task_delete

    def build(self):
        self.display_task = Checkbox(
            value=False, label=self.task_name, on_change=self.status_changed
        )
        # ...

    def status_changed(self, e):
        self.completed = self.display_task.value
        self.task_status_change(self)

Run the app and try filtering tasks by clicking on the tabs:

Final touches

Our Todo app is almost complete now. As a final touch, we will add a footer (Column control) displaying the number of incomplete tasks (Text control) and a "Clear completed" button.

Copy the entire code for this step from here. Below we highlighted the changes we've done to implement the footer:

class TodoApp():
    def __init__(self):
        # ...

        self.items_left = Text("0 items left")

        self.view = Column(
            width=600,
            controls=[
                Row([Text(value="Todos", style="headlineMedium")], alignment="center"),
                Row(
                    controls=[
                        self.new_task,
                        FloatingActionButton(icon=icons.ADD, on_click=self.add_clicked),
                    ],
                ),
                Column(
                    spacing=25,
                    controls=[
                        self.filter,
                        self.tasks,
                        Row(
                            alignment="spaceBetween",
                            vertical_alignment="center",
                            controls=[
                                self.items_left,
                                OutlinedButton(
                                    text="Clear completed", on_click=self.clear_clicked
                                ),
                            ],
                        ),
                    ],
                ),
            ],
        )

    # ...

    def clear_clicked(self, e):
        for task in self.tasks.controls[:]:
            if task.completed:
                self.task_delete(task)

    def update(self):
        status = self.filter.tabs[self.filter.selected_index].text
        count = 0
        for task in self.tasks.controls:
            task.visible = (
                status == "all"
                or (status == "active" and task.completed == False)
                or (status == "completed" and task.completed)
            )
            if not task.completed:
                count += 1
        self.items_left.value = f"{count} active item(s) left"
        super().update()

Run the app:

Deploying a web app

Congratulations! You have created your first Python app with Flet, and it looks awesome! Now it's time to share your app with the world!

Follow these instructions to deploy your Flet app as a web app to Fly.io or Replit.

Packaging as a desktop app

Flet Python app and all its dependencies can be packaged into an executable and user can run it on their computer without installing a Python interpreter or any modules.

Follow these instructions to package your app into an executable.

Summary

In this tutorial you have learned how to:

Create a simple Flet app;
Work with Reusable UI components;
Design UI layout using Column and Row controls;
Work with lists: view, edit and delete items, filtering;
Deploy your Flet app to the web;
Package your Flet app into an executable;

For further reading you can explore controls and examples repository.

We would love to hear your feedback! Please drop us an email, join the discussion on Discord, follow on Twitter.

Tutorial: Build and package a multi-platform desktop app in Python

Flet — Tue, 28 Jun 2022 21:24:30 +0000

In this tutorial we will show you, step-by-step, how to create a Calculator app in Python using Flet framework and package it as a standalone executable for Windows, macOS and Linux, or deploy it as a web app. The app is a a simple console program, yet it is a multi-platform application with similar to iPhone calculator app UI:

You can find the live demo here.

In this tutorial, we will cover all of the basic concepts for creating a multi-platform desktop app: building a page layout, adding controls, handling events, and packaging/deployment options.

The tutorial consists of the following steps:

Step 1: Getting started with Flet
Step 2: Adding page controls
Step 3: Building page layout
Step 4: Handling events
Step 5: Packaging as a desktop app
Step 6: Deploying a web app
Summary

Step 1: Getting started with Flet

To write a Flet web app you don't need to know HTML, CSS or JavaScript, but you do need a basic knowledge of Python and object-oriented programming.

Flet requires Python 3.7 or above. To create a web app in Python with Flet, you need to install flet module first:

pip install flet

To start, let's create a simple hello-world app.

Create hello.py with the following contents:

import flet
from flet import Page, Text

def main(page: Page):
    page.add(Text(value="Hello, world!"))

flet.app(target=main)

Run this app and you will see a new window with a greeting:

Step 2: Adding page controls

Now you are ready to create a calculator app.

To start, you'll need a Text control for showing the result of calculation, and a few ElevatedButtons with all the numbers and actions on them.

Create calc.py with the following contents:

import flet
from flet import ElevatedButton, Page, Text

def main(page: Page):
    page.title = "Calc App"
    result = Text(value="0")
    page.add(
        result,
        ElevatedButton(text="AC"),
        ElevatedButton(text="+/-"),
        ElevatedButton(text="%"),
        ElevatedButton(text="/"),
        ElevatedButton(text="7"),
        ElevatedButton(text="8"),
        ElevatedButton(text="9"),
        ElevatedButton(text="*"),
        ElevatedButton(text="4"),
        ElevatedButton(text="5"),
        ElevatedButton(text="6"),
        ElevatedButton(text="-"),
        ElevatedButton(text="1"),
        ElevatedButton(text="2"),
        ElevatedButton(text="3"),
        ElevatedButton(text="+"),
        ElevatedButton(text="0"),
        ElevatedButton(text="."),
        ElevatedButton(text="="),
    )

flet.app(target=main)

Run the app and you should see a page like this:

Step 3: Building page layout

Now let's arrange the text and buttons in 6 horizontal rows.

Replace calc.py contents with the following:

import flet
from flet import ElevatedButton, Page, Row, Text

def main(page: Page):
    page.title = "Calc App"
    result = Text(value="0")
    page.add(
        Row(controls=[result]),
        Row(
            controls=[
                ElevatedButton(text="AC"),
                ElevatedButton(text="+/-"),
                ElevatedButton(text="%"),
                ElevatedButton(text="/"),
            ]
        ),
        Row(
            controls=[
                ElevatedButton(text="7"),
                ElevatedButton(text="8"),
                ElevatedButton(text="9"),
                ElevatedButton(text="*"),
            ]
        ),
        Row(
            controls=[
                ElevatedButton(text="4"),
                ElevatedButton(text="5"),
                ElevatedButton(text="6"),
                ElevatedButton(text="-"),
            ]
        ),
        Row(
            controls=[
                ElevatedButton(text="1"),
                ElevatedButton(text="2"),
                ElevatedButton(text="3"),
                ElevatedButton(text="+"),
            ]
        ),
        Row(
            controls=[
                ElevatedButton(text="0"),
                ElevatedButton(text="."),
                ElevatedButton(text="="),
            ]
        ),
    )

flet.app(target=main)

Run the app and you should see a page like this:

Using Container for decoration

To add a black background with rounded border around the calculator, we will be using Container control. Container may decorate only one control, so we will need to wrap all the 6 rows into a single vertical Column that will be used as the container's content:

To complete the UI portion of the program, update color and size properties for the Text, and color and bgcolor properties for the buttons. For even alignment of the buttons within the rows, we will be using expand property as shown on the diagram above.

Replace calc.py contents with the following:

import flet
from flet import (
    Column,
    Container,
    ElevatedButton,
    Page,
    Row,
    Text,
    border_radius,
    colors,
)

def main(page: Page):
    page.title = "Calc App"
    result = Text(value="0", color=colors.WHITE, size=20)
    page.add(
        Container(
            width=300,
            bgcolor=colors.BLACK,
            border_radius=border_radius.all(20),
            padding=20,
            content=Column(
                controls=[
                    Row(controls=[result], alignment="end"),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="AC",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="+/-",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="%",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="/",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="7",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="8",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="9",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="*",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="4",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="5",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="6",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="-",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="1",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="2",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="3",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="+",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="0",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=2,
                            ),
                            ElevatedButton(
                                text=".",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="=",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                ]
            ),
        )
    )

flet.app(target=main)

Run the app and you should see a page like this:

Just what we wanted!

Reusable UI components

While you can continue writing your app in the main function, the best practice would be to create a reusable UI component.

Imagine you are working on an app header, a side menu, or UI that will be a part of a larger project (for example, at Flet we will be using this Calculator app in a bigger "Gallery" app that will show all the examples for Flet framework).

Even if you can't think of such uses right now, we still recommend creating all your web apps with composability and reusability in mind.

To make a reusable Calc app component, we are going to encapsulate its state and presentation logic in a separate CalculatorApp class.

Replace calc.py contents with the following:

import flet
from flet import (
    Column,
    Container,
    ElevatedButton,
    Page,
    Row,
    Text,
    UserControl,
    border_radius,
    colors,
)

class CalculatorApp(UserControl):
    def build(self):
        result = Text(value="0", color=colors.WHITE, size=20)

        # application's root control (i.e. "view") containing all other controls
        return Container(
            width=300,
            bgcolor=colors.BLACK,
            border_radius=border_radius.all(20),
            padding=20,
            content=Column(
                controls=[
                    Row(controls=[result], alignment="end"),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="AC",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="+/-",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="%",
                                bgcolor=colors.BLUE_GREY_100,
                                color=colors.BLACK,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="/",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="7",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="8",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="9",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="*",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="4",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="5",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="6",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="-",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="1",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="2",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="3",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="+",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                    Row(
                        controls=[
                            ElevatedButton(
                                text="0",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=2,
                            ),
                            ElevatedButton(
                                text=".",
                                bgcolor=colors.WHITE24,
                                color=colors.WHITE,
                                expand=1,
                            ),
                            ElevatedButton(
                                text="=",
                                bgcolor=colors.ORANGE,
                                color=colors.WHITE,
                                expand=1,
                            ),
                        ]
                    ),
                ]
            ),
        )

def main(page: Page):
    page.title = "Calc App"
    # create application instance
    calc = CalculatorApp()

    # add application's root control to the page
    page.add(calc)

flet.app(target=main)

Step 4: Handling events

Now let's make the calculator do its job. We will be using the same event handler for all the buttons and use data property to differentiate between the actions depending on the button clicked. For each ElevatedButton control, specify on_click=self.button_clicked event and set data property equal to button's text, for example:

ElevatedButton(
    text="AC",
    bgcolor=colors.BLUE_GREY_100,
    color=colors.BLACK,
    expand=1,
    on_click=self.button_clicked,
    data="AC",
)

Below is on_click event handler that will reset the Text value when "AC" button is clicked:

def button_clicked(self, e):
    if e.data == "AC":
        self.result.value = "0"

With similar approach, specify on_click event and data property for each button and add expected action to the button_clicked event handler depending on e.data value. Copy the entire code for this step from here.

Run the app and see it in the action:

Step 5: Packaging as a desktop app

Congratulations! You have created your Calculator app with Flet, and it looks awesome! Now it's time to share your app with the world!

Flet Python app and all its dependencies can be packaged into an executable and user can run it on their computer without installing a Python interpreter or any modules.

PyInstaller is used to package Flet Python app and all its dependencies into a single package for Windows, macOS and Linux. To create Windows package, PyInstaller must be run on Windows; to build Linux app, it must be run on Linux; and to build macOS app - on macOS.

Start from installing PyInstaller:

pip install pyinstaller

Navigate to the directory where your .py file is located and build your app with the following command:

pyinstaller your_program.py

Your bundled Flet app should now be available in dist/your_program folder. Try running the program to see if it works.

On macOS/Linux:

./dist/your_program/your_program

on Windows:

dist\your_program\your_program.exe

Now you can just zip the contents of dist/your_program folder and distribute to your users! They don't need Python or Flet installed to run your packaged program - what a great alternative to Electron!

You'll notice though when you run a packaged program from macOS Finder or Windows Explorer a new console window is opened and then a window with app UI on top of it.

You can hide that console window by rebuilding the package with --noconsole switch:

pyinstaller your_program.py --noconsole --noconfirm

Bundling to one file

Contents of dist/your_program directory is an app executable plus supporting resources: Python runtime, modules, libraries.

You can package all these in a single executable by using --onefile switch:

pyinstaller your_program.py --noconsole --noconfirm --onefile

You'll get a larger executable in dist folder. That executable is a self-running archive with your program and runtime resources which gets unpacked into temp directory when run - that's why it takes longer to start "onefile" package.

Note:
For macOS you can distribute either dist/your_program or dist/your_program.app which is an application bundle.

Customizing package icon

Default bundle app icon is diskette which might be confusing for younger developers missed those ancient times when floppy disks were used to store computer data.

You can replace the icon with your own by adding --icon argument:

pyinstaller your_program.py --noconsole --noconfirm --onefile --icon <your-image.png>

PyInstaller will convert provided PNG to a platform specific format (.ico for Windows and .icns for macOS), but you need to install Pillow module for that:

pip install pillow

Packaging assets

Your Flet app can include assets. Provided app assets are in assets folder next to your_program.py they can be added to an application package with --add-data argument, on macOS/Linux:

pyinstaller your_program.py --noconsole --noconfirm --onefile --add-data "assets:assets"

On Windows assets;assets must be delimited with ;:

pyinstaller your_program.py --noconsole --noconfirm --onefile --add-data "assets;assets"

Note:
You can find here all PyInstaller command-line options

Using CI for multi-platform packaging

To create an app package with PyInstaller for specific OS it must be run on that OS.

If you don't have an access to Mac or PC you can bundle your app for all three platforms with AppVeyor - Continuous Integration service for Windows, Linux and macOS. In short, Continuous Integration (CI) is an automated process of building, testing and deploying (Continuous Delivery - CD) application on every push to a repository.

AppVeyor is free for open source projects hosted on GitHub, GitLab and Bitbucket. To use AppVeyor, push your app to a repository within one of those source-control providers.

To get started with AppVeyor sign up for a free account.

Click "New project" button, authorize AppVeyor to access your GitHub, GitLab or Bitbucket account, choose a repository with your program and create a new project.

Now, to configure packaging of your app for Windows, Linux and macOS, add file with the following contents into the root of your repository appveyor.yml. appveyor.yml is a build configuration file, or CI workflow, describing build, test, packaging and deploy commands that must be run on every commit.

Note:
You can just fork flet-dev/python-ci-example repository and customize it to your needs.

When you push any changes to GitHub repository, AppVeyor will automatically start a new build:

What that CI workflow does on every push to the repository:

Clones the repository to a clean virtual machine.
Installs app dependencies using pip.
Runs pyinstaller to package Python app into "onefile" bundle for Windows, macOS and Ubuntu.
Zip/Tar packages and uploads them to "Artifacts".
Uploads packages to GitHub releases when a new tag is pushed. Just push a new tag to make a release!

GITHUB_TOKEN
GITHUB_TOKEN in appveyor.yml is a GitHub Personal Access Token (PAT) used by AppVeyor to publish created packages to repository "Releases". You need to generate your own token and replace it in appveyor.yml. Login to your GitHub account and navigate to Personal access token page. Click "Generate new token" and select "public_repo" or "repo" scope for public or private repository respectively. Copy generated token to a clipboard and return to AppVeyor Portal. Navigate to Encrypt configuration data page and paste token to "Value to encrypt" field, click "Encrypt" button. Put encrypted value under GITHUB_TOKEN in your appveyor.yml.

Configure AppVeyor for your Python project, push a new tag to a repository and "automagically" get desktop bundle for all three platforms in GitHub releases! 🎉

In addition to GitHub Releases, you can also configure releasing of artifacts to Amazon S3 bucket or Azure Blob storage.

Step 6: Deploying a web app

Flet app can be deployed as a "standalone" web app which means both your Python app and Flet web server are deployed together as a bundle.

Flet apps use WebSockets for real-time partial updates of their UI and sending events back to your program.
When choosing a hosting provider for your Flet app you should pay attention to their support of WebSockets. Sometimes WebSockets are not allowed or come as a part of more expensive offering, sometimes there is a proxy that periodically breaks WebSocket connection by a timeout (Flet implements re-connection logic, but it could be unpleasant behavior for users of your app anyway).

Another important factor while choosing a hosting provider for Flet app is latency. Every user action on UI sends a message to Flet app and the app sends updated UI back to user. Make sure your hosting provider has multiple data centers, so you can run your app closer to the majority of your users.

Note:
We are not affiliated with hosting providers in this section - we just use their service and love it.

Fly.io

Fly.io has robust WebSocket support and can deploy your app to a data center that is close to your users. They have very attractive pricing with a generous free tier which allows you to host up to 3 applications for free.

To get started with Fly install flyctl and then authenticate:

flyctl auth login

To deploy the app with flyctl you have to add the following 3 files into the folder with your Python app.

Create requirements.txt with a list of application dependencies. At minimum it should contain flet module:

flet>=0.1.33

Create fly.toml describing Fly application:

app = "<your-app-name>"

kill_signal = "SIGINT"
kill_timeout = 5
processes = []

[env]
  FLET_SERVER_PORT = "8080"

[experimental]
  allowed_public_ports = []
  auto_rollback = true

[[services]]
  http_checks = []
  internal_port = 8080
  processes = ["app"]
  protocol = "tcp"
  script_checks = []

  [services.concurrency]
    hard_limit = 25
    soft_limit = 20
    type = "connections"

  [[services.ports]]
    force_https = true
    handlers = ["http"]
    port = 80

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

  [[services.tcp_checks]]
    grace_period = "1s"
    interval = "15s"
    restart_limit = 0
    timeout = "2s"

Replace <your-app-name> with desired application name which will be also used in application URL, such as https://<your-app-name>.fly.dev.

Note we are setting the value of FLET_SERVER_PORT environment variable to 8080 which is an internal TCP port Flet web app is going to run on.

Create Dockerfile containing the commands to build your application container:

FROM python:3-alpine

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

CMD ["python", "./main.py"]

main.py is a file with your Python program.

Note:
Fly.io deploys every app as a Docker container, but a great thing about Fly is that it provides a free remote Docker builder, so you don't need Docker installed on your machine.

Next, switch command line to a folder with your app and run the following command to create and initialize a new Fly app:

flyctl apps create --name <your-app-name>

Deploy the app by running:

flyctl deploy

That's it! Open your app in the browser by running:

flyctl apps open

Replit

Replit is an online IDE and hosting platform for web apps written in any language. Their free tier allows running any number of apps with some performance limitations.

To run your app on Replit:

Sign up on Replit.
Click "New repl" button.
Select "Python" language from a list and provide repl name, e.g. my-app.
Click "Packages" tab and search for flet package; select its latest version.
Click "Secrets" tab and add FLET_SERVER_PORT variable with value 5000.
Switch back to "Files" tab and copy-paste your app into main.py.
Run the app. Enjoy.

Summary

In this tutorial you have learned how to:

Create a simple Flet app;
Work with Reusable UI components;
Design UI layout using Column, Row and Container controls;
Handle events;
Package your Flet app into an executable;
Deploy your Flet app to the web;

For further reading you can explore controls and examples repository.

We would love to hear your feedback! Please drop us an email, join the discussion on Discord, follow on Twitter.

Building email signup form for Docusaurus with hCaptcha, Cloudflare Pages and Mailgun

Flet — Thu, 13 Jan 2022 18:26:07 +0000

Introduction

Staying in touch with your users via email is still an effective and reliable communication channel. In this tutorial we are going to implement email signup form for a React-based static website that allows users to submit their email address and subscribe to a project mailing list. We are going to implement "double opt-in" process where upon signup an email is sent to the user which includes a link to click and confirm the subscription.

Pglet website is made with Docusaurus and hosted on Cloudflare Pages. However, the following solution could be easily adopted for other React-based website frameworks such as Next.js and use a different backend for server-side logic such as Vercel Functions or Deno Deploy.

Project requirements:

The form must be as simple as possible: just "email" field and "submit" button.
The form must protected by CAPTCHA.
Double opt-in subscription process should be implemented: after submitting the form a user receives an email with a confirmation link to complete the process.

For CAPTCHA we are going to use hCaptcha, which is a great alternative to Google's reCAPTCHA and has a similar API.

A signup form requires server-side processing and for that we re going to use Cloudflare Pages Functions which are a part of Cloudflare Pages platform.

For maintaining mailing list and sending email messages we are going to use Mailgun. Mailgun offers great functionality, first-class API at a flexible pricing, plus we have a lot of experience with it.

All code samples in this article can be found in:

Email signup form

Signup form is implemented as a React component and includes an email entry form with hCaptcha and two messages:

The official hCaptcha demo React app with invisible captcha was a perfect starting point for making our own Docusaurus component.

Add hCaptcha component to your project:

yarn add @hcaptcha/react-hcaptcha --save

Create src/components/signup-form.js with the following contents:

import React, { useEffect, useRef, useState } from "react";
import BrowserOnly from '@docusaurus/BrowserOnly';
import HCaptcha from "@hcaptcha/react-hcaptcha";

export default function SignupForm() {
    const [token, setToken] = useState(null);
    const [email, setEmail] = useState("");
    const captchaRef = useRef(null);

    const onSubmit = (event) => {
        event.preventDefault();
        captchaRef.current.execute();
    };

    useEffect(async () => {
        if (token) {
            var data = {
                email: email,
                captchaToken: token
            };

            // send message
            const response = await fetch("/api/email-signup", {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify(data),
              });
        }
    }, [token, email]);

    return (
        <div id="signup" className="signup-form">
            <BrowserOnly fallback={<div>Loading...</div>}>
                {() => {
                    if (token) {
                        // signup submitted
                        return <div>Thank you! You will receive the confirmation email shortly.</div>
                    } else if (window.location.href.endsWith('?signup-confirmed')) {
                        // signup confirmed
                        return <div><span style={{fontSize:'25px', marginRight:'10px'}}>🎉</span>Congratulations! You have successfully subscribed to Pglet newsletter.</div>
                    } else {
                        // signup form
                        return <form onSubmit={onSubmit}>
                            <h3>Subscribe to Pglet newsletter for project updates and tutorials!</h3>
                            <input
                                type="email"
                                value={email}
                                placeholder="Your email address"
                                onChange={(evt) => setEmail(evt.target.value)}
                            />
                            <input type="submit" value="Submit" />
                            <HCaptcha
                                sitekey="{YOUR-HCAPTCHA-SITE-KEY}"
                                size="invisible"
                                onVerify={setToken}
                                ref={captchaRef}
                            />
                        </form>
                    }
                }}
            </BrowserOnly>
        </div>
    );
}

It's simply <form> element with "email" and "submit" inputs - except hCaptcha, no other 3rd-party components or hooks were used.

Replace {YOUR-HCAPTCHA-SITE-KEY} with your own hCaptcha site key.

Captcha is verified on form.onSubmit event which supports submitting form with ENTER and triggers built-in form validators. The result of captcha verification is stored in token state variable which is sent to /api/email-signup server function along with entered email for further verification and processing.

Add signup-form.js component to src/pages/index.js page:

import SignupForm from '@site/src/components/signup-form'

and then put <SignupForm/> inside <main> element:

<main>
    <SignupForm/>
    ...
</main>

When you run Docusaurus site with yarn start and navigate to a page with captcha at http://localhost:3000 you'll get "blocked by CORS policy" JavaScript errors. To make captcha work locally you should browse with a domain instead of "localhost".

Add a new mapping 127.0.0.1 mysite.local to sudo nano /private/etc/hosts and then you can open http://mysite.local:3000 with working captcha.

Note
A part of form component is wrapped with <BrowserOnly> element which tells Docusaurus that the contents inside <BrowserOnly> is not suitable for server-side rendering because of client-side API used, in our case window.location.ref. You can read more about <BrowserOnly> here.

Configuring Mailgun

Mailgun is a transactional email service that offers first-class APIs for sending, receiving and tracking email messages.

Note
We are not affiliated with Mailgun - we just like their service and have a lot of experience with it.

Some advice before creating a mailing list in Mailgun:

Start with a free "Flex" plan - it allows sending 5,000 messages per month and includes custom domains.
Configure custom domain - of course, you can test everything on a built-in {something}.mailgun.org domain, but messages sent from it will be trapped in recipient's Junk folder. Custom domain is included with a free plan and setting it up is just a matter of adding a few records to your DNS zone.
Get dedicated IP address - if you require even greater email deliverability, assign your domain to a dedicated IP address. Dedicated IP is part of "Foundation" plan which starts at $35/month.

Cloudflare Pages Functions

Cloudflare Page Functions are based on Cloudflare Workers.

Be aware that Functions runtime environment is different from Node.js - you can't use Node.js built-in modules, you can't install anything from NPM. It's more like JavaScript in a headless browser with fetch(), WebSocket, Crypto and other Web APIs.

For signup form, we are going to add two functions:

POST /api/email-signup - for initial form processing and signup
GET /api/confirm-subscription?email={email}&code={code} - for confirming subscription

To generate routes above, we need to create two files: /functions/api/email-signup.js and /functions/api/confirm-subscription.js in the project repository.

Caution!
/functions directory must be in the root of your repository, not in /static directory, and must be published along with the site.

You can glance through Functions docs to become familiar with the technology. Here I'll only cover some tricky issues which could arise while you develop.

First, it's possible to run and debug your functions locally. A beta version of Wrangler tool should be installed for that:

yarn add wrangler@beta --save-dev

Caution!
Disregard scary deprecation warning while looking for wrangler package on npmjs.com and don't install @cloudflare/wrangler as it suggests.
Apparently, Cloudflare team is actively working on Wrangler v2 and publishes it as wrangler package.

Run Wrangler as a proxy for your local Docusaurus run:

npx wrangler pages dev -- yarn start

For configurable settings in functions we use environment variables. In contrast with Cloudflare Workers, environment variables are not set as globals in your functions, however they can be accessed via handler's context, like that:

// handler function
export async function onRequestPost(context) {
  const { request, env } = context;
  const apiKey = env.API_KEY;
}

where API_KEY is the name of environment variable.

For Workers environment variables can be configured in wrangler.toml, but wrangler.toml is not supported by Functions, so the only way to test with environment variables locally is to pass them via command line with -b switch:

npx wrangler pages dev -b API_KEY=123! -b MY_VAR2=some_value ... -- yarn start

For your Cloudflare Pages website, you can configure Production and Preview environment variables on Settings → Environment variables page:

Environment variables are immutable. If you update/add/delete environment variable and then call the function using it again, it won't work - once variables have changed, the website must be re-built to pick up new values.

Do not put real secrets into "Preview" environment variables if your project in a public repository. Any pull request to the repository publishes "preview" website to a temp URL which is visible to everyone in commit status. Therefore, it's possible for the attacker to submit malicious PR with a function printing all environment variables and then run it via temp URL.

Form submit handler

Email signup form POSTs entered email and hCaptcha response to /api/email-signup function, which performs the following:

Parses request body as JSON and validates its email and captchaToken fields.
Performs hCaptcha response validation and aborts the request if validation fails.
Tries adding a new email (member) into Mailgun mailing list and exits if it's already added.
Sends email with confirmation link via Mailgun to a newly added email address.

Validating hCaptcha response

Validating hCaptcha response on the server is just a POST request to https://hcaptcha.com/siteverify with hCaptcha response received from browser and hCaptcha site key secret in the body:

async function validateCaptcha(token, secret) {
  const data = {
    response: token,
    secret: secret
  }

  const encData = urlEncodeObject(data)
  const captchaResponse = await fetch(
    `https://hcaptcha.com/siteverify`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': encData.length.toString()
      },
      body: encData
    }
  )
  const captchaBody = await captchaResponse.json()
  if (!captchaBody.success) {
    throw captchaBody["error-codes"]
  }
}

Thanks to this great example on how to send a form request with fetch() method.

Adding email to a mailing list

In utils.js we implemented a helper method for calling Mailgun API:

export function callMailgunApi(mailgunApiKey, method, url, data) {
    const encData = urlEncodeObject(data)
    return fetch(
      url,
      {
        method: method,
        headers: {
          Authorization: 'Basic ' + btoa('api:' + mailgunApiKey),
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': encData.length.toString()
        },
        body: encData
      }
    )
  }

export function urlEncodeObject(obj) {
    return Object.keys(obj)
      .map(k => encodeURIComponent(k) + '=' + encodeURIComponent(obj[k]))
      .join('&')
  }

Request parameters are passed in URL-encoded form in the body.

Requests require Basic authentication header with api and Mailgun primary account API key as username and password respectively.

With callMailgunApi() helper function adding a new member into Mailgun mailing lists becomes trivial:

async function addMailingListMember(mailgunApiKey, listName, memberAddress) {
  const data = {
    address: memberAddress,
    subscribed: 'no',
    upsert: 'no'
  }

  const response = await callMailgunApi(mailgunApiKey,
    'POST', `https://api.mailgun.net/v3/lists/${listName}/members`, data)

  if (response.status === 200) {
    return true; // member has been added
  } else if (response.status === 400) {
    return false; // member already added
  } else {
    const responseBody = await response.json()
    throw `Error adding mailing list member: ${responseBody.message}`
  }
}

It tries to add a new member into mailing list and returns true if it was successfully added; otherwise returns false.

Sending confirmation email

The function for sending confirmation email message to a user via Mailgun is just a few lines:

async function sendEmail(mailgunApiKey, mailDomain, from, to, subject, htmlBody) {
  const data = {
    from: from,
    to: to,
    subject: subject,
    html: htmlBody
  }

  const response = await callMailgunApi(mailgunApiKey,
    'POST', `https://api.mailgun.net/v3/${mailDomain}/messages`, data)  

  if (response.status !== 200) {
    const responseBody = await response.text()
    throw `Error sending email message: ${responseBody}`
  }
}

An interesting part here is how confirmation URL is built, which is sent in the message and should be clicked by a user to confirm subscription.

Confirmation URL contains two parameters: email and confirmation code. Email is just recipient's email address which is, obviously, not a secret. Confirmation code is calculated as sha1(email + secret), with secret known to the server only.

When the server receives a request with email and confirmation code, it calculates a new confirmation code for the received email and compares it with the code from the request.

The algorithm could be further improved by implementing expiring confirmation code, but we want to keep it simple for now.

Verifying email and completing signup process

/api/confirm-subscription function has a single onRequestGet() handler which performs the following:

Validates email and code request parameters.
Calculates confirmation code and compares it to the one from the request.
If both codes match, updates Mailgun mailing list member's subscribed status to yes.
Redirects to a home page with ?signup-confirmed appended to the URL.

export async function onRequestGet(context) {
  const { request, env } = context;

  // get request params
  const { searchParams } = new URL(request.url)
  const email = searchParams.get('email')
  const code = searchParams.get('code')

  if (!code || !email) {
    throw "Invalid request parameters"
  }

  // validate confirmation code
  const calculatedCode = await sha1(email + env.CONFIRM_SECRET)
  if (calculatedCode !== code) {
    throw "Invalid email or confirmation code"
  }

  // update subscription status
  await subscribeMailingListMember(env.MAILGUN_API_KEY, env.MAILGUN_MAILING_LIST, email);

  // redirect to a home page
  return Response.redirect(new URL(request.url).origin + "?signup-confirmed", 302)
}

Conclusion

In this article we created an email signup form for Docusaurus website protected with hCaptcha. The form allows user to submit their email address and subscribe to a project mailing list. We implemented "double opt-in" process, where upon signup an email is sent to the user which includes a link to click and confirm the subscription. We used Cloudflare Pages Functions to implement all server-side logic. Mailgun service was used to send email messages and maintain mailing list.

In the next article we will build an interactive Python app using Pglet for sending newsletter to Mailgun mailing lists. Make sure to subscribe to Pglet mailing list not to miss it!

Build and deploy a web app in Python without knowledge of HTML/CSS/JavaScript

Flet — Fri, 30 Apr 2021 18:29:07 +0000

In this tutorial we will show you, step-by-step, how to create a ToDo web app in Python using Pglet framework and then share it on the internet. The app is a single-file console program of just 100 lines of Python code, yet it is a multi-session, modern single-page application with rich, responsive UI.

You can play with the live demo here.

We chose a ToDo app for the tutorial, because it covers the basic concepts you would need to create any web app: building a page layout, adding controls, handling events, displaying and editing lists, making reusable UI components, and deploy options.

The tutorial consists of the following steps:

Step 1: Getting started with Pglet
Step 2: Pglet app structure
Step 3: Adding page controls and handling events
Step 4: View, edit and delete list items
Step 5: Filtering list items
Step 6: Final touches
Step 7: Deploying the app
Summary

Step 1: Getting started with Pglet

To create and deploy this ToDo app, you don't need to know HTML, CSS or JavaScript, but you do need a basic knowledge of Python and object-oriented programming, and a Pglet framework.

Pglet requires Python 3.7 or above. To create a web app in Python with Pglet, you need to install pglet module first:

pip install pglet

To start, let's create a simple hello-world app.

Create hello.py with the following contents:

python title="hello.py"
import pglet
from pglet import Text

page = pglet.page()
page.add(Text(value="Hello, world!"))

Run this app and you will see a new browser window with a greeting:

Try something
In this example, the page URL is a random string, because we didn't specify it in pglet.page() call. Try changing it to pglet.page('hello').

Step 2: Pglet app structure

In the previous step, we learned how to create a simple Pglet page. On that page, all users work with the same contents ("shared page").

A shared page may be useful for certain types of apps, such as dashboards, status pages, or reports. But for a ToDo app, we want every user to see their own set of tasks. To achieve this, we need to create a "multi-user app".

Create hello-app.py with the following contents:

import pglet
from pglet import Textbox

def main(page):
  page.add(Textbox())

pglet.app("hello-app", target=main)

While the application is running, for every new user session Pglet calls main function with unique page contents.

Try something
To see multiple sessions in action, open the application URL in a new "incognito" browser window.

Step 3: Adding page controls and handling events

Now we're ready to create a multi-user ToDo app.

To start, we'll need a Textbox for entering a task name, and an "Add" button with an event handler that will display a checkbox with a new task.

Create todo.py with the following contents:

import pglet
from pglet import Textbox, Button, Checkbox

def main(page):

    def add_clicked(e):
        page.add(Checkbox(label=new_task.value))

    new_task = Textbox(placeholder='Whats needs to be done?')

    page.add(
        new_task,
        Button('Add', on_click=add_clicked)
    )

pglet.app("todo-app", target=main)

Run the app and you should see a page like this:

Page layout

Now let's make the app look nice! We want the entire app to be at the top center of the page, stretched over 70% of the page width. The textbox and the button should be aligned horizontally, and take up full app width:

Stack is a container control that is used to lay other controls out on a page. Stack can be vertical (default) or horizontal, and can contain other stacks.

Replace todo.py contents with the following:

import pglet
from pglet import Stack, Textbox, Button, Checkbox

def main(page):

    page.title = "ToDo App"
    page.horizontal_align = 'center'
    page.update() # needs to be called every time "page" control is changed

    def add_clicked(e):
        tasks_view.controls.append(Checkbox(label=new_task.value))
        tasks_view.update()

    new_task = Textbox(placeholder='Whats needs to be done?', width='100%')
    tasks_view = Stack()

    page.add(Stack(width='70%', controls=[
        Stack(horizontal=True, on_submit=add_clicked, controls=[
            new_task,
            Button('Add', on_click=add_clicked)
        ]),
        tasks_view
    ]))

pglet.app("todo-app", target=main)

Run the app and you should see a page like this:

Reusable UI components

To make a reusable ToDo app component, we are going to encapsulate its state and presentation logic in a separate class.

Replace todo.py contents with the following:

import pglet
from pglet import Stack, Textbox, Button, Checkbox

class TodoApp():
    def __init__(self):
        self.new_task = Textbox(placeholder='Whats needs to be done?', width='100%')
        self.tasks_view = Stack()

        # application's root control (i.e. "view") containing all other controls
        self.view = Stack(width='70%', controls=[
            Stack(horizontal=True, on_submit=self.add_clicked, controls=[
                self.new_task,
                Button('Add', on_click=self.add_clicked)
            ]),
            self.tasks_view
        ])

    def add_clicked(self, e):
        self.tasks_view.controls.append(Checkbox(label=self.new_task.value))
        self.tasks_view.update()

def main(page):
    page.title = "ToDo App"
    page.horizontal_align = 'center'
    page.update()

    # create application instance
    app = TodoApp()

    # add application's root control to the page
    page.add(app.view)

pglet.app("todo-app", target=main)

Try something
Try adding two TodoApp components to the page:

# create application instance
app1 = TodoApp()
app2 = TodoApp()

# add application's root control to the page
page.add(app1.view, app2.view)

Step 4: View, edit and delete list items

Each task item is represented by two stacks: display_view stack with Checkbox, "Edit" and "Delete" buttons and edit_view stack with Textbox and "Save" button. view stack serves as a container for both display_view and edit_view stacks.

Before this step, the code was short enough to be fully included in the tutorial. Going forward, we will be highlighting only the changes introduced in a step.

Copy the entire code for this step from here. Below we will explain the changes we've done to implement view, edit, and delete tasks.

To encapsulate task item views and actions, we introduced a new Task class:

class Task():
    def __init__(self, name):
        self.display_task = Checkbox(value=False, label=name)
        self.edit_name = Textbox(width='100%')

        self.display_view = Stack(horizontal=True, horizontal_align='space-between',
                vertical_align='center', controls=[
            self.display_task,
            Stack(horizontal=True, gap='0', controls=[
                Button(icon='Edit', title='Edit todo', on_click=self.edit_clicked),
                Button(icon='Delete', title='Delete todo')]),
            ])

        self.edit_view = Stack(visible=False, horizontal=True, horizontal_align='space-between',
                vertical_align='center', controls=[
            self.edit_name, Button(text='Save', on_click=self.save_clicked)
            ])
        self.view = Stack(controls=[self.display_view, self.edit_view])

    def edit_clicked(self, e):
        self.edit_name.value = self.display_task.label
        self.display_view.visible = False
        self.edit_view.visible = True
        self.view.update()

    def save_clicked(self, e):
        self.display_task.label = self.edit_name.value
        self.display_view.visible = True
        self.edit_view.visible = False
        self.view.update()

Additionally, we changed TodoApp class to create and hold Task instances when the "Add" button is clicked:

class TodoApp():
    def __init__(self):
        self.tasks = []
        # ... the rest of constructor is the same

    def add_clicked(self, e):
        task = Task(self.new_task.value)
        self.tasks.append(task)
        self.tasks_view.controls.append(task.view)
        self.new_task.value = ''
        self.view.update()

For "Delete" task operation, we implemented delete_task() method in TodoApp class which accepts task instance as a parameter:

class TodoApp():

    # ...

    def delete_task(self, task):
        self.tasks.remove(task)
        self.tasks_view.controls.remove(task.view)
        self.view.update()

Then, we passed a reference to TodoApp into Task constructor and called TodoApp.delete_task() in "Delete" button event handler:

class Task():
    def __init__(self, app, name):
        self.app = app

        # ...

        self.display_view = Stack(horizontal=True, horizontal_align='space-between', vertical_align='center', controls=[
            self.display_task,
            Stack(horizontal=True, gap='0', controls=[
                Button(icon='Edit', title='Edit todo', on_click=self.edit_clicked),
                Button(icon='Delete', title='Delete todo', on_click=self.delete_clicked)]),
            ])

        # ...        

    def delete_clicked(self, e):
        self.app.delete_task(self)

class TodoApp():

    # ...

    def add_clicked(self, e):
        task = Task(self, self.new_task.value)
        # ...

Run the app and try to edit and delete tasks:

Step 5: Filtering list items

We already have a functional ToDo app where we can create, edit, and delete tasks. To be even more productive, we want to be able to filter tasks by their status.

Copy the entire code for this step from here. Below we will explain the changes we've done to implement filtering.

Tabs control is used to display filter:

from pglet import Tabs, Tab

# ...

class TodoApp():
    def __init__(self):
        self.tasks = []
        self.new_task = Textbox(placeholder='Whats needs to be done?', width='100%')
        self.tasks_view = Stack()

        self.filter = Tabs(value='all', on_change=self.tabs_changed, tabs=[
                Tab(text='all'),
                Tab(text='active'),
                Tab(text='completed')])

        self.view = Stack(width='70%', controls=[
            Text(value='Todos', size='large', align='center'),
            Stack(horizontal=True, on_submit=self.add_clicked, controls=[
                self.new_task,
                Button(primary=True, text='Add', on_click=self.add_clicked)]),
            Stack(gap=25, controls=[
                self.filter,
                self.tasks_view
            ])
        ])

In TodoApp class we introduced update() method which iterates through all the tasks and updates their view Stack's visible property depending on the status of the task:

class TodoApp():

    # ...

    def update(self):
        status = self.filter.value
        for task in self.tasks:
            task.view.visible = (status == 'all'
                or (status == 'active' and task.display_task.value == False)
                or (status == 'completed' and task.display_task.value))
        self.view.update()

Filtering should occur when we click on a tab or change a task status. TodoApp.update() method is called when Tabs selected value is changed or Task item checkbox is clicked:

class TodoApp():

    # ...

    def tabs_changed(self, e):
        self.update()

class Task():
    def __init__(self, app, name):
        self.display_task = Checkbox(value=False, label=name, on_change=self.status_changed)
        # ...

    def status_changed(self, e):
        self.app.update()

Run the app and try filtering tasks by clicking on the tabs:

Step 6: Final touches

Our Todo app is almost complete now. As a final touch, we will add a footer (Stack control) displaying the number of incomplete tasks (Text control) and a "Clear completed" button.

Copy the entire code for this step from here. Below we highlighted the changes we've done to implement the footer:

class TodoApp():
    def __init__(self):
        # ...

        self.items_left = Text('0 items left')

        self.view = Stack(width='70%', controls=[
            Text(value='Todos', size='large', align='center'),
            Stack(horizontal=True, on_submit=self.add_clicked, controls=[
                self.new_task,
                Button(primary=True, text='Add', on_click=self.add_clicked)]),
            Stack(gap=25, controls=[
                self.filter,
                self.tasks_view,
                Stack(horizontal=True, horizontal_align='space-between', vertical_align='center', controls=[
                    self.items_left,
                    Button(text='Clear completed', on_click=self.clear_clicked)
                ])
            ])
        ])

    # ...

    def update(self):
        status = self.filter.value
        count = 0
        for task in self.tasks:
            task.view.visible = (status == 'all'
                or (status == 'active' and task.display_task.value == False)
                or (status == 'completed' and task.display_task.value))
            if task.display_task.value == False:
                count += 1
        self.items_left.value = f"{count} active item(s) left"
        self.view.update()        

    def clear_clicked(self, e):
        for task in self.tasks[:]:
            if task.display_task.value == True:
                self.delete_task(task)

Run the app:

Step 7: Deploying the app

Congratulations! You have created your first Python web app with Pglet, and it looks awesome!

Now it's time to share your app with the world!

Instant sharing

Pglet is not only a framework for building web apps, but it is also a service for hosting apps' UI.
You can have the application running on your computer while its UI is streaming to Pglet service in real-time.

To make the app instantly available on the Internet, just add web=True parameter to pglet.app() call at the very end of the program:

# ...

pglet.app(target=main, web=True)

A new browser windows will be opened with the URL like this:

https://app.pglet.io/public/{random}

Note
Pglet Service is in technical preview now and you are sharing the app in a public namespace.

Please note that we have removed the name of the page from the call above, so it's generated randomly to avoid name collision on public Pglet service with other users.

Replit

Instant sharing is a great option to quickly share an app on the web, but it requires your computer to be on all the time.

Replit is an online IDE and hosting platform for web apps written in any language. Their free tier allows running any number of apps with some limitations.

To run your ToDo app on Replit:

Sign up on Replit.
Click "New repl" button.
Select "Python" language from a list and provide repl name, e.g. my-todo.
Click "Packages" tab and search for pglet package; select its latest version.
Switch back to "Files" tab and copy-paste the code of Todo app into main.py.
Update pglet.app() call (at the very end of the program) to:

pglet.app("index", target=main)

Run the app. Now both the application code and UI are running on Replit service as a "standalone" app.

Note
We are not affiliated with Replit - we just love the service. Todo app demo for this tutorial is hosted on Replit and you can just "fork" it there and play.

Summary

In this tutorial you have learned how to:

Create a shared page and a multi-user web app;
Work with Reusable UI components;
Design UI layout using Stack control;
Work with lists: view, edit and delete items, filtering;
Deploy your app two ways: Pglet Service and Replit;

For further reading you can explore controls and examples repository.

We would love to hear your feedback! Please drop us an email at "hello AT pglet.io", join the discussion on Discord, follow on Twitter.

DEV Community: Flet

Creating realtime chat app in Python with Flutter UI

Getting started with Flet

Adding page controls and handling events

Broadcasting chat messages

User name dialog

Enhancing user interface

Re-usable user controls

Laying out controls

Keyboard support

Focusing input controls

Submitting forms on Enter

Entering multiline messages

Animated scrolling to the last message

Page title

Deploying the app

What's next

Summary

Create Solitaire game with Python and Flet - Part 1

Getting started with Flet

Proof of concept app for draggable cards

Step 1: Drag the card around

Step 2: Drop the card in the slot or bounce it back

Step 3: Adding a second card

Step 4: Adding more slots

Fanned card piles

Slot, Card and Solitaire classes

Placing card with offset

Drag pile of cards

Solitaire setup

Create card deck

Create slots

Deal cards

Reveal top cards in tableau piles

Solitaire rules

General rules

Foundations rules

Tableau rules

Stock and waste

Winning the game

Deploying the app

Summary

Create 2-in-1 web and desktop app in Python without knowledge of HTML/CSS/JavaScript

Getting started with Flet

Adding page controls and handling events

Page layout

Reusable UI components

View, edit and delete list items

Filtering list items

Final touches

Deploying a web app

Packaging as a desktop app

Summary

Tutorial: Build and package a multi-platform desktop app in Python

Step 1: Getting started with Flet

Step 2: Adding page controls

Step 3: Building page layout

Using Container for decoration

Reusable UI components

Step 4: Handling events

Step 5: Packaging as a desktop app

Bundling to one file

Customizing package icon

Packaging assets

Using CI for multi-platform packaging

Step 6: Deploying a web app

Fly.io

Replit

Summary

Building email signup form for Docusaurus with hCaptcha, Cloudflare Pages and Mailgun

Introduction

Email signup form

Configuring Mailgun

Cloudflare Pages Functions

Form submit handler

Validating hCaptcha response

Adding email to a mailing list

Sending confirmation email

Verifying email and completing signup process

Conclusion

Submitting forms on `Enter`