Introducció

Briefcase és una eina per convertir un projecte Python en una aplicació nativa autònoma.

Pots empaquetar projectes per a:

macOS (com un paquet .app, un arxiu DMG o un instal·lador PKG)
Windows (com un .zip, o un instal·lador MSI)
Linux (com un Flatpak, o un paquet natiu del sistema .rpm, .deb o .pkg.zip)
iPhone/iPad
Android
Web

El suport per a Apple TV, watchOS i Wear OS està previst.

Inicia un projecte nou

Precaució

De moment no pots utilitzar uv per a crear un projecte (Compatibility with uv)

Farem servir la comanda new de Briefcase per crear una aplicació anomenada BriefcaseBasic.

Obre un terminal de Powershell.

uvx briefcase new

Briefcase et demanarà alguns detalls de la nova aplicació.

Per a aquest tutorial, utilitza el següent:


Formal name	BriefcaseBasic
App Name	briefcase-basic
Bundle Identifier	dev.xtec.briefcase.basic

Per executar la teva aplicació, escriu:

cd briefcase-basic
uvx briefcase dev

Empaquetar per a distribució

Fins ara, hem estat executant l’aplicació en “mode desenvolupador”. Això facilita executar-la localment — però el que realment volem és poder donar la nostra aplicació a altres persones.

Briefcase es pot utilitzar per empaquetar la teva aplicació per distribuir-la d’aquesta manera.

Crear l’esquelet de l’aplicació

Com que és la primera vegada que empaquetem l’aplicació, hem de crear alguns fitxers de configuració i altres elements d’esquelet per donar suport al procés d’empaquetat.

Des del directori briefcase-basic, executa:

uvx briefcase create

Probablement acabes de veure pàgines i pàgines de contingut desfilant pel terminal… què ha passat? Briefcase ha fet el següent:

Mira

Quan això acabi, si mires el directori del projecte, ara hi veuràs un directori corresponent a la teva plataforma (macOS, linux o windows) que conté fitxers addicionals. Aquesta és la configuració d’empaquetat específica de la plataforma per a la teva aplicació.

Compilar la teva aplicació

Ara pots compilar la teva aplicació. Aquest pas realitza qualsevol compilació binària necessària perquè la teva aplicació sigui executable a la plataforma objectiu.

uvx briefcase build

Quan aquest pas acabi, la carpeta build contindrà el binari de l’aplicació per a la teva plataforma objectiu.

...
[briefcase-basic] Built build\briefcase-basic\windows\app\src\BriefcaseBasic.exe

Executar la teva aplicació

Ara pots utilitzar Briefcase per executar la teva aplicació:

uvx briefcase run

O directament:

.\build\briefcase-basic\windows\app\src\BriefcaseBasic.exe

Això iniciarà l’execució de la teva aplicació nativa, utilitzant el paquet d’aplicació creat per la comanda de compilació.

Pots notar petites diferències en l’aparença quan s’executa. Per exemple, les icones i el nom que mostra el sistema operatiu poden ser lleugerament diferents dels que vas veure en mode desenvolupador. Això és perquè estàs utilitzant l’aplicació empaquetada, no executant només codi Python. Des de la perspectiva del sistema operatiu, ara estàs executant “una aplicació”, no “un programa Python”, i això es reflecteix en com apareix.

Crear el teu instal·lador

Ara pots empaquetar la teva aplicació per a la distribució utilitzant la comanda package. Aquesta comanda fa qualsevol compilació necessària per convertir el projecte amb l’esquelet en un producte final distribuïble. Depenent de la plataforma, això pot implicar compilar un instal·lador, fer el signat de codi, o altres tasques prèvies a la distribució.

uvx briefcase package

La carpeta dist contindrà el fitxer .msi generat.

...
[briefcase-basic] Packaged dist\BriefcaseBasic-0.0.1.msi

Activitat. Instal·la l’aplicació que has generat.

Actualitzar la teva aplicació

Tutorial

Portar-ho al mòbil: Android

Briefcase gestiona la instal·lació de dependències per a Android, incloent l’Android SDK, l’emulador d’Android i un compilador Java.

Obre un terminal de Powershell i navega a la carpeta on has creat el projecte.

Executa:

uvx briefcase create android

Quan executis briefcase create android per primera vegada, Briefcase descarregarà un JDK de Java i l’Android SDK. La mida dels fitxers i els temps de descàrrega poden ser considerables; això pot trigar una estona (10 minuts o més, depenent de la velocitat de la teva connexió). Quan la descàrrega acabi, se’t demanarà acceptar la llicència de l’Android SDK de Google. Hi ha diverses llicències que hauràs d’acceptar — continua prement y per revisar i acceptar cadascuna de les llicències necessàries.

Quan això acabi, tindrem un directori build\briefcase-basic\android\gradle dins del projecte, que contindrà un projecte d’Android amb configuració de compilació Gradle. Aquest projecte contindrà el codi de la teva aplicació i un paquet de suport que inclou l’intèrpret de Python.

Després podem utilitzar la comanda build de Briefcase per compilar-ho en un fitxer APK d’Android.

uvx briefcase build android

Nota

Pot semblar que Gradle està aturat

Durant el pas briefcase build android, Gradle (l’eina de compilació d’Android) pot mostrar CONFIGURING: 100% i sembla que no faci res. No et preocupis, no està aturat — està descarregant més components de l’Android SDK. Depenent de la velocitat de la teva connexió, això pot trigar 10 minuts més (o més). Aquesta espera només passa la primera vegada que executes build; les eines es posen en memòria cau i, en la propera compilació, s’utilitzaran les versions en memòria cau.

Ara estem a punt per executar l’aplicació. Pots utilitzar la comanda run de Briefcase per executar l’app en un dispositiu Android. Comencem executant-la en un emulador d’Android.

Per executar la teva aplicació, executa briefcase run android. Quan ho facis, se’t mostrarà una llista de dispositius on podries executar l’app. L’últim element sempre serà l’opció de crear un emulador d’Android nou.

uvx briefcase run android

Continua: Tutorial

Activitat. Executa l’aplicació en el teu dispositiu Android.

Web

Precaució

El backend Web de Toga és el menys madur de tots els backends de Toga. És prou madur per mostrar algunes funcionalitats, però probablement tingui errors i li faltin molts dels widgets disponibles en altres plataformes.

El procés de desplegar com a aplicació web d’una sola pàgina segueix el patró habitual: crees l’aplicació, després la construeixes i finalment l’executes. Tot i això, Briefcase pot ser una mica llest; si intentes executar una aplicació i Briefcase determina que no s’ha creat o construït per a la plataforma objectiu, farà els passos de creació i construcció per tu.

Com que és la primera vegada que executem l’app per al web, podem fer els tres passos amb una sola comanda:

uvx briefcase run web

Això obrirà un navegador web apuntant a http://127.0.0.1:8080.

Aquesta aplicació web és un lloc estàtic — una sola pàgina HTML, amb una mica de CSS i altres recursos. Briefcase ha iniciat un servidor web local per servir aquesta pàgina perquè el navegador la pugui veure. Si volguessis posar aquesta pàgina en producció, podries copiar el contingut de la carpeta www a qualsevol servidor web que pugui servir contingut estàtic.

Però quan prems el botó, s’està executant codi Python… com funciona? Toga utilitza PyScript per proporcionar un intèrpret de Python al navegador. Briefcase paquetitza el codi de la teva app com a rodes (wheels) que PyScript pot carregar al navegador. Quan es carrega la pàgina, el codi de l’aplicació s’executa al navegador, construint la interfície d’usuari amb el DOM del navegador. Quan cliques un botó, aquest botó executa el codi de maneig d’esdeveniments al navegador.