From 09683ce911a98e2ba93ddd05f1f7fee2ce720a30 Mon Sep 17 00:00:00 2001 From: adamXbot <111877622+adamXbot@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:58:24 +1100 Subject: [PATCH] Make Pillow a required dependency `pipx install fxcss` now installs everything the image commands need. The `images` extra stays, empty, so `fxcss[images]` commands, scripts and generated workflows keep working. fxcss can still run without Pillow from an uninstalled checkout or after `pip install --no-deps`, so the missing-Pillow message and lazy imports stay. The README covers Linux CPUs with no prebuilt Pillow. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 2 +- README.md | 66 +++++++++++++++++++----------- fxcss/cli.py | 4 +- pyproject.toml | 11 +++-- scripts/package_smoke.py | 12 ++++-- tests/test_capture_state_checks.py | 4 +- tests/test_units.py | 7 +++- 7 files changed, 66 insertions(+), 40 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d8fb67d..ab49104 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -86,7 +86,7 @@ jobs: # Python 3.9 is unavailable on Ubuntu 26.04; preserve the supported floor. - { os: ubuntu-24.04, python: '3.9', label: py3.9 } - { os: ubuntu-latest, python: '3.12', label: py3.12 } - # The oldest Pillow the images extra accepts, so an image API newer + # The oldest Pillow fxcss accepts, so an image API newer # than that floor fails here rather than for a theme author. - { os: ubuntu-latest, python: '3.12', label: 'py3.12, Pillow 10.1.0', pillow: '10.1.0' } - { os: ubuntu-latest, python: '3.14', label: py3.14 } diff --git a/README.md b/README.md index bbb053d..7b912a2 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,10 @@ with visual previews and Firefox compatibility checks. ## Getting started You need **Python 3.9+** and an installed **Firefox** on macOS, Windows or -Linux. Install fxcss with its image tools, then try a theme in a disposable -profile: +Linux. Install fxcss, then try a theme in a disposable profile: ```bash -pipx install "fxcss[images]" +pipx install fxcss fxcss try AdamXweb/WhiteSurFirefoxThemeMacOS ``` @@ -568,8 +567,8 @@ a re-fetch of what the manifest says — and diffs them before the confirmation prompt, printing where the before/after images landed. It completes the three questions an upgrade can answer about a theme with no API: do the selectors still exist (`--audit`), has the user edited anything (always checked), and -what actually changes on screen (`--compare`). Needs Pillow and a local -Firefox, like `shot`. +what actually changes on screen (`--compare`). Needs a local Firefox, like +`shot`. `--check` changes nothing and answers with its exit code, for cron, launchd or CI: **0** up to date, **1** an upgrade is available, **2** it cannot be told @@ -990,10 +989,10 @@ restyled tab strip, say — leaves it alone: | `*-11-settings` | Settings | `about:preferences`, styled by `userContent.css` | Panels are separate OS windows that Marionette cannot see, so these four are -taken with a screen capture of the panel's area. That needs Pillow (the -`fxcss[images]` extra) and briefly brings the capture Firefox to the front. The -capture is first checked against Marionette's own image of the window; when it -cannot see Firefox (no screen-recording permission on macOS, a Wayland session, +taken with a screen capture of the panel's area. That briefly brings the +capture Firefox to the front. The capture is first checked against Marionette's +own image of the window; when it cannot see Firefox (no screen-recording +permission on macOS, a Wayland session, another window on top) the panel views are reported as unsupported with that reason rather than captured wrong. A Firefox without the search engine button skips its two views the same way. @@ -1724,9 +1723,8 @@ here if something isn't behaving. - Python 3.9+ - Firefox (any recent release; the toolkit finds it automatically on macOS, Windows and Linux, or set `FIREFOX_BIN`) -- Pillow for `catalogue`, `compare`, `check`, `tweaks` and `upgrade --compare`. - The `fxcss[images]` extra includes it; add it later with - `pipx inject fxcss pillow`. Other commands use the Python standard library. +- Pillow 10.1 or newer, installed automatically. `catalogue`, `compare`, + `check`, `tweaks` and `upgrade --compare` use it. ### Installation @@ -1734,7 +1732,7 @@ fxcss is [on PyPI](https://pypi.org/project/fxcss/). Install it with **pipx**, which gives it its own environment and puts `fxcss` on your PATH: ```bash -pipx install "fxcss[images]" +pipx install fxcss ``` No pipx yet? `brew install pipx` (macOS), `sudo apt install pipx` (Debian and @@ -1747,9 +1745,26 @@ Ubuntu), or `python3 -m pip install --user pipx` elsewhere. > application. pip still works fine *inside a virtual environment*: > > ```bash -> python3 -m venv ~/.venvs/fxcss && ~/.venvs/fxcss/bin/pip install "fxcss[images]" +> python3 -m venv ~/.venvs/fxcss && ~/.venvs/fxcss/bin/pip install fxcss > ``` +On Linux, Pillow comes prebuilt for x86_64 and aarch64, including musl +distributions such as Alpine. On other CPUs (32-bit x86, RISC-V, ppc64le, +s390x) or glibc older than 2.27, pip compiles it, so install a compiler and the +image headers first. On Debian and Ubuntu: + +```bash +sudo apt install gcc libc6-dev python3-dev libjpeg-dev zlib1g-dev libfreetype-dev +``` + +If Pillow cannot be built, install fxcss without it in a virtual environment. +pipx cannot do this. The image commands will say Pillow is missing, and +everything else works: + +```bash +python3 -m venv ~/.venvs/fxcss && ~/.venvs/fxcss/bin/pip install --no-deps fxcss +``` + For CI, or anywhere a surprise upgrade would be unwelcome, pin the release — the [releases page](https://github.com/AdamXweb/fxcss/releases) has the latest. CI runners' Pythons are not externally managed, so plain pip is fine there: @@ -1758,7 +1773,9 @@ CI runners' Pythons are not externally managed, so plain pip is fine there: pip install "fxcss[images]==0.25.0" ``` -Upgrade an existing pipx installation with `pipx upgrade fxcss`. +Pinned installs keep the `[images]` extra so the same line also brings in Pillow +on older releases. Upgrade an existing pipx installation with +`pipx upgrade fxcss`. ### Upgrading to 0.22 @@ -1900,7 +1917,7 @@ To work on fxcss itself, clone and install it in an editable environment: ```bash git clone https://github.com/AdamXweb/fxcss.git -cd fxcss && python3 -m pip install -e ".[images]" +cd fxcss && python3 -m pip install -e . ``` And if you would rather install nothing at all, the repo runs as-is: @@ -1934,17 +1951,17 @@ and enable **compatibility** to include all four channels. Normal PR CI runs Stable and ESR; the additional channels are optional for manual runs. Package publishing is gated on CI and checks of the exact wheel and source -archive being published. Clean environments outside the checkout test the -base install, optional image dependencies, generated workflows and profile -compatibility with the latest released fxcss. Package checks run on all three -operating systems with Python 3.9 and 3.14; the release tag must also match the +archive being published. Clean environments outside the checkout test an +install without dependencies, a normal install with Pillow, generated workflows +and profile compatibility with the latest released fxcss. Package checks run on +all three operating systems with Python 3.9 and 3.14; the release tag must also match the built package version. These are fxcss's own checks; `init` generates the theme repository workflows described above. Run the checks locally with: ```bash -python3 -m pip install -e ".[images]" # the unit tests need Pillow +python3 -m pip install -e . # includes Pillow, which the unit tests need python3 -m unittest discover -s tests -v python3 -m tests.smoke_themes # requires Firefox and a display python3 -m tests.smoke_variants # requires Firefox and a display @@ -1954,10 +1971,9 @@ python3 scripts/package_smoke.py --dist dist # downloads the released package a ``` The unit tests cover `compare`, `catalogue` and the other image commands, so -they need Pillow: install the `[images]` extra as above rather than the bare -package, or the image tests error instead of being skipped. If `pip install` -refuses with `externally-managed-environment`, create a virtual environment -first (`python3 -m venv .venv && . .venv/bin/activate`). The publisher +they need Pillow: without the install above, the image tests error instead of +being skipped. If `pip install` refuses with `externally-managed-environment`, +create a virtual environment first (`python3 -m venv .venv && . .venv/bin/activate`). The publisher workflow tests also use Node and bash when they are installed, and skip otherwise. Offline release orchestration tests execute the workflow scripts with stubbed pip, sleep and gh commands to check tag validation, the PyPI diff --git a/fxcss/cli.py b/fxcss/cli.py index c856eda..145a63f 100644 --- a/fxcss/cli.py +++ b/fxcss/cli.py @@ -256,8 +256,8 @@ def _bail(signum, frame): PILLOW_HINT = ( - "error: `fxcss {cmd}` needs Pillow, which the base install leaves out.\n" - " pipx: pipx inject fxcss pillow (or reinstall: pipx install \"fxcss[images]\")\n" + "error: `fxcss {cmd}` needs Pillow, which is missing from this environment.\n" + " pipx: pipx inject fxcss pillow\n" " pip: pip install pillow") diff --git a/pyproject.toml b/pyproject.toml index 83e26e7..19ab1f7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,12 +19,15 @@ classifiers = [ "Topic :: Software Development :: Testing", ] -# The core (watch, pick, inspect, doctor, shot) is standard library only. -# Pillow is needed for image work: catalogue and compare. -dependencies = [] +# Pillow does the image work: catalogue, compare, check, tweaks and +# upgrade --compare. Everything else still imports it lazily, so a checkout +# run without installing, or a --no-deps install, keeps working. +dependencies = ["pillow>=10.1"] [project.optional-dependencies] -images = ["pillow>=10.1"] +# Empty on purpose: Pillow used to live here, and `fxcss[images]` must keep +# installing for existing commands, scripts and generated workflows. +images = [] [project.scripts] fxcss = "fxcss.cli:main" diff --git a/scripts/package_smoke.py b/scripts/package_smoke.py index 46950dc..275399b 100644 --- a/scripts/package_smoke.py +++ b/scripts/package_smoke.py @@ -1,7 +1,8 @@ """Test built distributions in clean environments, outside the source checkout. -No third-party test dependencies are required. The images stage installs the -wheel's declared extra. The upgrade stage starts with the latest PyPI release. +No third-party test dependencies are required. The base stage installs the +wheel without dependencies and the images stage installs it with them. The +upgrade stage starts with the latest PyPI release. """ import argparse import hashlib @@ -125,9 +126,12 @@ def check(stage): print(run([python, script, "--stage", stage, "--root", root, "--wheel", wheel], root, env), flush=True) pip("install", "--no-deps", wheel) check("base") - # Extras are resolved from artifact metadata, not a hand-maintained dependency list. - pip("install", f"{wheel}[images]") + # Dependencies are resolved from artifact metadata, not a hand-maintained list. + pip("install", wheel) check("images") + # Existing install commands name this extra, so it must stay declared. + output = pip("install", f"{wheel}[images]") + assert "does not provide the extra" not in output, output pip("uninstall", "-y", "fxcss") pip("install", "--no-cache-dir", "fxcss") check("previous") diff --git a/tests/test_capture_state_checks.py b/tests/test_capture_state_checks.py index 31e10c9..83720a4 100644 --- a/tests/test_capture_state_checks.py +++ b/tests/test_capture_state_checks.py @@ -14,7 +14,7 @@ try: from PIL import Image -except ImportError: # pragma: no cover - the images extra is optional +except ImportError: # pragma: no cover - a bare checkout can run without Pillow Image = None REPO = Path(__file__).resolve().parents[1] @@ -85,7 +85,7 @@ def test_unit_matrix_adds_the_minimum_pillow_and_keeps_unconstrained_jobs(self): self.assertEqual(len(floor), 1, entries) self.assertIn("python: '3.12'", floor[0]) self.assertIn("ubuntu", floor[0]) - # Pinned to exactly the floor the images extra declares. + # Pinned to exactly the floor pyproject declares. dependency, = re.findall(r'"pillow>=([\d.]+)"', (REPO / "pyproject.toml").read_text()) pinned = re.search(r"pillow: '([\d.]+)'", floor[0])[1] diff --git a/tests/test_units.py b/tests/test_units.py index 796690c..16eba20 100644 --- a/tests/test_units.py +++ b/tests/test_units.py @@ -1528,11 +1528,14 @@ def test_parse_choice(self): class PillowFreeCoreTests(unittest.TestCase): - """The base install must never touch PIL outside the three image commands. + """Commands that do no image work must never touch PIL. + + Pillow is a required dependency, but fxcss still runs without it: from a + checkout that was never installed, or after `pip install --no-deps`. This exact regression shipped once: css_references lived in catalogue.py, whose module header imports PIL, so `fxcss pick` crashed for anyone - installed without the [images] extra. + without Pillow. """ def run_blocked(self, code):