[color=]THIS POST IS IN WORK - PLEASE DO NOT FOLLOW THE GUIDELINE YET[/color]
Hi,
in here I am going to write about a HowTo Deploy and Distribute a wxPython App with Briefcase because so far I could not find any blog post or wiki page (if so, please send a link to this topic and I will add it in the first post!).
This HowTo shall be understandable by Python Newbies and thus this HowTo is done with step-by-step instructions.
First, I just want to cover Python version 3. This is because for older Python versions I would suggest the existing tools py2exe, py2app or other tools you will find in the wxpython wiki - Creating Standalone Executables.
What is Briefcase?
Briefcase is part of the BeeWare python package, which slogan is Write once. Deploy everywhere.
According to the website, Briefcase
is a tool for converting a Python project into a standalone native application. You can package projects for:
- Mac
- Windows
- Linux
- iPhone/iPad
- Android
However, wxPython supports the operation systems Mac, Windows and Linux - thus I will just cover these platforms.
Briefcase vs. Pyinstaller
Briefcase is a packaging tool, this means you specify the Python packages and your source code and Briefcase takes the packages with pip and your source code and bundles it to a platform native installer (in Windows it is a .msi-file). So basically everything you install in your Python environment setup is also done by Briefcase later on. Note that briefcase is using pip - so do not mess up a python environment with other distribution platforms like anaconda.
The difference to Pyinstaller is that Pyinstaller tries to freeze your current Python Environment. You have to specify hooks so that pyinstaller gets all the files your application needs.
More information about the difference between Briefcase and Pyinstaller is found here:
If you want to have support for Android and iPhone look for other GUI libraries like Toga (BeeWare’s GUI), PySide/PyQt or Kivy.
Windows
Install Environment & Briefcase
A good practice is to create a virtual environment. In this case I will use Python’s native package: venv
We will create this environment in your windows home directory with cmd.exe (python must be available in the system variables):
python -m venv %userprofile%/wxpython_env
We are going to activate the environment with cmd.exe:
cd %userprofile%/wxpython_env/scripts
activate
Now we are going to install packages which are needed for our Simple Test-GUI.
pip install numpy==1.21.2
pip install wxpython==4.1.1
pip install opencv-python==4.5.1.48
pip install beeware==0.3.0
Setup a Briefcase project
Before we write python code we need to initialize a briefcase project, thus we are typing in cmd.exe:
briefcase new
From now we have to go through the set up of briefcase. Note that the information you are going to type in is used for the package you want to deploy.
The following is an example only the last setup (GUI Framework) is important for our HowTo:
Formal Name [Hello World]: wxWebcam
App Name [wxwebcam]: wxWebcam
Bundle Identifier [com.example]: org.wxpython
Project Name [wxWebcam]: wxPython
Description [My first application]: A small application to look at yourself and take an image!
Author [Jane Developer]: Rune Monzel
Author's Email [rune@wxpython.org]: thisisnotmy@email.com
Application URL [https://wxpython.org/wxWebcam]: https://wxpython.org/
Project License [1]: 1
The GUI Frameworks must be None!
GUI Framework [1]: 3
Now we have set up briefcase. A new briefcase folder have been done in %userprofile%/wxpython_env/scripts/wxwebcam. Here we will find the folder src and four other files:
- pyproject.toml - in here we set up the build process of briefcase. It is the most important file in briefcase. See next chapter on how to setup the pyproject.toml file.
- LICENSE - in the example above we choosed the MIT License - you should care about Licensing
- README.rst - in here you should write your project description - it is not visible in the deployed package
- .gitignore - usefull .gitignore file to suppress the build / output of briefcase which should not be commited to git
In %userprofile%/wxpython_env/scripts/wxwebcam/src/wxWebcam folder we see the following files:
- folder resources with .icns-, .ico- and .png-files
- __init__.py
- __main__.py
- app.py
pyproject.toml
The pyproject.toml file configures your Briefcase project. In here you should specify the python packages which is needed by your application.
In our example you should see the following lines:
[tool.briefcase.app.wxWebcam]
formal_name = “wxWebcam”
description = “A small application to look at yourself and take an image!”
icon = “src/wxWebcam/resources/wxWebcam”
sources = [‘src/wxWebcam’]
requires =
Here, at requires = [], we need to add the python packages which is needed for our application. The packages specified here are platform independent. The packages listed here are taken from PyPi In our example we should replace it with the packages we installed in our environment (see Install Environment & Briefcase):
requires = [
'wyPython=4.1.1',
'numpy==1.20.2',
'opencv-python==4.5.1.48']
It is also possible to add a wheel-packages which are not uploaded on PyPi. This is crucial if you want to add a package which you have written by yourself or which is an OpenSource Library on GitHub, but can not be downloaded from PyPi. You need to build a wheel with python (more information: Packaging Python Projects - Python Packaging User Guide) and add it to the requires option, like in the following:
requires = [
'wyPython=4.1.1',
'numpy==1.20.2',
'opencv-python==4.5.1.48',
'..\..\..\..\MyPackage\python\dist\MyPackage-0.1.0-cp38-cp38-win_amd64.whl']
Note: the python package MyPackage is in the windows home directory %userprofile% - make sure the relative path to the wheel is correct! Also, .whl packages are often platfrom dependent - thus, add it to the requires option under the platform, for Windows it would be [tool.briefcase.app.wxWebcam.windows].
Adding the application code
We are now adding our application code which you can find attached in this post.
The python code uses OpenCV to use the WebCam. OpenCV is a famous library for image processing.
The app.py file in %userprofile%/wxpython_env/scripts/wxwebcam/src/wxWebcam is not needed anymore - you can delete it.
Linux
TO-BE-DONE!
Mac
TO-BE-DONE!
