From 7f18eb4a731317556a72d656a9bee5d0dcef0f6f Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Tue, 10 Mar 2026 16:14:44 -0700 Subject: [PATCH 01/10] fix typo (item 2 in Issue 67) --- docs/en/tutorial/tutorial-7.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-7.md b/docs/en/tutorial/tutorial-7.md index 9af3b92..1025a64 100644 --- a/docs/en/tutorial/tutorial-7.md +++ b/docs/en/tutorial/tutorial-7.md @@ -654,7 +654,7 @@ The `-r` option for updating requirements is also honored by the `build` and `ru Faker is just one example of a third-party Python package - a collection of code that isn't part what Python provides out of the box. These third-party packages are most commonly distributed using the [Python Package Index (PyPI)](https://pypi.org), and installed into your local virtual environment. We've been using `pip` in this tutorial, but there are other options. -On desktop platforms (macOS, Windows, Linux), essentially any package on PyPI package can be installed into your virtual environment, or added to your app's requirements. However, when building an app for mobile or web platforms, [your options are slightly limited](https://briefcase.beeware.org/en/latest/about/faq#can-i-use-third-party-python-packages-in-my-app). +On desktop platforms (macOS, Windows, Linux), essentially any package on PyPI can be installed into your virtual environment, or added to your app's requirements. However, when building an app for mobile or web platforms, [your options are slightly limited](https://briefcase.beeware.org/en/latest/about/faq#can-i-use-third-party-python-packages-in-my-app). In short; any *pure Python* package (i.e. any package created from a project written *only* in Python) can be used without difficulty. Some packages, though, are created from projects that contain both Python and other languages (e.g. C, C++, Rust, etc). Code written in those languages needs to be compiled to platform-specific binary modules before it can be used, and those pre-compiled binary modules are only available on specific platforms. Mobile and web platforms have very different requirements than "standard" desktop platforms. At this time, most Python packages don't provide pre-compiled binaries for mobile and web platforms. From a124f27ab2246163dde5758fd4a493dccc2a495b Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Tue, 10 Mar 2026 16:15:24 -0700 Subject: [PATCH 02/10] clarify when -r is needed for adding httpx (item 4) --- docs/en/tutorial/tutorial-8.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index b333980..6c57b70 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -12,9 +12,9 @@ This is a toy app, so we don't have a *real* API to work with, so we'll use a sa The Python standard library contains all the tools you'd need to access an API. However, the built-in APIs are very low level. They are good implementations of the HTTP protocol - but they require the user to manage lots of low-level details, like URL redirection, sessions, authentication, and payload encoding. As a "normal browser user" you're probably used to taking these details for granted, as a browser manages them for you. -As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the {JSON} Placeholder API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local environment - you don't need to install it separately to use it here. +As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the {JSON} Placeholder API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (dev) environment - you don't need to install it separately to use it here. -Let's add a `httpx` API call to our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: +But to use it in our app, it will still need to be installed in our packaged environment. So let's add a `httpx` API call to our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: ```python requires = [ @@ -54,14 +54,14 @@ This will change the `say_hello()` callback so that when it is invoked, it will: - extract the body of the post; and - include the body of that post as the text of the "message" dialog, in place of the text generated by Faker. -Lets run our updated app in Briefcase developer mode to check that our change has worked. As we've added a new requirement, we need to tell developer mode to reinstall requirements, by using the `-r` argument: +Lets run our updated app in Briefcase developer mode to check that our change has worked. We've added `httpx` as a new requirement, but since Briefcase uses it internally, we don't need to reinstall requirements with the `-r` flag. /// tab | macOS ```console -(beeware-venv) $ briefcase dev -r +(beeware-venv) $ briefcase dev -[helloworld] Installing requirements... +[helloworld] Activating dev environment... ... [helloworld] Starting in dev mode... =========================================================================== @@ -80,9 +80,9 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Linux ```console -(beeware-venv) $ briefcase dev -r +(beeware-venv) $ briefcase dev -[helloworld] Installing requirements... +[helloworld] Activating dev environment... ... [helloworld] Starting in dev mode... =========================================================================== @@ -101,9 +101,9 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Windows ```doscon -(beeware-venv) C:\...>briefcase dev -r +(beeware-venv) C:\...>briefcase dev -[helloworld] Installing requirements... +[helloworld] Activating dev environment... ... [helloworld] Starting in dev mode... =========================================================================== @@ -208,7 +208,7 @@ If you save these changes and re-run the app in development mode, there won't be - If you move/resize the app window while waiting for the dialog to appear, the window will redraw. - If you try to open an app menu, the menu will appear immediately. -We can now run the full app. However, as we've added an extra requirement (`httpx`) we also need to update our app's requirements; we can do this by passing `-r` to `briefcase run`. This will update our app's requirements, then re-build the app, then launch the app: +We can now run the full app. However, as we've added an extra requirement (`httpx`) we now need to update our app's requirements; we can do this by passing `-r` to `briefcase run`. This will update our app's requirements, then re-build the app, then launch the app: /// tab | macOS From 07352ff3e68e748f8877a2e7474fbd37d5812bdd Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Tue, 10 Mar 2026 16:22:47 -0700 Subject: [PATCH 03/10] change confusing text about post 42 (item 3) --- docs/en/tutorial/tutorial-8.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index 6c57b70..1229a90 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -49,10 +49,10 @@ async def say_hello(self, widget): This will change the `say_hello()` callback so that when it is invoked, it will: -- make a GET request on the JSON placeholder API to obtain post 42; +- make a GET request on the tutorial API to retrieve a message; - decode the response as JSON; -- extract the body of the post; and -- include the body of that post as the text of the "message" dialog, in place of the text generated by Faker. +- extract the body of the message; and +- include the body of that message as the text of the dialog, in place of the text generated by Faker. Lets run our updated app in Briefcase developer mode to check that our change has worked. We've added `httpx` as a new requirement, but since Briefcase uses it internally, we don't need to reinstall requirements with the `-r` flag. From 3e909a47919853e44a5200fdd092fd36c548f3f7 Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Tue, 10 Mar 2026 16:22:57 -0700 Subject: [PATCH 04/10] clarify where platform directory lives (item 1) --- docs/en/tutorial/tutorial-3.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-3.md b/docs/en/tutorial/tutorial-3.md index b357c7e..8a1d8b1 100644 --- a/docs/en/tutorial/tutorial-3.md +++ b/docs/en/tutorial/tutorial-3.md @@ -122,7 +122,14 @@ You've probably just seen pages of content go past in your terminal... so what j 5. It **installed your resources needed by your application.** Lastly, it adds any additional resources that are needed by the installer itself. This includes things like icons that need to be attached to the final application and splash screen images. -Once this completes, if you look in the project directory, you should now see a directory corresponding to your platform (`macOS`, `linux`, or `windows`) that contains additional files. This is the platform-specific packaging configuration for your application. +Once this completes, if you look in the project's `build` directory, you should now see a directory corresponding to your platform (`macOS`, `linux`, or `windows`) that contains additional files. This is the platform-specific packaging configuration for your application. For example, on macOS, your project directory will now include: + +```text +helloworld/ +└── build/ + └── helloworld/ + └── macos/ +``` ## Building your application From ca76ab2f9aebc75017c6233b9961d21a8e03f1b6 Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Wed, 11 Mar 2026 11:59:17 -0700 Subject: [PATCH 05/10] =?UTF-8?q?wrap=20=E2=80=98dev=E2=80=99=20in=20backt?= =?UTF-8?q?icks=20for=20spell=20check?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/tutorial/tutorial-8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index 1229a90..e89accf 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -12,7 +12,7 @@ This is a toy app, so we don't have a *real* API to work with, so we'll use a sa The Python standard library contains all the tools you'd need to access an API. However, the built-in APIs are very low level. They are good implementations of the HTTP protocol - but they require the user to manage lots of low-level details, like URL redirection, sessions, authentication, and payload encoding. As a "normal browser user" you're probably used to taking these details for granted, as a browser manages them for you. -As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the {JSON} Placeholder API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (dev) environment - you don't need to install it separately to use it here. +As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the {JSON} Placeholder API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (`dev`) environment - you don't need to install it separately to use it here. But to use it in our app, it will still need to be installed in our packaged environment. So let's add a `httpx` API call to our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: From c1daef9501e83aa397ffb111494cfcc28b8406ad Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Wed, 11 Mar 2026 12:18:25 -0700 Subject: [PATCH 06/10] fix another reference to {JSON} Placeholder API --- docs/en/tutorial/tutorial-8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index e89accf..9b02f1e 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -12,7 +12,7 @@ This is a toy app, so we don't have a *real* API to work with, so we'll use a sa The Python standard library contains all the tools you'd need to access an API. However, the built-in APIs are very low level. They are good implementations of the HTTP protocol - but they require the user to manage lots of low-level details, like URL redirection, sessions, authentication, and payload encoding. As a "normal browser user" you're probably used to taking these details for granted, as a browser manages them for you. -As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the {JSON} Placeholder API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (`dev`) environment - you don't need to install it separately to use it here. +As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the tutorial API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (`dev`) environment - you don't need to install it separately to use it here. But to use it in our app, it will still need to be installed in our packaged environment. So let's add a `httpx` API call to our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: From a66dcbbd83b8637ec2d51304264fe6fb3fda4832 Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Thu, 12 Mar 2026 15:11:09 -0700 Subject: [PATCH 07/10] Correct requierments to use httpx in dev mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `-r` _is_ required even in dev mode, so add that back in - Remove the confusing part about how it’s already in the local environment --- docs/en/tutorial/tutorial-8.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index 9b02f1e..34c67b0 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -12,9 +12,9 @@ This is a toy app, so we don't have a *real* API to work with, so we'll use a sa The Python standard library contains all the tools you'd need to access an API. However, the built-in APIs are very low level. They are good implementations of the HTTP protocol - but they require the user to manage lots of low-level details, like URL redirection, sessions, authentication, and payload encoding. As a "normal browser user" you're probably used to taking these details for granted, as a browser manages them for you. -As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the tutorial API - a library called [`httpx`](https://www.python-httpx.org). Briefcase uses `httpx` internally, so it's already in your local (`dev`) environment - you don't need to install it separately to use it here. +As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the tutorial API - a library called [`httpx`](https://www.python-httpx.org). -But to use it in our app, it will still need to be installed in our packaged environment. So let's add a `httpx` API call to our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: +Let's add an `httpx` API call to our app. First, as with `faker` in the [previous step](tutorial-7.md), we need to tell briefcase to install `httpx` when it builds our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: ```python requires = [ @@ -54,14 +54,14 @@ This will change the `say_hello()` callback so that when it is invoked, it will: - extract the body of the message; and - include the body of that message as the text of the dialog, in place of the text generated by Faker. -Lets run our updated app in Briefcase developer mode to check that our change has worked. We've added `httpx` as a new requirement, but since Briefcase uses it internally, we don't need to reinstall requirements with the `-r` flag. +Lets run our updated app in Briefcase developer mode to check that our change has worked. As we've added a new requirement, we need to tell developer mode to reinstall requirements, by using the `-r` argument: /// tab | macOS ```console -(beeware-venv) $ briefcase dev +(beeware-venv) $ briefcase dev -r -[helloworld] Activating dev environment... +[helloworld] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== @@ -80,9 +80,9 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Linux ```console -(beeware-venv) $ briefcase dev +(beeware-venv) $ briefcase dev -r -[helloworld] Activating dev environment... +[helloworld] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== @@ -101,9 +101,9 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Windows ```doscon -(beeware-venv) C:\...>briefcase dev +(beeware-venv) C:\...>briefcase dev -r -[helloworld] Activating dev environment... +[helloworld] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== From 935df8eb748786f7c96101f87d7350e6ff058094 Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Thu, 12 Mar 2026 15:16:46 -0700 Subject: [PATCH 08/10] revert unnecessary change --- docs/en/tutorial/tutorial-8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index 34c67b0..ee9eb7d 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -208,7 +208,7 @@ If you save these changes and re-run the app in development mode, there won't be - If you move/resize the app window while waiting for the dialog to appear, the window will redraw. - If you try to open an app menu, the menu will appear immediately. -We can now run the full app. However, as we've added an extra requirement (`httpx`) we now need to update our app's requirements; we can do this by passing `-r` to `briefcase run`. This will update our app's requirements, then re-build the app, then launch the app: +We can now run the full app. However, as we've added an extra requirement (`httpx`) we also need to update our app's requirements; we can do this by passing `-r` to `briefcase run`. This will update our app's requirements, then re-build the app, then launch the app: /// tab | macOS From 042ff19065d60744e787ad474ebe4ece91048a4a Mon Sep 17 00:00:00 2001 From: Scott Halgrim Date: Thu, 12 Mar 2026 15:23:52 -0700 Subject: [PATCH 09/10] retrigger CI From eb81d7ed70a5fc2c8d965f2daf1a9037fe4fc514 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Fri, 13 Mar 2026 08:23:34 +0800 Subject: [PATCH 10/10] Minor clarification tweak. --- docs/en/tutorial/tutorial-8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorial/tutorial-8.md b/docs/en/tutorial/tutorial-8.md index ee9eb7d..532e1ec 100644 --- a/docs/en/tutorial/tutorial-8.md +++ b/docs/en/tutorial/tutorial-8.md @@ -12,7 +12,7 @@ This is a toy app, so we don't have a *real* API to work with, so we'll use a sa The Python standard library contains all the tools you'd need to access an API. However, the built-in APIs are very low level. They are good implementations of the HTTP protocol - but they require the user to manage lots of low-level details, like URL redirection, sessions, authentication, and payload encoding. As a "normal browser user" you're probably used to taking these details for granted, as a browser manages them for you. -As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries to access the tutorial API - a library called [`httpx`](https://www.python-httpx.org). +As a result, people have developed third-party libraries that wrap the built-in APIs and provide a simpler API that is a closer match for the everyday browser experience. We're going to use one of those libraries - a library called [`httpx`](https://www.python-httpx.org) - to access a simple API. Let's add an `httpx` API call to our app. First, as with `faker` in the [previous step](tutorial-7.md), we need to tell briefcase to install `httpx` when it builds our app. Modify the `requires` setting in our `pyproject.toml` to include the new requirement: