Skip to content

Latest commit

 

History

History
282 lines (198 loc) · 9.82 KB

CONTRIBUTING.md

File metadata and controls

282 lines (198 loc) · 9.82 KB
Raw

Contributing to Flet

Thank you for your interest in contributing to Flet!

Clone repo

git clone https://github.com/flet-dev/flet

Python SDK

Install Poetry

Windows

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Be sure to add %USERPROFILE%\AppData\Roaming\Python\Scripts to PATH.

macOS

curl -sSL https://install.python-poetry.org | python3 -

Open worker directory

cd sdk/python

Install dependencies

To install all Flet dependencies and enable the project as editable package run:

poetry install

Check the installation

Create hello.py file with a minimal Flet program:

import flet
from flet import Page, Text

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

flet.app(target=main)

and then run it:

poetry run python hello.py

During the first run Flet Client (flet) executable will be downloaded from Flet GitHub releases to a user temp directory and then started from there. The version of release to download from is taken from flet/version.py file.

You should see a new native OS window opened with "Hello, world!" in it.

Running tests

Pytest should be run with poetry run:

poetry run pytest

Code formatting

The project uses Black formatting style. All .py files in a PR must be black-formatted.

Install black extension for Visualtudio Code: https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter

IDE-specific Black integration guides:

Type checking

Enable "pylance" type checking in VS Code.

Open user settings, search by "pylance", scroll down to Python > Analysis: Type checking mode section. Enable basic mode.

Sort imports on Save

Install isort extension for imports formatting: https://marketplace.visualstudio.com/items?itemName=ms-python.isort

pre-commit

pre-commit is a dev dependency of Flet and is automatically installed by poetry install. To install the pre-commit hooks run: poetry run pre-commit install. Once installed, every time you commit, pre-commit will run the configured hooks against changed files.

Possible installation error when working with a source package

When you run python3 hello.py, you might encounter an error like this: FileNotFoundError: [Error 2] No such file or directory: '/var/folders/xm/cyv42vbs27gff3s39vy97rx00000gn/T/fletd-0.1.50/fletd'

To resolve the issue, just delete this folder ../T/fletd-0.1.50/fletd. The folder is the one with the FileNotFound Error encountered earlier.

It should work now.

Flutter client

Add the FLET_VIEW_PATH and FLET_WEB_PATH variables to the environment variables or profile scripts for your respective OS, making sure to modify the path accordingly:

  • On macOS (in ~/.zprofile or any other profile script):
# Flet
export FLET_VIEW_PATH="$HOME/{path-to-flet}/flet/client/build/macos/Build/Products/Release"
export FLET_WEB_PATH="$HOME/{path-to-flet}/flet/client/build/web"

  • On Windows (open "System Properties" > "Environment Variables", then add a new environment variable):

    • as "Variable name", enter FLET_VIEW_PATH, and as "Value", {path-to-flet}\flet\client\build\windows\x64\runner\Release
    • as "Variable name", enter FLET_WEB_PATH, and as "Value", {path-to-flet}\flet\client\build\web

  • On Linux (in ~/.bash_profile or any other profile script):

# Flet
export FLET_VIEW_PATH="$HOME/{path-to-flet}/flet/client/build/linux/{arch}/release/bundle"
export FLET_WEB_PATH="$HOME/{path-to-flet}/flet/client/build/web"

If you have Microsoft Edge installed and want to use it for debugging Flutter apps:

# Flutter
export CHROME_EXECUTABLE="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"

If you added these through the terminal, close that terminal session and create a new one.

Building the Flutter client

Open an instance of your IDE (preferably VS Code) at the flet-dev/flet/client directory.

First, run printenv | grep FLET (or gci env:* | findstr FLET on Windows) in the built-in terminal to make sure everything is set. You should see the above environment variables you set (FLET_VIEW_PATH, FLET_WEB_PATH) printed out.

  • To build the Flutter client for MacOS, run: 
    flutter build macos
    When the build is complete, you should see the Flet bundle in the FLET_VIEW_PATH. (Running it will open a blank window.)
  • To build the Flutter client for Web, run the below command: 
    flutter build web
    When the build is complete, a directory client/build/web will be created.

Running the Flutter client

Now open another instance of VS Code at flet-dev/flet/sdk/python directory.

Create a new folder preferably named playground (it has been added to the gitignore) in which you will test your additions.

Try running the below command, where <your-main.py> is the file to test your additions:

poetry run flet run -w -p 8550 playground/<your-main.py>

You should see http://127.0.0.1:8550/ opened in the browser and also a desktop window with the output of your code. Making changes to the <your-main.py> will automatically trigger a hot reload.

Now, switch to your flutter vscode instance and run the below command to start/connect the flet client:

flutter run

then choose your device from the shown options. You will be able to see the debugging outputs of the flet client in this terminal.

Restarting/Rebuilding

  • When you make changes to the flet dart files, you will need to restart/rerun the Flutter client for the changes to take effect in your playground. There are two ways to do this:

    • fastest: press the keyboard button R while in the client's terminal (press h to see all other possible options);
    • slowest: use flutter run as seen previously.

  • When you make changes to the flet python files, you will need to restart/rerun the Python client for the changes to take effect in the opened flutter applications. This is done with the same command:

    poetry run flet run -w -p 8550 playground/<your-main.py>

Releasing Flet

  • Create a new prepare-{version} branch in flet-dev/flet repository.
  • For every package in packages/flet* directory:
    • Update package version to {version} in pubspec.yaml.
    • Add # {version} with new/changed/fixed items into CHANGELOG.md. Only packages/flet/CHANGELOG.md should contain real items; other packages could have just a stub.
  • Copy # {version} section from packages/flet/CHANGELOG.md to the root CHANGELOG.md.
  • Open terminal in client directory and run flutter pub get to update Flet dependency versions in client/pubspec.lock.
  • Create a new {version} branch in flet-dev/flet-app-templates repository from a previously released {current-version} branch.
  • Create a new {version} branch in flet-dev/flet-build-template repository from a previously released {current-version} branch.
  • Create Prepare Flet {version} PR to merge into main branch.
  • In Build Flet package for Flutter job of Flet CI build make sure analysis report of every flet* Flutter package has only 1 issue "Publishable packages can't have 'path' dependencies.".
  • Merge Prepare Flet {version} PR.
  • Create and push new v{version} tag (with v prefix).
  • Update release notes at https://github.com/flet-dev/flet/releases/tag/v{version}.

New macOS environment for Flet developer

After installing homebrew, install xz libraries with it:

brew install xz

pyenv install 3.12.6
pyenv global 3.12.6

Setup your shell environment: https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zprofile

Ensure Python version is 3.12.6 and location is /Users/{user}/.pyenv/shims/python:

python --version
which python

rbenv install 3.3.5
rbenv global 3.3.5

Ensure Ruby version is 3.3.5 and location is /Users/{user}/.rbenv/shims/ruby:

ruby --version
which ruby

After installing poetry, set PATH:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zprofile

Check Poetry version and make sure it's in PATH:

poetry --version

fvm install 3.24.3
fvm global 3.24.3

Set PATH:

echo 'export PATH=$HOME/fvm/default/bin:$PATH' >> ~/.zprofile