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
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down
66 changes: 41 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -1724,17 +1723,16 @@ 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

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
Expand All @@ -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:
Expand All @@ -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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions fxcss/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")


Expand Down
11 changes: 7 additions & 4 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
12 changes: 8 additions & 4 deletions scripts/package_smoke.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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")
Expand Down
4 changes: 2 additions & 2 deletions tests/test_capture_state_checks.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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]

Expand Down
7 changes: 5 additions & 2 deletions tests/test_units.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
Loading