qt-css-engine 0.1.2__tar.gz → 0.1.4__tar.gz

qt_css_engine-0.1.4/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

{qt_css_engine-0.1.2 → qt_css_engine-0.1.4}/.gitignore

@@ -8,6 +8,7 @@ wheels/
 .venv
 .pytest_cache
 .ruff_cache
+.benchmarks/
 .vscode
 .python-version
 

{qt_css_engine-0.1.2 → qt_css_engine-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: qt-css-engine
-Version: 0.1.2
+Version: 0.1.4
 Summary: CSS transition animations for PyQt6/PySide6 — extends static QSS with transition and other properties
 Project-URL: Homepage, https://github.com/Video-Nomad/qt-css-engine
 Project-URL: Repository, https://github.com/Video-Nomad/qt-css-engine
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 
 A CSS animation engine for PyQt6/PySide6 that extends Qt's static stylesheet system (QSS) with dynamic CSS transitions and extra properties like `box-shadow`, `opacity` and CSS gradients. Qt's stylesheet engine has no concept of time or interpolation — this project implements an out-of-band animation system that intercepts `transition:` declarations from a stylesheet, tracks widget pseudo-states (hover, pressed, focus), and drives smooth property animations via Qt's animation framework. Dynamic class change is also supported so `.btn` -> `.btn.active` -> `.btn.other-state` will animate based on the `transition` property.
 
-All that is required is to install `TransitionEngine` as an event filter and it will take care of the rest.
+All that is required is to install `TransitionEngine` as an event filter and it will take care of the rest. It can be installed directly on a QApplication or any child QWidget.
 
 CSS Hot reload is supported via `TransitionEngine.reload_rules(new_rules)`
 

{qt_css_engine-0.1.2 → qt_css_engine-0.1.4}/README.md

@@ -2,7 +2,7 @@
 
 A CSS animation engine for PyQt6/PySide6 that extends Qt's static stylesheet system (QSS) with dynamic CSS transitions and extra properties like `box-shadow`, `opacity` and CSS gradients. Qt's stylesheet engine has no concept of time or interpolation — this project implements an out-of-band animation system that intercepts `transition:` declarations from a stylesheet, tracks widget pseudo-states (hover, pressed, focus), and drives smooth property animations via Qt's animation framework. Dynamic class change is also supported so `.btn` -> `.btn.active` -> `.btn.other-state` will animate based on the `transition` property.
 
-All that is required is to install `TransitionEngine` as an event filter and it will take care of the rest.
+All that is required is to install `TransitionEngine` as an event filter and it will take care of the rest. It can be installed directly on a QApplication or any child QWidget.
 
 CSS Hot reload is supported via `TransitionEngine.reload_rules(new_rules)`
 

qt_css_engine-0.1.4/benchmarks/README.md

@@ -0,0 +1,76 @@
+# Performance comparisons
+
+Run from the repository root in PowerShell. Pin the binding, then save a baseline
+**using this version of the benchmarks before changing the engine**:
+
+```powershell
+$env:QT_API = "pyqt6"  # or pyside6; keep it the same for both runs
+uv run python -m benchmarks --output .benchmarks/before.json
+
+# Make the engine change, then run:
+uv run python -m benchmarks --compare .benchmarks/before.json --output .benchmarks/after.json
+```
+
+Negative median changes mean faster; positive changes mean slower. Compare the
+sample spread too. Small changes within the run-to-run variation are inconclusive.
+For a closer look, use `--repeat 15 --warmup 3` on **both** runs and repeat the
+before/after experiment. Use the same machine, power mode, dependencies and idle
+background workload. Run timings without other test suites or profilers running.
+
+`--filter class` selects a subset; `--list` lists keys. A filtered run can compare
+against a full baseline. `--repeat 1 --warmup 0` is a smoke check, not a reliable
+performance measurement. `--json` emits a complete JSON document on stdout;
+progress and Qt diagnostics go to stderr. `.benchmarks/` is ignored by Git.
+
+Display a saved report as the usual results table without running benchmarks:
+
+```powershell
+uv run python -m benchmarks --show .benchmarks/after.json
+```
+
+## Measurement boundaries
+
+The fixture has 321 widgets and 458 rules (498 for attribute cases). It includes
+40 buttons, nested wrapper/container branches and radius-styled noise labels.
+The cleaned static QSS is applied to the root, alongside the engine rules, so
+style writes and repolishing exercise Qt's stylesheet machinery too.
+
+| Key | Timed work |
+| --- | --- |
+| `cold` | One matching pass over all 321 widgets with empty widget/identity caches; rule compilation/index construction and cache clearing are excluded. |
+| `warm` | Matching with primed caches; 100 passes per sample, reported as milliseconds per **one 321-widget pass**. |
+| `attr_cold`, `attr_warm` | Matching plus live attribute predicates, as used by the cascade. Half the 40 buttons have `active=true`. Warm samples use 100 passes and the same per-pass normalization. |
+| `initial`, `attr_initial` | New engine/index construction, 321 delivered Polish events, and queued engine work until settled. Each sample has a fresh tree with static QSS already installed. CSS parsing, tree creation, native first show, and destruction are excluded. |
+| `class_change`, `attr` | A synchronous burst of 40 property changes through Qt's event filter, including repolish and creation of 200 animations. Deferred flushes, layout, painting and animation ticks are excluded. |
+| `hover` | 40 delivered `QHoverEvent` enters through the event filter, including creation of 200 animations. Like the property-change cases, deferred work is excluded. |
+| `class_anim`, `hover_anim` | 15 synthetic frames at 20–300 ms for 40 × 5 animations, including deferred style/layout work and final completion callbacks. Trigger/setup work is excluded. Results are per **15-frame sequence**, not FPS or per-frame latency. |
+| `resize` | One actual resize on each of 100 labels, from 120×30 to 122×34, plus queued clamp/style work. Layouts are frozen beforehand so they cannot undo or multiply the resizes. Each radius must change from 15 to 17 px. |
+
+These are fixed workload regression benchmarks, not exhaustive engine coverage.
+They do not currently measure parsing, hot reload, reparenting, effects, or
+real-time paint/compositor throughput. Class and attribute scenarios also have
+different rule counts; compare each scenario to itself across engine revisions.
+
+## Repeatability and correctness
+
+- Each scenario runs in a fresh Python process. `PYTHONHASHSEED` defaults to `0`
+  for the worker processes, or preserves your explicitly supplied seed.
+- Setup, teardown, correctness checks and garbage collection are outside timing.
+  Cyclic GC is disabled during each timed sample and its previous state restored.
+  Samples have fresh trees/engines; warm matcher caches are deliberately primed.
+- Animation clocks are paused at time zero before processing any queued events.
+  Every synthetic frame seeks all 200 animations explicitly; the wall clock cannot
+  advance them. The last frame includes completion, so write counts need not be
+  exactly 15 × 40. Write counts are diagnostics from a separate untimed sample.
+- Windows use the native Qt platform with `WA_DontShowOnScreen`, avoiding desktop
+  focus/mouse interference. The CLI rejects `offscreen` and `minimal` platforms.
+  No global Qt message handler suppresses errors.
+- Assertions verify fixture sizes, matcher results against an uncached scan,
+  attribute hits/misses, five running properties per button, final animation
+  values and resize clamp changes. Errors fail the run; partial suites are never
+  saved as successful baselines. Run Python normally, without `-O`.
+- JSON retains every sample, summary statistics, warmup counts, workload sizes,
+  source revision/dirty flag, engine and benchmark source hashes, Python/Qt/binding
+  versions, platform, style, font, DPI and hash seed. Comparisons reject changed
+  benchmark code, environment or sampling settings. Engine code/revision changes
+  are expected. Metadata cannot detect every source of system noise.

qt_css_engine-0.1.4/benchmarks/__init__.py

@@ -0,0 +1,8 @@
+"""Benchmark suite for qt_css_engine.
+
+Run with:
+    uv run python -m benchmarks
+    uv run python -m benchmarks --help
+    uv run python -m benchmarks --filter cold
+    uv run python -m benchmarks --json
+"""

qt_css_engine-0.1.4/benchmarks/__main__.py

@@ -0,0 +1,160 @@
+"""Run each scenario in a fresh Python process and save comparable results."""
+
+import argparse
+import os
+import subprocess
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from benchmarks import (
+    bench_attr_change,
+    bench_attr_matching,
+    bench_class_anim_frames,
+    bench_class_change,
+    bench_cold_matching,
+    bench_hover_change,
+    bench_hover_frames,
+    bench_initial_eval,
+    bench_resize_storm,
+    bench_warm_matching,
+)
+from benchmarks.reporting import Report, comparison_table, environment, read_report, report_json
+from benchmarks.runner import BenchResult, format_table
+
+
+@dataclass(frozen=True)
+class BenchEntry:
+    key: str
+    name: str
+    benchmark: Callable[..., BenchResult]
+
+
+# Order for baseline table
+ALL_BENCHES: list[BenchEntry] = [
+    BenchEntry("cold", bench_cold_matching.NAME, bench_cold_matching.benchmark),
+    BenchEntry("warm", bench_warm_matching.NAME, bench_warm_matching.benchmark),
+    BenchEntry("initial", bench_initial_eval.NAME, bench_initial_eval.benchmark),
+    BenchEntry("attr_cold", bench_attr_matching.NAME_COLD, bench_attr_matching.benchmark_cold),
+    BenchEntry("attr_warm", bench_attr_matching.NAME_WARM, bench_attr_matching.benchmark_warm),
+    BenchEntry("attr_initial", bench_attr_matching.NAME_INITIAL, bench_attr_matching.benchmark_initial),
+    BenchEntry("class_change", bench_class_change.NAME, bench_class_change.benchmark),
+    BenchEntry("attr", bench_attr_change.NAME, bench_attr_change.benchmark),
+    BenchEntry("class_anim", bench_class_anim_frames.NAME, bench_class_anim_frames.benchmark),
+    BenchEntry("hover", bench_hover_change.NAME, bench_hover_change.benchmark),
+    BenchEntry("hover_anim", bench_hover_frames.NAME, bench_hover_frames.benchmark),
+    BenchEntry("resize", bench_resize_storm.NAME, bench_resize_storm.benchmark),
+]
+
+
+def positive(value: str) -> int:
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
+
+
+def nonnegative(value: str) -> int:
+    number = int(value)
+    if number < 0:
+        raise argparse.ArgumentTypeError("must be at least 0")
+    return number
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--list", action="store_true", help="list scenarios and exit")
+    parser.add_argument("--filter", default="", help="case-insensitive substring of key or name")
+    parser.add_argument("--json", action="store_true", help="print only a JSON report to stdout")
+    parser.add_argument("--output", type=Path, help="save a JSON report")
+    parser.add_argument("--show", type=Path, help="print a saved JSON report as a table and exit")
+    parser.add_argument("--compare", type=Path, help="compare medians with a saved report")
+    parser.add_argument("--repeat", type=positive, help="measured samples per scenario")
+    parser.add_argument("--warmup", type=nonnegative, help="discarded warmup samples")
+    parser.add_argument("-q", "--quiet", action="store_true", help="suppress progress on stderr")
+    parser.add_argument("--worker", choices=[entry.key for entry in ALL_BENCHES], help=argparse.SUPPRESS)
+    args = parser.parse_args()
+    if args.list:
+        for entry in ALL_BENCHES:
+            print(f"{entry.key:14} {entry.name}")
+        return
+    if args.show:
+        try:
+            report = read_report(args.show)
+        except (OSError, ValueError, KeyError, TypeError) as error:
+            parser.error(f"cannot read report: {error}")
+        print(format_table(list(report.results.values())))
+        print("\nAll timings are milliseconds per workload; writes are from a separate untimed sample.")
+        return
+    if os.environ.get("QT_QPA_PLATFORM", "").lower() in {"offscreen", "minimal"}:
+        parser.error("use the native Qt platform; remove QT_QPA_PLATFORM=offscreen/minimal")
+    if args.worker:
+        entry = next(entry for entry in ALL_BENCHES if entry.key == args.worker)
+        options: dict[str, int] = {}
+        if args.repeat is not None:
+            options["runs"] = args.repeat
+        if args.warmup is not None:
+            options["warmup"] = args.warmup
+        result = entry.benchmark(**options)
+        print(report_json(Report(environment(), {entry.key: result})))
+        return
+    selected = [entry for entry in ALL_BENCHES if args.filter.lower() in f"{entry.key} {entry.name}".lower()]
+    if not selected:
+        parser.error(f"no scenarios match {args.filter!r}")
+    try:
+        baseline = read_report(args.compare) if args.compare else None
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        parser.error(f"cannot read baseline: {error}")
+    report = Report({}, {})
+    failures: list[str] = []
+    env = os.environ.copy()
+    env.setdefault("PYTHONHASHSEED", "0")
+    for entry in selected:
+        if not args.quiet:
+            print(f"Running {entry.name} ...", file=sys.stderr, flush=True)
+        command = [sys.executable, "-m", "benchmarks", "--worker", entry.key]
+        if args.repeat is not None:
+            command += ["--repeat", str(args.repeat)]
+        if args.warmup is not None:
+            command += ["--warmup", str(args.warmup)]
+        process = subprocess.run(
+            command, cwd=Path(__file__).resolve().parents[1], env=env, capture_output=True, text=True
+        )
+        if process.stderr:
+            print(process.stderr, file=sys.stderr, end="")
+        if process.returncode:
+            failures.append(entry.key)
+            continue
+        child = Report.from_json(process.stdout)
+        if report.metadata and any(
+            report.metadata.get(key) != value for key, value in child.metadata.items() if key != "recorded_at"
+        ):
+            parser.exit(1, "Code or environment changed during the run; no report saved.\n")
+        report.metadata = child.metadata
+        report.results.update(child.results)
+    if failures:
+        # Never save a partial run as a successful baseline.
+        parser.exit(1, f"Failed scenarios: {', '.join(failures)}; no report saved.\n")
+    comparison = None
+    if baseline:
+        try:
+            comparison = comparison_table(baseline, report)
+        except ValueError as error:
+            parser.error(str(error))
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(report_json(report) + "\n", encoding="utf-8")
+    if args.json:
+        print(report_json(report))
+        if comparison:
+            print(comparison, file=sys.stderr)
+    else:
+        print(format_table(list(report.results.values())))
+        print("\nAll timings are milliseconds per workload; writes are from a separate untimed sample.")
+        if comparison:
+            print("\n" + comparison)
+
+
+if __name__ == "__main__":
+    main()

qt_css_engine-0.1.4/benchmarks/bench_attr_change.py

@@ -0,0 +1,10 @@
+"""Attr change. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import change
+
+NAME = "Attr change"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return change(NAME, kind="attr", warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_attr_matching.py

@@ -0,0 +1,25 @@
+"""Matching includes the live attribute predicates used by the cascade."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import initial, matching
+
+NAME_COLD = "Cold attr matching"
+NAME_WARM = "Warm attr matching"
+NAME_INITIAL = "Initial attr evaluation"
+NAME = NAME_COLD
+
+
+def benchmark_cold(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return matching(NAME_COLD, cold=True, attrs=True, warmup=warmup, runs=runs)
+
+
+def benchmark_warm(*, warmup: int = 3, runs: int = 15) -> BenchResult:
+    return matching(NAME_WARM, cold=False, attrs=True, warmup=warmup, runs=runs)
+
+
+def benchmark_initial(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return initial(NAME_INITIAL, attrs=True, warmup=warmup, runs=runs)
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return benchmark_cold(warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_class_anim_frames.py

@@ -0,0 +1,10 @@
+"""Class-animation frames. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import frames
+
+NAME = "Class-animation frames"
+
+
+def benchmark(*, warmup: int = 1, runs: int = 5) -> BenchResult:
+    return frames(NAME, kind="class", warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_class_change.py

@@ -0,0 +1,10 @@
+"""Class change. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import change
+
+NAME = "Class change"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return change(NAME, kind="class", warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_cold_matching.py

@@ -0,0 +1,10 @@
+"""Cold rule matching. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import matching
+
+NAME = "Cold rule matching"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return matching(NAME, cold=True, attrs=False, warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_hover_change.py

@@ -0,0 +1,10 @@
+"""Hover event. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import change
+
+NAME = "Hover event"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return change(NAME, kind="hover", warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_hover_frames.py

@@ -0,0 +1,10 @@
+"""Hover-animation frames. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import frames
+
+NAME = "Hover-animation frames"
+
+
+def benchmark(*, warmup: int = 1, runs: int = 5) -> BenchResult:
+    return frames(NAME, kind="hover", warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_initial_eval.py

@@ -0,0 +1,10 @@
+"""Initial evaluation. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import initial
+
+NAME = "Initial evaluation"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return initial(NAME, attrs=False, warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_resize_storm.py

@@ -0,0 +1,10 @@
+"""Resize storm. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import resize
+
+NAME = "Resize storm"
+
+
+def benchmark(*, warmup: int = 2, runs: int = 7) -> BenchResult:
+    return resize(NAME, warmup=warmup, runs=runs)

qt_css_engine-0.1.4/benchmarks/bench_warm_matching.py

@@ -0,0 +1,10 @@
+"""Warm cached matching. See benchmarks/README.md for the timing boundary."""
+
+from benchmarks.runner import BenchResult
+from benchmarks.workloads import matching
+
+NAME = "Warm cached matching"
+
+
+def benchmark(*, warmup: int = 3, runs: int = 15) -> BenchResult:
+    return matching(NAME, cold=False, attrs=False, warmup=warmup, runs=runs)