Tutorial and target directory config.

Author: filiplajszczak

docs/index.md

@@ -10,6 +10,8 @@ pip install git+https://github.com/beeware/briefcase@main
 ```
 ///
 
+There is a [tutorial](tutorial.md) that builds on top of the [BeeWare Tutorial](https://tutorial.beeware.org/) and walks you through deploying your first app to PythonAnywhere.
+
 ## Prerequisites
 
 * A PythonAnywhere account
@@ -75,6 +77,15 @@ The domain name for your PythonAnywhere webapp. If not specified, defaults to `<
 domain = "www.mycustomdomain.com"
 ```
 
+### `directory`
+
+The remote directory on PythonAnywhere where the app files will be uploaded. If not specified, defaults to `/home/<username>/<app_name>`.
+
+```toml
+[tool.briefcase.app.myapp.pythonanywhere]
+directory = "/home/mypauser/www"
+```
+
 ## Environment variables
 
 The following environment variables are used by the plugin:

docs/tutorial.md

@@ -0,0 +1,211 @@
+# Tutorial - Deploy to PythonAnywhere
+
+This tutorial picks up where [Tutorial 6 - Put it on the web!](https://tutorial.beeware.org/en/latest/tutorial/tutorial-6/) of the BeeWare Tutorial leaves off. In that tutorial, you built a static web app and ran it locally with `briefcase run web`. Now we'll publish it to PythonAnywhere so it's accessible on the internet.
+
+/// admonition | Prerequisites
+    type: info
+
+Before starting, make sure you have:
+
+* Completed the BeeWare tutorial through [Tutorial 6](https://tutorial.beeware.org/en/latest/tutorial/tutorial-6/) (or at least run `briefcase create web static` and `briefcase build web static`)
+* A [PythonAnywhere](https://www.pythonanywhere.com/) account
+* An API token from your [Account page](https://www.pythonanywhere.com/account/#api_token)
+
+///
+
+## Install the plugin
+
+With your BeeWare tutorial virtual environment active, install the plugin:
+
+/// tab | macOS
+
+```console
+(beeware-venv) $ pip install pythonanywhere-briefcase-plugin
+```
+
+///
+
+/// tab | Linux
+
+```console
+(beeware-venv) $ pip install pythonanywhere-briefcase-plugin
+```
+
+///
+
+/// tab | Windows
+
+```doscon
+(beeware-venv) C:\...>pip install pythonanywhere-briefcase-plugin
+```
+
+///
+
+## Package the app
+
+In Tutorial 6, you ran the app locally with `briefcase run web`. To publish it, we first need to package the app into a distributable artifact:
+
+/// tab | macOS
+
+```console
+(beeware-venv) $ briefcase package web static
+
+[helloworld] Packaging Hello World...
+...
+
+[helloworld] Packaged dist/Hello World-0.0.1.web.zip
+```
+
+///
+
+/// tab | Linux
+
+```console
+(beeware-venv) $ briefcase package web static
+
+[helloworld] Packaging Hello World...
+...
+
+[helloworld] Packaged dist/Hello World-0.0.1.web.zip
+```
+
+///
+
+/// tab | Windows
+
+```doscon
+(beeware-venv) C:\...>briefcase package web static
+
+[helloworld] Packaging Hello World...
+...
+
+[helloworld] Packaged dist\Hello World-0.0.1.web.zip
+```
+
+///
+
+This creates a ZIP file containing all the static files needed to serve your app.
+
+## Set your API token
+
+The plugin needs your PythonAnywhere API token to upload files and configure the webapp. Set it as an environment variable:
+
+/// tab | macOS
+
+```console
+(beeware-venv) $ export API_TOKEN=your-api-token-here
+```
+
+///
+
+/// tab | Linux
+
+```console
+(beeware-venv) $ export API_TOKEN=your-api-token-here
+```
+
+///
+
+/// tab | Windows
+
+```doscon
+(beeware-venv) C:\...>set API_TOKEN=your-api-token-here
+```
+
+///
+
+Replace `your-api-token-here` with the token from your [Account page](https://www.pythonanywhere.com/account/#api_token).
+
+//// admonition | Username
+    type: note
+
+The plugin needs to know your PythonAnywhere username to upload files to the right place. By default, it uses the `PYTHONANYWHERE_USERNAME` environment variable, falling back to your local system username.
+
+If you're running this from a PythonAnywhere console, the username is detected automatically -- no extra configuration needed.
+
+If you're running locally and your PythonAnywhere username is different from your local system username, either set the environment variable:
+
+/// tab | macOS
+
+```console
+(beeware-venv) $ export PYTHONANYWHERE_USERNAME=your-pa-username
+```
+
+///
+
+/// tab | Linux
+
+```console
+(beeware-venv) $ export PYTHONANYWHERE_USERNAME=your-pa-username
+```
+
+///
+
+/// tab | Windows
+
+```doscon
+(beeware-venv) C:\...>set PYTHONANYWHERE_USERNAME=your-pa-username
+```
+
+///
+
+or add it to the `pyproject.toml` of your app:
+
+```toml
+[tool.briefcase.app.helloworld.pythonanywhere]
+username = "your-pa-username"
+```
+
+////
+
+## Publish
+
+Now, publish the app to PythonAnywhere:
+
+/// tab | macOS
+
+```console
+(beeware-venv) $ briefcase publish web static
+```
+
+///
+
+/// tab | Linux
+
+```console
+(beeware-venv) $ briefcase publish web static
+```
+
+///
+
+/// tab | Windows
+
+```doscon
+(beeware-venv) C:\...>briefcase publish web static
+```
+
+///
+
+The plugin will:
+
+1. Extract the packaged ZIP file.
+2. Upload the contents to `/home/<your-username>/helloworld/` on PythonAnywhere.
+3. Create a webapp (or update the existing one) with a static file mapping pointing `/` to that directory.
+4. Reload the webapp.
+
+Once it's done, your app is live at `https://<your-username>.pythonanywhere.com/`!
+
+## How does this work?
+
+In Tutorial 6, Briefcase started a local web server to serve your static web app. The `publish` command takes the same static files and deploys them to PythonAnywhere's infrastructure instead.
+
+PythonAnywhere serves the files as a static website -- no Python process runs on the server. The Python code in your app runs in the *browser*, using [PyScript](https://pyscript.net), just as it did when you ran it locally.
+
+The plugin uses the [PythonAnywhere API](https://help.pythonanywhere.com/pages/API/) to upload files and configure the webapp, which is why the API token is required.
+
+## Next steps
+
+Your app is now live on the internet. From here you might want to:
+
+* **Use a custom domain** -- configure a `domain` in your `pyproject.toml` to serve the app from your own domain name. See the [Configuration](index.md#configuration) section.
+* **Continue the BeeWare tutorial** -- [Tutorial 7](https://tutorial.beeware.org/en/latest/tutorial/tutorial-7/) covers adding third-party libraries to your app.

mkdocs.yml

@@ -6,6 +6,10 @@ repo_name: pythonanywhere/pythonanywhere-briefcase-plugin
 
 docs_dir: docs
 
+nav:
+  - Home: index.md
+  - Tutorial: tutorial.md
+
 theme:
   name: material
   language: en
@@ -36,6 +40,8 @@ markdown_extensions:
   pymdownx.highlight: {}
   pymdownx.superfences: {}
   pymdownx.blocks.admonition: {}
+  pymdownx.blocks.tab:
+    alternate_style: true
   pymdownx.details: {}
   toc:
     permalink: true

pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "pythonanywhere-briefcase-plugin"
-version = "0.0.1a3"
+version = "0.0.1a4"
 description = "A Briefcase publication channel plugin for deploying static web apps to PythonAnywhere."
 requires-python = ">= 3.10"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
-    {name = "Filip Lajszczak", email = "filip@lajszczak.dev"},
+    {name = "PythonAnywhere", email = "developers@pythonanywhere.com"},
 ]
 keywords = ["briefcase", "pythonanywhere", "deployment", "web", "static"]
 classifiers = [
@@ -26,6 +26,10 @@ dependencies = [
     "pythonanywhere-core >= 0.3.0",
 ]
 
+[project.urls]
+Documentation = "https://briefcase.pythonanywhere.com/"
+Repository = "https://github.com/pythonanywhere/pythonanywhere-briefcase-plugin"
+
 [build-system]
 requires = ["uv_build >= 0.7.2, < 0.8"]
 build-backend = "uv_build"

src/pythonanywhere_briefcase_plugin/__init__.py

@@ -1,4 +1,4 @@
 from pythonanywhere_briefcase_plugin.channel import PythonAnywherePublicationChannel
 
-__version__ = "0.0.1a3"
+__version__ = "0.0.1a4"
 __all__ = ["PythonAnywherePublicationChannel"]

src/pythonanywhere_briefcase_plugin/channel.py

@@ -58,7 +58,9 @@ def publish_app(self, app: AppConfig, command: PublishCommandAPI, **options):
 
         username = self._resolve_username(app)
         domain = self._resolve_domain(app)
-        remote_path = f"/home/{username}/{app.app_name}"
+        remote_path = getattr(app, "pythonanywhere_directory", None)
+        if not remote_path:
+            remote_path = f"/home/{username}/{app.app_name}"
 
         try:
             with tempfile.TemporaryDirectory() as tmpdir:

tests/conftest.py

@@ -24,6 +24,7 @@ def mock_app(mocker):
     # No pythonanywhere-specific config by default
     del app.pythonanywhere_username
     del app.pythonanywhere_domain
+    del app.pythonanywhere_directory
     return app
 
 

tests/test_channel.py

@@ -187,3 +187,24 @@ def test_publish_updates_existing_webapp(mock_app, mock_command, dist_zip, mocke
         "/", Path("/home/testuser/myapp")
     )
     mock_webapp.reload.assert_called_once()
+
+
+def test_publish_custom_directory(mock_app, mock_command, dist_zip, mocker):
+    mock_app.pythonanywhere_username = "testuser"
+    mock_app.pythonanywhere_directory = "/home/testuser/custom-dir"
+
+    mock_files_cls = mocker.patch("pythonanywhere_briefcase_plugin.channel.Files")
+    mock_webapp_cls = mocker.patch("pythonanywhere_briefcase_plugin.channel.Webapp")
+    mock_webapp_cls.return_value.get.return_value = {"id": 1}
+
+    channel = PythonAnywherePublicationChannel()
+    channel.publish_app(mock_app, mock_command)
+
+    # Files uploaded to custom remote path
+    _, remote_path = mock_files_cls.return_value.tree_post.call_args[0]
+    assert remote_path == "/home/testuser/custom-dir"
+
+    # Static file mapping uses custom path
+    mock_webapp_cls.return_value.create_static_file_mapping.assert_called_once_with(
+        "/", Path("/home/testuser/custom-dir")
+    )