Make cairocffi optional: lazy import only when render pipeline is used

[Copilot]

• Make cairocffi a lazy import in glyph.py
• Move cairocffi to optional dependencies under [cairo] extra in pyproject.toml
• Add helpful error message when cairocffi is not installed but rendering is attempted
• Update installation documentation
• Add separate tox test environment for Cairo-dependent tests
• Split test_render.py into tests requiring Cairo and tests not requiring Cairo
• Make test_http work without Cairo
• Add Cairo tests to GitHub Actions test matrix
  • Default test jobs run 335 tests without Cairo
  • Cairo matrix entry runs 161 Cairo-dependent tests

Original prompt

Only import cairoffi if its really used in the render pipeline, as its not easily available on all platforms

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

PR Preview Action v1.8.0
🚀 View preview at https://csett86.github.io/graphite-render/pr-preview/pr-36/
Built to branch gh-pages at 2026-01-18 20:14 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[csett86]

@copilot Add a separate tox test env with cairo and run the tests that require cairo only there

[Copilot]

@copilot Add a separate tox test env with cairo and run the tests that require cairo only there

Added in cf391a1. The tox configuration now has:

• Default environments (py39-py314, no-flask-caching) run 316 tests without Cairo
• New render environment installs [render] extra and runs 170 Cairo-dependent tests (test_render, test_render_glyph, test_http)

[csett86]

@copilot Rename the extra feature and environment to render

[Copilot]

@copilot Rename the extra feature and environment to render

Renamed to cairo in 4152d2c. The extra feature is now [cairo] and the tox environment is cairo.

[csett86]

@copilot Split the tests in test_render between ones requiring cairo and ones not requiring cairo so that majority of test_render tests are still executed without cairo

[Copilot]

@copilot Split the tests in test_render between ones requiring cairo and ones not requiring cairo so that majority of test_render tests are still executed without cairo

Split in 7a90276. Created test_render_cairo.py with 7 Cairo-dependent tests (PNG/SVG/PDF rendering). The original test_render.py now contains 17 tests that only use JSON/raw/csv/dygraph/rickshaw formats and run without Cairo. Default environments now run 333 tests without Cairo.

[csett86]

@copilot Make the test_http work without cairo

[Copilot]

@copilot Make the test_http work without cairo

Fixed in db19c41. Changed test_trailing_slash to use format=json in the query string instead of defaulting to PNG rendering. Both tests in test_http now work without Cairo. Default environments now run 335 tests without Cairo.

[csett86]

@copilot Run the cairo tests also (separately) in github actions workflow

[Copilot]

@copilot Run the cairo tests also (separately) in github actions workflow

Added in 6eb7c52. Created a new test-cairo job in the GitHub Actions workflow that:

• Installs libcairo2-dev system package
• Runs tox -e cairo to execute the Cairo-dependent tests (test_render_cairo, test_render_glyph)

The job is included in the failure notification dependencies.

[csett86]

@copilot Add it to the test matrix instead of own test job, and no need for any library installation

[Copilot]

@copilot Add it to the test matrix instead of own test job, and no need for any library installation

Fixed in b433830. Moved the cairo tests into the test matrix as a new entry (toxenv: cairo with Python 3.12) and removed the separate test-cairo job along with the library installation step.