Add CEF 147, Python 3.10–3.14, Linux/macOS ARM64/Windows support with modern build system

[linesight]

Overview

This PR modernizes cefpython from CEF 66 (2018) to CEF 147, adds full support
for Linux and macOS Apple Silicon, and replaces the legacy build toolchain with
a pip-installable wheel workflow. It also incorporates all work from the
cefpython123 branch (PR #679) which was never merged to master.

What's new

CEF & Python versions

• CEF updated to 147.0.10 (Chromium 147.0.7727.118)
• Supports Python 3.10–3.14 (64-bit); Python 2 and pre-3.10 dropped
• Cython updated to 3.2+

Platform support

Platform	Architecture	Status
Windows 10+	x64	Full support
Linux (Ubuntu 20.04+ / Debian 11+)	x64	Full support (GTK3/X11)
macOS 10.15+	ARM64 (Apple Silicon)	Full support

Build system

• Replaced legacy setup.py with scikit-build-core + CMake
• build_distrib.py produces installable wheels per platform/Python version
• CI publishes wheel artifacts for all 15 combinations (3 platforms × 5 Python versions)

CI (GitHub Actions)

• Separate workflows for Windows, Linux, and macOS
• Each workflow builds and runs the unit test suite across all 5 Python versions
• CEF is downloaded once in a dedicated job and cached; all matrix jobs restore
  from cache rather than downloading independently

Linux

• Native-windowed embedding via GTK3/X11
• Wayland sessions: automatic XCB backend forcing with HiDPI scaling support
• Compatible with GCC 13 / Ubuntu 24.04

macOS

• Apple Silicon (ARM64) only — Intel Mac dropped
• Handles Mach port rendezvous requirements for CEF 130+ subprocess isolation
• Ad-hoc code signing for local use; wheel binaries are codesigned

Qt

• PyQt6 and PySide6 embedding and context menu support on Linux

API changes

• Removed APIs dropped in CEF 123+: OnPluginCrashed; SendFocusEvent kept
  as no-op stub for compatibility
• Cookie API updated: CanSendCookie / CanSaveCookie handler signatures revised
• All examples updated and verified on current Chromium behavior

Open issues addressed

Definitely fixed

Issue	Title
#393	[gtk3.py] Blank window / browser embedding fails due to invalid X11 handle
#467	GTK 2 dependency will be removed in CEF v70+
#528	Linux: Discontinue x86 32-bit build support
#585	Use python_requires in setup.py
#609	New v66.1 release only for Windows?
#641	Problem with cefpython on Python 3.8/3.9/3.10 on Linux
#646	No support for Python 3.10
#650	Doesn't support the latest Python version
#652	Chromium 100+ support
#673	Support for Python 3.12
#676	CanSendCookie and CanSaveCookie not called by handler
#683	Error in CookieVisitor_Visit (IO thread assertion)
#685	"Please customize CefSettings.root_cache_path" warning
#686	GPU process crashes 3 times when running unit tests
#530	cef.DpiAware.EnableHighDpiSupport() doesn't work well

Likely fixed

Issue	Title
#452	Linux: Crash in Qt and wxPython examples
#520	API changes due to implementing support for NetworkService
#523	Support for ozone builds / Wayland and X11 backends
#538	Mac: CEF 76 requires multiple helper app bundles
#645	Error when running qt.py example on Windows

[linesight]

above test harness concern is fixed

[cztomczak]

I see lots of Chromium flags removed from unit tests e.g. disable-dev-shm-usage, disable-gpu and others. So is this not needed? How does it run currently under github CI?

[cztomczak]

I guess at some point you started using xvfb - so all these switches aren't required anymore?

[cztomczak]

It's best to run unit tests using default cefpython configuration, however I didn't state that this is a must for CI (although prefered to be as close to default configuration if possible). To be clear,my comment on unit tests was that the unit test scripts should use cefpython configuration as default, however I am aware that CI has limitations. But by just running "python main_test.py" it shouldn't use CI configuration as default - that was my point.

[linesight]

Linux CI was already using Xvfb before this cleanup. It currently runs:

xvfb-run python unittests/_test_runner.py

Xvfb only supplies the X11 display. The unit tests themselves do not detect CI or inject CI-specific Chromium switches. Flags such as disable-dev-shm-usage, in-process-gpu and no-zygote were troubleshooting leftovers and turned out not to be needed on the hosted runner.

[cztomczak]

Why is main_test_async_completed func inside _common.py? It's name even states that it is main test functionality, so it should be in main test.

[linesight]

Why is main_test_async_completed func inside _common.py? It's name even states that it is main test functionality, so it should be in main test.

fixed

[linesight]

Is there any remaining code concern I've missed? The only knowingly-deferred code item is the py_string ->object revert (waiting for new version of cython lands). If the code is otherwise stable, I would like to treat the docs as the final (or near-final) polishing pass before landing

[linesight]

I believe this PR is now ready to merge — please take another look when you have a moment and let me know if anything else is needed.

[cztomczak]

I checked some of the code. Please see my comments.

[cztomczak]

Should we log a message here? The function fails silently.

[linesight]

Extra logging is added
linesight@24b01a1

[cztomczak]

Why was this removed?

[linesight]

The Python-side regex is now redundant, and removing it is intended. CEF + Chromium already validate the domain and reject invalid ones gracefully — the crash from #459 can no longer happen.

The path a cookie takes through CookieManager.SetCookie():

Chromium — net::CanonicalCookie::CreateSanitizedCookie() (net/cookies/canonical_cookie.cc) validates the domain (character set, size, and resolvability via GetCookieDomainWithString), records any problem as an EXCLUDE_INVALID_DOMAIN exclusion reason, then fails closed:

if (!status->IsInclude())
  return nullptr;

It never builds a cookie from a bad domain — validation runs before GetCookieDomainWithString specifically "so it doesn't fail DCHECKs."

CEF — CefCookieManagerImpl::SetCookieInternal()
(libcef/browser/net_service/cookie_manager_impl.cc) null-checks that result:

auto canonical_cookie = net::CanonicalCookie::CreateSanitizedCookie(...);
if (!canonical_cookie) {
  // adds EXCLUDE_UNKNOWN_ERROR, runs the callback, returns cleanly
  return true;
}

So an invalid domain becomes: return nullptr -> null-check -> clean return with a LOG(WARNING) << "SetCookie failed with reason: ...". No dereference, no crash. The #459 segfault was in old pre-net_service CEF that lacked this guarding.

The old regex was also over-strict — it required at least one dot, so it rejected legitimate cookie domains like localhost and single-label intranet hosts, and duplicated validation Chromium already does more correctly.

[cztomczak]

Why is -Wno-stringop-overflow needed? Which warning does it suppress? Could we fix the underlying code instead of disabling the warning?

I'm not accepting any workarounds unless there is a corresponding issue in the CEF Python issue tracker and it has been discussed first.

[linesight]

Opened #696 to track and discuss this properly.

The -Wno-stringop-overflow was suppressing a GCC false positive on the CefRefPtr<T> x = new T(id) idiom under -O3 -flto.

I've dropped the suppression from this PR in linesight/cefpython@9e3ba1b so no workaround remains here — the actual fix can land separately once we've agreed on the approach in #696.

[cztomczak]

Why is this exposed? For testing? I don't think we actually use it.

[linesight]

Thanks for catching, it was other experimental code I fogot to clean up. Now I have removed at linesight@53f4c90

[cztomczak]

I don't understand why this change is needed. We still use IF UNAME_SYSNAME in many places, so why replace it only here?

[linesight]

It was one of early attempt to mute IF UNAME_SYSNAME == "Windows": warning. CEF 147 defaults to CEF_STRING_TYPE_UTF16 and uses the built-in char16_t uniformly on all platforms, so the generated char16_t already matches CEF's ABI with no per-platform typedef. Simplified in linesight/cefpython@01343d0

[cztomczak]

GetScreenInfo used to be unimplemented. This adds a fair amount of new logic. Is all of this required for CEF 147? Which problem does it solve?

[linesight]

it isn't required for cef 147. What it solves is HiDPI OSR rendering, I did spend quite a bit of time to crack HiDPI issue: in OSR there's no native window to carry display density — device_scale_factor here is the only way to tell Chromium the pixel ratio, the pysdl2 example is the concrete consumer: it detects the host ratio and feeds it through here so that buffer matches the physical surface 1:1

[cztomczak]

These callbacks are being dropped because there is no associated PyBrowser to dispatch them on. Since this is a limitation of the current cefpython architecture rather than a CEF bug, it should be documented. Otherwise users may assume these callbacks are always delivered, as in the CEF API.

[linesight]

Fixed at linesight@a853a76

[cztomczak]

This is another silent early return. At least add a comment explaining why GetBrowser() can legitimately be NULL here and why skipping the callback is the correct behavior. A debug log would also make unexpected cases much easier to diagnose.

[linesight]

Fixed at linesight@a853a76

[cztomczak]

The comment explains why Rebind() happens before the callback, but not why Rebind() is needed in the first place. It would be helpful to mention that this handles new V8 contexts (e.g. after cross-origin navigation / site isolation), otherwise the reason for the rebind isn't obvious from the code.

[linesight]

Fixed at linesight@a853a76

[cztomczak]

Does this mean Rebind() is now called for every OnContextCreated, including cases where the renderer already has the bindings? If so, is Rebind() expected to be cheap/idempotent, or can we avoid the unnecessary resend?

[linesight]

Yes — it runs on every OnContextCreated (main frame only). But the "cases where the renderer already has the bindings" part is the bit worth unpacking: that situation doesn't really arise here.

Bindings live per V8 context, and OnContextCreated fires because a new context was just created (page load, navigation, cross-origin nav under site isolation). That context starts empty — globals from the previous one don't carry over — so each call is the first send for that context, not a resend to one that already has them. That's the race this fixes: without it a new context can end up with no bindings.

The genuinely "nothing to do" case is already short-circuited: if an app never calls SetJavascriptBindings, GetJavascriptBindings() is None and the if jsBindings: check skips Rebind().

On cost: Rebind() builds the payload and sends one DoJavascriptBindings message — idempotent, and only once per main-frame navigation, so not a hot path.

The one avoidable resend left is an app that attaches an empty JavascriptBindings() object — that'd still send an empty message. I can add a quick early-out for that if you think it's worth it, though it's a fairly degenerate case.