Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .template_sync/manifest.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
template_version: 0.1.39
template_version: 0.1.40
migrations:
- from: 0.0.0
to: 0.0.1
Expand Down Expand Up @@ -123,3 +123,6 @@ migrations:
- from: 0.1.38
to: 0.1.39
script: migrations/v0_1_38_to_v0_1_39.py
- from: 0.1.39
to: 0.1.40
script: migrations/v0_1_39_to_v0_1_40.py
134 changes: 134 additions & 0 deletions .template_sync/migrations/v0_1_39_to_v0_1_40.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
"""Template 0.1.39 -> 0.1.40: an editorial pass on seven guides.

Design note: https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_40.md

Seven guides are rewritten to lead with what the reader does: filler, screenshot narration and brochure sections are removed, and the
behaviour they describe is unchanged. install.md no longer gives app users the `hosts:` rules of labconstrictor-app.yaml, and
workflow_status.md asks to remove tokens and private paths before showing a log to an AI assistant.

What this changes in an app repository: each file in FILES is replaced by the 0.1.40 page when it is still the template file last shipped
(the 0.1.39 copy; compared with LF line endings; the file keeps its own line endings). A file the app changed itself stays as it is
(SKIPPED, with a note of what to change by hand). A missing file is not created, and nothing is deleted. external_code_upload.md is also
recognised with the app's Python package name in place of PYTHON_PROJ_NAME. The changes reach users with the app's next release.
"""
from __future__ import annotations

import re
from pathlib import Path
from typing import Any


DOCS_URL = "https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/docs/migration_0_1_40.md"
TAG = "[migration 0.1.40]"
RESOURCE_ROOT = Path(__file__).resolve().parents[1] / "resources" / "v0_1_39_to_v0_1_40"
PREVIOUS_ROOT = RESOURCE_ROOT / "previous"

DOCS = Path(".tools/docs")
EXTERNAL_CODE_DOC = DOCS / "external_code_upload.md"

# Files replaced whole, only when they are the template file last shipped (the 0.1.39 copy, compared with LF line endings).
FILES = tuple(
DOCS / name
for name in (
"before_getting_started.md",
"code_hiding.md",
"external_code_upload.md",
"install.md",
"notebook_portability.md",
"tools_bridge.md",
"workflow_status.md",
)
)

# What to change by hand in a customised file, by file (added to the SKIPPED note).
BY_HAND = {
DOCS / "before_getting_started.md": "nothing is required: the template's page condenses the six feature sections into two paragraphs",
DOCS / "code_hiding.md": "nothing is required: the template's page has a plainer first paragraph",
EXTERNAL_CODE_DOC: "nothing is required: the template's page has plainer instructions and calls \"Good to know\" \"Limits and options\"",
DOCS / "install.md": (
"the section \"Where the app is listed\" of the template's page no longer explains the hosts: line of labconstrictor-app.yaml "
"(app users only need to know that the App Centre page says which programs an app works in)"
),
DOCS / "notebook_portability.md": "nothing is required: the template's page has plainer instructions",
DOCS / "tools_bridge.md": "nothing is required: \"Apps that declare no tools are not affected\" moved to \"What the installer does\"",
DOCS / "workflow_status.md": (
"if the page tells readers to paste the log file into an AI assistant, add that they must first remove tokens, private paths "
"and anything else they would not share, and check any suggested fix against the error before running the workflow again"
),
}

# The placeholder the repository form replaces in a guide, by guide: the form writes the app's Python package name in place of it.
RENDERED = {EXTERNAL_CODE_DOC: "PYTHON_PROJ_NAME"}
IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"


def log(message: str) -> None:
print(f"{TAG} {message}")


def lf_text(path: Path) -> str:
return path.read_bytes().decode("utf-8").replace("\r\n", "\n")


def filled_in_name(template_lf: str, text_lf: str, placeholder: str) -> str | None:
"""The name written in `text_lf` everywhere `template_lf` has `placeholder` (the same name each time), or None when the texts differ
elsewhere."""
if placeholder not in template_lf:
return None
parts = template_lf.split(placeholder)
pattern = re.escape(parts[0]) + f"(?P<name>{IDENTIFIER})" + "".join(re.escape(part) + "(?P=name)" for part in parts[1:-1])
pattern += re.escape(parts[-1])
match = re.fullmatch(pattern, text_lf, flags=re.DOTALL)
return match.group("name") if match else None


def replaced_file(relative: Path, text_lf: str) -> tuple[str, str]:
"""The 0.1.40 text of `relative` for the app's `text_lf`, and what was done. The text is unchanged when it is not the 0.1.39 template file."""
new = lf_text(RESOURCE_ROOT / relative)
previous = lf_text(PREVIOUS_ROOT / relative)
if text_lf == new:
return text_lf, "already up to date"
if text_lf == previous:
return new, "replaced by the 0.1.40 page"
placeholder = RENDERED.get(relative)
if placeholder:
name = filled_in_name(new, text_lf, placeholder)
if name:
return text_lf, "already up to date"
name = filled_in_name(previous, text_lf, placeholder)
if name:
return new.replace(placeholder, name), f"replaced by the 0.1.40 page (with the package name {name})"
by_hand = f" By hand: {BY_HAND[relative]}." if relative in BY_HAND else ""
return text_lf, f"SKIPPED: customised (not the 0.1.39 template file), so it was left unchanged; compare it with the template's page.{by_hand} See {DOCS_URL}"


def update(path: Path, relative: Path) -> str:
data = path.read_bytes().decode("utf-8")
newline = "\r\n" if "\r\n" in data else "\n"
original = data.replace("\r\n", "\n")
text, note = replaced_file(relative, original)
if text == original:
return note if note.startswith("SKIPPED") else f"unchanged: {note}"
path.write_bytes(text.replace("\n", newline).encode("utf-8"))
return f"updated: {note}"


def migrate(repo_root: Path, context: dict[str, Any]) -> None:
"""Apply the 0.1.40 documentation changes (idempotent, never raises for a customised file, creates and deletes nothing)."""
_ = context
changed = 0
for relative in FILES:
path = repo_root / relative
if not path.is_file():
log(f"{relative}: not present in this repository (nothing was created)")
continue
try:
status = update(path, relative)
except (OSError, UnicodeDecodeError) as exc:
status = f"SKIPPED: {exc}; left unchanged. See {DOCS_URL}"
changed += status.startswith("updated")
log(f"{relative}: {status}")
if changed:
log(f"done: {changed} file(s) changed. The changes reach users with the next release of the app.")
else:
log("done: no repository changes were required.")
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Before getting started with LabConstrictor

## LabConstrictor in a nutshell

LabConstrictor is a GitHub template repository that turns your Jupyter notebooks into a desktop app that people install with one installer. A web form sets up your repository and uploads your notebooks with their requirements; GitHub Actions workflows in your repository do the rest. They merge the requirements of all notebooks and fix every package version, so each installation of a release gets the same packages. Publishing a release builds installers with [conda constructor](https://github.com/conda/constructor): Windows (`.exe`), macOS (`.pkg`) and Linux (`.sh`), or only the systems you list under `distribution.platforms` in [`labconstrictor-app.yaml`](app_manifest.md#distribution-how-people-get-the-app).

The installed app opens JupyterLab with a Welcome notebook that lists your notebooks, shows when a newer version of one exists and updates it. Code cells can be hidden and run with a play button, so a notebook looks like a simple app. Once installed, the app runs without internet access, unless your notebooks need it. Your repository can be public or private; a private repository cannot be listed in the App Centre.

## What you need

- **A GitHub account**, to create your repository from the template.
- **Your Jupyter notebooks.**
- **A Python environment where your notebooks run without errors**, on your computer or in Google Colab. You use it to generate the requirements files. You can also write these files by hand.
- **A GitHub personal access token** (classic, with the **repo** scope), which the web forms use to open pull requests in your repository: see [Generate a GitHub personal access token](personal_access_token.md).
- **Optional: images** (logo, banner, header) to brand the installer: see [Customise the installer images](installer_images.md).

Next: [Create your repository](create_repository.md).


---

<div align="center">

← Previous &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](create_repository.md)


</div>
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Hide code cells in notebooks

If people use your notebook through its widgets rather than by editing Python, you can hide the code and leave the controls visible.

## Who is this for?

This feature is only useful if your notebooks don't require any code modifications by the user. For example, if your notebook is purely for data visualisation and analysis, or if interaction with the user is done through widgets, hiding code cells can enhance the user experience. If your notebook requires users to modify code cells, it's best to keep them visible.

## How is this different from collapsing cells?

JupyterLab already provides a way of collapsing the cell by clicking the blue bar on the left side of the cell. However, this method uncollapses the cell when the user clicks anywhere inside the cell, which can be inconvenient for users to chose the cell they want to run.

This feature avoids that problem by providing a dedicated button to show or hide all code cells in the notebook and allowing the user to freely click the code cell. Additionally, when hiding code cells using this feature, a play button appears next to each code cell, allowing users to run code cells more intuitively.

## How does the play button work?

Depending on the versions of JupyterLab and ipywidgets you use, when code cells are hidden, a play button might show up next to each code cell:

![Play Button vs Missing](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Cell_Button.png)

Clicking this button runs the corresponding code cell without revealing the code. Whether or not the play button appears, you can always run a code cell by selecting it and clicking the play button in the top toolbar:

![Toolbar Play Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_Play_Button.png)

## How to hide or show code cells?

Depending on your initialisation your code cells will be hidden by default or shown by default. In either case, the visibility of code cells can be toggled using the `Show/Hide Code` button in the top toolbar:

![Show Hide Code Button](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Notebook_ShowHide_Button.png)

## Where is this controlled?

Hiding code cells is done by a small script, [`hide_code_cells.py`](https://github.com/CellMigrationLab/LabConstrictor/blob/main/.tools/templates/hide_code_cells.py). In your own repository it is `app/python_scripts/hide_code_cells.py`, and it runs when you upload or change a notebook. To switch the feature on or off, set `HIDE_CODE_DISABLED` in that file (`False` hides the code cells), or initialise your repository again with the [repository initialiser](https://labconstrictor-form.streamlit.app/) and choose the other option.
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Upload external code

Put your own Python code in your repository so that every notebook of your app can import it.

## 1. Prepare your external code

Put your functions in a package under `src/`: a folder with an `__init__.py` file, so notebooks can import it. List the packages your code needs in your notebooks' requirements.

**Suggested folder structure:**

```text
src/
|-- PYTHON_PROJ_NAME/
| |-- __init__.py
| |-- my_script.py
| |-- subpackage/
| |-- __init__.py
```

### What goes in `__init__.py`?

`__init__.py` tells Python that the folder is a package. It can stay empty. To let notebooks import your main functions directly from the package, re-export them:

```python
# src/PYTHON_PROJ_NAME/__init__.py
from .my_script import run_analysis, load_config

__all__ = ["run_analysis", "load_config"]
```

Each folder that you plan to import (for example, `src/subpackage/`) should also have its own `__init__.py`. Keep it empty unless you want to expose selected helpers from that subpackage.

More on `__init__.py`: the [Real Python guide](https://realpython.com/python-init-py/).

## 2. Upload your external code to the repository

Open the `src` folder of your repository on GitHub and upload your files or folders there.

![Upload external code GIF](https://github.com/CellMigrationLab/LabConstrictor/blob/doc_source/Upload_src.gif)

## 3. How to import into your notebook

Your notebooks import the code as a package:

**Import the whole package:**
```python
import PYTHON_PROJ_NAME
```

If your folder under `src/` is called `celltools`, then `import celltools` will work because `src/celltools/__init__.py` exists.

**Import function:**
```python
from PYTHON_PROJ_NAME import my_script
```

**Import submodule:**
```python
from PYTHON_PROJ_NAME.subpackage import submodule1
```

## 4. Publish the code on PyPI (optional)

The installer always puts your package into the app. You can also publish it on [PyPI](https://pypi.org), so that anyone can install it with `pip install`, in Google Colab or in their own Python. Each release then does both, with the same version: the GitHub Actions workflow `.github/workflows/publish_pypi.yml` builds the package and uploads it when you publish a release, next to the installers.

It is **off until you turn it on**, and GitHub stores no password or token for it: PyPI trusts this repository's workflow directly ([trusted publishing](https://docs.pypi.org/trusted-publishers/)).

**What is published**

| | |
|---|---|
| Name | The `name=` of `setup.py`: the name of the package, given when the repository was initialised (unless you changed it). If `labconstrictor-app.yaml` has `distribution.pip`, it must be the same name. |
| Version | The release tag without the `v`: release `v1.2.0` publishes 1.2.0. |
| Code | Every package in `src/` (a folder with an `__init__.py`). |
| Dependencies | Each line of `requirements.txt`, as it is written (exact versions included). Options (`-r`, `--extra-index-url`), paths and URLs are left out, with a warning in the log: PyPI refuses dependencies given as URLs. |
| Description | `README.md` of the repository, shown on the PyPI page. |
| License | The `LICENSE` file. |

### One-time setup

1. **Check that the name is free.** Open `https://pypi.org/project/<name>/`. A "404 Not Found" page means nobody uses it. If it is taken, change `name=` in `setup.py` (and `distribution.pip`) and commit.
2. **Register this workflow on PyPI.** Log in to [pypi.org](https://pypi.org) (create an account if you have none; PyPI asks for two-factor authentication). Open your account menu > **Your projects** > **Publishing** ([pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/)). Under **Add a new pending publisher**, choose the **GitHub** tab. The form has five fields; fill them in exactly:
- **PyPI Project Name:** the name of the package.
- **Owner:** the GitHub user or organisation that owns the repository (`CellMigrationLab` in `github.com/CellMigrationLab/MyApp`).
- **Repository name:** the repository (`MyApp`).
- **Workflow name:** `publish_pypi.yml`
- **Environment name:** `pypi`

Click **Add**. The publisher appears under **Pending publishers** below the form. It does not reserve the name: the project is created by your first release. If the project already exists on PyPI and you own it, add the publisher in the project instead: **Your projects** > the project > **Manage** > **Publishing**.
3. **Turn it on in GitHub.** In the repository, open **Settings** > **Secrets and variables** > **Actions**, then the **Variables** tab (not **Secrets**: a secret cannot turn a workflow on). Click **New repository variable**, type `PYPI_PUBLISH` as the name and `true` as the value, and click **Add variable**.
4. **Publish a release** as usual ([Create executable installers](executable_creation.md)). In the **Actions** tab, the workflow **Publish the Python package to PyPI** runs next to **Build Release Installers**. When both jobs are green, the package is at `https://pypi.org/project/<name>/`. The upload job shows the link too.

### Try it on TestPyPI first (optional)

[TestPyPI](https://test.pypi.org) is a separate copy of PyPI for trials, with its own account. Add the same pending publisher at [test.pypi.org/manage/account/publishing](https://test.pypi.org/manage/account/publishing/), give the variable `PYPI_PUBLISH` the value `testpypi`, and publish a release. Install the result with:

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ <name>
```

Then change the variable to `true`: the next release goes to PyPI.

### Turn it off

Delete the variable `PYPI_PUBLISH` (**Settings** > **Secrets and variables** > **Actions** > **Variables**). The workflow stays in the repository and is skipped at each release (a grey icon in the **Actions** tab, not a failure). What was published stays on PyPI.

### Limits and options

- **A version can be uploaded only once**, even after it was deleted from PyPI. The workflow checks this before it builds anything and stops with a clear message; to publish a fix, make a new release with a higher version.
- **The release writes its version into `setup.py`** (the "Update version" commit of the release workflow), so the file and PyPI agree.
- **To approve each upload by hand**, open **Settings** > **Environments** > **pypi** (GitHub creates it at the first run) and add **Required reviewers**.
- **A repository that already publishes to PyPI with a workflow of its own** does not get `publish_pypi.yml` from the template update, so nothing is uploaded twice.
- If the workflow fails, see [Troubleshooting](troubleshooting.md#publishing-to-pypi-fails).

---

<div align="center">

[← Previous](app_manifest.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[🏠 Home](README.md) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
[Next →](tools_bridge.md)


</div>
Loading
Loading