qt-css-engine 0.1.0__tar.gz

qt_css_engine-0.1.0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,58 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others’ private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+1. **Correction**
+2. **Warning**
+3. **Temporary Ban**
+4. **Permanent Ban**
+
+(See [Contributor Covenant Community Impact Guidelines](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines) for details.)
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct/](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+[homepage]: https://www.contributor-covenant.org

qt_css_engine-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+## Contributing
+
+Contributions are welcome. Make sure to run the tests and check the demo app and all widgets before submitting a pull request.
+Tests do not cover all the cases so visual confirmation is required.
+Keep in mind that there might be big changes to the codebase so prepare to rebase your branch if needed.
+Messy commit histories will be squashed before merging.
+
+PR names and commit messages are in the format: `type(scope): short description`
+
+Extra details must be added to the commit message after a newline so:
+
+```text
+fix(css_parser): fix parsing of :hover pseudo-class
+
+- :hover pseudo-class was not being parsed correctly in some cases
+- added tests to cover that case
+- more details here
+```
+
+## Dev commands
+
+```bash
+# Install dependencies and run the demo
+uv sync --all-extras
+uv run ./demo/main.py
+
+# Run the test suite
+uv run pytest
+
+# Check and format the code
+uvx ruff check --fix
+uvx ruff format
+uvx basedpyright
+```

qt_css_engine-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    if: github.event.base_ref == 'refs/heads/main'
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v8.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Build
+        run: uv build
+
+      - name: Smoke test wheel
+        run: uv run --isolated --no-project --with dist/*.whl -- python -c "import qt_css_engine"
+
+      - name: Smoke test sdist
+        run: uv run --isolated --no-project --with dist/*.tar.gz -- python -c "import qt_css_engine"
+
+      - name: Publish
+        run: uv publish

qt_css_engine-0.1.0/.github/workflows/test-publish.yml

@@ -0,0 +1,33 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v8.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Build
+        run: uv build
+
+      - name: Smoke test wheel
+        run: uv run --isolated --no-project --with dist/*.whl -- python -c "import qt_css_engine"
+
+      - name: Smoke test sdist
+        run: uv run --isolated --no-project --with dist/*.tar.gz -- python -c "import qt_css_engine"
+
+      - name: Publish
+        run: uv publish --index testpypi

qt_css_engine-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.venv
+.pytest_cache
+.ruff_cache
+.vscode
+.python-version
+
+uv.lock

qt_css_engine-0.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 George Sladkovsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

qt_css_engine-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: qt-css-engine
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/Video-Nomad/qt-css-engine/issues
+Author-email: George Sladkovsky <george.sladkovsky@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: animation,css,pyqt6,qss,qt,stylesheet,transition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.14
+Requires-Dist: tinycss2>=1.5.1
+Description-Content-Type: text/markdown
+
+# Qt CSS Engine
+
+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.
+
+CSS Hot reload is supported via `TransitionEngine.reload_rules(new_rules)`
+
+Subcontrols (e.g `::item`, `::handle`) are not supported because they are not real QWidgets. They will be just passed through as classic QSS stylesheet blocks.
+
+This engine was made primarily for use in [YASB](https://github.com/amnweb/yasb) project and this will be the main focus for now, but it can be integrated into any Qt application.
+
+**WARNING: This project is still in early development, very experimental and is not ready for production use. There will be bugs and breaking changes.**
+
+## Python and Qt version
+
+Python 3.14+
+
+PySide6/PyQt6 6.10+
+
+## Installation
+
+```
+uv add qt-css-engine
+```
+
+## Usage
+
+```python
+from qt_css_engine import TransitionEngine, extract_rules
+
+app = QApplication([])
+cleaned_qss, rules = extract_rules(stylesheet)
+app.setStyleSheet(cleaned_qss)
+engine = TransitionEngine(rules)
+app.installEventFilter(engine)
+```
+
+## Simple transition examples
+
+```css
+/* A simple widget with a hover transition */
+.btn {
+    background-color: steelblue;
+    color: white;
+    border-radius: 4px;
+    transition: background-color 300ms ease;
+}
+
+.btn:hover {
+    background-color: royalblue;
+}
+
+/* A widget with a box-shadow transition */
+#btn {
+    background-color: steelblue;
+    color: white;
+    border-radius: 4px;
+    box-shadow: 0px 0px 0px black;
+    transition: box-shadow 300ms ease;
+}
+
+#btn:hover {
+    box-shadow: 4px 4px 4px black;
+}
+```
+
+## More complex examples
+
+Check the `./demo/main.py` for hot reloading, dynamic class change and more.
+
+## Transition syntax and supported values
+
+### Shorthand
+
+```css
+transition: <property> <duration> [<easing>] [<delay>];
+transition: <property> <duration> [<delay>] [<easing>];
+
+/* multiple */
+transition: background-color 300ms ease, border-radius 200ms linear 50ms;
+
+/* all animatable properties */
+transition: all 300ms ease-in-out;
+```
+
+### Longhands
+
+```css
+transition-property: background-color, border-radius;
+transition-duration: 300ms, 200ms;
+transition-timing-function: ease, linear;
+transition-delay: 0ms, 50ms;
+```
+
+Longhands override the shorthand when both are declared in the same block. Values cycle per the CSS spec when list lengths differ.
+
+### Time units
+
+| Unit | Example |
+| --- | --- |
+| Milliseconds | `300ms` |
+| Seconds | `0.3s` |
+
+### Easing curves
+
+| Value | Description |
+| --- | --- |
+| `linear` | Constant speed |
+| `ease` | Slow in, slow out (default) |
+| `ease-in` | Slow start |
+| `ease-out` | Slow end |
+| `ease-in-out` | Slow start and end |
+| `cubic-bezier(x1, y1, x2, y2)` | Custom curve — values outside `[0, 1]` produce overshoot |
+| `steps(n)` / `steps(n, jump-end\|jump-start\|jump-none\|jump-both)` | Discrete stepped animation |
+| `step-start` / `step-end` | Aliases for `steps(1, jump-start)` / `steps(1, jump-end)` |
+
+### Delay
+
+Positive delay: animation starts after the delay elapses. The property is frozen at its current rendered value during the delay period.
+
+Negative delay: animation starts immediately but offset `|delay|` ms into the timeline, as if it had already been running that long.
+
+```css
+transition: background 400ms ease 100ms;   /* 100ms positive delay */
+transition: background 400ms ease -100ms;  /* starts 100ms in */
+/* OR */
+transition: background 400ms 100ms ease;
+transition: background 400ms -100ms ease;
+```
+
+## Supported properties
+
+Color values accepted everywhere a color is listed: named (`red`, `steelblue`, …), `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`.
+
+Numeric values accepted everywhere a length is listed: `<n>px`, `<n>pt`, `<n>em`.
+
+| Property | Description | Supported values | Transition | Static |
+| --- | --- | --- | --- | --- |
+| `background-color` / `background` | Background color | color values; `linear-gradient()`, `radial-gradient()`, `conic-gradient()` (static only) | ✅ solid colors | ✅ |
+| `color` | Text color | color values | ✅ | ✅ |
+| `border-color` | Border color shorthand (→ 4 sides) | color values | ✅ | ✅ |
+| `border-top-color`, `border-right-color`, `border-bottom-color`, `border-left-color` | Per-side border color | color values | ✅ | ✅ |
+| `border-width` | Border width shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `border-top-width`, `border-right-width`, `border-bottom-width`, `border-left-width` | Per-side border width | length values | ✅ | ✅ |
+| `border-radius` | Border radius shorthand (→ 4 corners) | length values | ✅ | ✅ |
+| `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, `border-bottom-left-radius` | Per-corner border radius | length values | ✅ | ✅ |
+| `padding` | Padding shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `padding-top`, `padding-right`, `padding-bottom`, `padding-left` | Per-side padding | length values | ✅ | ✅ |
+| `margin` | Margin shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `margin-top`, `margin-right`, `margin-bottom`, `margin-left` | Per-side margin | length values | ✅ | ✅ |
+| `width`, `height` | Widget size | length values | ✅ | ✅ |
+| `min-width`, `max-width`, `min-height`, `max-height` | Size constraints | length values | ✅ | ✅ |
+| `font-size` | Font size | length values | ✅ | ✅ |
+| `font-weight` | Font weight | `100`–`900` | ✅ | ✅ |
+| `letter-spacing` | Letter spacing | length values | ✅ | ✅ |
+| `word-spacing` | Word spacing | length values | ✅ | ✅ |
+| `spacing` | Qt widget item spacing | length values | ✅ | ✅ |
+| `opacity` | Widget opacity — not native QSS, applied via `QGraphicsOpacityEffect` | `0.0`–`1.0` | ✅ | ✅ |
+| `box-shadow` | Drop shadow — not native QSS, applied via `QGraphicsDropShadowEffect`. No `inset`, `spread` is ignored. First shadow wins when multiple are declared. | `<x> <y> [blur] [spread] <color>` | ✅ | ✅ |
+| `cursor` | Mouse cursor — Qt QSS ignores `cursor`, applied via `setCursor()` | `default`, `pointer`, `text`, `crosshair`, `wait`, `progress`, `help`, `move`, `grab`, `grabbing`, `copy`, `alias`, `not-allowed`, `no-drop`, `cell`, `all-scroll`, `n-resize`, `s-resize`, `e-resize`, `w-resize`, `ne-resize`, `nw-resize`, `se-resize`, `sw-resize`, `ns-resize`, `ew-resize`, `nesw-resize`, `nwse-resize`, `row-resize`, `col-resize`, `none` | ❌ | ✅ |
+

qt_css_engine-0.1.0/README.md

@@ -0,0 +1,162 @@
+# Qt CSS Engine
+
+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.
+
+CSS Hot reload is supported via `TransitionEngine.reload_rules(new_rules)`
+
+Subcontrols (e.g `::item`, `::handle`) are not supported because they are not real QWidgets. They will be just passed through as classic QSS stylesheet blocks.
+
+This engine was made primarily for use in [YASB](https://github.com/amnweb/yasb) project and this will be the main focus for now, but it can be integrated into any Qt application.
+
+**WARNING: This project is still in early development, very experimental and is not ready for production use. There will be bugs and breaking changes.**
+
+## Python and Qt version
+
+Python 3.14+
+
+PySide6/PyQt6 6.10+
+
+## Installation
+
+```
+uv add qt-css-engine
+```
+
+## Usage
+
+```python
+from qt_css_engine import TransitionEngine, extract_rules
+
+app = QApplication([])
+cleaned_qss, rules = extract_rules(stylesheet)
+app.setStyleSheet(cleaned_qss)
+engine = TransitionEngine(rules)
+app.installEventFilter(engine)
+```
+
+## Simple transition examples
+
+```css
+/* A simple widget with a hover transition */
+.btn {
+    background-color: steelblue;
+    color: white;
+    border-radius: 4px;
+    transition: background-color 300ms ease;
+}
+
+.btn:hover {
+    background-color: royalblue;
+}
+
+/* A widget with a box-shadow transition */
+#btn {
+    background-color: steelblue;
+    color: white;
+    border-radius: 4px;
+    box-shadow: 0px 0px 0px black;
+    transition: box-shadow 300ms ease;
+}
+
+#btn:hover {
+    box-shadow: 4px 4px 4px black;
+}
+```
+
+## More complex examples
+
+Check the `./demo/main.py` for hot reloading, dynamic class change and more.
+
+## Transition syntax and supported values
+
+### Shorthand
+
+```css
+transition: <property> <duration> [<easing>] [<delay>];
+transition: <property> <duration> [<delay>] [<easing>];
+
+/* multiple */
+transition: background-color 300ms ease, border-radius 200ms linear 50ms;
+
+/* all animatable properties */
+transition: all 300ms ease-in-out;
+```
+
+### Longhands
+
+```css
+transition-property: background-color, border-radius;
+transition-duration: 300ms, 200ms;
+transition-timing-function: ease, linear;
+transition-delay: 0ms, 50ms;
+```
+
+Longhands override the shorthand when both are declared in the same block. Values cycle per the CSS spec when list lengths differ.
+
+### Time units
+
+| Unit | Example |
+| --- | --- |
+| Milliseconds | `300ms` |
+| Seconds | `0.3s` |
+
+### Easing curves
+
+| Value | Description |
+| --- | --- |
+| `linear` | Constant speed |
+| `ease` | Slow in, slow out (default) |
+| `ease-in` | Slow start |
+| `ease-out` | Slow end |
+| `ease-in-out` | Slow start and end |
+| `cubic-bezier(x1, y1, x2, y2)` | Custom curve — values outside `[0, 1]` produce overshoot |
+| `steps(n)` / `steps(n, jump-end\|jump-start\|jump-none\|jump-both)` | Discrete stepped animation |
+| `step-start` / `step-end` | Aliases for `steps(1, jump-start)` / `steps(1, jump-end)` |
+
+### Delay
+
+Positive delay: animation starts after the delay elapses. The property is frozen at its current rendered value during the delay period.
+
+Negative delay: animation starts immediately but offset `|delay|` ms into the timeline, as if it had already been running that long.
+
+```css
+transition: background 400ms ease 100ms;   /* 100ms positive delay */
+transition: background 400ms ease -100ms;  /* starts 100ms in */
+/* OR */
+transition: background 400ms 100ms ease;
+transition: background 400ms -100ms ease;
+```
+
+## Supported properties
+
+Color values accepted everywhere a color is listed: named (`red`, `steelblue`, …), `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`.
+
+Numeric values accepted everywhere a length is listed: `<n>px`, `<n>pt`, `<n>em`.
+
+| Property | Description | Supported values | Transition | Static |
+| --- | --- | --- | --- | --- |
+| `background-color` / `background` | Background color | color values; `linear-gradient()`, `radial-gradient()`, `conic-gradient()` (static only) | ✅ solid colors | ✅ |
+| `color` | Text color | color values | ✅ | ✅ |
+| `border-color` | Border color shorthand (→ 4 sides) | color values | ✅ | ✅ |
+| `border-top-color`, `border-right-color`, `border-bottom-color`, `border-left-color` | Per-side border color | color values | ✅ | ✅ |
+| `border-width` | Border width shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `border-top-width`, `border-right-width`, `border-bottom-width`, `border-left-width` | Per-side border width | length values | ✅ | ✅ |
+| `border-radius` | Border radius shorthand (→ 4 corners) | length values | ✅ | ✅ |
+| `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, `border-bottom-left-radius` | Per-corner border radius | length values | ✅ | ✅ |
+| `padding` | Padding shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `padding-top`, `padding-right`, `padding-bottom`, `padding-left` | Per-side padding | length values | ✅ | ✅ |
+| `margin` | Margin shorthand (→ 4 sides) | length values | ✅ | ✅ |
+| `margin-top`, `margin-right`, `margin-bottom`, `margin-left` | Per-side margin | length values | ✅ | ✅ |
+| `width`, `height` | Widget size | length values | ✅ | ✅ |
+| `min-width`, `max-width`, `min-height`, `max-height` | Size constraints | length values | ✅ | ✅ |
+| `font-size` | Font size | length values | ✅ | ✅ |
+| `font-weight` | Font weight | `100`–`900` | ✅ | ✅ |
+| `letter-spacing` | Letter spacing | length values | ✅ | ✅ |
+| `word-spacing` | Word spacing | length values | ✅ | ✅ |
+| `spacing` | Qt widget item spacing | length values | ✅ | ✅ |
+| `opacity` | Widget opacity — not native QSS, applied via `QGraphicsOpacityEffect` | `0.0`–`1.0` | ✅ | ✅ |
+| `box-shadow` | Drop shadow — not native QSS, applied via `QGraphicsDropShadowEffect`. No `inset`, `spread` is ignored. First shadow wins when multiple are declared. | `<x> <y> [blur] [spread] <color>` | ✅ | ✅ |
+| `cursor` | Mouse cursor — Qt QSS ignores `cursor`, applied via `setCursor()` | `default`, `pointer`, `text`, `crosshair`, `wait`, `progress`, `help`, `move`, `grab`, `grabbing`, `copy`, `alias`, `not-allowed`, `no-drop`, `cell`, `all-scroll`, `n-resize`, `s-resize`, `e-resize`, `w-resize`, `ne-resize`, `nw-resize`, `se-resize`, `sw-resize`, `ns-resize`, `ew-resize`, `nesw-resize`, `nwse-resize`, `row-resize`, `col-resize`, `none` | ❌ | ✅ |
+