chore: changelog v0.5.4

* feat: add error messagebox context

* typing

* Update src/superqt/utils/_errormsg_context.py

Co-authored-by: Grzegorz Bokota <bokota+github@gmail.com>

* add tests

* style: [pre-commit.ci] auto fixes [...]

* docs: add docs

* test button result

* format doc

* docs: update docs

* docs

* add dialog example

* pass flags

* skip mac ci pyside6

---------

Co-authored-by: Grzegorz Bokota <bokota+github@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/dependabot.yml

@@ -0,0 +1,10 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci(dependabot):"

.github/workflows/test_and_deploy.yml

@@ -1,15 +1,17 @@
 name: Test
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches:
-      - master
       - main
     tags:
       - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10
   pull_request:
     branches:
-      - master
       - main
   workflow_dispatch:
 
@@ -17,144 +19,94 @@ jobs:
   test:
     name: ${{ matrix.platform }} py${{ matrix.python-version }} ${{ matrix.backend }}
     runs-on: ${{ matrix.platform }}
-    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
         platform: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: [3.7, 3.8, 3.9]
-        backend: [pyqt5, pyside2]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        backend: [pyqt5, pyside2, pyqt6]
+        exclude:
+          # Abort (core dumped) on linux pyqt6, unknown reason
+          - platform: ubuntu-latest
+            backend: pyqt6
+          # lack of wheels for pyside2/py3.11
+          - python-version: "3.11"
+            backend: pyside2
+
         include:
-          # pyqt6 and pyside6 on latest platforms
-          - python-version: 3.9
-            platform: ubuntu-latest
+          - python-version: "3.10"
+            platform: macos-latest
             backend: pyside6
-            screenshot: 1
-          - python-version: 3.9
+          - python-version: "3.11"
+            platform: macos-latest
+            backend: pyside6
+          - python-version: "3.10"
             platform: windows-latest
             backend: pyside6
-            screenshot: 1
-          - python-version: 3.9
-            platform: macos-11.0
-            backend: pyside6
-            screenshot: 1
-          - python-version: 3.9
-            platform: ubuntu-latest
-            backend: pyqt6
-          - python-version: 3.9
+          - python-version: "3.11"
             platform: windows-latest
-            backend: pyqt6
-          - python-version: 3.9
-            platform: macos-11.0
-            backend: pyqt6
-          # py3.10
-          - python-version: "3.10"
-            platform: ubuntu-latest
             backend: pyside6
-          - python-version: "3.10"
-            platform: ubuntu-latest
-            backend: pyqt5
-          - python-version: "3.10"
-            platform: ubuntu-latest
-            backend: pyqt6
-
-          # big sur, 3.9
-          - python-version: 3.9
-            platform: macos-11.0
-            backend: pyside2
-          - python-version: 3.9
-            platform: macos-11.0
-            backend: pyqt5
-
-          # legacy OS
-          - python-version: 3.8
-            platform: ubuntu-18.04
-            backend: pyside2
 
           # legacy Qt
-          - python-version: 3.7
+          - python-version: 3.8
             platform: ubuntu-latest
-            backend: pyqt512
-          - python-version: 3.7
+            backend: "pyqt5==5.12.*"
+          - python-version: 3.8
             platform: ubuntu-latest
-            backend: pyqt513
-          - python-version: 3.7
+            backend: "pyqt5==5.13.*"
+          - python-version: 3.8
             platform: ubuntu-latest
-            backend: pyqt514
+            backend: "pyqt5==5.14.*"
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
-      - uses: tlambert03/setup-qt-libs@v1
+      - uses: tlambert03/setup-qt-libs@v1.4
 
       - name: Linux opengl
-        if: runner.os == 'Linux' && ( matrix.backend == 'pyside6' || matrix.backend == 'pyqt6' )
+        if: runner.os == 'Linux' && ( startsWith(matrix.backend, 'pyside6') || startsWith(matrix.backend, 'pyqt6') )
         run: sudo apt-get install -y libopengl0 libegl1-mesa libxcb-xinput0
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install setuptools tox tox-gh-actions
+          python -m pip install -e .[test]
+          python -m pip install ${{ matrix.backend }}
 
-      - name: Test with tox
-        uses: GabrielBB/xvfb-action@v1
-        timeout-minutes: 3
+      - name: Test
+        uses: aganders3/headless-gui@v1.2
         with:
-          run: python -m tox
-        env:
-          PLATFORM: ${{ matrix.platform }}
-          BACKEND: ${{ matrix.backend }}
+          run: python -m pytest --color=yes --cov=superqt --cov-report=xml
 
       - name: Coverage
-        uses: codecov/codecov-action@v1
-
-      - name: Install for screenshots
-        if: matrix.screenshot
-        run: pip install . ${{ matrix.backend }}
-
-      - name: Screenshots (Linux)
-        if: runner.os == 'Linux' && matrix.screenshot
-        uses: GabrielBB/xvfb-action@v1
-        with:
-          run: python examples/demo_widget.py -snap
-
-      - name: Screenshots (macOS/Win)
-        if: runner.os != 'Linux' && matrix.screenshot
-        run: python examples/demo_widget.py -snap
-
-      - uses: actions/upload-artifact@v2
-        if: matrix.screenshot
-        with:
-          name: screenshots ${{ runner.os }}
-          path: screenshots
+        uses: codecov/codecov-action@v3
 
   test_old_qtpy:
     name: qtpy minreq
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: tlambert03/setup-qt-libs@v1
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: tlambert03/setup-qt-libs@v1.4
+      - uses: actions/setup-python@v4
         with:
-          python-version: '3.8'
+          python-version: "3.8"
 
       - name: install
         run: |
           python -m pip install -U pip
-          python -m pip install -e .[testing,pyqt5]
-          python -m pip install qtpy==1.1.0 typing-extensions==3.10.0.0
+          python -m pip install -e .[test,pyqt5]
+          python -m pip install qtpy==1.1.0 typing-extensions==3.7.4.3
 
-      - name: Test napari magicgui
-        uses: GabrielBB/xvfb-action@v1
+      - name: Test
+        uses: aganders3/headless-gui@v1.2
         with:
           run: python -m pytest --color=yes
 
-
   test_napari:
     name: napari tests
     runs-on: ubuntu-latest
@@ -173,7 +125,7 @@ jobs:
       - uses: tlambert03/setup-qt-libs@v1
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.10"
 
       - name: install
         run: |
@@ -182,35 +134,34 @@ jobs:
           python -m pip install ./napari-repo[testing,pyqt5]
 
       - name: Test napari
-        uses: GabrielBB/xvfb-action@v1
+        uses: aganders3/headless-gui@v1.2
         with:
           working-directory: napari-repo
           run: python -m pytest --color=yes napari/_qt
 
-  check_manifest:
+  check-manifest:
+    name: Check Manifest
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: "3.x"
-      - name: Check manifest
-        run: |
-          python -m pip install --upgrade pip
-          pip install check-manifest
-          check-manifest
+      - run: pip install check-manifest && check-manifest
 
   deploy:
     # this will run when you have tagged a commit, starting with "v*"
     # and requires that you have put your twine API key in your
     # github secrets (see readme for details)
-    needs: [test, check_manifest]
-    if: ${{ github.repository == 'napari/superqt' && contains(github.ref, 'tags') }}
+    needs: [test, check-manifest]
+    if: ${{ github.repository == 'pyapp-kit/superqt' && contains(github.ref, 'tags') }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: "3.x"
       - name: Install dependencies

.github_changelog_generator

@@ -1,7 +1,7 @@
 # run this with:
 # export CHANGELOG_GITHUB_TOKEN=......
 # github_changelog_generator --future-release vX.Y.Z
-user=napari
+user=pyapp-kit
 project=superqt
 issues=false
 since-tag=v0.2.0

.gitignore

@@ -45,7 +45,6 @@ nosetests.xml
 coverage.xml
 *,cover
 .hypothesis/
-.napari_cache
 
 # Translations
 *.mo
@@ -82,3 +81,4 @@ src/superqt/_version.py
 screenshots
 
 .mypy_cache
+docs/_auto_images/

.pre-commit-config.yaml

@@ -1,41 +1,38 @@
+ci:
+  autoupdate_schedule: monthly
+  autofix_commit_msg: "style: [pre-commit.ci] auto fixes [...]"
+  autoupdate_commit_msg: "ci: [pre-commit.ci] autoupdate"
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
+      - id: check-docstring-first
       - id: end-of-file-fixer
       - id: trailing-whitespace
-  - repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v2.0.0
-    hooks:
-      - id: setup-cfg-fmt
-        args: ["--include-version-classifiers"]
-  - repo: https://github.com/PyCQA/flake8
-    rev: 5.0.4
-    hooks:
-      - id: flake8
-        additional_dependencies: [flake8-typing-imports==1.7.0]
-        exclude: examples
-  - repo: https://github.com/PyCQA/autoflake
-    rev: v1.6.1
-    hooks:
-      - id: autoflake
-        args: ["--in-place", "--remove-all-unused-imports"]
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.10.1
-    hooks:
-      - id: isort
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v2.38.2
-    hooks:
-      - id: pyupgrade
-        args: [--py37-plus, --keep-runtime-typing]
+
   - repo: https://github.com/psf/black
-    rev: 22.8.0
+    rev: 23.7.0
     hooks:
       - id: black
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.0.281
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.13
+    hooks:
+      - id: validate-pyproject
+
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.981
+    rev: v1.4.1
     hooks:
       - id: mypy
-        exclude: examples
-        stages: [manual]
+        exclude: tests|examples
+        additional_dependencies:
+          - types-Pygments
+        stages:
+          - manual

CHANGELOG.md

@@ -1,211 +1,347 @@
 # Changelog
 
-## [v0.3.6](https://github.com/napari/superqt/tree/v0.3.6) (2022-10-03)
+## [v0.5.4](https://github.com/pyapp-kit/superqt/tree/v0.5.4) (2023-08-31)
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.5...v0.3.6)
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.5.3...v0.5.4)
+
+**Fixed bugs:**
+
+- fix: fix mysterious segfault [\#192](https://github.com/pyapp-kit/superqt/pull/192) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.5.3](https://github.com/pyapp-kit/superqt/tree/v0.5.3) (2023-08-21)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.5.2...v0.5.3)
 
 **Implemented enhancements:**
 
-- feat: add editing finished signal to LabeledSliders [\#122](https://github.com/napari/superqt/pull/122) ([tlambert03](https://github.com/tlambert03))
+- feat: add error `exceptions_as_dialog` context manager to catch and show Exceptions [\#191](https://github.com/pyapp-kit/superqt/pull/191) ([tlambert03](https://github.com/tlambert03))
 
 **Fixed bugs:**
 
-- fix: fix missing labels after setValue [\#123](https://github.com/napari/superqt/pull/123) ([tlambert03](https://github.com/tlambert03))
-- fix: Fix TypeError on slider rangeChanged signal [\#121](https://github.com/napari/superqt/pull/121) ([tlambert03](https://github.com/tlambert03))
-- Simple workaround for pyside 6 [\#119](https://github.com/napari/superqt/pull/119) ([Czaki](https://github.com/Czaki))
-- fix: Offer patch for \(unstyled\) QSliders on macos 12 and Qt \<6 [\#117](https://github.com/napari/superqt/pull/117) ([tlambert03](https://github.com/tlambert03))
+- fix: remove dupes/aliases in QEnumCombo [\#190](https://github.com/pyapp-kit/superqt/pull/190) ([tlambert03](https://github.com/tlambert03))
 
-## [v0.3.5](https://github.com/napari/superqt/tree/v0.3.5) (2022-08-17)
+## [v0.5.2](https://github.com/pyapp-kit/superqt/tree/v0.5.2) (2023-08-18)
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.4...v0.3.5)
-
-**Fixed bugs:**
-
-- fix range slider drag crash on PyQt6 [\#108](https://github.com/napari/superqt/pull/108) ([sfhbarnett](https://github.com/sfhbarnett))
-- Fix float value error in pyqt configuration [\#106](https://github.com/napari/superqt/pull/106) ([mstabrin](https://github.com/mstabrin))
-
-**Merged pull requests:**
-
-- chore: changelog v0.3.5 [\#110](https://github.com/napari/superqt/pull/110) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.3.4](https://github.com/napari/superqt/tree/v0.3.4) (2022-07-24)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.3...v0.3.4)
-
-**Fixed bugs:**
-
-- fix: relax runtime typing extensions requirement [\#101](https://github.com/napari/superqt/pull/101) ([tlambert03](https://github.com/tlambert03))
-- fix: catch qpixmap deprecation [\#99](https://github.com/napari/superqt/pull/99) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.3.3](https://github.com/napari/superqt/tree/v0.3.3) (2022-07-10)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.2...v0.3.3)
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.5.1...v0.5.2)
 
 **Implemented enhancements:**
 
-- Add code syntax highlight utils [\#88](https://github.com/napari/superqt/pull/88) ([Czaki](https://github.com/Czaki))
+- feat: allow throttler/debouncer as method decorator [\#188](https://github.com/pyapp-kit/superqt/pull/188) ([Czaki](https://github.com/Czaki))
 
 **Fixed bugs:**
 
-- fix: fix deprecation warning on fonticon plugin discovery on python 3.10 [\#95](https://github.com/napari/superqt/pull/95) ([tlambert03](https://github.com/tlambert03))
+- fix: Add descriptive exception when fail to add instance to weakref dictionary  [\#189](https://github.com/pyapp-kit/superqt/pull/189) ([Czaki](https://github.com/Czaki))
 
-## [v0.3.2](https://github.com/napari/superqt/tree/v0.3.2) (2022-05-03)
+## [v0.5.1](https://github.com/pyapp-kit/superqt/tree/v0.5.1) (2023-08-17)
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.1...v0.3.2)
-
-**Implemented enhancements:**
-
-- Add QSearchableListWidget and QSearchableComboBox widgets [\#80](https://github.com/napari/superqt/pull/80) ([Czaki](https://github.com/Czaki))
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.5.0...v0.5.1)
 
 **Fixed bugs:**
 
-- Fix crazy animation loop on Qcollapsible [\#84](https://github.com/napari/superqt/pull/84) ([tlambert03](https://github.com/tlambert03))
-- Reorder label update signal [\#83](https://github.com/napari/superqt/pull/83) ([tlambert03](https://github.com/tlambert03))
-- Fix height of expanded QCollapsible when child changes size [\#72](https://github.com/napari/superqt/pull/72) ([tlambert03](https://github.com/tlambert03))
-
-**Tests & CI:**
-
-- Fix deprecation warnings in tests [\#82](https://github.com/napari/superqt/pull/82) ([tlambert03](https://github.com/tlambert03))
-
-**Merged pull requests:**
-
-- Add changelog for v0.3.2 [\#86](https://github.com/napari/superqt/pull/86) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.3.1](https://github.com/napari/superqt/tree/v0.3.1) (2022-03-02)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.3.0...v0.3.1)
-
-**Implemented enhancements:**
-
-- Add `signals_blocked` util [\#69](https://github.com/napari/superqt/pull/69) ([tlambert03](https://github.com/tlambert03))
-
-**Fixed bugs:**
-
-- put SignalInstance in TYPE\_CHECKING clause, check min requirements [\#70](https://github.com/napari/superqt/pull/70) ([tlambert03](https://github.com/tlambert03))
-
-**Merged pull requests:**
-
-- Add changelog for v0.3.1 [\#71](https://github.com/napari/superqt/pull/71) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.3.0](https://github.com/napari/superqt/tree/v0.3.0) (2022-02-16)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.5-1...v0.3.0)
-
-**Implemented enhancements:**
-
-- Qthrottler and debouncer [\#62](https://github.com/napari/superqt/pull/62) ([tlambert03](https://github.com/tlambert03))
-- add edgeLabelMode option to QLabeledSlider [\#59](https://github.com/napari/superqt/pull/59) ([tlambert03](https://github.com/tlambert03))
-
-**Fixed bugs:**
-
-- Fix nested threadworker not starting [\#63](https://github.com/napari/superqt/pull/63) ([tlambert03](https://github.com/tlambert03))
-- Add missing signals on proxy sliders  [\#54](https://github.com/napari/superqt/pull/54) ([tlambert03](https://github.com/tlambert03))
-- Ugly but functional workaround for pyside6.2.1 breakages [\#51](https://github.com/napari/superqt/pull/51) ([tlambert03](https://github.com/tlambert03))
-
-**Tests & CI:**
-
-- add napari test to CI [\#67](https://github.com/napari/superqt/pull/67) ([tlambert03](https://github.com/tlambert03))
-- add gh-release action [\#65](https://github.com/napari/superqt/pull/65) ([tlambert03](https://github.com/tlambert03))
-- fix xvfb tests [\#61](https://github.com/napari/superqt/pull/61) ([tlambert03](https://github.com/tlambert03))
-
-**Refactors:**
-
-- Use qtpy, deprecate superqt.qtcompat, drop support for Qt \<5.12 [\#39](https://github.com/napari/superqt/pull/39) ([tlambert03](https://github.com/tlambert03))
-
-**Merged pull requests:**
-
-- Add changelog for v0.3.0 [\#68](https://github.com/napari/superqt/pull/68) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.2.5-1](https://github.com/napari/superqt/tree/v0.2.5-1) (2021-11-23)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.5...v0.2.5-1)
-
-**Merged pull requests:**
-
-- typing-extensions version pinning [\#46](https://github.com/napari/superqt/pull/46) ([AhmetCanSolak](https://github.com/AhmetCanSolak))
-
-## [v0.2.5](https://github.com/napari/superqt/tree/v0.2.5) (2021-11-22)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.4...v0.2.5)
-
-**Implemented enhancements:**
-
-- add support for python 3.10 [\#42](https://github.com/napari/superqt/pull/42) ([tlambert03](https://github.com/tlambert03))
-- QCollapsible for Collapsible Section Control [\#37](https://github.com/napari/superqt/pull/37) ([MosGeo](https://github.com/MosGeo))
-- Threadworker [\#31](https://github.com/napari/superqt/pull/31) ([tlambert03](https://github.com/tlambert03))
-- Add font icons [\#24](https://github.com/napari/superqt/pull/24) ([tlambert03](https://github.com/tlambert03))
-
-**Fixed bugs:**
-
-- Fix some small linting issues. [\#41](https://github.com/napari/superqt/pull/41) ([tlambert03](https://github.com/tlambert03))
-- Use functools.wraps insterad of \_\_wraped\_\_ and manual proxing \_\_name\_\_ [\#29](https://github.com/napari/superqt/pull/29) ([Czaki](https://github.com/Czaki))
-- Propagate function name in `ensure_main_thread` and `ensure_object_thread` [\#28](https://github.com/napari/superqt/pull/28) ([Czaki](https://github.com/Czaki))
-
-**Tests & CI:**
-
-- reskip test\_object\_thread\_return on ci [\#43](https://github.com/napari/superqt/pull/43) ([tlambert03](https://github.com/tlambert03))
-
-**Refactors:**
-
-- refactoring qtcompat [\#34](https://github.com/napari/superqt/pull/34) ([tlambert03](https://github.com/tlambert03))
-
-**Merged pull requests:**
-
-- Fix-manifest, move font tests [\#44](https://github.com/napari/superqt/pull/44) ([tlambert03](https://github.com/tlambert03))
-- update deploy [\#33](https://github.com/napari/superqt/pull/33) ([tlambert03](https://github.com/tlambert03))
-- move to src layout [\#32](https://github.com/napari/superqt/pull/32) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.2.4](https://github.com/napari/superqt/tree/v0.2.4) (2021-09-13)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.3...v0.2.4)
-
-**Implemented enhancements:**
-
-- Add type stubs for ensure\_thread decorator [\#23](https://github.com/napari/superqt/pull/23) ([tlambert03](https://github.com/tlambert03))
-- Add `ensure_main_tread` and `ensure_object_thread` [\#22](https://github.com/napari/superqt/pull/22) ([Czaki](https://github.com/Czaki))
-- Add QMessageHandler context manager [\#21](https://github.com/napari/superqt/pull/21) ([tlambert03](https://github.com/tlambert03))
-
-**Merged pull requests:**
-
-- add changelog for 0.2.4 [\#25](https://github.com/napari/superqt/pull/25) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.2.3](https://github.com/napari/superqt/tree/v0.2.3) (2021-08-25)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.2...v0.2.3)
-
-**Fixed bugs:**
-
-- Fix warnings on eliding label for 5.12, test more qt versions [\#19](https://github.com/napari/superqt/pull/19) ([tlambert03](https://github.com/tlambert03))
-
-## [v0.2.2](https://github.com/napari/superqt/tree/v0.2.2) (2021-08-17)
-
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.1...v0.2.2)
-
-**Implemented enhancements:**
-
-- Add QElidingLabel [\#16](https://github.com/napari/superqt/pull/16) ([tlambert03](https://github.com/tlambert03))
-- Enum ComboBox implementation [\#13](https://github.com/napari/superqt/pull/13) ([Czaki](https://github.com/Czaki))
+- fix: fix parameter inspection on ensure\_thread decorators \(alternate\) [\#185](https://github.com/pyapp-kit/superqt/pull/185) ([tlambert03](https://github.com/tlambert03))
+- fix: fix callback of throttled/debounced decorated functions with mismatched args [\#184](https://github.com/pyapp-kit/superqt/pull/184) ([tlambert03](https://github.com/tlambert03))
 
 **Documentation updates:**
 
-- fix broken link [\#18](https://github.com/napari/superqt/pull/18) ([haesleinhuepf](https://github.com/haesleinhuepf))
+- docs: document signals blocked [\#186](https://github.com/pyapp-kit/superqt/pull/186) ([tlambert03](https://github.com/tlambert03))
 
-## [v0.2.1](https://github.com/napari/superqt/tree/v0.2.1) (2021-07-10)
+**Merged pull requests:**
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.0rc1...v0.2.1)
+- test: change wait pattern [\#187](https://github.com/pyapp-kit/superqt/pull/187) ([tlambert03](https://github.com/tlambert03))
+- build: drop python3.7, misc updates to repo [\#180](https://github.com/pyapp-kit/superqt/pull/180) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.5.0](https://github.com/pyapp-kit/superqt/tree/v0.5.0) (2023-08-06)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.4.1...v0.5.0)
+
+**Implemented enhancements:**
+
+- feat: add stepType to largeInt spinbox [\#179](https://github.com/pyapp-kit/superqt/pull/179) ([tlambert03](https://github.com/tlambert03))
+- Searchable tree widget from a mapping [\#158](https://github.com/pyapp-kit/superqt/pull/158) ([andy-sweet](https://github.com/andy-sweet))
+- Add `QElidingLineEdit` class for elidable `QLineEdit`s [\#154](https://github.com/pyapp-kit/superqt/pull/154) ([dalthviz](https://github.com/dalthviz))
 
 **Fixed bugs:**
 
-- Fix QLabeledRangeSlider API \(fix slider proxy\) [\#10](https://github.com/napari/superqt/pull/10) ([tlambert03](https://github.com/tlambert03))
-- Fix range slider with negative min range [\#9](https://github.com/napari/superqt/pull/9) ([tlambert03](https://github.com/tlambert03))
+- fix: focus events on QLabeledSlider [\#175](https://github.com/pyapp-kit/superqt/pull/175) ([tlambert03](https://github.com/tlambert03))
+- Set parent of timer in throttler [\#171](https://github.com/pyapp-kit/superqt/pull/171) ([Czaki](https://github.com/Czaki))
+- fix: fix double slider label editing [\#168](https://github.com/pyapp-kit/superqt/pull/168) ([tlambert03](https://github.com/tlambert03))
 
-## [v0.2.0rc1](https://github.com/napari/superqt/tree/v0.2.0rc1) (2021-06-26)
+**Documentation updates:**
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.0rc0...v0.2.0rc1)
+- Fix typos [\#147](https://github.com/pyapp-kit/superqt/pull/147) ([kianmeng](https://github.com/kianmeng))
 
-## [v0.2.0rc0](https://github.com/napari/superqt/tree/v0.2.0rc0) (2021-06-26)
+**Tests & CI:**
 
-[Full Changelog](https://github.com/napari/superqt/compare/v0.2.0...v0.2.0rc0)
+- tests: add qtbot to test to fix windows segfault [\#165](https://github.com/pyapp-kit/superqt/pull/165) ([tlambert03](https://github.com/tlambert03))
+- test: fixing tests \[wip\] [\#164](https://github.com/pyapp-kit/superqt/pull/164) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- build: unpin pyside6.5 [\#178](https://github.com/pyapp-kit/superqt/pull/178) ([tlambert03](https://github.com/tlambert03))
+- build: pin pyside6 to \<6.5.1 [\#169](https://github.com/pyapp-kit/superqt/pull/169) ([tlambert03](https://github.com/tlambert03))
+- pin pyside6\<6.5 [\#160](https://github.com/pyapp-kit/superqt/pull/160) ([tlambert03](https://github.com/tlambert03))
+- ci: \[pre-commit.ci\] autoupdate [\#146](https://github.com/pyapp-kit/superqt/pull/146) ([pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci))
+
+## [v0.4.1](https://github.com/pyapp-kit/superqt/tree/v0.4.1) (2022-12-01)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.4.0...v0.4.1)
+
+**Implemented enhancements:**
+
+- feat: Add signal to QCollapsible [\#142](https://github.com/pyapp-kit/superqt/pull/142) ([ppwadhwa](https://github.com/ppwadhwa))
+- feat: Change icon used in Collapsible widget [\#140](https://github.com/pyapp-kit/superqt/pull/140) ([ppwadhwa](https://github.com/ppwadhwa))
+
+**Fixed bugs:**
+
+- Move QCollapsible toggle signal emit [\#144](https://github.com/pyapp-kit/superqt/pull/144) ([ppwadhwa](https://github.com/ppwadhwa))
+
+**Merged pull requests:**
+
+- build: use hatch for build backend, and use ruff for linting [\#139](https://github.com/pyapp-kit/superqt/pull/139) ([tlambert03](https://github.com/tlambert03))
+- chore: rename napari org to pyapp-kit [\#137](https://github.com/pyapp-kit/superqt/pull/137) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.4.0](https://github.com/pyapp-kit/superqt/tree/v0.4.0) (2022-11-09)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.8...v0.4.0)
+
+**Fixed bugs:**
+
+- fix: fix quantity set value and add test [\#131](https://github.com/pyapp-kit/superqt/pull/131) ([tlambert03](https://github.com/tlambert03))
+
+**Refactors:**
+
+- refactor: update pyproject and ci, add py3.11 test [\#132](https://github.com/pyapp-kit/superqt/pull/132) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- chore: changelog v0.4.0 [\#136](https://github.com/pyapp-kit/superqt/pull/136) ([tlambert03](https://github.com/tlambert03))
+- ci\(dependabot\): bump actions/upload-artifact from 2 to 3 [\#135](https://github.com/pyapp-kit/superqt/pull/135) ([dependabot[bot]](https://github.com/apps/dependabot))
+- ci\(dependabot\): bump codecov/codecov-action from 2 to 3 [\#134](https://github.com/pyapp-kit/superqt/pull/134) ([dependabot[bot]](https://github.com/apps/dependabot))
+- build: unpin pyside6 [\#133](https://github.com/pyapp-kit/superqt/pull/133) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.8](https://github.com/pyapp-kit/superqt/tree/v0.3.8) (2022-10-10)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.7...v0.3.8)
+
+**Fixed bugs:**
+
+- fix: allow submodule imports [\#128](https://github.com/pyapp-kit/superqt/pull/128) ([kne42](https://github.com/kne42))
+
+## [v0.3.7](https://github.com/pyapp-kit/superqt/tree/v0.3.7) (2022-10-10)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.6...v0.3.7)
+
+**Implemented enhancements:**
+
+- feat: add Quantity widget \(using pint\) [\#126](https://github.com/pyapp-kit/superqt/pull/126) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.6](https://github.com/pyapp-kit/superqt/tree/v0.3.6) (2022-10-05)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.6rc0...v0.3.6)
+
+**Documentation updates:**
+
+- minor fix to readme [\#125](https://github.com/pyapp-kit/superqt/pull/125) ([tlambert03](https://github.com/tlambert03))
+- Docs [\#124](https://github.com/pyapp-kit/superqt/pull/124) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.6rc0](https://github.com/pyapp-kit/superqt/tree/v0.3.6rc0) (2022-10-03)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.5...v0.3.6rc0)
+
+**Implemented enhancements:**
+
+- feat: add editing finished signal to LabeledSliders [\#122](https://github.com/pyapp-kit/superqt/pull/122) ([tlambert03](https://github.com/tlambert03))
+
+**Fixed bugs:**
+
+- fix: fix missing labels after setValue [\#123](https://github.com/pyapp-kit/superqt/pull/123) ([tlambert03](https://github.com/tlambert03))
+- fix: Fix TypeError on slider rangeChanged signal [\#121](https://github.com/pyapp-kit/superqt/pull/121) ([tlambert03](https://github.com/tlambert03))
+- Simple workaround for pyside 6 [\#119](https://github.com/pyapp-kit/superqt/pull/119) ([Czaki](https://github.com/Czaki))
+- fix: Offer patch for \(unstyled\) QSliders on macos 12 and Qt \<6 [\#117](https://github.com/pyapp-kit/superqt/pull/117) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.5](https://github.com/pyapp-kit/superqt/tree/v0.3.5) (2022-08-17)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.4...v0.3.5)
+
+**Fixed bugs:**
+
+- fix range slider drag crash on PyQt6 [\#108](https://github.com/pyapp-kit/superqt/pull/108) ([sfhbarnett](https://github.com/sfhbarnett))
+- Fix float value error in pyqt configuration [\#106](https://github.com/pyapp-kit/superqt/pull/106) ([mstabrin](https://github.com/mstabrin))
+
+**Merged pull requests:**
+
+- chore: changelog v0.3.5 [\#110](https://github.com/pyapp-kit/superqt/pull/110) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.4](https://github.com/pyapp-kit/superqt/tree/v0.3.4) (2022-07-24)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.3...v0.3.4)
+
+**Fixed bugs:**
+
+- fix: relax runtime typing extensions requirement [\#101](https://github.com/pyapp-kit/superqt/pull/101) ([tlambert03](https://github.com/tlambert03))
+- fix: catch qpixmap deprecation [\#99](https://github.com/pyapp-kit/superqt/pull/99) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.3](https://github.com/pyapp-kit/superqt/tree/v0.3.3) (2022-07-10)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.2...v0.3.3)
+
+**Implemented enhancements:**
+
+- Add code syntax highlight utils [\#88](https://github.com/pyapp-kit/superqt/pull/88) ([Czaki](https://github.com/Czaki))
+
+**Fixed bugs:**
+
+- fix: fix deprecation warning on fonticon plugin discovery on python 3.10 [\#95](https://github.com/pyapp-kit/superqt/pull/95) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.2](https://github.com/pyapp-kit/superqt/tree/v0.3.2) (2022-05-03)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.1...v0.3.2)
+
+**Implemented enhancements:**
+
+- Add QSearchableListWidget and QSearchableComboBox widgets [\#80](https://github.com/pyapp-kit/superqt/pull/80) ([Czaki](https://github.com/Czaki))
+
+**Fixed bugs:**
+
+- Fix crazy animation loop on Qcollapsible [\#84](https://github.com/pyapp-kit/superqt/pull/84) ([tlambert03](https://github.com/tlambert03))
+- Reorder label update signal [\#83](https://github.com/pyapp-kit/superqt/pull/83) ([tlambert03](https://github.com/tlambert03))
+- Fix height of expanded QCollapsible when child changes size [\#72](https://github.com/pyapp-kit/superqt/pull/72) ([tlambert03](https://github.com/tlambert03))
+
+**Tests & CI:**
+
+- Fix deprecation warnings in tests [\#82](https://github.com/pyapp-kit/superqt/pull/82) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- Add changelog for v0.3.2 [\#86](https://github.com/pyapp-kit/superqt/pull/86) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.1](https://github.com/pyapp-kit/superqt/tree/v0.3.1) (2022-03-02)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.3.0...v0.3.1)
+
+**Implemented enhancements:**
+
+- Add `signals_blocked` util [\#69](https://github.com/pyapp-kit/superqt/pull/69) ([tlambert03](https://github.com/tlambert03))
+
+**Fixed bugs:**
+
+- put SignalInstance in TYPE\_CHECKING clause, check min requirements [\#70](https://github.com/pyapp-kit/superqt/pull/70) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- Add changelog for v0.3.1 [\#71](https://github.com/pyapp-kit/superqt/pull/71) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.3.0](https://github.com/pyapp-kit/superqt/tree/v0.3.0) (2022-02-16)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.5-1...v0.3.0)
+
+**Implemented enhancements:**
+
+- Qthrottler and debouncer [\#62](https://github.com/pyapp-kit/superqt/pull/62) ([tlambert03](https://github.com/tlambert03))
+- add edgeLabelMode option to QLabeledSlider [\#59](https://github.com/pyapp-kit/superqt/pull/59) ([tlambert03](https://github.com/tlambert03))
+
+**Fixed bugs:**
+
+- Fix nested threadworker not starting [\#63](https://github.com/pyapp-kit/superqt/pull/63) ([tlambert03](https://github.com/tlambert03))
+- Add missing signals on proxy sliders  [\#54](https://github.com/pyapp-kit/superqt/pull/54) ([tlambert03](https://github.com/tlambert03))
+- Ugly but functional workaround for pyside6.2.1 breakages [\#51](https://github.com/pyapp-kit/superqt/pull/51) ([tlambert03](https://github.com/tlambert03))
+
+**Tests & CI:**
+
+- add napari test to CI [\#67](https://github.com/pyapp-kit/superqt/pull/67) ([tlambert03](https://github.com/tlambert03))
+- add gh-release action [\#65](https://github.com/pyapp-kit/superqt/pull/65) ([tlambert03](https://github.com/tlambert03))
+- fix xvfb tests [\#61](https://github.com/pyapp-kit/superqt/pull/61) ([tlambert03](https://github.com/tlambert03))
+
+**Refactors:**
+
+- Use qtpy, deprecate superqt.qtcompat, drop support for Qt \<5.12 [\#39](https://github.com/pyapp-kit/superqt/pull/39) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- Add changelog for v0.3.0 [\#68](https://github.com/pyapp-kit/superqt/pull/68) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.2.5-1](https://github.com/pyapp-kit/superqt/tree/v0.2.5-1) (2021-11-23)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.5...v0.2.5-1)
+
+**Merged pull requests:**
+
+- typing-extensions version pinning [\#46](https://github.com/pyapp-kit/superqt/pull/46) ([AhmetCanSolak](https://github.com/AhmetCanSolak))
+
+## [v0.2.5](https://github.com/pyapp-kit/superqt/tree/v0.2.5) (2021-11-22)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.4...v0.2.5)
+
+**Implemented enhancements:**
+
+- add support for python 3.10 [\#42](https://github.com/pyapp-kit/superqt/pull/42) ([tlambert03](https://github.com/tlambert03))
+- QCollapsible for Collapsible Section Control [\#37](https://github.com/pyapp-kit/superqt/pull/37) ([MosGeo](https://github.com/MosGeo))
+- Threadworker [\#31](https://github.com/pyapp-kit/superqt/pull/31) ([tlambert03](https://github.com/tlambert03))
+- Add font icons [\#24](https://github.com/pyapp-kit/superqt/pull/24) ([tlambert03](https://github.com/tlambert03))
+
+**Fixed bugs:**
+
+- Fix some small linting issues. [\#41](https://github.com/pyapp-kit/superqt/pull/41) ([tlambert03](https://github.com/tlambert03))
+- Use functools.wraps insterad of \_\_wraped\_\_ and manual proxing \_\_name\_\_ [\#29](https://github.com/pyapp-kit/superqt/pull/29) ([Czaki](https://github.com/Czaki))
+- Propagate function name in `ensure_main_thread` and `ensure_object_thread` [\#28](https://github.com/pyapp-kit/superqt/pull/28) ([Czaki](https://github.com/Czaki))
+
+**Tests & CI:**
+
+- reskip test\_object\_thread\_return on ci [\#43](https://github.com/pyapp-kit/superqt/pull/43) ([tlambert03](https://github.com/tlambert03))
+
+**Refactors:**
+
+- refactoring qtcompat [\#34](https://github.com/pyapp-kit/superqt/pull/34) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- Fix-manifest, move font tests [\#44](https://github.com/pyapp-kit/superqt/pull/44) ([tlambert03](https://github.com/tlambert03))
+- update deploy [\#33](https://github.com/pyapp-kit/superqt/pull/33) ([tlambert03](https://github.com/tlambert03))
+- move to src layout [\#32](https://github.com/pyapp-kit/superqt/pull/32) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.2.4](https://github.com/pyapp-kit/superqt/tree/v0.2.4) (2021-09-13)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.3...v0.2.4)
+
+**Implemented enhancements:**
+
+- Add type stubs for ensure\_thread decorator [\#23](https://github.com/pyapp-kit/superqt/pull/23) ([tlambert03](https://github.com/tlambert03))
+- Add `ensure_main_tread` and `ensure_object_thread` [\#22](https://github.com/pyapp-kit/superqt/pull/22) ([Czaki](https://github.com/Czaki))
+- Add QMessageHandler context manager [\#21](https://github.com/pyapp-kit/superqt/pull/21) ([tlambert03](https://github.com/tlambert03))
+
+**Merged pull requests:**
+
+- add changelog for 0.2.4 [\#25](https://github.com/pyapp-kit/superqt/pull/25) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.2.3](https://github.com/pyapp-kit/superqt/tree/v0.2.3) (2021-08-25)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.2...v0.2.3)
+
+**Fixed bugs:**
+
+- Fix warnings on eliding label for 5.12, test more qt versions [\#19](https://github.com/pyapp-kit/superqt/pull/19) ([tlambert03](https://github.com/tlambert03))
+
+## [v0.2.2](https://github.com/pyapp-kit/superqt/tree/v0.2.2) (2021-08-17)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.1...v0.2.2)
+
+**Implemented enhancements:**
+
+- Add QElidingLabel [\#16](https://github.com/pyapp-kit/superqt/pull/16) ([tlambert03](https://github.com/tlambert03))
+- Enum ComboBox implementation [\#13](https://github.com/pyapp-kit/superqt/pull/13) ([Czaki](https://github.com/Czaki))
+
+**Documentation updates:**
+
+- fix broken link [\#18](https://github.com/pyapp-kit/superqt/pull/18) ([haesleinhuepf](https://github.com/haesleinhuepf))
+
+## [v0.2.1](https://github.com/pyapp-kit/superqt/tree/v0.2.1) (2021-07-10)
+
+[Full Changelog](https://github.com/pyapp-kit/superqt/compare/v0.2.0...v0.2.1)
+
+**Fixed bugs:**
+
+- Fix QLabeledRangeSlider API \(fix slider proxy\) [\#10](https://github.com/pyapp-kit/superqt/pull/10) ([tlambert03](https://github.com/tlambert03))
+- Fix range slider with negative min range [\#9](https://github.com/pyapp-kit/superqt/pull/9) ([tlambert03](https://github.com/tlambert03))
 
 
 

CONTRIBUTING.md

@@ -26,7 +26,7 @@ pytest
 
 All widgets must be well-tested, and should work on:
 
-- Python 3.7 and above
+- Python 3.8 and above
 - PyQt5 (5.11 and above) & PyQt6
 - PySide2 (5.11 and above) & PySide6
 - macOS, Windows, & Linux
@@ -48,5 +48,4 @@ All widgets should try to match the native Qt API as much as possible:
 
 ## Testing
 
-Tests can be run in the current environment with `pytest`.  Or, to run tests
-against all supported python & Qt versions, run `tox`.
+Tests can be run in the current environment with `pytest`.

MANIFEST.in

@@ -1,17 +0,0 @@
-include LICENSE
-include README.md
-include CHANGELOG.md
-include src/superqt/py.typed
-recursive-include src/superqt *.py
-recursive-include src/superqt *.pyi
-
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-recursive-exclude docs *
-recursive-exclude examples *
-recursive-exclude tests *
-exclude tox.ini
-exclude CONTRIBUTING.md
-exclude codecov.yml
-exclude .github_changelog_generator
-exclude .pre-commit-config.yaml

README.md

@@ -1,12 +1,11 @@
 # ![tiny](https://user-images.githubusercontent.com/1609449/120636353-8c3f3800-c43b-11eb-8732-a14dec578897.png)  superqt!
 
-
-[![License](https://img.shields.io/pypi/l/superqt.svg?color=green)](https://github.com/napari/superqt/raw/master/LICENSE)
+[![License](https://img.shields.io/pypi/l/superqt.svg?color=green)](https://github.com/pyapp-kit/superqt/raw/master/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/superqt.svg?color=green)](https://pypi.org/project/superqt)
 [![Python
 Version](https://img.shields.io/pypi/pyversions/superqt.svg?color=green)](https://python.org)
-[![Test](https://github.com/napari/superqt/actions/workflows/test_and_deploy.yml/badge.svg)](https://github.com/napari/superqt/actions/workflows/test_and_deploy.yml)
-[![codecov](https://codecov.io/gh/napari/superqt/branch/main/graph/badge.svg?token=dcsjgl1sOi)](https://codecov.io/gh/napari/superqt)
+[![Test](https://github.com/pyapp-kit/superqt/actions/workflows/test_and_deploy.yml/badge.svg)](https://github.com/pyapp-kit/superqt/actions/workflows/test_and_deploy.yml)
+[![codecov](https://codecov.io/gh/pyapp-kit/superqt/branch/main/graph/badge.svg?token=dcsjgl1sOi)](https://codecov.io/gh/pyapp-kit/superqt)
 
 ###  "missing" widgets and components for PyQt/PySide
 
@@ -16,29 +15,36 @@ that are not provided in the native QtWidgets module.
 Components are tested on:
 
 - macOS, Windows, & Linux
-- Python 3.7 and above
+- Python 3.8 and above
 - PyQt5 (5.11 and above) & PyQt6
 - PySide2 (5.11 and above) & PySide6
 
+## Documentation
+
+Documentation is available at https://pyapp-kit.github.io/superqt/
+
 ## Widgets
 
-Widgets include:
+superqt provides a variety of widgets that are not included in the native QtWidgets module, including multihandle (range) sliders, comboboxes, and more.
 
-- [Float Slider](docs/sliders.md#float-slider)
+See the [widgets documentation](https://pyapp-kit.github.io/superqt/widgets) for a full list of widgets.
 
-- [Range Slider](docs/sliders.md#range-slider) (multi-handle slider)
+- [Range Slider](https://pyapp-kit.github.io/superqt/widgets/qrangeslider/) (multi-handle slider)
 
-<img src="https://raw.githubusercontent.com/napari/superqt/main/docs/images/demo_darwin10.png" alt="range sliders" width=680>
+<img src="https://raw.githubusercontent.com/pyapp-kit/superqt/main/docs/images/demo_darwin10.png" alt="range sliders" width=680>
 
+<img src="https://raw.githubusercontent.com/pyapp-kit/superqt/main/docs/images/labeled_qslider.png" alt="range sliders" width=680>
 
-- [Labeled Sliders](docs/sliders.md#labeled-sliders) (sliders with linked
-  spinboxes)
+<img src="https://raw.githubusercontent.com/pyapp-kit/superqt/main/docs/images/labeled_range.png" alt="range sliders" width=680>
 
-<img src="https://raw.githubusercontent.com/napari/superqt/main/docs/images/labeled_qslider.png" alt="range sliders" width=680>
+## Utilities
 
-<img src="https://raw.githubusercontent.com/napari/superqt/main/docs/images/labeled_range.png" alt="range sliders" width=680>
+superqt includes a number of utilities for working with Qt, including:
 
-- Unbound Integer SpinBox (backed by python `int`)
+- tools and decorators for working with threads in qt.
+- `superqt.fonticon` for generating icons from font files (such as [Material Design Icons](https://materialdesignicons.com/) and [Font Awesome](https://fontawesome.com/))
+
+See the [utilities documentation](https://pyapp-kit.github.io/superqt/utilities/) for a full list of utilities.
 
 ## Contributing
 

docs/_macros.py

@@ -0,0 +1,146 @@
+import sys
+from enum import EnumMeta
+from importlib import import_module
+from pathlib import Path
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+from jinja2 import pass_context
+from qtpy.QtCore import QObject, Signal
+
+if TYPE_CHECKING:
+    from mkdocs_macros.plugin import MacrosPlugin
+
+EXAMPLES = Path(__file__).parent.parent / "examples"
+IMAGES = Path(__file__).parent / "_auto_images"
+IMAGES.mkdir(exist_ok=True, parents=True)
+
+
+def define_env(env: "MacrosPlugin"):
+    @env.macro
+    @pass_context
+    def show_widget(context, width: int = 500) -> list[Path]:
+        # extract all fenced code blocks starting with "python"
+        page = context["page"]
+        dest = IMAGES / f"{page.title}.png"
+        if "build" in sys.argv:
+            dest.unlink(missing_ok=True)
+
+            codeblocks = [
+                b[6:].strip()
+                for b in page.markdown.split("```")
+                if b.startswith("python")
+            ]
+            src = codeblocks[0].strip()
+            src = src.replace(
+                "QApplication([])", "QApplication.instance() or QApplication([])"
+            )
+            src = src.replace("app.exec_()", "")
+
+            exec(src)  # noqa: S102
+            _grab(dest, width)
+        return (
+            f"![{page.title}](../{dest.parent.name}/{dest.name})"
+            f"{{ loading=lazy; width={width} }}\n\n"
+        )
+
+    @env.macro
+    def show_members(cls: str):
+        # import class
+        module, name = cls.rsplit(".", 1)
+        _cls = getattr(import_module(module), name)
+
+        first_q = next(
+            (
+                b.__name__
+                for b in _cls.__mro__
+                if issubclass(b, QObject) and ".Qt" in b.__module__
+            ),
+            None,
+        )
+
+        inherited_members = set()
+        for base in _cls.__mro__:
+            if issubclass(base, QObject) and ".Qt" in base.__module__:
+                inherited_members.update(
+                    {k for k in dir(base) if not k.startswith("_")}
+                )
+
+        new_signals = {
+            k
+            for k, v in vars(_cls).items()
+            if not k.startswith("_") and isinstance(v, Signal)
+        }
+
+        self_members = {
+            k
+            for k in dir(_cls)
+            if not k.startswith("_") and k not in inherited_members | new_signals
+        }
+
+        enums = []
+        for m in list(self_members):
+            if isinstance(getattr(_cls, m), EnumMeta):
+                self_members.remove(m)
+                enums.append(m)
+
+        out = ""
+        if first_q:
+            url = f"https://doc.qt.io/qt-6/{first_q.lower()}.html"
+            out += f"## Qt Class\n\n<a href='{url}'>`{first_q}`</a>\n\n"
+
+        out += ""
+
+        if new_signals:
+            out += "## Signals\n\n"
+            for sig in new_signals:
+                out += f"### `{sig}`\n\n"
+
+        if enums:
+            out += "## Enums\n\n"
+            for e in enums:
+                out += f"### `{_cls.__name__}.{e}`\n\n"
+                for m in getattr(_cls, e):
+                    out += f"- `{m.name}`\n\n"
+
+        if self_members:
+            out += dedent(
+                f"""
+            ## Methods
+
+            ::: {cls}
+                options:
+                  heading_level: 3
+                  show_source: False
+                  show_inherited_members: false
+                  show_signature_annotations: True
+                  members: {sorted(self_members)}
+                  docstring_style: numpy
+                  show_bases: False
+                  show_root_toc_entry: False
+                  show_root_heading: False
+            """
+            )
+
+        return out
+
+
+def _grab(dest: str | Path, width) -> list[Path]:
+    """Grab the top widgets of the application."""
+    from qtpy.QtCore import QTimer
+    from qtpy.QtWidgets import QApplication
+
+    w = QApplication.topLevelWidgets()[-1]
+    w.setFixedWidth(width)
+    w.activateWindow()
+    w.setMinimumHeight(40)
+    w.grab().save(str(dest))
+
+    # hack to make sure the object is truly closed and deleted
+    while True:
+        QTimer.singleShot(10, w.deleteLater)
+        QApplication.processEvents()
+        try:
+            w.parent()
+        except RuntimeError:
+            return

docs/combobox.md

@@ -1,68 +0,0 @@
-# ComboBox
-
-
-## Enum Combo Box
-
-`QEnumComboBox` is a variant of [`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html)
-that populates the items in the combobox based on a python `Enum` class.  In addition to all
-the methods provided by `QComboBox`, this subclass adds the methods
-`enumClass`/`setEnumClass` to get/set the current `Enum` class represented by the combobox,
-and `currentEnum`/`setCurrentEnum` to get/set the current `Enum` member in the combobox.
-There is also a new signal `currentEnumChanged(enum)` analogous to `currentIndexChanged` and `currentTextChanged`.
-
-Method like `insertItem` and `addItem` are blocked and try of its usage will end with `RuntimeError`
-
-```python
-from enum import Enum
-
-from superqt import QEnumComboBox
-
-class SampleEnum(Enum):
-    first = 1
-    second = 2
-    third = 3
-
-# as usual:
-# you must create a QApplication before create a widget.
-
-combo = QEnumComboBox()
-combo.setEnumClass(SampleEnum)
-```
-
-other option is to use optional `enum_class` argument of constructor and change
-```python
-combo = QEnumComboBox()
-combo.setEnumClass(SampleEnum)
-```
-to
-```python
-combo = QEnumComboBox(enum_class=SampleEnum)
-```
-
-
-### Allow `None`
-`QEnumComboBox` allow using Optional type annotation:
-
-```python
-from enum import Enum
-
-from superqt import QEnumComboBox
-
-class SampleEnum(Enum):
-    first = 1
-    second = 2
-    third = 3
-
-# as usual:
-# you must create a QApplication before create a widget.
-
-combo = QEnumComboBox()
-combo.setEnumClass(SampleEnum, allow_none=True)
-```
-
-In this case there is added option `----` and `currentEnum` will return `None` for it.
-
-## QSearchableComboBox
-
-`QSearchableComboBox` is a variant of [`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that
-allow to filter list of options by enter part of text. It could be drop in replacement for `QComboBox`.

docs/faq.md

@@ -0,0 +1,26 @@
+# FAQ
+
+## Sliders not dragging properly on MacOS 12+
+
+??? details
+    On MacOS Monterey, with Qt5, there is a bug that causes all sliders
+    (including native Qt sliders) to not respond properly to drag events.  See:
+
+    - [https://bugreports.qt.io/browse/QTBUG-98093](https://bugreports.qt.io/browse/QTBUG-98093)
+    - [https://github.com/pyapp-kit/superqt/issues/74](https://github.com/pyapp-kit/superqt/issues/74)
+
+    Superqt includes a workaround for this issue, but it is not perfect, and it requires using a custom stylesheet (which may interfere with your own styles).  Note that you
+    may not see this issue if you're already using custom stylesheets.
+
+    To opt in to the workaround, do any of the following:
+
+    - set the environment variable `USE_MAC_SLIDER_PATCH=1` before importing superqt
+    (note: this is safe to use even if you're targeting more than just MacOS 12, it will only be applied when needed)
+    - call the `applyMacStylePatch()` method on any of the superqt slider subclasses (note, this will override your slider styles)
+    - apply the stylesheet manually:
+
+    ```python
+    from superqt.sliders import MONTEREY_SLIDER_STYLES_FIX
+
+    slider.setStyleSheet(MONTEREY_SLIDER_STYLES_FIX)
+    ```

docs/index.md

@@ -0,0 +1,29 @@
+# superqt
+
+## ![tiny](https://user-images.githubusercontent.com/1609449/120636353-8c3f3800-c43b-11eb-8732-a14dec578897.png) "missing" widgets and components for PyQt/PySide
+
+This repository aims to provide high-quality community-contributed Qt widgets
+and components for [PyQt](https://riverbankcomputing.com/software/pyqt/) &
+[PySide](https://www.qt.io/qt-for-python) that are not provided in the native
+QtWidgets module.
+
+Components are tested on:
+
+- macOS, Windows, & Linux
+- Python 3.8 and above
+- PyQt5 (5.11 and above) & PyQt6
+- PySide2 (5.11 and above) & PySide6
+
+## Installation
+
+```bash
+pip install superqt
+```
+
+```bash
+conda install -c conda-forge superqt
+```
+
+## Usage
+
+See the [Widgets](./widgets/) and [Utilities](./utilities/) pages for features offered by superqt.

docs/listwidgets.md

@@ -1,8 +0,0 @@
-# ListWidget
-
-## QSearchableListWidget
-
-`QSearchableListWidget` is a variant of [`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) that add text entry above list widget that allow to filter list
-of available options.
-
-Because of implementation it does not inherit directly from `QListWidget` but satisfy it all api. The only limitation is that it cannot be used as argument of `QListWidgetItem` constructor.

docs/sliders.md

@@ -1,257 +0,0 @@
-# Sliders
-
-
-![slider](images/slider.png)
-
-- `QRangeSlider` inherits from [`QSlider`](https://doc.qt.io/qt-5/qslider.html)
-  and attempts to match the Qt API as closely as possible
-- Uses platform-specific styles (for handle, groove, & ticks) but also supports
-  QSS style sheets.
-- Supports mouse wheel and keypress (soon) events
-- Supports more than 2 handles (e.g. `slider.setValue([0, 10, 60, 80])`)
-
-*Note: There is a Qt5 Bug that affects sliders in MacOS 12+, see fix at bottom of page.*
-
-## Range Slider
-
-```python
-from superqt import QRangeSlider
-
-# as usual:
-# you must create a QApplication before create a widget.
-range_slider = QRangeSlider()
-```
-
-As `QRangeSlider` inherits from `QtWidgets.QSlider`, you can use all of the
-same methods available in the [QSlider API](https://doc.qt.io/qt-5/qslider.html).  The major difference is that `value` and `sliderPosition` are reimplemented as `tuples` of `int` (where the length of the tuple is equal to the number of handles in the slider.)
-
-### `value: Tuple[int, ...]`
-
-This property holds the current value of all handles in the slider.
-
-The slider forces all values to be within the legal range:
-`minimum <= value <= maximum`.
-
-Changing the value also changes the sliderPosition.
-
-##### Access Functions:
-
-```python
-range_slider.value() -> Tuple[int, ...]
-```
-
-```python
-range_slider.setValue(val: Sequence[int]) -> None
-```
-
-##### Notifier Signal:
-
-```python
-valueChanged(Tuple[int, ...])
-```
-
-### `sliderPosition: Tuple[int, ...]`
-
-This property holds the current slider positions.  It is a `tuple` with length equal to the number of handles.
-
-If [tracking](https://doc.qt.io/qt-5/qabstractslider.html#tracking-prop) is enabled (the default), this is identical to [`value`](#value--tupleint-).
-
-##### Access Functions:
-
-```python
-range_slider.sliderPosition() -> Tuple[int, ...]
-```
-
-```python
-range_slider.setSliderPosition(val: Sequence[int]) -> None
-```
-
-##### Notifier Signal:
-
-```python
-sliderMoved(Tuple[int, ...])
-```
-
-### Additional properties
-
-These options are in addition to the Qt QSlider API, and control the behavior of the bar between handles.
-
-| getter               | setter                                      | type   | default | description                                                                                      |
-| -------------------- | ------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------ |
-| `barIsVisible`       | `setBarIsVisible` <br>`hideBar` / `showBar` | `bool` | `True`  | <small>Whether the bar between handles is visible.</small>                                       |
-| `barMovesAllHandles` | `setBarMovesAllHandles`                     | `bool` | `True`  | <small>Whether clicking on the bar moves all handles or just the nearest</small>                 |
-| `barIsRigid`         | `setBarIsRigid`                             | `bool` | `True`  | <small>Whether bar length is constant or "elastic" when dragging the bar beyond min/max.</small> |
-------
-
-### Examples
-
-These screenshots show `QRangeSlider` (multiple handles) next to the native `QSlider`
-(single handle). With no styles applied, `QRangeSlider` will match the native OS
-style of `QSlider` – with or without tick marks.  When styles have been applied
-using [Qt Style Sheets](https://doc.qt.io/qt-5/stylesheet-reference.html), then
-`QRangeSlider` will inherit any styles applied to `QSlider` (since it inherits
-from QSlider).  If you'd like to style `QRangeSlider` differently than `QSlider`,
-then you can also target it directly in your style sheet.  The one "special"
-property for QRangeSlider is `qproperty-barColor`, which sets the color of the
-bar between the handles.
-
-> The code for these example widgets is [here](../examples/demo_widget.py)
-<details>
-
-<summary><em>See style sheet used for this example</em></summary>
-
-```css
-/*
-Because QRangeSlider inherits from QSlider, it will also inherit styles
-*/
-QSlider {
-    min-height: 20px;
-}
-
-QSlider::groove:horizontal {
-    border: 0px;
-    background: qlineargradient(x1:0, y1:0, x2:1, y2:1,
-                                stop:0 #777, stop:1 #aaa);
-    height: 20px;
-    border-radius: 10px;
-}
-
-QSlider::handle {
-    background: qradialgradient(cx:0, cy:0, radius: 1.2, fx:0.5,
-                                fy:0.5, stop:0 #eef, stop:1 #000);
-    height: 20px;
-    width: 20px;
-    border-radius: 10px;
-}
-
-/*
-"QSlider::sub-page" is the one exception ...
-(it styles the area to the left of the QSlider handle)
-*/
-QSlider::sub-page:horizontal {
-    background: #447;
-    border-top-left-radius: 10px;
-    border-bottom-left-radius: 10px;
-}
-
-/*
-for QRangeSlider: use "qproperty-barColor".  "sub-page" will not work.
-*/
-QRangeSlider {
-    qproperty-barColor: #447;
-}
-```
-
-</details>
-
-#### macOS
-
-##### Catalina
-
-![mac10](images/demo_darwin10.png)
-
-##### Big Sur
-
-![mac11](images/demo_darwin11.png)
-
-#### Windows
-
-![window](images/demo_windows.png)
-
-#### Linux
-
-![linux](images/demo_linux.png)
-
-## Labeled Sliders
-
-This package also includes two "labeled" slider variants. One for `QRangeSlider`, and one for the native `QSlider`:
-
-### `QLabeledRangeSlider`
-
-![labeled_range](images/labeled_range.png)
-
-```python
-from superqt import QLabeledRangeSlider
-```
-
-This has the same API as `QRangeSlider` with the following additional options:
-
-#### `handleLabelPosition`/`setHandleLabelPosition`
-
-Where/whether labels are shown adjacent to slider handles.
-
-**type:** `QLabeledRangeSlider.LabelPosition`
-
-**default:** `LabelPosition.LabelsAbove`
-
-*options:*
-
-- `LabelPosition.NoLabel` (no labels shown adjacent to handles)
-- `LabelPosition.LabelsAbove`
-- `LabelPosition.LabelsBelow`
-- `LabelPosition.LabelsRight` (alias for `LabelPosition.LabelsAbove`)
-- `LabelPosition.LabelsLeft` (alias for `LabelPosition.LabelsBelow`)
-
-#### `edgeLabelMode`/`setEdgeLabelMode`
-
-**type:** `QLabeledRangeSlider.EdgeLabelMode`
-
-**default:** `EdgeLabelMode.LabelIsRange`
-
-*options:*
-
-- `EdgeLabelMode.NoLabel`: no labels shown at slider extremes
-- `EdgeLabelMode.LabelIsRange`: edge labels shown the min/max values
-- `EdgeLabelMode.LabelIsValue`: edge labels shown the slider range
-
-#### fine tuning position of labels:
-
-If you find that you need to fine tune the position of the handle labels:
-
-- `QLabeledRangeSlider.label_shift_x`: adjust horizontal label position
-- `QLabeledRangeSlider.label_shift_y`: adjust vertical label position
-
-### `QLabeledSlider`
-
-![labeled_range](images/labeled_qslider.png)
-
-```python
-from superqt import QLabeledSlider
-```
-
-(no additional options at this point)
-
-
-## Float Slider
-
-just like QSlider, but supports float values
-
-```python
-from superqt import QDoubleSlider
-```
-
-## Issues
-
-### MacOS Monterey Slider issue
-
-On MacOS Monterey, with Qt5, there is a bug that causes all sliders
-(including native Qt sliders) to not respond properly to drag events.  See:
-
-- https://bugreports.qt.io/browse/QTBUG-98093
-- https://github.com/napari/superqt/issues/74
-
-Superqt includes a workaround for this issue, but it is not perfect, and it requires using a custom stylesheet (which may interfere with your own styles).  Note that you
-may not see this issue if you're already using custom stylesheets.
-
-To opt in to the workaround, do any of the following:
-
-- set the environment variable `USE_MAC_SLIDER_PATCH=1` before importing superqt
-  (note: this is safe to use even if you're targeting more than just MacOS 12, it will only be applied when needed)
-- call the `applyMacStylePatch()` method on any of the superqt slider subclasses (note, this will override your slider styles)
-- apply the stylesheet manually:
-
-```python
-from superqt.sliders import MONTEREY_SLIDER_STYLES_FIX
-
-slider.setStyleSheet(MONTEREY_SLIDER_STYLES_FIX)
-```

docs/utilities/code_syntax_highlight.md

@@ -0,0 +1,52 @@
+# CodeSyntaxHighlight
+
+A code highlighter subclass of `QSyntaxHighlighter`
+that can be used to highlight code in a QTextEdit.
+
+Code lexer and available styles are from [`pygments`](https://pygments.org/) python library
+
+List of available languages are available [here](https://pygments.org/languages/).
+
+List of available styles are available [here](https://pygments.org/styles/).
+
+## Example
+
+```python
+from qtpy.QtGui import QColor, QPalette
+from qtpy.QtWidgets import QApplication, QTextEdit
+
+from superqt.utils import CodeSyntaxHighlight
+
+app = QApplication([])
+
+text_area = QTextEdit()
+
+highlight = CodeSyntaxHighlight(text_area.document(), "python", "monokai")
+
+palette = text_area.palette()
+palette.setColor(QPalette.Base, QColor(highlight.background_color))
+text_area.setPalette(palette)
+text_area.setText(
+    """from argparse import ArgumentParser
+
+def main():
+    parser = ArgumentParser()
+    parser.add_argument("name", help="Your name")
+    args = parser.parse_args()
+    print(f"Hello {args.name}")
+
+
+if __name__ == "__main__":
+    main()
+"""
+)
+
+text_area.show()
+text_area.resize(400, 200)
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.utils.CodeSyntaxHighlight') }}

docs/utilities/error_dialog_contexts.md

@@ -0,0 +1,3 @@
+# Error message context manager
+
+::: superqt.utils.exceptions_as_dialog

docs/utilities/fonticon.md

@@ -0,0 +1,101 @@
+# Font icons
+
+The `superqt.fonticon` module provides a set of utilities for working with font
+icons such as [Font Awesome](https://fontawesome.com/) or [Material Design
+Icons](https://materialdesignicons.com/).
+
+## Basic Example
+
+```python
+from fonticon_fa5 import FA5S
+
+from qtpy.QtCore import QSize
+from qtpy.QtWidgets import QApplication, QPushButton
+
+from superqt.fonticon import icon, pulse
+
+app = QApplication([])
+
+btn2 = QPushButton()
+btn2.setIcon(icon(FA5S.smile, color="blue"))
+btn2.setIconSize(QSize(225, 225))
+btn2.show()
+
+app.exec()
+```
+
+{{ show_widget(225) }}
+
+## Font Icon plugins
+
+Ready-made fonticon packs are available as plugins:
+
+### [Font Awesome 5](https://fontawesome.com/v5/search)
+
+```bash
+pip install fonticon-fontawesome5
+```
+
+### [Font Awesome 6](https://fontawesome.com/v6/search)
+
+```bash
+pip install fonticon-fontawesome6
+```
+
+### [Material Design Icons](https://materialdesignicons.com/)
+
+```bash
+pip install fonticon-materialdesignicons6
+```
+
+### See also
+
+- <https://github.com/tlambert03/fonticon-bootstrapicons>
+- <https://github.com/tlambert03/fonticon-linearicons>
+- <https://github.com/tlambert03/fonticon-feather>
+
+`superqt.fonticon` is a pluggable system, and font icon packs may use the `"superqt.fonticon"`
+entry point to register themselves with superqt.  See [`fonticon-cookiecutter`](https://github.com/tlambert03/fonticon-cookiecutter) for a template, or look through the following repos for examples:
+
+- <https://github.com/tlambert03/fonticon-fontawesome6>
+- <https://github.com/tlambert03/fonticon-fontawesome5>
+- <https://github.com/tlambert03/fonticon-materialdesignicons6>
+
+## API
+
+::: superqt.fonticon.icon
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.setTextIcon
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.font
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.IconOpts
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.addFont
+    options:
+        heading_level: 3
+
+## Animations
+
+the `animation` parameter to `icon()` accepts a subclass of
+`Animation` that will be
+
+::: superqt.fonticon.Animation
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.pulse
+    options:
+        heading_level: 3
+
+::: superqt.fonticon.spin
+    options:
+        heading_level: 3

docs/utilities/index.md

@@ -0,0 +1,31 @@
+# Utilities
+
+## Font Icons
+
+| Object                          | Description           |
+| -----------                     | --------------------- |
+| [`addFont`](./fonticon.md#superqt.fonticon.addFont) | Add an `OTF/TTF` file at to the font registry. |
+| [`font`](./fonticon.md#superqt.fonticon.font) | Create `QFont` for a given font-icon font family key |
+| [`icon`](./fonticon.md#superqt.fonticon.icon) | Create a `QIcon` for font-con glyph key |
+| [`setTextIcon`](./fonticon.md#superqt.fonticon.setTextIcon) | Set text on a `QWidget` to a specific font & glyph. |
+| [`IconFont`](./fonticon.md#superqt.fonticon.IconFont) | Helper class that provides a standard way to create an `IconFont`. |
+| [`IconOpts`](./fonticon.md#superqt.fonticon.IconOpts) | Options for rendering an icon |
+| [`Animation`](./fonticon.md#superqt.fonticon.Animation) | Base class for adding animations to a font-icon. |
+
+## Threading tools
+
+| Object                          | Description           |
+| -----------                     | --------------------- |
+| [`ensure_main_thread`](./thread_decorators.md#ensure_main_thread)        | Decorator that ensures a function is called in the main `QApplication` thread. |
+| [`ensure_object_thread`](./thread_decorators.md#ensure_object_thread)      | Decorator that ensures a `QObject` method is called in the object's thread. |
+| [`FunctionWorker`](./threading.md#superqt.utils.FunctionWorker)      | `QRunnable` with signals that wraps a simple long-running function. |
+| [`GeneratorWorker`](./threading.md#superqt.utils.GeneratorWorker)      | `QRunnable` with signals that wraps a long-running generator. |
+| [`create_worker`](./threading.md#superqt.utils.create_worker)      | Create a worker to run a target function in another thread. |
+| [`thread_worker`](./threading.md#superqt.utils.thread_worker)      | Decorator for `create_worker`, turn a function into a worker. |
+
+## Miscellaneous
+
+| Object                          | Description           |
+| -----------                     | --------------------- |
+| [`QMessageHandler`](./qmessagehandler.md)           | A context manager to intercept messages from Qt. |
+| [`CodeSyntaxHighlight`](./code_syntax_highlight.md) | A `QSyntaxHighlighter` for code syntax highlighting. |

docs/utilities/qmessagehandler.md

@@ -0,0 +1,8 @@
+# QMessageHandler
+
+::: superqt.utils.QMessageHandler
+    options:
+        heading_level: 3
+        show_signature_annotations: True
+        docstring_style: numpy
+        show_bases: False

docs/utilities/signal_utils.md

@@ -0,0 +1,3 @@
+# Signal Utilities
+
+::: superqt.utils.signals_blocked

docs/utilities/thread_decorators.md

@@ -1,18 +1,24 @@
-# Decorators
-
-## Move to thread decorators
+# Threading decorators
 
 `superqt` provides two decorators that help to ensure that given function is
 running in the desired thread:
 
-* `ensure_main_thread` - ensures that the decorated function/method runs in the main thread
-* `ensure_object_thread` - ensures that a decorated bound method of a `QObject` runs in the
-  thread in which the instance lives ([qt
-  documentation](https://doc.qt.io/qt-5/threads-qobject.html#accessing-qobject-subclasses-from-other-threads)).
+## `ensure_main_thread`
+
+`ensure_main_thread` ensures that the decorated function/method runs in the main thread
+
+## `ensure_object_thread`
+
+`ensure_object_thread` ensures that a decorated bound method of a `QObject` runs
+in the thread in which the instance lives ([see qt documentation for
+details](https://doc.qt.io/qt-5/threads-qobject.html#accessing-qobject-subclasses-from-other-threads)).
+
+## Usage
 
 By default, functions are executed asynchronously (they return immediately with
 an instance of
 [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future)).
+
 To block and wait for the result, see [Synchronous mode](#synchronous-mode)
 
 ```python
@@ -57,12 +63,14 @@ As can be seen in this example these decorators can also be used for setters.
 These decorators should not be used as replacement of Qt Signals but rather to
 interact with Qt objects from non Qt code.
 
-### Synchronous mode
+## Synchronous mode
 
 If you'd like for the program to block and wait for the result of your function
 call, use the `await_return=True` parameter, and optionally specify a timeout.
 
-> *Note: Using synchronous mode may significantly impact performance.*
+!!! important
+
+    Using synchronous mode may significantly impact performance.
 
 ```python
 from superqt import ensure_main_thread

docs/utilities/threading.md

@@ -0,0 +1,36 @@
+# Thread workers
+
+The objects in this module provide utilities for running tasks in a separate
+thread. In general (with the exception of `new_worker_qthread`), everything
+here wraps Qt's [QRunnable API](https://doc.qt.io/qt-6/qrunnable.html).
+
+The highest level object is the
+[`@thread_worker`][superqt.utils.thread_worker] decorator.  It was originally
+written for `napari`, and was later extracted into `superqt`.  You may also be
+interested in reading the [napari
+documentation](https://napari.org/stable/guides/threading.html#threading-in-napari-with-thread-worker) on this feature,
+which provides a more in-depth/introductory usage guide.
+
+For additional control, you can create your own
+[`FunctionWorker`][superqt.utils.FunctionWorker] or
+[`GeneratorWorker`][superqt.utils.GeneratorWorker] objects.
+
+::: superqt.utils.WorkerBase
+
+::: superqt.utils.FunctionWorker
+
+::: superqt.utils.GeneratorWorker
+
+## Convenience functions
+
+::: superqt.utils.thread_worker
+    options:
+        heading_level: 3
+
+::: superqt.utils.create_worker
+    options:
+        heading_level: 3
+
+::: superqt.utils.new_worker_qthread
+    options:
+        heading_level: 3

docs/utilities/throttling.md

@@ -0,0 +1,46 @@
+# Throttling & Debouncing
+
+These utilities allow you to throttle or debounce a function. This is useful
+when you have a function that is called multiple times in a short period of
+time, and you want to make sure it is only "actually" called once (or at least
+no more than a certain frequency).
+
+For background on throttling and debouncing, see:
+
+- <https://blog.openreplay.com/forever-functional-debouncing-and-throttling-for-performance>
+- <https://css-tricks.com/debouncing-throttling-explained-examples/>
+
+::: superqt.utils.qdebounced
+    options:
+        show_source: false
+        docstring_style: numpy
+        show_root_toc_entry: True
+        show_root_heading: True
+
+::: superqt.utils.qthrottled
+    options:
+        show_source: false
+        docstring_style: numpy
+        show_root_toc_entry: True
+        show_root_heading: True
+
+::: superqt.utils.QSignalDebouncer
+    options:
+        show_source: false
+        docstring_style: numpy
+        show_root_toc_entry: True
+        show_root_heading: True
+
+::: superqt.utils.QSignalThrottler
+    options:
+        show_source: false
+        docstring_style: numpy
+        show_root_toc_entry: True
+        show_root_heading: True
+
+::: superqt.utils._throttler.GenericSignalThrottler
+    options:
+        show_source: false
+        docstring_style: numpy
+        show_root_toc_entry: True
+        show_root_heading: True

docs/utils.md

@@ -1,10 +0,0 @@
-# Utils
-
-## Code highlighting
-
-`superqt` provides a code highlighter subclass of `QSyntaxHighlighter`
-that can be used to highlight code in a QTextEdit.
-
-Code lexer and available styles are from [`pygments`](https://pygments.org/) python library
-List of available languages are available [here](https://pygments.org/languages/).
-List of available styles are available [here](https://pygments.org/styles/).

docs/widgets/index.md

@@ -0,0 +1,32 @@
+# Widgets
+
+The following are QWidget subclasses:
+
+## Sliders and Numerical Inputs
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QDoubleRangeSlider`](./qdoublerangeslider.md) | Multi-handle slider for float values   |
+| [`QDoubleSlider`](./qdoubleslider.md) | Slider for float values |
+| [`QLabeledDoubleRangeSlider`](./qlabeleddoublerangeslider.md) | `QDoubleRangeSlider` variant with editable labels for each handle |
+| [`QLabeledDoubleSlider`](./qlabeleddoubleslider.md) | `QSlider` for float values with editable `QSpinBox` with the current value |
+| [`QLabeledRangeSlider`](./qlabeledrangeslider.md) | `QRangeSlider` variant, with editable labels for each handle |
+| [`QLabeledSlider`](./qlabeledslider.md) | `QSlider` with editable `QSpinBox` that shows the current value |
+| [`QLargeIntSpinBox`](./qlargeintspinbox.md) | `QSpinbox` that accepts arbitrarily large integers |
+| [`QRangeSlider`](./qrangeslider.md) | Multi-handle slider   |
+| [`QQuantity`](./qquantity.md) | Pint-backed quantity widget (magnitude combined with unit dropdown)   |
+
+## Labels and categorical inputs
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QElidingLabel`](./qelidinglabel.md)             | A `QLabel` variant that will elide text (add `…`) to fit width. |
+| [`QEnumComboBox`](./qenumcombobox.md)             | `QComboBox` that populates the combobox from a python `Enum` |
+| [`QSearchableComboBox`](./qsearchablecombobox.md)       | `QComboBox` variant that filters available options based on text input |
+| [`QSearchableListWidget`](./qsearchablelistwidget.md)     | `QListWidget` variant with search field that filters available options |
+
+## Frames and containers
+
+| Widget                          | Description           |
+| -----------                     | --------------------- |
+| [`QCollapsible`](./qcollapsible.md)              | A collapsible widget to hide and unhide child widgets. |

docs/widgets/qcollapsible.md

@@ -0,0 +1,24 @@
+# QCollapsible
+
+Collapsible `QFrame` that can be expanded or collapsed by clicking on the header.
+
+```python
+from qtpy.QtWidgets import QApplication, QLabel, QPushButton
+
+from superqt import QCollapsible
+
+app = QApplication([])
+
+collapsible = QCollapsible("Advanced analysis")
+collapsible.addWidget(QLabel("This is the inside of the collapsible frame"))
+for i in range(10):
+    collapsible.addWidget(QPushButton(f"Content button {i + 1}"))
+
+collapsible.expand(animate=False)
+collapsible.show()
+app.exec_()
+```
+
+{{ show_widget(350) }}
+
+{{ show_members('superqt.QCollapsible') }}

docs/widgets/qdoublerangeslider.md

@@ -0,0 +1,23 @@
+# QDoubleRangeSlider
+
+Float variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QDoubleRangeSlider
+
+app = QApplication([])
+
+slider = QDoubleRangeSlider(Qt.Orientation.Horizontal)
+slider.setRange(0, 1)
+slider.setValue((0.2, 0.8))
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QDoubleRangeSlider') }}

docs/widgets/qdoubleslider.md

@@ -0,0 +1,23 @@
+# QDoubleSlider
+
+`QSlider` variant that accepts floating point values.
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QDoubleSlider
+
+app = QApplication([])
+
+slider = QDoubleSlider(Qt.Orientation.Horizontal)
+slider.setRange(0, 1)
+slider.setValue(0.5)
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QDoubleSlider') }}

docs/widgets/qelidinglabel.md

@@ -0,0 +1,26 @@
+# QElidingLabel
+
+`QLabel` variant that will elide text (i.e. add an ellipsis)
+if it is too long to fit in the available space.
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QElidingLabel
+
+app = QApplication([])
+
+widget = QElidingLabel(
+    "a skj skjfskfj sdlf sdfl sdlfk jsdf sdlkf jdsf dslfksdl sdlfk sdf sdl "
+    "fjsdlf kjsdlfk laskdfsal as lsdfjdsl kfjdslf asfd dslkjfldskf sdlkfj"
+)
+widget.setWordWrap(True)
+widget.resize(300, 20)
+widget.show()
+
+app.exec_()
+```
+
+{{ show_widget(300) }}
+
+{{ show_members('superqt.QElidingLabel') }}

docs/widgets/qenumcombobox.md

@@ -0,0 +1,72 @@
+# QEnumComboBox
+
+`QEnumComboBox` is a variant of
+[`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that populates the items in
+the combobox based on a python `Enum` class.  In addition to all the methods
+provided by `QComboBox`, this subclass adds the methods
+`enumClass`/`setEnumClass` to get/set the current `Enum` class represented by
+the combobox, and `currentEnum`/`setCurrentEnum` to get/set the current `Enum`
+member in the combobox. There is also a new signal `currentEnumChanged(enum)`
+analogous to `currentIndexChanged` and `currentTextChanged`.
+
+Method like `insertItem` and `addItem` are blocked and try of its usage will end
+with `RuntimeError`
+
+```python
+from enum import Enum
+
+from qtpy.QtWidgets import QApplication
+from superqt import QEnumComboBox
+
+
+class SampleEnum(Enum):
+    first = 1
+    second = 2
+    third = 3
+
+app = QApplication([])
+
+combo = QEnumComboBox()
+combo.setEnumClass(SampleEnum)
+combo.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+Another option is to use optional `enum_class` argument of constructor and change
+
+```python
+# option A:
+combo = QEnumComboBox()
+combo.setEnumClass(SampleEnum)
+# option B:
+combo = QEnumComboBox(enum_class=SampleEnum)
+```
+
+## Allow `None`
+
+`QEnumComboBox` also allows using `Optional` type annotation:
+
+```python
+from enum import Enum
+
+from superqt import QEnumComboBox
+
+class SampleEnum(Enum):
+    first = 1
+    second = 2
+    third = 3
+
+# as usual:
+# you must create a QApplication before create a widget.
+
+combo = QEnumComboBox()
+combo.setEnumClass(SampleEnum, allow_none=True)
+```
+
+In this case there is added option `----` and the `currentEnum()` method will
+return `None` when it is selected.
+
+{{ show_members('superqt.QEnumComboBox') }}

docs/widgets/qlabeleddoublerangeslider.md

@@ -0,0 +1,23 @@
+# QLabeledDoubleRangeSlider
+
+Labeled Float variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QLabeledDoubleRangeSlider
+
+app = QApplication([])
+
+slider = QLabeledDoubleRangeSlider(Qt.Orientation.Horizontal)
+slider.setRange(0, 1)
+slider.setValue((0.2, 0.8))
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QLabeledDoubleRangeSlider') }}

docs/widgets/qlabeleddoubleslider.md

@@ -0,0 +1,24 @@
+# QLabeledDoubleSlider
+
+[`QDoubleSlider`](./qdoubleslider.md) variant that shows an editable (SpinBox) label next to the slider.
+
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QLabeledDoubleSlider
+
+app = QApplication([])
+
+slider = QLabeledDoubleSlider(Qt.Orientation.Horizontal)
+slider.setRange(0, 2.5)
+slider.setValue(1.3)
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QLabeledDoubleSlider') }}

docs/widgets/qlabeledrangeslider.md

@@ -0,0 +1,29 @@
+# QLabeledRangeSlider
+
+Labeled variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QLabeledRangeSlider
+
+app = QApplication([])
+
+slider = QLabeledRangeSlider(Qt.Orientation.Horizontal)
+slider.setValue((20, 80))
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QLabeledRangeSlider') }}
+
+----
+
+If you find that you need to fine tune the position of the handle labels:
+
+- `QLabeledRangeSlider.label_shift_x`: adjust horizontal label position
+- `QLabeledRangeSlider.label_shift_y`: adjust vertical label position

docs/widgets/qlabeledslider.md

@@ -0,0 +1,22 @@
+# QLabeledSlider
+
+`QSlider` variant that shows an editable (SpinBox) label next to the slider.
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QLabeledSlider
+
+app = QApplication([])
+
+slider = QLabeledSlider(Qt.Orientation.Horizontal)
+slider.setValue(42)
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QLabeledSlider') }}

docs/widgets/qlargeintspinbox.md

@@ -0,0 +1,23 @@
+# QLargeIntSpinBox
+
+`QSpinBox` variant that allows to enter large integers, without overflow.
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QLargeIntSpinBox
+
+app = QApplication([])
+
+slider = QLargeIntSpinBox()
+slider.setRange(0, 4.53e8)
+slider.setValue(4.53e8)
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget(150) }}
+
+{{ show_members('superqt.QLargeIntSpinBox') }}

docs/widgets/qquantity.md

@@ -0,0 +1,33 @@
+# QQuantity
+
+A widget that allows the user to edit a quantity (a magnitude associated with a unit).
+
+!!! note
+
+    This widget requires [`pint`](https://pint.readthedocs.io):
+
+    ```
+    pip install pint
+    ```
+
+    or
+
+    ```
+    pip install superqt[quantity]
+    ```
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QQuantity
+
+app = QApplication([])
+w = QQuantity("1m")
+w.show()
+
+app.exec()
+```
+
+{{ show_widget(150) }}
+
+{{ show_members('superqt.QQuantity') }}

docs/widgets/qrangeslider.md

@@ -0,0 +1,229 @@
+# QRangeSlider
+
+A multi-handle slider widget than can be used to
+select a range of values.
+
+```python
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QApplication
+
+from superqt import QRangeSlider
+
+app = QApplication([])
+
+slider = QRangeSlider(Qt.Orientation.Horizontal)
+slider.setValue((20, 80))
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+- `QRangeSlider` inherits from [`QSlider`](https://doc.qt.io/qt-5/qslider.html)
+  and attempts to match the Qt API as closely as possible
+- It uses platform-specific styles (for handle, groove, & ticks) but also supports
+  QSS style sheets.
+- Supports mouse wheel events
+- Supports more than 2 handles (e.g. `slider.setValue([0, 10, 60, 80])`)
+
+As `QRangeSlider` inherits from
+[`QtWidgets.QSlider`](https://doc.qt.io/qt-5/qslider.html), you can use all of
+the same methods available in the [QSlider
+API](https://doc.qt.io/qt-5/qslider.html). The major difference is that `value()`
+and `sliderPosition()` are reimplemented as `tuples` of `int` (where the length of
+the tuple is equal to the number of handles in the slider.)
+
+These options are in addition to the Qt QSlider API, and control the behavior of the bar between handles.
+
+| getter               | setter                                      | type   | default | description                                                                                      |
+| -------------------- | ------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------ |
+| `barIsVisible`       | `setBarIsVisible` <br>`hideBar` / `showBar` | `bool` | `True`  | <small>Whether the bar between handles is visible.</small>                                       |
+| `barMovesAllHandles` | `setBarMovesAllHandles`                     | `bool` | `True`  | <small>Whether clicking on the bar moves all handles or just the nearest</small>                 |
+| `barIsRigid`         | `setBarIsRigid`                             | `bool` | `True`  | <small>Whether bar length is constant or "elastic" when dragging the bar beyond min/max.</small> |
+
+###  Screenshots
+
+??? title "code that generates the images below"
+
+    ```python
+    import os
+
+    from qtpy import QtCore
+    from qtpy import QtWidgets as QtW
+
+    # patch for Qt 5.15 on macos >= 12
+    os.environ["USE_MAC_SLIDER_PATCH"] = "1"
+
+    from superqt import QRangeSlider  # noqa
+
+    QSS = """
+    QSlider {
+        min-height: 20px;
+    }
+
+    QSlider::groove:horizontal {
+        border: 0px;
+        background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #888, stop:1 #ddd);
+        height: 20px;
+        border-radius: 10px;
+    }
+
+    QSlider::handle {
+        background: qradialgradient(cx:0, cy:0, radius: 1.2, fx:0.35,
+                                    fy:0.3, stop:0 #eef, stop:1 #002);
+        height: 20px;
+        width: 20px;
+        border-radius: 10px;
+    }
+
+    QSlider::sub-page:horizontal {
+        background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #227, stop:1 #77a);
+        border-top-left-radius: 10px;
+        border-bottom-left-radius: 10px;
+    }
+
+    QRangeSlider {
+        qproperty-barColor: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #227, stop:1 #77a);
+    }
+    """
+
+    Horizontal = QtCore.Qt.Orientation.Horizontal
+
+
+    class DemoWidget(QtW.QWidget):
+        def __init__(self) -> None:
+            super().__init__()
+
+            reg_hslider = QtW.QSlider(Horizontal)
+            reg_hslider.setValue(50)
+            range_hslider = QRangeSlider(Horizontal)
+            range_hslider.setValue((20, 80))
+            multi_range_hslider = QRangeSlider(Horizontal)
+            multi_range_hslider.setValue((11, 33, 66, 88))
+            multi_range_hslider.setTickPosition(QtW.QSlider.TickPosition.TicksAbove)
+
+            styled_reg_hslider = QtW.QSlider(Horizontal)
+            styled_reg_hslider.setValue(50)
+            styled_reg_hslider.setStyleSheet(QSS)
+            styled_range_hslider = QRangeSlider(Horizontal)
+            styled_range_hslider.setValue((20, 80))
+            styled_range_hslider.setStyleSheet(QSS)
+
+            reg_vslider = QtW.QSlider(QtCore.Qt.Orientation.Vertical)
+            reg_vslider.setValue(50)
+            range_vslider = QRangeSlider(QtCore.Qt.Orientation.Vertical)
+            range_vslider.setValue((22, 77))
+
+            tick_vslider = QtW.QSlider(QtCore.Qt.Orientation.Vertical)
+            tick_vslider.setValue(55)
+            tick_vslider.setTickPosition(QtW.QSlider.TicksRight)
+            range_tick_vslider = QRangeSlider(QtCore.Qt.Orientation.Vertical)
+            range_tick_vslider.setValue((22, 77))
+            range_tick_vslider.setTickPosition(QtW.QSlider.TicksLeft)
+
+            szp = QtW.QSizePolicy.Maximum
+            left = QtW.QWidget()
+            left.setLayout(QtW.QVBoxLayout())
+            left.setContentsMargins(2, 2, 2, 2)
+            label1 = QtW.QLabel("Regular QSlider Unstyled")
+            label2 = QtW.QLabel("QRangeSliders Unstyled")
+            label3 = QtW.QLabel("Styled Sliders (using same stylesheet)")
+            label1.setSizePolicy(szp, szp)
+            label2.setSizePolicy(szp, szp)
+            label3.setSizePolicy(szp, szp)
+            left.layout().addWidget(label1)
+            left.layout().addWidget(reg_hslider)
+            left.layout().addWidget(label2)
+            left.layout().addWidget(range_hslider)
+            left.layout().addWidget(multi_range_hslider)
+            left.layout().addWidget(label3)
+            left.layout().addWidget(styled_reg_hslider)
+            left.layout().addWidget(styled_range_hslider)
+
+            right = QtW.QWidget()
+            right.setLayout(QtW.QHBoxLayout())
+            right.setContentsMargins(15, 5, 5, 0)
+            right.layout().setSpacing(30)
+            right.layout().addWidget(reg_vslider)
+            right.layout().addWidget(range_vslider)
+            right.layout().addWidget(tick_vslider)
+            right.layout().addWidget(range_tick_vslider)
+
+            self.setLayout(QtW.QHBoxLayout())
+            self.layout().addWidget(left)
+            self.layout().addWidget(right)
+            self.setGeometry(600, 300, 580, 300)
+            self.activateWindow()
+            self.show()
+
+
+    if __name__ == "__main__":
+
+        import sys
+        from pathlib import Path
+
+        dest = Path("screenshots")
+        dest.mkdir(exist_ok=True)
+
+        app = QtW.QApplication([])
+        demo = DemoWidget()
+
+        if "-snap" in sys.argv:
+            import platform
+
+            QtW.QApplication.processEvents()
+            demo.grab().save(str(dest / f"demo_{platform.system().lower()}.png"))
+        else:
+            app.exec_()
+    ```
+
+#### macOS
+
+##### Catalina
+
+![mac10](../images/demo_darwin10.png){ width=580; }
+
+##### Big Sur
+
+![mac11](../images/demo_darwin11.png){ width=580; }
+
+#### Windows
+
+![window](../images/demo_windows.png)
+
+#### Linux
+
+![linux](../images/demo_linux.png)
+
+
+{{ show_members('superqt.sliders._sliders._GenericRangeSlider') }}
+
+## Type changes
+
+Note the following changes in types compared to the `QSlider` API:
+
+```python
+value() -> Tuple[int, ...]
+```
+
+```python
+setValue(val: Sequence[int]) -> None
+```
+
+```python
+# Signal
+valueChanged(Tuple[int, ...])
+```
+
+```python
+sliderPosition() -> Tuple[int, ...]
+```
+
+```python
+setSliderPosition(val: Sequence[int]) -> None
+```
+
+```python
+sliderMoved(Tuple[int, ...])
+```

docs/widgets/qsearchablecombobox.md

@@ -0,0 +1,25 @@
+# QSearchableComboBox
+
+`QSearchableComboBox` is a variant of
+[`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that allow to filter list
+of options by enter part of text. It could be drop in replacement for
+`QComboBox`.
+
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QSearchableComboBox
+
+app = QApplication([])
+
+combo = QSearchableComboBox()
+combo.addItems(["foo", "bar", "baz", "foobar", "foobaz", "barbaz"])
+combo.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QSearchableComboBox') }}

docs/widgets/qsearchablelistwidget.md

@@ -0,0 +1,28 @@
+# QSearchableListWidget
+
+`QSearchableListWidget` is a variant of
+[`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) that add text entry
+above list widget that allow to filter list of available options.
+
+Due to implementation details, this widget it does not inherit directly from
+[`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) but it does fully
+satisfy its api. The only limitation is that it cannot be used as argument of
+[`QListWidgetItem`](https://doc.qt.io/qt-5/qlistwidgetitem.html) constructor.
+
+```python
+from qtpy.QtWidgets import QApplication
+
+from superqt import QSearchableListWidget
+
+app = QApplication([])
+
+slider = QSearchableListWidget()
+slider.addItems(["foo", "bar", "baz", "foobar", "foobaz", "barbaz"])
+slider.show()
+
+app.exec_()
+```
+
+{{ show_widget() }}
+
+{{ show_members('superqt.QSearchableListWidget') }}

examples/demo_widget.py

@@ -110,7 +110,6 @@ class DemoWidget(QtW.QWidget):
 
 
 if __name__ == "__main__":
-
     import sys
     from pathlib import Path
 

examples/double_slider.py

@@ -8,6 +8,7 @@ app = QApplication([])
 slider = QDoubleSlider(Qt.Orientation.Horizontal)
 slider.setRange(0, 1)
 slider.setValue(0.5)
+slider.resize(500, 50)
 slider.show()
 
 app.exec_()

examples/icon_explorer.py

@@ -219,7 +219,7 @@ class MainWindow(QtWidgets.QMainWindow):
         self.previewGroupBox.setLayout(layout)
 
     def createGlyphBox(self):
-        self.glyphGroupBox = QtWidgets.QGroupBox("Glpyhs")
+        self.glyphGroupBox = QtWidgets.QGroupBox("Glyphs")
         self.glyphGroupBox.setMinimumSize(480, 200)
         self.glyphTable = QtWidgets.QTableWidget()
         self.glyphTable.setSelectionMode(QtWidgets.QAbstractItemView.NoSelection)
@@ -369,7 +369,6 @@ class MainWindow(QtWidgets.QMainWindow):
 
 
 if __name__ == "__main__":
-
     import sys
 
     app = QtWidgets.QApplication(sys.argv)

examples/qcollapsible.py

@@ -1,4 +1,4 @@
-"""Example for QCollapsible"""
+"""Example for QCollapsible."""
 from qtpy.QtWidgets import QApplication, QLabel, QPushButton
 
 from superqt import QCollapsible
@@ -6,6 +6,8 @@ from superqt import QCollapsible
 app = QApplication([])
 
 collapsible = QCollapsible("Advanced analysis")
+collapsible.setCollapsedIcon("+")
+collapsible.setExpandedIcon("-")
 collapsible.addWidget(QLabel("This is the inside of the collapsible frame"))
 for i in range(10):
     collapsible.addWidget(QPushButton(f"Content button {i + 1}"))

examples/quantity.py

@@ -0,0 +1,9 @@
+from qtpy.QtWidgets import QApplication
+
+from superqt import QQuantity
+
+app = QApplication([])
+w = QQuantity("1m")
+w.show()
+
+app.exec()

examples/searchable_tree_widget.py

@@ -0,0 +1,29 @@
+import logging
+
+from qtpy.QtWidgets import QApplication
+
+from superqt import QSearchableTreeWidget
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s : %(levelname)s : %(filename)s : %(message)s",
+)
+
+data = {
+    "none": None,
+    "str": "test",
+    "int": 42,
+    "list": [2, 3, 5],
+    "dict": {
+        "float": 0.5,
+        "tuple": (22, 99),
+        "bool": False,
+    },
+}
+
+app = QApplication([])
+
+tree = QSearchableTreeWidget.fromData(data)
+tree.show()
+
+app.exec_()

examples/throttler_demo.py

@@ -1,4 +1,4 @@
-"""Adapted for python from the KDToolBox
+"""Adapted for python from the KDToolBox.
 
 https://github.com/KDAB/KDToolBox/tree/master/qt/KDSignalThrottler
 
@@ -85,12 +85,10 @@ class DrawSignalsWidget(QWidget):
         self.update()
 
     def scrollAndCut(self, v: Deque[int], cutoff: int):
-        x = 0
         L = len(v)
         for p in range(L):
             v[p] += 1
             if v[p] > cutoff:
-                x = p
                 break
 
         # TODO: fix this... delete old ones

mkdocs.yml

@@ -0,0 +1,59 @@
+site_name: superqt
+site_url: https://github.com/pyapp-kit/superqt
+site_description: >-
+  missing widgets and components for PyQt/PySide
+# Repository
+repo_name: pyapp-kit/superqt
+repo_url: https://github.com/pyapp-kit/superqt
+
+# Copyright
+copyright: Copyright © 2021 - 2022 Talley Lambert
+
+extra_css:
+  - stylesheets/extra.css
+
+watch:
+  - src
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.indexes
+    - navigation.expand
+    # - navigation.tracking
+    # - navigation.tabs
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - tables
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - toc:
+      permalink: "#"
+
+
+plugins:
+  - search
+  - autorefs
+  - mkdocstrings
+  - macros:
+      module_name: docs/_macros
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+          options:
+              show_source: false
+              docstring_style: numpy
+              show_root_toc_entry: True
+              show_root_heading: True

pyproject.toml

@@ -1,10 +1,183 @@
-# pyproject.toml
+# https://peps.python.org/pep-0517/
 [build-system]
-requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
 
-[tool.setuptools_scm]
-write_to = "src/superqt/_version.py"
+# https://peps.python.org/pep-0621/
+[project]
+name = "superqt"
+description = "Missing widgets and components for PyQt/PySide"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "BSD 3-Clause License" }
+authors = [{ email = "talley.lambert@gmail.com", name = "Talley Lambert" }]
+keywords = [
+    "qt",
+    "pyqt",
+    "pyside",
+    "widgets",
+    "range slider",
+    "components",
+    "gui",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Desktop Environment",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Software Development :: Widget Sets",
+]
+dynamic = ["version"]
+dependencies = [
+    "packaging",
+    "pygments>=2.4.0",
+    "qtpy>=1.1.0",
+    "typing-extensions >=3.7.4.3,!=3.10.0.0",
+]
 
+# extras
+# https://peps.python.org/pep-0621/#dependencies-optional-dependencies
+[project.optional-dependencies]
+test = ["pint", "pytest", "pytest-cov", "pytest-qt"]
+dev = [
+    "black",
+    "ipython",
+    "ruff",
+    "mypy",
+    "pdbpp",
+    "pre-commit",
+    "pydocstyle",
+    "rich",
+    "types-Pygments",
+]
+docs = ["mkdocs-macros-plugin", "mkdocs-material", "mkdocstrings[python]"]
+quantity = ["pint"]
+pyside2 = ["pyside2"]
+# see issues surrounding usage of Generics in pyside6.5.x
+# https://github.com/pyapp-kit/superqt/pull/177
+# https://github.com/pyapp-kit/superqt/pull/164
+pyside6 = ["pyside6 !=6.5.0,!=6.5.1"]
+pyqt5 = ["pyqt5"]
+pyqt6 = ["pyqt6"]
+font-fa5 = ["fonticon-fontawesome5"]
+font-fa6 = ["fonticon-fontawesome6"]
+font-mi6 = ["fonticon-materialdesignicons6"]
+font-mi7 = ["fonticon-materialdesignicons7"]
+
+[project.urls]
+Source = "https://github.com/pyapp-kit/superqt"
+Tracker = "https://github.com/pyapp-kit/superqt/issues"
+Changelog = "https://github.com/pyapp-kit/superqt/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md"]
+
+# https://pycqa.github.io/isort/docs/configuration/options.html
+[tool.isort]
+profile = "black"
+src_paths = ["src/superqt", "tests"]
+
+# https://github.com/charliermarsh/ruff
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+src = ["src", "tests"]
+select = [
+    "E",    # style errors
+    "F",    # flakes
+    "W",    # flakes
+    "D",    # pydocstyle
+    "I",    # isort
+    "UP",   # pyupgrade
+    "S",    # bandit
+    "C4",   # flake8-comprehensions
+    "B",    # flake8-bugbear
+    "A001", # flake8-builtins
+    "RUF",  # ruff-specific rules
+    "TID",  # tidy imports
+]
+ignore = [
+    "D100", # Missing docstring in public module
+    "D101", # Missing docstring in public class
+    "D104", # Missing docstring in public package
+    "D107", # Missing docstring in __init__
+    "D203", # 1 blank line required before class docstring
+    "D212", # Multi-line docstring summary should start at the first line
+    "D213", # Multi-line docstring summary should start at the second line
+    "D401", # First line should be in imperative mood
+    "D413", # Missing blank line after last section
+    "D416", # Section name should end with a colon
+]
+
+
+[tool.ruff.per-file-ignores]
+"tests/*.py" = ["D", "S101"]
+"examples/demo_widget.py" = ["E501"]
+"examples/*.py" = ["B", "D"]
+
+# https://docs.pytest.org/en/6.2.x/customize.html
+[tool.pytest.ini_options]
+minversion = "6.0"
+testpaths = ["tests"]
+filterwarnings = [
+    "error",
+    "ignore:QPixmapCache.find:DeprecationWarning:",
+    "ignore:SelectableGroups dict interface:DeprecationWarning",
+    "ignore:The distutils package is deprecated:DeprecationWarning",
+]
+
+# https://mypy.readthedocs.io/en/stable/config_file.html
+[tool.mypy]
+files = "src/**/*.py"
+strict = true
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+disallow_any_generics = false
+disallow_subclassing_any = false
+show_error_codes = true
+pretty = true
+exclude = ['tests/**/*']
+
+
+[[tool.mypy.overrides]]
+module = ["superqt.qtcompat.*"]
+ignore_missing_imports = true
+warn_unused_ignores = false
+allow_redefinition = true
+
+# https://coverage.readthedocs.io/en/6.4/config.html
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "@overload",
+    "except ImportError",
+]
+
+# https://github.com/mgedmin/check-manifest#configuration
 [tool.check-manifest]
-ignore = ["src/superqt/_version.py"]
+ignore = [
+    ".github_changelog_generator",
+    ".pre-commit-config.yaml",
+    "tests/**/*",
+    "src/superqt/_version.py",
+    "mkdocs.yml",
+    "docs/**/*",
+    "examples/**/*",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "codecov.yml",
+    ".ruff_cache/**/*",
+]

setup.cfg

@@ -1,115 +0,0 @@
-[metadata]
-name = superqt
-description = Missing widgets for PyQt/PySide
-long_description = file: README.md
-long_description_content_type = text/markdown
-url = https://github.com/napari/superqt
-author = Talley Lambert
-author_email = talley.lambert@gmail.com
-license = BSD-3-Clause
-license_file = LICENSE
-classifiers =
-    Development Status :: 4 - Beta
-    Environment :: X11 Applications :: Qt
-    Intended Audience :: Developers
-    License :: OSI Approved :: BSD License
-    Operating System :: OS Independent
-    Programming Language :: Python
-    Programming Language :: Python :: 3
-    Programming Language :: Python :: 3 :: Only
-    Programming Language :: Python :: 3.7
-    Programming Language :: Python :: 3.8
-    Programming Language :: Python :: 3.9
-    Programming Language :: Python :: 3.10
-    Programming Language :: Python :: Implementation :: CPython
-    Topic :: Desktop Environment
-    Topic :: Software Development
-    Topic :: Software Development :: User Interfaces
-    Topic :: Software Development :: Widget Sets
-keywords = qt, range slider, widget
-project_urls =
-    Source = https://github.com/napari/superqt
-    Tracker = https://github.com/napari/superqt/issues
-    Changelog = https://github.com/napari/superqt/blob/master/CHANGELOG.md
-
-[options]
-packages = find:
-install_requires =
-    packaging
-    pygments>=2.4.0
-    qtpy>=1.1.0
-    typing-extensions
-python_requires = >=3.7
-include_package_data = True
-package_dir =
-    =src
-setup_requires =
-    setuptools-scm
-zip_safe = False
-
-[options.packages.find]
-where = src
-
-[options.extras_require]
-dev =
-    ipython
-    isort
-    jedi<0.18.0
-    mypy
-    pre-commit
-    pyside2
-    pytest
-    pytest-cov
-    pytest-qt
-    tox
-    tox-conda
-font_fa5 =
-    fonticon-fontawesome5
-font_mi5 =
-    fonticon-materialdesignicons5
-pyqt5 =
-    pyqt5
-pyqt6 =
-    pyqt6
-pyside2 =
-    pyside2
-pyside6 =
-    pyside6
-testing =
-    pytest
-    pytest-cov
-    pytest-qt
-    tox
-    tox-conda
-
-[options.package_data]
-superqt = py.typed
-
-[flake8]
-exclude = _version.py,.eggs,examples
-docstring-convention = numpy
-ignore = E203,W503,E501,C901,F403,F405,D100
-
-[pydocstyle]
-convention = numpy
-add_select = D402,D415,D417
-ignore = D100
-
-[isort]
-profile = black
-
-[tool:pytest]
-filterwarnings =
-    error
-    ignore:QPixmapCache.find:DeprecationWarning:
-    ignore:SelectableGroups dict interface:DeprecationWarning
-    ignore:The distutils package is deprecated:DeprecationWarning
-
-[mypy]
-strict = True
-files = src/superqt
-
-[mypy-superqt.qtcompat.*]
-ignore_missing_imports = True
-warn_unused_ignores = False
-allow_redefinition = True

src/superqt/__init__.py

@@ -1,14 +1,19 @@
-"""superqt is a collection of QtWidgets for python."""
+"""superqt is a collection of Qt components for python."""
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
 try:
-    from ._version import version as __version__
-except ImportError:
+    __version__ = version("superqt")
+except PackageNotFoundError:
     __version__ = "unknown"
 
+if TYPE_CHECKING:
+    from .spinbox._quantity import QQuantity
 
-from ._eliding_label import QElidingLabel
 from .collapsible import QCollapsible
 from .combobox import QEnumComboBox, QSearchableComboBox
-from .selection import QSearchableListWidget
+from .elidable import QElidingLabel, QElidingLineEdit
+from .selection import QSearchableListWidget, QSearchableTreeWidget
 from .sliders import (
     QDoubleRangeSlider,
     QDoubleSlider,
@@ -25,8 +30,10 @@ __all__ = [
     "ensure_main_thread",
     "ensure_object_thread",
     "QDoubleRangeSlider",
+    "QCollapsible",
     "QDoubleSlider",
     "QElidingLabel",
+    "QElidingLineEdit",
     "QEnumComboBox",
     "QLabeledDoubleRangeSlider",
     "QLabeledDoubleSlider",
@@ -34,8 +41,17 @@ __all__ = [
     "QLabeledSlider",
     "QLargeIntSpinBox",
     "QMessageHandler",
+    "QQuantity",
+    "QRangeSlider",
     "QSearchableComboBox",
     "QSearchableListWidget",
-    "QRangeSlider",
-    "QCollapsible",
+    "QSearchableTreeWidget",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "QQuantity":
+        from .spinbox._quantity import QQuantity
+
+        return QQuantity
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/superqt/_eliding_label.py

@@ -1,110 +0,0 @@
-from typing import List
-
-from qtpy.QtCore import QPoint, QRect, QSize, Qt
-from qtpy.QtGui import QFont, QFontMetrics, QResizeEvent, QTextLayout
-from qtpy.QtWidgets import QLabel
-
-
-class QElidingLabel(QLabel):
-    """A QLabel variant that will elide text (add '…') to fit width.
-
-    QElidingLabel()
-    QElidingLabel(parent: Optional[QWidget], f: Qt.WindowFlags = ...)
-    QElidingLabel(text: str, parent: Optional[QWidget] = None, f: Qt.WindowFlags = ...)
-
-    For a multiline eliding label, use `setWordWrap(True)`.  In this case, text
-    will wrap to fit the width, and only the last line will be elided.
-    When `wordWrap()` is True, `sizeHint()` will return the size required to fit
-    the full text.
-    """
-
-    def __init__(self, *args, **kwargs) -> None:
-        self._elide_mode = Qt.TextElideMode.ElideRight
-        super().__init__(*args, **kwargs)
-        self.setText(args[0] if args and isinstance(args[0], str) else "")
-
-    # New Public methods
-
-    def elideMode(self) -> Qt.TextElideMode:
-        """The current Qt.TextElideMode."""
-        return self._elide_mode
-
-    def setElideMode(self, mode: Qt.TextElideMode):
-        """Set the elide mode to a Qt.TextElideMode."""
-        self._elide_mode = Qt.TextElideMode(mode)
-        super().setText(self._elidedText())
-
-    @staticmethod
-    def wrapText(text, width, font=None) -> List[str]:
-        """Returns `text`, split as it would be wrapped for `width`, given `font`.
-
-        Static method.
-        """
-        tl = QTextLayout(text, font or QFont())
-        tl.beginLayout()
-        lines = []
-        while True:
-            ln = tl.createLine()
-            if not ln.isValid():
-                break
-            ln.setLineWidth(width)
-            start = ln.textStart()
-            lines.append(text[start : start + ln.textLength()])
-        tl.endLayout()
-        return lines
-
-    # Reimplemented QT methods
-
-    def text(self) -> str:
-        """This property holds the label's text.
-
-        If no text has been set this will return an empty string.
-        """
-        return self._text
-
-    def setText(self, txt: str):
-        """Set the label's text.
-
-        Setting the text clears any previous content.
-        NOTE: we set the QLabel private text to the elided version
-        """
-        self._text = txt
-        super().setText(self._elidedText())
-
-    def resizeEvent(self, ev: QResizeEvent) -> None:
-        ev.accept()
-        super().setText(self._elidedText())
-
-    def setWordWrap(self, wrap: bool) -> None:
-        super().setWordWrap(wrap)
-        super().setText(self._elidedText())
-
-    def sizeHint(self) -> QSize:
-        if not self.wordWrap():
-            return super().sizeHint()
-        fm = QFontMetrics(self.font())
-        flags = int(self.alignment() | Qt.TextFlag.TextWordWrap)
-        r = fm.boundingRect(QRect(QPoint(0, 0), self.size()), flags, self._text)
-        return QSize(self.width(), r.height())
-
-    # private implementation methods
-
-    def _elidedText(self) -> str:
-        """Return `self._text` elided to `width`"""
-        fm = QFontMetrics(self.font())
-        # the 2 is a magic number that prevents the ellipses from going missing
-        # in certain cases (?)
-        width = self.width() - 2
-        if not self.wordWrap():
-            return fm.elidedText(self._text, self._elide_mode, width)
-
-        # get number of lines we can fit without eliding
-        nlines = self.height() // fm.height() - 1
-        # get the last line (elided)
-        text = self._wrappedText()
-        last_line = fm.elidedText("".join(text[nlines:]), self._elide_mode, width)
-        # join them
-        return "".join(text[:nlines] + [last_line])
-
-    def _wrappedText(self) -> List[str]:
-        return QElidingLabel.wrapText(self._text, self.width(), self.font())

src/superqt/collapsible/_collapsible.py

@@ -1,26 +1,46 @@
-"""A collapsible widget to hide and unhide child widgets"""
-from typing import Optional
+"""A collapsible widget to hide and unhide child widgets."""
+from typing import Optional, Union
 
-from qtpy.QtCore import QEasingCurve, QEvent, QMargins, QObject, QPropertyAnimation, Qt
+from qtpy.QtCore import (
+    QEasingCurve,
+    QEvent,
+    QMargins,
+    QObject,
+    QPropertyAnimation,
+    QRect,
+    Qt,
+    Signal,
+)
+from qtpy.QtGui import QIcon, QPainter, QPalette, QPixmap
 from qtpy.QtWidgets import QFrame, QPushButton, QVBoxLayout, QWidget
 
 
 class QCollapsible(QFrame):
     """A collapsible widget to hide and unhide child widgets.
 
+    A signal is emitted when the widget is expanded (True) or collapsed (False).
+
     Based on https://stackoverflow.com/a/68141638
     """
 
-    _EXPANDED = "▼  "
-    _COLLAPSED = "▲  "
+    toggled = Signal(bool)
 
-    def __init__(self, title: str = "", parent: Optional[QWidget] = None):
+    def __init__(
+        self,
+        title: str = "",
+        parent: Optional[QWidget] = None,
+        expandedIcon: Optional[Union[QIcon, str]] = "▼",
+        collapsedIcon: Optional[Union[QIcon, str]] = "▲",
+    ):
         super().__init__(parent)
         self._locked = False
         self._is_animating = False
+        self._text = title
 
-        self._toggle_btn = QPushButton(self._COLLAPSED + title)
+        self._toggle_btn = QPushButton(title)
         self._toggle_btn.setCheckable(True)
+        self.setCollapsedIcon(icon=collapsedIcon)
+        self.setExpandedIcon(icon=expandedIcon)
         self._toggle_btn.setStyleSheet("text-align: left; border: none; outline: none;")
         self._toggle_btn.toggled.connect(self._toggle)
 
@@ -44,16 +64,16 @@ class QCollapsible(QFrame):
         _content.layout().setContentsMargins(QMargins(5, 0, 0, 0))
         self.setContent(_content)
 
-    def setText(self, text: str):
+    def setText(self, text: str) -> None:
         """Set the text of the toggle button."""
-        current = self._toggle_btn.text()[: len(self._EXPANDED)]
+        current = self._toggle_btn.text()
         self._toggle_btn.setText(current + text)
 
     def text(self) -> str:
         """Return the text of the toggle button."""
-        return self._toggle_btn.text()[len(self._EXPANDED) :]
+        return self._toggle_btn.text()
 
-    def setContent(self, content: QWidget):
+    def setContent(self, content: QWidget) -> None:
         """Replace central widget (the widget that gets expanded/collapsed)."""
         self._content = content
         self.layout().addWidget(self._content)
@@ -63,56 +83,104 @@ class QCollapsible(QFrame):
         """Return the current content widget."""
         return self._content
 
-    def setDuration(self, msecs: int):
+    def _convert_string_to_icon(self, symbol: str) -> QIcon:
+        """Create a QIcon from a string."""
+        size = self._toggle_btn.font().pointSize()
+        pixmap = QPixmap(size, size)
+        pixmap.fill(Qt.GlobalColor.transparent)
+        painter = QPainter(pixmap)
+        color = self._toggle_btn.palette().color(QPalette.ColorRole.WindowText)
+        painter.setPen(color)
+        painter.drawText(QRect(0, 0, size, size), Qt.AlignmentFlag.AlignCenter, symbol)
+        painter.end()
+        return QIcon(pixmap)
+
+    def expandedIcon(self) -> QIcon:
+        """Returns the icon used when the widget is expanded."""
+        return self._expanded_icon
+
+    def setExpandedIcon(self, icon: Optional[Union[QIcon, str]] = None) -> None:
+        """Set the icon on the toggle button when the widget is expanded."""
+        if icon and isinstance(icon, QIcon):
+            self._expanded_icon = icon
+        elif icon and isinstance(icon, str):
+            self._expanded_icon = self._convert_string_to_icon(icon)
+
+        if self.isExpanded():
+            self._toggle_btn.setIcon(self._expanded_icon)
+
+    def collapsedIcon(self) -> QIcon:
+        """Returns the icon used when the widget is collapsed."""
+        return self._collapsed_icon
+
+    def setCollapsedIcon(self, icon: Optional[Union[QIcon, str]] = None) -> None:
+        """Set the icon on the toggle button when the widget is collapsed."""
+        if icon and isinstance(icon, QIcon):
+            self._collapsed_icon = icon
+        elif icon and isinstance(icon, str):
+            self._collapsed_icon = self._convert_string_to_icon(icon)
+
+        if not self.isExpanded():
+            self._toggle_btn.setIcon(self._collapsed_icon)
+
+    def setDuration(self, msecs: int) -> None:
         """Set duration of the collapse/expand animation."""
         self._animation.setDuration(msecs)
 
-    def setEasingCurve(self, easing: QEasingCurve):
-        """Set the easing curve for the collapse/expand animation"""
+    def setEasingCurve(self, easing: QEasingCurve) -> None:
+        """Set the easing curve for the collapse/expand animation."""
         self._animation.setEasingCurve(easing)
 
-    def addWidget(self, widget: QWidget):
+    def addWidget(self, widget: QWidget) -> None:
         """Add a widget to the central content widget's layout."""
         widget.installEventFilter(self)
         self._content.layout().addWidget(widget)
 
-    def removeWidget(self, widget: QWidget):
+    def removeWidget(self, widget: QWidget) -> None:
         """Remove widget from the central content widget's layout."""
         self._content.layout().removeWidget(widget)
         widget.removeEventFilter(self)
 
-    def expand(self, animate: bool = True):
-        """Expand (show) the collapsible section"""
+    def expand(self, animate: bool = True) -> None:
+        """Expand (show) the collapsible section."""
         self._expand_collapse(QPropertyAnimation.Direction.Forward, animate)
 
-    def collapse(self, animate: bool = True):
-        """Collapse (hide) the collapsible section"""
+    def collapse(self, animate: bool = True) -> None:
+        """Collapse (hide) the collapsible section."""
         self._expand_collapse(QPropertyAnimation.Direction.Backward, animate)
 
     def isExpanded(self) -> bool:
-        """Return whether the collapsible section is visible"""
+        """Return whether the collapsible section is visible."""
         return self._toggle_btn.isChecked()
 
-    def setLocked(self, locked: bool = True):
-        """Set whether collapse/expand is disabled"""
+    def setLocked(self, locked: bool = True) -> None:
+        """Set whether collapse/expand is disabled."""
         self._locked = locked
         self._toggle_btn.setCheckable(not locked)
 
     def locked(self) -> bool:
-        """Return True if collapse/expand is disabled"""
+        """Return True if collapse/expand is disabled."""
         return self._locked
 
     def _expand_collapse(
-        self, direction: QPropertyAnimation.Direction, animate: bool = True
-    ):
+        self,
+        direction: QPropertyAnimation.Direction,
+        animate: bool = True,
+        emit: bool = True,
+    ) -> None:
+        """Set values for the widget based on whether it is expanding or collapsing.
+
+        An emit flag is included so that the toggle signal is only called once (it
+        was being emitted a few times via eventFilter when the widget was expanding
+        previously).
+        """
         if self._locked:
             return
 
         forward = direction == QPropertyAnimation.Direction.Forward
-        text = self._EXPANDED if forward else self._COLLAPSED
-
+        icon = self._expanded_icon if forward else self._collapsed_icon
+        self._toggle_btn.setIcon(icon)
         self._toggle_btn.setChecked(forward)
-        self._toggle_btn.setText(text + self._toggle_btn.text()[len(self._EXPANDED) :])
 
         _content_height = self._content.sizeHint().height() + 10
         if animate:
@@ -122,8 +190,10 @@ class QCollapsible(QFrame):
             self._animation.start()
         else:
             self._content.setMaximumHeight(_content_height if forward else 0)
+        if emit:
+            self.toggled.emit(direction == QPropertyAnimation.Direction.Forward)
 
-    def _toggle(self):
+    def _toggle(self) -> None:
         self.expand() if self.isExpanded() else self.collapse()
 
     def eventFilter(self, a0: QObject, a1: QEvent) -> bool:
@@ -133,8 +203,10 @@ class QCollapsible(QFrame):
             and self.isExpanded()
             and not self._is_animating
         ):
-            self._expand_collapse(QPropertyAnimation.Direction.Forward, animate=False)
+            self._expand_collapse(
+                QPropertyAnimation.Direction.Forward, animate=False, emit=False
+            )
         return False
 
-    def _on_animation_done(self):
+    def _on_animation_done(self) -> None:
         self._is_animating = False

src/superqt/combobox/_enum_combobox.py

@@ -11,7 +11,7 @@ NONE_STRING = "----"
 
 
 def _get_name(enum_value: Enum):
-    """Create human readable name if user does not provide own implementation of __str__"""
+    """Create human readable name if user does not implement `__str__`."""
     if (
         enum_value.__str__.__module__ != "enum"
         and not enum_value.__str__.__module__.startswith("shibokensupport")
@@ -24,8 +24,7 @@ def _get_name(enum_value: Enum):
 
 
 class QEnumComboBox(QComboBox):
-    """
-    ComboBox presenting options from a python Enum.
+    """ComboBox presenting options from a python Enum.
 
     If the Enum class does not implement `__str__` then a human readable name
     is created from the name of the enum member, replacing underscores with spaces.
@@ -44,22 +43,22 @@ class QEnumComboBox(QComboBox):
         self.currentIndexChanged.connect(self._emit_signal)
 
     def setEnumClass(self, enum: Optional[EnumMeta], allow_none=False):
-        """
-        Set enum class from which members value should be selected
-        """
+        """Set enum class from which members value should be selected."""
         self.clear()
         self._enum_class = enum
         self._allow_none = allow_none and enum is not None
         if allow_none:
             super().addItem(NONE_STRING)
-        super().addItems(list(map(_get_name, self._enum_class.__members__.values())))
+        names = map(_get_name, self._enum_class.__members__.values())
+        _names = dict.fromkeys(names)  # remove duplicates/aliases, keep order
+        super().addItems(list(_names))
 
     def enumClass(self) -> Optional[EnumMeta]:
-        """return current Enum class"""
+        """Return current Enum class."""
         return self._enum_class
 
     def isOptional(self) -> bool:
-        """return if current enum is with optional annotation"""
+        """Return if current enum is with optional annotation."""
         return self._allow_none
 
     def clear(self):
@@ -68,7 +67,7 @@ class QEnumComboBox(QComboBox):
         super().clear()
 
     def currentEnum(self) -> Optional[EnumType]:
-        """current value as Enum member"""
+        """Current value as Enum member."""
         if self._enum_class is not None:
             if self._allow_none:
                 if self.currentText() == NONE_STRING:
@@ -91,7 +90,8 @@ class QEnumComboBox(QComboBox):
             return
         if not isinstance(value, self._enum_class):
             raise TypeError(
-                f"setValue(self, Enum): argument 1 has unexpected type {type(value).__name__!r}"
+                "setValue(self, Enum): argument 1 has unexpected type "
+                f"{type(value).__name__!r}"
             )
         self.setCurrentText(_get_name(value))
 

src/superqt/combobox/_searchable_combo_box.py

@@ -1,6 +1,8 @@
+from typing import Optional
+
 from qtpy import QT_VERSION
 from qtpy.QtCore import Qt, Signal
-from qtpy.QtWidgets import QComboBox, QCompleter
+from qtpy.QtWidgets import QComboBox, QCompleter, QWidget
 
 try:
     is_qt_bellow_5_14 = tuple(int(x) for x in QT_VERSION.split(".")[:2]) < (5, 14)
@@ -9,14 +11,12 @@ except ValueError:
 
 
 class QSearchableComboBox(QComboBox):
-    """
-    ComboCox with completer for fast search in multiple options
-    """
+    """ComboCox with completer for fast search in multiple options."""
 
     if is_qt_bellow_5_14:
         textActivated = Signal(str)  # pragma: no cover
 
-    def __init__(self, parent=None):
+    def __init__(self, parent: Optional[QWidget] = None):
         super().__init__(parent)
         self.setEditable(True)
         self.completer_object = QCompleter()

src/superqt/elidable/__init__.py

@@ -0,0 +1,4 @@
+from ._eliding_label import QElidingLabel
+from ._eliding_line_edit import QElidingLineEdit
+
+__all__ = ["QElidingLabel", "QElidingLineEdit"]

src/superqt/elidable/_eliding.py

@@ -0,0 +1,78 @@
+from typing import List
+
+from qtpy.QtCore import Qt
+from qtpy.QtGui import QFont, QFontMetrics, QTextLayout
+
+
+class _GenericEliding:
+    """A mixin to provide capabilities to elide text (could add '…') to fit width."""
+
+    _elide_mode: Qt.TextElideMode = Qt.TextElideMode.ElideRight
+    _text: str = ""
+    # the 2 is a magic number that prevents the ellipses from going missing
+    # in certain cases (?)
+    _ellipses_width: int = 2
+
+    # Public methods
+
+    def elideMode(self) -> Qt.TextElideMode:
+        """The current Qt.TextElideMode."""
+        return self._elide_mode
+
+    def setElideMode(self, mode: Qt.TextElideMode) -> None:
+        """Set the elide mode to a Qt.TextElideMode."""
+        self._elide_mode = Qt.TextElideMode(mode)
+
+    def full_text(self) -> str:
+        """The current text without eliding."""
+        return self._text
+
+    def setEllipsesWidth(self, width: int) -> None:
+        """A width value to take into account ellipses width when eliding text.
+
+        The value is deducted from the widget width when computing the elided version
+        of the text.
+        """
+        self._ellipses_width = width
+
+    @staticmethod
+    def wrapText(text, width, font=None) -> List[str]:
+        """Returns `text`, split as it would be wrapped for `width`, given `font`.
+
+        Static method.
+        """
+        tl = QTextLayout(text, font or QFont())
+        tl.beginLayout()
+        lines = []
+        while True:
+            ln = tl.createLine()
+            if not ln.isValid():
+                break
+            ln.setLineWidth(width)
+            start = ln.textStart()
+            lines.append(text[start : start + ln.textLength()])
+        tl.endLayout()
+        return lines
+
+    # private implementation methods
+
+    def _elidedText(self) -> str:
+        """Return `self._text` elided to `width`."""
+        fm = QFontMetrics(self.font())
+        ellipses_width = 0
+        if self._elide_mode != Qt.TextElideMode.ElideNone:
+            ellipses_width = self._ellipses_width
+        width = self.width() - ellipses_width
+        if not getattr(self, "wordWrap", None) or not self.wordWrap():
+            return fm.elidedText(self._text, self._elide_mode, width)
+
+        # get number of lines we can fit without eliding
+        nlines = self.height() // fm.height() - 1
+        # get the last line (elided)
+        text = self._wrappedText()
+        last_line = fm.elidedText("".join(text[nlines:]), self._elide_mode, width)
+        # join them
+        return "".join(text[:nlines] + [last_line])
+
+    def _wrappedText(self) -> List[str]:
+        return _GenericEliding.wrapText(self._text, self.width(), self.font())

src/superqt/elidable/_eliding_label.py

@@ -0,0 +1,75 @@
+from qtpy.QtCore import QPoint, QRect, QSize, Qt
+from qtpy.QtGui import QFontMetrics, QResizeEvent
+from qtpy.QtWidgets import QLabel
+
+from ._eliding import _GenericEliding
+
+
+class QElidingLabel(_GenericEliding, QLabel):
+    """
+    A QLabel variant that will elide text (could add '…') to fit width.
+
+    QElidingLabel()
+    QElidingLabel(parent: Optional[QWidget], f: Qt.WindowFlags = ...)
+    QElidingLabel(text: str, parent: Optional[QWidget] = None, f: Qt.WindowFlags = ...)
+
+    For a multiline eliding label, use `setWordWrap(True)`.  In this case, text
+    will wrap to fit the width, and only the last line will be elided.
+    When `wordWrap()` is True, `sizeHint()` will return the size required to fit
+    the full text.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        if args and isinstance(args[0], str):
+            self.setText(args[0])
+
+    # Reimplemented _GenericEliding methods
+
+    def setElideMode(self, mode: Qt.TextElideMode) -> None:
+        """Set the elide mode to a Qt.TextElideMode."""
+        super().setElideMode(mode)
+        super().setText(self._elidedText())
+
+    def setEllipsesWidth(self, width: int) -> None:
+        """A width value to take into account ellipses width when eliding text.
+
+        The value is deducted from the widget width when computing the elided version
+        of the text.
+        """
+        super().setEllipsesWidth(width)
+        super().setText(self._elidedText())
+
+    # Reimplemented QT methods
+
+    def text(self) -> str:
+        """Return the label's text.
+
+        If no text has been set this will return an empty string.
+        """
+        return self._text
+
+    def setText(self, txt: str) -> None:
+        """Set the label's text.
+
+        Setting the text clears any previous content.
+        NOTE: we set the QLabel private text to the elided version
+        """
+        self._text = txt
+        super().setText(self._elidedText())
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        event.accept()
+        super().setText(self._elidedText())
+
+    def setWordWrap(self, wrap: bool) -> None:
+        super().setWordWrap(wrap)
+        super().setText(self._elidedText())
+
+    def sizeHint(self) -> QSize:
+        if not self.wordWrap():
+            return super().sizeHint()
+        fm = QFontMetrics(self.font())
+        flags = int(self.alignment() | Qt.TextFlag.TextWordWrap)
+        r = fm.boundingRect(QRect(QPoint(0, 0), self.size()), flags, self._text)
+        return QSize(self.width(), r.height())

src/superqt/elidable/_eliding_line_edit.py

@@ -0,0 +1,91 @@
+from qtpy.QtCore import Qt
+from qtpy.QtGui import QFocusEvent, QResizeEvent
+from qtpy.QtWidgets import QLineEdit
+
+from ._eliding import _GenericEliding
+
+
+class QElidingLineEdit(_GenericEliding, QLineEdit):
+    """A QLineEdit variant that will elide text (could add '…') to fit width.
+
+    QElidingLineEdit()
+    QElidingLineEdit(parent: Optional[QWidget])
+    QElidingLineEdit(text: str, parent: Optional[QWidget] = None)
+
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        if args and isinstance(args[0], str):
+            self.setText(args[0])
+        # The `textEdited` signal doesn't trigger the `textChanged` signal if
+        # text is changed with `setText`, so we connect to `textEdited` to only
+        # update _text when text is being edited by the user graphically.
+        self.textEdited.connect(self._update_text)
+
+    # Reimplemented _GenericEliding methods
+
+    def setElideMode(self, mode: Qt.TextElideMode) -> None:
+        """Set the elide mode to a Qt.TextElideMode.
+
+        The text shown is updated to the elided version only if the widget is not
+        focused.
+        """
+        super().setElideMode(mode)
+        if not self.hasFocus():
+            super().setText(self._elidedText())
+
+    def setEllipsesWidth(self, width: int) -> None:
+        """A width value to take into account ellipses width when eliding text.
+
+        The value is deducted from the widget width when computing the elided version
+        of the text. The text shown is updated to the elided version only if the widget
+        is not focused.
+        """
+        super().setEllipsesWidth(width)
+        if not self.hasFocus():
+            super().setText(self._elidedText())
+
+    # Reimplemented QT methods
+
+    def text(self) -> str:
+        """Return the label's text being shown.
+
+        If no text has been set this will return an empty string.
+        """
+        return self._text
+
+    def setText(self, text) -> None:
+        """Set the line edit's text.
+
+        Setting the text clears any previous content.
+        NOTE: we set the QLineEdit private text to the elided version
+        """
+        self._text = text
+        if not self.hasFocus():
+            super().setText(self._elidedText())
+
+    def focusInEvent(self, event: QFocusEvent) -> None:
+        """Set the full text when the widget is focused."""
+        super().setText(self._text)
+        super().focusInEvent(event)
+
+    def focusOutEvent(self, event: QFocusEvent) -> None:
+        """Set an elided version of the text (if needed) when the focus is out."""
+        super().setText(self._elidedText())
+        super().focusOutEvent(event)
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Update elided text being shown when the widget is resized."""
+        if not self.hasFocus():
+            super().setText(self._elidedText())
+        super().resizeEvent(event)
+
+    # private implementation methods
+
+    def _update_text(self, text: str) -> None:
+        """Update only the actual text of the widget.
+
+        The actual text is the text the widget has without eliding.
+        """
+        self._text = text

src/superqt/fonticon/__init__.py

@@ -2,18 +2,19 @@ from __future__ import annotations
 
 __all__ = [
     "addFont",
+    "Animation",
     "ENTRY_POINT",
     "font",
     "icon",
     "IconFont",
     "IconFontMeta",
     "IconOpts",
-    "Animation",
     "pulse",
+    "setTextIcon",
     "spin",
 ]
 
-from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+from typing import TYPE_CHECKING
 
 from ._animations import Animation, pulse, spin
 from ._iconfont import IconFont, IconFontMeta
@@ -38,21 +39,23 @@ ENTRY_POINT = _FIM.ENTRY_POINT
 def icon(
     glyph_key: str,
     scale_factor: float = DEFAULT_SCALING_FACTOR,
-    color: ValidColor = None,
+    color: ValidColor | None = None,
     opacity: float = 1,
-    animation: Optional[Animation] = None,
-    transform: Optional[QTransform] = None,
-    states: Dict[str, Union[IconOptionDict, IconOpts]] = {},
+    animation: Animation | None = None,
+    transform: QTransform | None = None,
+    states: dict[str, IconOptionDict | IconOpts] | None = None,
 ) -> QFontIcon:
-    """Create a QIcon for `glyph_key`, with a number of optional settings
+    """Create a QIcon for `glyph_key`, with a number of optional settings.
 
-    The `glyph_key` (e.g. 'fa5s.smile') represents a Font-family & style, and a glpyh.
+    The `glyph_key` (e.g. 'fa5s.smile') represents a Font-family & style, and a glyph.
     In most cases, the key should be provided by a plugin in the environment, like:
 
-    https://github.com/tlambert03/fonticon-fontawesome5  ('fa5s' & 'fa5r' prefixes)
-    https://github.com/tlambert03/fonticon-materialdesignicons6  ('mdi6' prefix)
+    - [fonticon-fontawesome5](https://pypi.org/project/fonticon-fontawesome5/) ('fa5s' &
+      'fa5r' prefixes)
+    - [fonticon-materialdesignicons6](https://pypi.org/project/fonticon-materialdesignicons6/)
+      ('mdi6' prefix)
 
-    ...but fonts can also be added manually using :func:`addFont`.
+    ...but fonts can also be added manually using [`addFont`][superqt.fonticon.addFont].
 
     Parameters
     ----------
@@ -86,7 +89,7 @@ def icon(
           `animation`, etc...)
 
         Missing keys in the state dicts will be taken from the default options, provided
-        by the paramters above.
+        by the parameters above.
 
     Returns
     -------
@@ -96,19 +99,21 @@ def icon(
 
     Examples
     --------
-    # simple example (assumes the font-awesome5 plugin is installed)
+    simple example (using the string `'fa5s.smile'` assumes the `fonticon-fontawesome5`
+    plugin is installed)
+
     >>> btn = QPushButton()
     >>> btn.setIcon(icon('fa5s.smile'))
 
-    # can also directly import from fonticon_fa5
+    can also directly import from fonticon_fa5
     >>> from fonticon_fa5 import FA5S
     >>> btn.setIcon(icon(FA5S.smile))
 
-    # with animation
+    with animation
     >>> btn2 = QPushButton()
     >>> btn2.setIcon(icon(FA5S.spinner, animation=pulse(btn2)))
 
-    # complicated example
+    complicated example
     >>> btn = QPushButton()
     >>> btn.setIcon(
     ...     icon(
@@ -140,11 +145,11 @@ def icon(
         opacity=opacity,
         animation=animation,
         transform=transform,
-        states=states,
+        states=states or {},
     )
 
 
-def setTextIcon(widget: QWidget, glyph_key: str, size: Optional[float] = None) -> None:
+def setTextIcon(widget: QWidget, glyph_key: str, size: float | None = None) -> None:
     """Set text on a widget to a specific font & glyph.
 
     This is an alternative to setting a QIcon with a pixmap.  It may be easier to
@@ -152,7 +157,7 @@ def setTextIcon(widget: QWidget, glyph_key: str, size: Optional[float] = None) -
 
     Parameters
     ----------
-    wdg : QWidget
+    widget : QWidget
         A widget supporting a `setText` method.
     glyph_key : str
         String encapsulating a font-family, style, and glyph. e.g. 'fa5s.smile'.
@@ -162,8 +167,8 @@ def setTextIcon(widget: QWidget, glyph_key: str, size: Optional[float] = None) -
     return _QFIS.instance().setTextIcon(widget, glyph_key, size)
 
 
-def font(font_prefix: str, size: Optional[int] = None) -> QFont:
-    """Create QFont for `font_prefix`
+def font(font_prefix: str, size: int | None = None) -> QFont:
+    """Create QFont for `font_prefix`.
 
     Parameters
     ----------
@@ -181,8 +186,8 @@ def font(font_prefix: str, size: Optional[int] = None) -> QFont:
 
 
 def addFont(
-    filepath: str, prefix: str, charmap: Optional[Dict[str, str]] = None
-) -> Optional[Tuple[str, str]]:
+    filepath: str, prefix: str, charmap: dict[str, str] | None = None
+) -> tuple[str, str] | None:
     """Add OTF/TTF file at `filepath` to the registry under `prefix`.
 
     If you'd like to later use a fontkey in the form of `prefix.some-name`, then
@@ -190,10 +195,12 @@ def addFont(
     to their unicode numbers. If a charmap is not provided, glyphs must be directly
     accessed with their unicode as something like `key.\uffff`.
 
-    NOTE: in most cases, users will not need this.
-    Instead, they should install a font plugin, like:
-    https://github.com/tlambert03/fonticon-fontawesome5
-    https://github.com/tlambert03/fonticon-materialdesignicons6
+    !!! Note
+        in most cases, users will not need this. Instead, they should install a
+        font plugin, like:
+
+        - [fonticon-fontawesome5](https://pypi.org/project/fonticon-fontawesome5/)
+        - [fonticon-materialdesignicons6](https://pypi.org/project/fonticon-materialdesignicons6/)
 
     Parameters
     ----------

src/superqt/fonticon/_animations.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from typing import Optional
 
 from qtpy.QtCore import QRectF, QTimer
 from qtpy.QtGui import QPainter
@@ -6,6 +7,8 @@ from qtpy.QtWidgets import QWidget
 
 
 class Animation(ABC):
+    """Base icon animation class."""
+
     def __init__(self, parent_widget: QWidget, interval: int = 10, step: int = 1):
         self.parent_widget = parent_widget
         self.timer = QTimer()
@@ -25,6 +28,8 @@ class Animation(ABC):
 
 
 class spin(Animation):
+    """Animation that smoothly spins an icon."""
+
     def animate(self, painter: QPainter):
         if not self.timer.isActive():
             self.timer.start()
@@ -36,5 +41,7 @@ class spin(Animation):
 
 
 class pulse(spin):
-    def __init__(self, parent_widget: QWidget = None):
+    """Animation that spins an icon in slower, discrete steps."""
+
+    def __init__(self, parent_widget: Optional[QWidget] = None):
         super().__init__(parent_widget, interval=200, step=45)

src/superqt/fonticon/_iconfont.py

@@ -60,7 +60,6 @@ class IconFont(metaclass=IconFontMeta):
 
     Examples
     --------
-
         class FA5S(IconFont):
             __font_file__ = '...'
             some_char = 0xfa42
@@ -73,10 +72,11 @@ class IconFont(metaclass=IconFontMeta):
 def namespace2font(namespace: Union[Mapping, Type], name: str) -> Type[IconFont]:
     """Convenience to convert a namespace (class, module, dict) into an IconFont."""
     if isinstance(namespace, type):
-        assert isinstance(
-            getattr(namespace, FONTFILE_ATTR), str
-        ), "Not a valid font type"
-        return namespace  # type: ignore
+        if not isinstance(getattr(namespace, FONTFILE_ATTR), str):
+            raise TypeError(
+                f"Invalid Font: must declare {FONTFILE_ATTR!r} attribute or classmethod"
+            )
+        return namespace
     elif hasattr(namespace, "__dict__"):
         ns = dict(namespace.__dict__)
     else:

src/superqt/fonticon/_plugins.py

@@ -1,4 +1,5 @@
-from typing import Dict, List, Set, Tuple
+import contextlib
+from typing import ClassVar, Dict, List, Set, Tuple
 
 from ._iconfont import IconFontMeta, namespace2font
 
@@ -9,11 +10,10 @@ except ImportError:
 
 
 class FontIconManager:
-
-    ENTRY_POINT = "superqt.fonticon"
-    _PLUGINS: Dict[str, EntryPoint] = {}
-    _LOADED: Dict[str, IconFontMeta] = {}
-    _BLOCKED: Set[EntryPoint] = set()
+    ENTRY_POINT: ClassVar[str] = "superqt.fonticon"
+    _PLUGINS: ClassVar[Dict[str, EntryPoint]] = {}
+    _LOADED: ClassVar[Dict[str, IconFontMeta]] = {}
+    _BLOCKED: ClassVar[Set[EntryPoint]] = set()
 
     def _discover_fonts(self) -> None:
         self._PLUGINS.clear()
@@ -98,10 +98,8 @@ def loaded(load_all=False) -> Dict[str, List[str]]:
     if load_all:
         discover()
         for x in available():
-            try:
+            with contextlib.suppress(Exception):
                 _manager._get_font_class(x)
-            except Exception:
-                continue
     return {
         key: sorted(filter(lambda x: not x.startswith("_"), cls.__dict__))
         for key, cls in _manager._LOADED.items()

src/superqt/fonticon/_qfont_icon.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 import warnings
-from collections import abc
+from collections import abc, defaultdict
 from dataclasses import dataclass
 from pathlib import Path
-from typing import DefaultDict, Dict, Optional, Sequence, Tuple, Type, Union, cast
+from typing import ClassVar, DefaultDict, Sequence, Tuple, Union, cast
 
 from qtpy import QT_VERSION
 from qtpy.QtCore import QObject, QPoint, QRect, QSize, Qt
@@ -23,7 +23,8 @@ from qtpy.QtGui import (
 from qtpy.QtWidgets import QApplication, QStyleOption, QWidget
 from typing_extensions import TypedDict
 
-from ..utils import QMessageHandler
+from superqt.utils import QMessageHandler
+
 from ._animations import Animation
 
 
@@ -52,7 +53,7 @@ ValidColor = Union[
 
 StateOrMode = Union[QIcon.State, QIcon.Mode]
 StateModeKey = Union[StateOrMode, str, Sequence[StateOrMode]]
-_SM_MAP: Dict[str, StateOrMode] = {
+_SM_MAP: dict[str, StateOrMode] = {
     "on": QIcon.State.On,
     "off": QIcon.State.Off,
     "normal": QIcon.Mode.Normal,
@@ -62,8 +63,8 @@ _SM_MAP: Dict[str, StateOrMode] = {
 }
 
 
-def _norm_state_mode(key: StateModeKey) -> Tuple[QIcon.State, QIcon.Mode]:
-    """return state/mode tuple given a variety of valid inputs.
+def _norm_state_mode(key: StateModeKey) -> tuple[QIcon.State, QIcon.Mode]:
+    """Return state/mode tuple given a variety of valid inputs.
 
     Input can be either a string, or a sequence of state or mode enums.
     Strings can be any combination of on, off, normal, active, selected, disabled,
@@ -73,13 +74,13 @@ def _norm_state_mode(key: StateModeKey) -> Tuple[QIcon.State, QIcon.Mode]:
     if isinstance(key, str):
         try:
             _sm = [_SM_MAP[k.lower()] for k in key.split("_")]
-        except KeyError:
+        except KeyError as e:
             raise ValueError(
                 f"{key!r} is not a valid state key, must be a combination of {{on, "
                 "off, active, disabled, selected, normal} separated by underscore"
-            )
+            ) from e
     else:
-        _sm = key if isinstance(key, abc.Sequence) else [key]  # type: ignore
+        _sm = key if isinstance(key, abc.Sequence) else [key]
 
     state = next((i for i in _sm if isinstance(i, QIcon.State)), QIcon.State.Off)
     mode = next((i for i in _sm if isinstance(i, QIcon.Mode)), QIcon.Mode.Normal)
@@ -91,8 +92,8 @@ class IconOptionDict(TypedDict, total=False):
     scale_factor: float
     color: ValidColor
     opacity: float
-    animation: Optional[Animation]
-    transform: Optional[QTransform]
+    animation: Animation | None
+    transform: QTransform | None
 
 
 # public facing, for a nicer IDE experience than a dict
@@ -102,12 +103,29 @@ class IconOptionDict(TypedDict, total=False):
 # IconOptions are.
 @dataclass
 class IconOpts:
-    glyph_key: Union[str, Unset] = _Unset
-    scale_factor: Union[float, Unset] = _Unset
-    color: Union[ValidColor, Unset] = _Unset
-    opacity: Union[float, Unset] = _Unset
-    animation: Union[Animation, Unset, None] = _Unset
-    transform: Union[QTransform, Unset, None] = _Unset
+    """Options for rendering an icon.
+
+    Parameters
+    ----------
+    glyph_key : str, optional
+        The key of the glyph to use, e.g. `'fa5s.smile'`, by default `None`
+    scale_factor : float, optional
+        The scale factor to use, by default `None`
+    color : ValidColor, optional
+        The color to use, by default `None`. Colors may be specified as a string,
+        `QColor`, `Qt.GlobalColor`, or a 3 or 4-tuple of integers.
+    opacity : float, optional
+        The opacity to use, by default `None`
+    animation : Animation, optional
+        The animation to use, by default `None`
+    """
+
+    glyph_key: str | Unset = _Unset
+    scale_factor: float | Unset = _Unset
+    color: ValidColor | Unset = _Unset
+    opacity: float | Unset = _Unset
+    animation: Animation | Unset | None = _Unset
+    transform: QTransform | Unset | None = _Unset
 
     def dict(self) -> IconOptionDict:
         # not using asdict due to pickle errors on animation
@@ -123,8 +141,8 @@ class _IconOptions:
     scale_factor: float = DEFAULT_SCALING_FACTOR
     color: ValidColor = None
     opacity: float = DEFAULT_OPACITY
-    animation: Optional[Animation] = None
-    transform: Optional[QTransform] = None
+    animation: Animation | None = None
+    transform: QTransform | None = None
 
     def _update(self, icon_opts: IconOpts) -> _IconOptions:
         return _IconOptions(**{**vars(self), **icon_opts.dict()})
@@ -139,8 +157,8 @@ class _QFontIconEngine(QIconEngine):
 
     def __init__(self, options: _IconOptions):
         super().__init__()
-        self._opts: DefaultDict[
-            QIcon.State, Dict[QIcon.Mode, Optional[_IconOptions]]
+        self._opts: defaultdict[
+            QIcon.State, dict[QIcon.Mode, _IconOptions | None]
         ] = DefaultDict(dict)
         self._opts[QIcon.State.Off][QIcon.Mode.Normal] = options
         self.update_hash()
@@ -213,7 +231,7 @@ class _QFontIconEngine(QIconEngine):
 
         # font
         font = QFont()
-        font.setFamily(family)  # set sepeartely for Qt6
+        font.setFamily(family)  # set separately for Qt6
         font.setPixelSize(round(rect.height() * opts.scale_factor))
         if style:
             font.setStyleName(style)
@@ -222,7 +240,7 @@ class _QFontIconEngine(QIconEngine):
         if isinstance(opts.color, tuple):
             color_args = opts.color
         else:
-            color_args = (opts.color,) if opts.color else ()  # type: ignore
+            color_args = (opts.color,) if opts.color else ()
 
         # animation
         if opts.animation is not None:
@@ -304,12 +322,12 @@ class QFontIcon(QIcon):
         self,
         state: QIcon.State = QIcon.State.Off,
         mode: QIcon.Mode = QIcon.Mode.Normal,
-        glyph_key: Union[str, Unset] = _Unset,
-        scale_factor: Union[float, Unset] = _Unset,
-        color: Union[ValidColor, Unset] = _Unset,
-        opacity: Union[float, Unset] = _Unset,
-        animation: Union[Animation, Unset, None] = _Unset,
-        transform: Union[QTransform, Unset, None] = _Unset,
+        glyph_key: str | Unset = _Unset,
+        scale_factor: float | Unset = _Unset,
+        color: ValidColor | Unset = _Unset,
+        opacity: float | Unset = _Unset,
+        animation: Animation | Unset | None = _Unset,
+        transform: QTransform | Unset | None = _Unset,
     ) -> None:
         """Set icon options for a specific mode/state."""
         if glyph_key is not _Unset:
@@ -327,22 +345,20 @@ class QFontIcon(QIcon):
 
 
 class QFontIconStore(QObject):
-
     # map of key -> (font_family, font_style)
-    _LOADED_KEYS: Dict[str, Tuple[str, Optional[str]]] = dict()
+    _LOADED_KEYS: ClassVar[dict[str, tuple[str, str]]] = {}
 
     # map of (font_family, font_style) -> character (char may include key)
-    _CHARMAPS: Dict[Tuple[str, Optional[str]], Dict[str, str]] = dict()
+    _CHARMAPS: ClassVar[dict[tuple[str, str | None], dict[str, str]]] = {}
 
     # singleton instance, use `instance()` to retrieve
-    __instance: Optional[QFontIconStore] = None
+    __instance: ClassVar[QFontIconStore | None] = None
 
-    def __init__(self, parent: Optional[QObject] = None) -> None:
+    def __init__(self, parent: QObject | None = None) -> None:
         super().__init__(parent=parent)
-        # QT6 drops this
-        dpi = getattr(Qt.ApplicationAttribute, "AA_UseHighDpiPixmaps", None)
-        if dpi:
-            QApplication.setAttribute(dpi)
+        if tuple(cast(str, QT_VERSION).split(".")) < ("6", "0"):
+            # QT6 drops this
+            QApplication.setAttribute(Qt.ApplicationAttribute.AA_UseHighDpiPixmaps)
 
     @classmethod
     def instance(cls) -> QFontIconStore:
@@ -357,8 +373,8 @@ class QFontIconStore(QObject):
         QFontDatabase.removeAllApplicationFonts()
 
     @classmethod
-    def _key2family(cls, key: str) -> Tuple[str, Optional[str]]:
-        """Return (family, style) given a font `key`"""
+    def _key2family(cls, key: str) -> tuple[str, str]:
+        """Return (family, style) given a font `key`."""
         key = key.split(".", maxsplit=1)[0]
         if key not in cls._LOADED_KEYS:
             from . import _plugins
@@ -366,7 +382,7 @@ class QFontIconStore(QObject):
             try:
                 font_cls = _plugins.get_font_class(key)
                 result = cls.addFont(
-                    font_cls.__font_file__, key, charmap=font_cls.__dict__
+                    font_cls.__font_file__, key, charmap=dict(font_cls.__dict__)
                 )
                 if not result:  # pragma: no cover
                     raise Exception("Invalid font file")
@@ -381,13 +397,15 @@ class QFontIconStore(QObject):
 
     @classmethod
     def _ensure_char(cls, char: str, family: str, style: str) -> str:
-        """make sure that `char` is a glyph provided by `family` and `style`."""
+        """Make sure that `char` is a glyph provided by `family` and `style`."""
         if len(char) == 1 and ord(char) > 256:
             return char
         try:
             charmap = cls._CHARMAPS[(family, style)]
-        except KeyError:
-            raise KeyError(f"No charmap registered for font '{family} ({style})'")
+        except KeyError as e:
+            raise KeyError(
+                f"No charmap registered for font '{family} ({style})'"
+            ) from e
         if char in charmap:
             # split in case the charmap includes the key
             return charmap[char].split(".", maxsplit=1)[-1]
@@ -400,8 +418,8 @@ class QFontIconStore(QObject):
         raise ValueError(f"Font '{family} ({style})' has no glyph with the key {ident}")
 
     @classmethod
-    def key2glyph(cls, glyph_key: str) -> tuple[str, str, Optional[str]]:
-        """Return (char, family, style) given a `glyph_key`"""
+    def key2glyph(cls, glyph_key: str) -> tuple[str, str, str | None]:
+        """Return (char, family, style) given a `glyph_key`."""
         if "." not in glyph_key:
             raise ValueError("Glyph key must contain a period")
         font_key, char = glyph_key.split(".", maxsplit=1)
@@ -411,20 +429,20 @@ class QFontIconStore(QObject):
 
     @classmethod
     def addFont(
-        cls, filepath: str, prefix: str, charmap: Optional[Dict[str, str]] = None
-    ) -> Optional[Tuple[str, str]]:
-        """Add font at `filepath` to the registry under `key`.
+        cls, filepath: str, prefix: str, charmap: dict[str, str] | None = None
+    ) -> tuple[str, str] | None:
+        r"""Add font at `filepath` to the registry under `key`.
 
         If you'd like to later use a fontkey in the form of `key.some-name`, then
         `charmap` must be provided and provide a mapping for all of the glyph names
         to their unicode numbers. If a charmap is not provided, glyphs must be directly
-        accessed with their unicode as something like `key.\uffff`.
+        accessed with their unicode as something like `key.\\uffff`.
 
         Parameters
         ----------
         filepath : str
             Path to an OTF or TTF file containing the fonts
-        key : str
+        prefix : str
             A key that will represent this font file when used for lookup.  For example,
             'fa5s' for 'Font-Awesome 5 Solid'.
         charmap : Dict[str, str], optional
@@ -438,8 +456,8 @@ class QFontIconStore(QObject):
             something goes wrong.
         """
         if prefix in cls._LOADED_KEYS:
-            warnings.warn(f"Prefix {prefix} already loaded")
-            return
+            warnings.warn(f"Prefix {prefix} already loaded", stacklevel=2)
+            return None
 
         if not Path(filepath).exists():
             raise FileNotFoundError(f"Font file doesn't exist: {filepath}")
@@ -448,28 +466,29 @@ class QFontIconStore(QObject):
 
         fontId = QFontDatabase.addApplicationFont(str(Path(filepath).absolute()))
         if fontId < 0:  # pragma: no cover
-            warnings.warn(f"Cannot load font file: {filepath}")
+            warnings.warn(f"Cannot load font file: {filepath}", stacklevel=2)
             return None
 
         families = QFontDatabase.applicationFontFamilies(fontId)
         if not families:  # pragma: no cover
-            warnings.warn(f"Font file is empty!: {filepath}")
+            warnings.warn(f"Font file is empty!: {filepath}", stacklevel=2)
             return None
         family: str = families[0]
 
         # in Qt6, everything becomes a static member
-        QFd: Union[QFontDatabase, Type[QFontDatabase]] = (
-            QFontDatabase()  # type: ignore
-            if tuple(QT_VERSION.split(".")) < ("6", "0")
+        QFd: QFontDatabase | type[QFontDatabase] = (
+            QFontDatabase()
+            if tuple(cast(str, QT_VERSION).split(".")) < ("6", "0")
             else QFontDatabase
         )
 
-        styles = QFd.styles(family)  # type: ignore
+        styles = QFd.styles(family)
         style: str = styles[-1] if styles else ""
         if not QFd.isSmoothlyScalable(family, style):  # pragma: no cover
             warnings.warn(
                 f"Registered font {family} ({style}) is not smoothly scalable. "
-                "Icons may not look attractive."
+                "Icons may not look attractive.",
+                stacklevel=2,
             )
 
         cls._LOADED_KEYS[prefix] = (family, style)
@@ -482,11 +501,11 @@ class QFontIconStore(QObject):
         glyph_key: str,
         *,
         scale_factor: float = DEFAULT_SCALING_FACTOR,
-        color: ValidColor = None,
+        color: ValidColor | None = None,
         opacity: float = 1,
-        animation: Optional[Animation] = None,
-        transform: Optional[QTransform] = None,
-        states: Dict[str, Union[IconOptionDict, IconOpts]] = {},
+        animation: Animation | None = None,
+        transform: QTransform | None = None,
+        states: dict[str, IconOptionDict | IconOpts] | None = None,
     ) -> QFontIcon:
         self.key2glyph(glyph_key)  # make sure it's a valid glyph_key
         default_opts = _IconOptions(
@@ -498,18 +517,18 @@ class QFontIconStore(QObject):
             transform=transform,
         )
         icon = QFontIcon(default_opts)
-        for kw, options in states.items():
+        for kw, options in (states or {}).items():
             if isinstance(options, IconOpts):
                 options = default_opts._update(options).dict()
             icon.addState(*_norm_state_mode(kw), **options)
         return icon
 
     def setTextIcon(
-        self, widget: QWidget, glyph_key: str, size: Optional[float] = None
+        self, widget: QWidget, glyph_key: str, size: float | None = None
     ) -> None:
         """Sets text on a widget to a specific font & glyph.
 
-        This is an alternative to setting a QIcon with a pixmap.  It may
+        This is an alternative to setting a `QIcon` with a pixmap.  It may
         be easier to combine with dynamic stylesheets.
         """
         setText = getattr(widget, "setText", None)
@@ -522,8 +541,8 @@ class QFontIconStore(QObject):
         widget.setFont(self.font(glyph_key, int(size)))
         setText(glyph)
 
-    def font(self, font_prefix: str, size: Optional[int] = None) -> QFont:
-        """Create QFont for `font_prefix`"""
+    def font(self, font_prefix: str, size: int | None = None) -> QFont:
+        """Create QFont for `font_prefix`."""
         font_key, _ = font_prefix.split(".", maxsplit=1)
         family, style = self._key2family(font_key)
         font = QFont()
@@ -536,7 +555,7 @@ class QFontIconStore(QObject):
 
 
 def _ensure_identifier(name: str) -> str:
-    """Normalize string to valid identifier"""
+    """Normalize string to valid identifier."""
     import keyword
 
     if not name:
@@ -553,5 +572,6 @@ def _ensure_identifier(name: str) -> str:
     # replace dashes and spaces with underscores
     name = name.replace("-", "_").replace(" ", "_")
 
-    assert str.isidentifier(name), f"Could not canonicalize name: {name}"
+    if not str.isidentifier(name):
+        raise ValueError(f"Could not canonicalize name: {name!r}. (not an identifier)")
     return name

src/superqt/qtcompat/__init__.py

@@ -6,13 +6,15 @@ from qtpy import *  # noqa
 
 warnings.warn(
     "The superqt.qtcompat module is deprecated as of v0.3.0. "
-    "Please import from `qtpy` instead."
+    "Please import from `qtpy` instead.",
+    stacklevel=2,
 )
 
 
 # forward any requests for superqt.qtcompat.* to qtpy.*
 class SuperQtImporter(abc.MetaPathFinder):
     def find_spec(self, fullname: str, path, target=None):  # type: ignore
+        """Forward any requests for superqt.qtcompat.* to qtpy.*."""
         if fullname.startswith(__name__):
             return util.find_spec(fullname.replace(__name__, "qtpy"))
 

src/superqt/selection/__init__.py

@@ -1,3 +1,4 @@
 from ._searchable_list_widget import QSearchableListWidget
+from ._searchable_tree_widget import QSearchableTreeWidget
 
-__all__ = ("QSearchableListWidget",)
+__all__ = ("QSearchableListWidget", "QSearchableTreeWidget")

src/superqt/selection/_searchable_tree_widget.py

@@ -0,0 +1,114 @@
+import logging
+from typing import Any, Iterable, Mapping
+
+from qtpy.QtCore import QRegularExpression
+from qtpy.QtWidgets import QLineEdit, QTreeWidget, QTreeWidgetItem, QVBoxLayout, QWidget
+
+
+class QSearchableTreeWidget(QWidget):
+    """A tree widget for showing a mapping that can be searched by key.
+
+    This is intended to be used with a read-only mapping and be conveniently
+    created using `QSearchableTreeWidget.fromData(data)`.
+    If the mapping changes, the easiest way to update this is by calling `setData`.
+
+    The tree can be searched by entering a regular expression pattern
+    into the `filter` line edit. An item is only shown if its, any of its ancestors',
+    or any of its descendants' keys or values match this pattern.
+    The regular expression follows the conventions described by the Qt docs:
+    https://doc.qt.io/qt-5/qregularexpression.html#details
+
+    Attributes
+    ----------
+    tree : QTreeWidget
+        Shows the mapping as a tree of items.
+    filter : QLineEdit
+        Used to filter items in the tree by matching their key against a
+        regular expression.
+    """
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+
+        self.tree: QTreeWidget = QTreeWidget(self)
+        self.tree.setHeaderLabels(("Key", "Value"))
+
+        self.filter: QLineEdit = QLineEdit(self)
+        self.filter.setClearButtonEnabled(True)
+        self.filter.textChanged.connect(self._updateVisibleItems)
+
+        layout = QVBoxLayout(self)
+        layout.addWidget(self.filter)
+        layout.addWidget(self.tree)
+
+    def setData(self, data: Mapping) -> None:
+        """Update the mapping data shown by the tree."""
+        self.tree.clear()
+        self.filter.clear()
+        top_level_items = [_make_item(name=k, value=v) for k, v in data.items()]
+        self.tree.addTopLevelItems(top_level_items)
+
+    def _updateVisibleItems(self, pattern: str) -> None:
+        """Recursively update the visibility of items based on the given pattern."""
+        expression = QRegularExpression(pattern)
+        for i in range(self.tree.topLevelItemCount()):
+            top_level_item = self.tree.topLevelItem(i)
+            _update_visible_items(top_level_item, expression)
+
+    @classmethod
+    def fromData(
+        cls, data: Mapping, *, parent: QWidget = None
+    ) -> "QSearchableTreeWidget":
+        """Make a searchable tree widget from a mapping."""
+        widget = cls(parent)
+        widget.setData(data)
+        return widget
+
+
+def _make_item(*, name: str, value: Any) -> QTreeWidgetItem:
+    """Make a tree item where the name and value are two columns.
+
+    Iterable values other than strings are recursively traversed to
+    add child items and build a tree. In this case, mappings use keys
+    as their names whereas other iterables use their enumerated index.
+    """
+    if isinstance(value, Mapping):
+        item = QTreeWidgetItem([name, type(value).__name__])
+        for k, v in value.items():
+            child = _make_item(name=k, value=v)
+            item.addChild(child)
+    elif isinstance(value, Iterable) and not isinstance(value, str):
+        item = QTreeWidgetItem([name, type(value).__name__])
+        for i, v in enumerate(value):
+            child = _make_item(name=str(i), value=v)
+            item.addChild(child)
+    else:
+        item = QTreeWidgetItem([name, str(value)])
+    logging.debug("_make_item: %s, %s, %s", item.text(0), item.text(1), item.flags())
+    return item
+
+
+def _update_visible_items(
+    item: QTreeWidgetItem, expression: QRegularExpression, ancestor_match: bool = False
+) -> bool:
+    """Recursively update the visibility of a tree item based on an expression.
+
+    An item is visible if any of its, any of its ancestors', or any of its descendants'
+    column's text matches the expression.
+    Returns True if the item is visible, False otherwise.
+    """
+    match = ancestor_match or any(
+        expression.match(item.text(i)).hasMatch() for i in range(item.columnCount())
+    )
+    visible = match
+    for i in range(item.childCount()):
+        child = item.child(i)
+        descendant_visible = _update_visible_items(child, expression, match)
+        visible = visible or descendant_visible
+    item.setHidden(not visible)
+    logging.debug(
+        "_update_visible_items: %s, %s",
+        tuple(item.text(i) for i in range(item.columnCount())),
+        visible,
+    )
+    return visible

src/superqt/sliders/__init__.pyi

@@ -1,12 +0,0 @@
-from qtpy.QtWidgets import QSlider
-
-from ._generic_range_slider import _GenericRangeSlider
-from ._generic_slider import _GenericSlider
-
-class QDoubleRangeSlider(_GenericRangeSlider): ...
-class QDoubleSlider(_GenericSlider): ...
-class QRangeSlider(_GenericRangeSlider): ...
-class QLabeledSlider(QSlider): ...
-class QLabeledDoubleSlider(QDoubleSlider): ...
-class QLabeledRangeSlider(QRangeSlider): ...
-class QLabeledDoubleRangeSlider(QDoubleRangeSlider): ...

src/superqt/sliders/_generic_range_slider.py

@@ -1,4 +1,4 @@
-from typing import Generic, List, Sequence, Tuple, TypeVar, Union
+from typing import List, Optional, Sequence, Tuple, TypeVar, Union
 
 from qtpy import QtGui
 from qtpy.QtCore import Property, QEvent, QPoint, QPointF, QRect, QRectF, Qt, Signal
@@ -17,7 +17,7 @@ _T = TypeVar("_T")
 SC_BAR = QStyle.SubControl.SC_ScrollBarSubPage
 
 
-class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
+class _GenericRangeSlider(_GenericSlider):
     """MultiHandle Range Slider widget.
 
     Same API as QSlider, but `value`, `setValue`, `sliderPosition`, and
@@ -68,23 +68,23 @@ class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
     def barIsRigid(self) -> bool:
         """Whether bar length is constant when dragging the bar.
 
-        If False, the bar can shorten when dragged beyond min/max. Default is True.
+        If `False`, the bar can shorten when dragged beyond min/max. Default is `True`.
         """
         return self._bar_is_rigid
 
     def setBarIsRigid(self, val: bool = True) -> None:
         """Whether bar length is constant when dragging the bar.
 
-        If False, the bar can shorten when dragged beyond min/max. Default is True.
+        If `False`, the bar can shorten when dragged beyond min/max. Default is `True`.
         """
         self._bar_is_rigid = bool(val)
 
     def barMovesAllHandles(self) -> bool:
-        """Whether clicking on the bar moves all handles (default), or just the nearest."""
+        """Whether clicking on the bar moves all handles, or just the nearest."""
         return self._bar_moves_all
 
     def setBarMovesAllHandles(self, val: bool = True) -> None:
-        """Whether clicking on the bar moves all handles (default), or just the nearest."""
+        """Whether clicking on the bar moves all handles, or just the nearest."""
         self._bar_moves_all = bool(val)
 
     def barIsVisible(self) -> bool:
@@ -96,12 +96,18 @@ class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
         self._should_draw_bar = bool(val)
 
     def hideBar(self) -> None:
+        """Hide the bar between the first and last handle."""
         self.setBarVisible(False)
 
     def showBar(self) -> None:
+        """Show the bar between the first and last handle."""
         self.setBarVisible(True)
 
     def applyMacStylePatch(self) -> str:
+        """Apply a QSS patch to fix sliders on macos>=12 with QT < 6.
+
+        see [FAQ](../faq.md#sliders-not-dragging-properly-on-macos-12) for more details.
+        """
         super().applyMacStylePatch()
         self._style._macpatch = True
 
@@ -205,6 +211,7 @@ class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
         self._style.brush_active = color
 
     barColor = Property(QtGui.QBrush, _getBarColor, _setBarColor)
+    """The color of the bar between the first and last handle."""
 
     def _offsetAllPositions(self, offset: float, ref=None) -> None:
         if ref is None:
@@ -226,7 +233,9 @@ class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
 
     # SubControl Positions
 
-    def _handleRect(self, handle_index: int, opt: QStyleOptionSlider = None) -> QRect:
+    def _handleRect(
+        self, handle_index: int, opt: Optional[QStyleOptionSlider] = None
+    ) -> QRect:
         """Return the QRect for all handles."""
         opt = opt or self._styleOption
         opt.sliderPosition = self._optSliderPositions[handle_index]
@@ -303,7 +312,7 @@ class _GenericRangeSlider(_GenericSlider[Tuple], Generic[_T]):
 
     # NOTE: this is very much tied to mousepress... not a generic "get control"
     def _getControlAtPos(
-        self, pos: QPoint, opt: QStyleOptionSlider = None
+        self, pos: QPoint, opt: Optional[QStyleOptionSlider] = None
     ) -> Tuple[QStyle.SubControl, int]:
         """Update self._pressedControl based on ev.pos()."""
         opt = opt or self._styleOption

src/superqt/sliders/_generic_slider.py

@@ -1,10 +1,10 @@
-"""Generic Sliders with internal python-based models
+"""Generic Sliders with internal python-based models.
 
 This module reimplements most of the logic from qslider.cpp in python:
 https://code.woboq.org/qt5/qtbase/src/widgets/widgets/qslider.cpp.html
 
 This probably looks like tremendous overkill at first (and it may be!),
-since a it's possible to acheive a very reasonable "float slider" by
+since a it's possible to achieve a very reasonable "float slider" by
 scaling input float values to some internal integer range for the QSlider,
 and converting back to float when getting `value()`.  However, one still
 runs into overflow limitations due to the internal integer model.
@@ -21,7 +21,7 @@ QRangeSlider.
 """
 import os
 import platform
-from typing import Generic, TypeVar
+from typing import TypeVar
 
 from qtpy import QT_VERSION, QtGui
 from qtpy.QtCore import QEvent, QPoint, QPointF, QRect, Qt, Signal
@@ -48,7 +48,7 @@ QOVERFLOW = 2**31 - 1
 # whether to use the MONTEREY_SLIDER_STYLES_FIX QSS hack
 # for fixing sliders on macos>=12 with QT < 6
 # https://bugreports.qt.io/browse/QTBUG-98093
-# https://github.com/napari/superqt/issues/74
+# https://github.com/pyapp-kit/superqt/issues/74
 USE_MAC_SLIDER_PATCH = (
     QT_VERSION
     and int(QT_VERSION.split(".")[0]) < 6
@@ -58,7 +58,7 @@ USE_MAC_SLIDER_PATCH = (
 )
 
 
-class _GenericSlider(QSlider, Generic[_T]):
+class _GenericSlider(QSlider):
     _fvalueChanged = Signal(int)
     _fsliderMoved = Signal(int)
     _frangeChanged = Signal(int, int)
@@ -66,7 +66,6 @@ class _GenericSlider(QSlider, Generic[_T]):
     MAX_DISPLAY = 5000
 
     def __init__(self, *args, **kwargs) -> None:
-
         self._minimum = 0.0
         self._maximum = 99.0
         self._pageStep = 10.0
@@ -99,6 +98,10 @@ class _GenericSlider(QSlider, Generic[_T]):
             self.applyMacStylePatch()
 
     def applyMacStylePatch(self) -> str:
+        """Apply a QSS patch to fix sliders on macos>=12 with QT < 6.
+
+        see [FAQ](../faq.md#sliders-not-dragging-properly-on-macos-12) for more details.
+        """
         self.setStyleSheet(MONTEREY_SLIDER_STYLES_FIX)
 
     # ###############  QtOverrides  #######################
@@ -272,7 +275,6 @@ class _GenericSlider(QSlider, Generic[_T]):
         self.update()
 
     def wheelEvent(self, e: QtGui.QWheelEvent) -> None:
-
         e.ignore()
         vertical = bool(e.angleDelta().y())
         delta = e.angleDelta().y() if vertical else e.angleDelta().x()
@@ -518,16 +520,7 @@ def _event_position(ev: QEvent) -> QPoint:
 def _sliderValueFromPosition(
     min: float, max: float, position: int, span: int, upsideDown: bool = False
 ) -> float:
-    """Converts the given pixel `position` to a value.
-
-    0 maps to the `min` parameter, `span` maps to `max` and other values are
-    distributed evenly in-between.
-
-    By default, this function assumes that the maximum value is on the right
-    for horizontal items and on the bottom for vertical items. Set the
-    `upsideDown` parameter to True to reverse this behavior.
-    """
-
+    """Converts the given pixel `position` to a value."""
     if span <= 0 or position <= 0:
         return max if upsideDown else min
     if position >= span:

src/superqt/sliders/_labeled.py

@@ -1,3 +1,4 @@
+import contextlib
 from enum import IntEnum
 from functools import partial
 from typing import Any
@@ -17,7 +18,8 @@ from qtpy.QtWidgets import (
     QWidget,
 )
 
-from ..utils import signals_blocked
+from superqt.utils import signals_blocked
+
 from ._sliders import QDoubleRangeSlider, QDoubleSlider, QRangeSlider
 
 
@@ -129,9 +131,12 @@ class QLabeledSlider(_SliderProxy, QAbstractSlider):
         parent, orientation = _handle_overloaded_slider_sig(args, kwargs)
 
         super().__init__(parent)
+        # accept focus events
+        fp = self.style().styleHint(QStyle.StyleHint.SH_Button_FocusPolicy)
+        self.setFocusPolicy(Qt.FocusPolicy(fp))
 
-        self._slider = self._slider_class()
-        self._label = SliderLabel(self._slider, connect=self._setValue)
+        self._slider = self._slider_class(parent=self)
+        self._label = SliderLabel(self._slider, connect=self._setValue, parent=self)
         self._edge_label_mode: EdgeLabelMode = EdgeLabelMode.LabelIsValue
 
         self._rename_signals()
@@ -140,17 +145,17 @@ class QLabeledSlider(_SliderProxy, QAbstractSlider):
         self._slider.sliderMoved.connect(self.sliderMoved.emit)
         self._slider.sliderPressed.connect(self.sliderPressed.emit)
         self._slider.sliderReleased.connect(self.sliderReleased.emit)
-        self._slider.valueChanged.connect(self._label.setValue)
-        self._slider.valueChanged.connect(self.valueChanged.emit)
+        self._slider.valueChanged.connect(self._on_slider_value_changed)
         self._label.editingFinished.connect(self.editingFinished)
 
         self.setOrientation(orientation)
 
+    def _on_slider_value_changed(self, v):
+        self._label.setValue(v)
+        self.valueChanged.emit(v)
+
     def _setValue(self, value: float):
-        """
-        Convert the value from float to int before
-        setting the slider value
-        """
+        """Convert the value from float to int before setting the slider value."""
         self._slider.setValue(int(value))
 
     def _rename_signals(self):
@@ -171,7 +176,7 @@ class QLabeledSlider(_SliderProxy, QAbstractSlider):
             if self._edge_label_mode == EdgeLabelMode.NoLabel:
                 marg = (0, 0, 5, 0)
 
-            layout = QHBoxLayout()
+            layout = QHBoxLayout()  # type: ignore
             layout.addWidget(self._slider)
             layout.addWidget(self._label)
             self._label.setAlignment(Qt.AlignmentFlag.AlignRight)
@@ -185,9 +190,11 @@ class QLabeledSlider(_SliderProxy, QAbstractSlider):
         self.setLayout(layout)
 
     def edgeLabelMode(self) -> EdgeLabelMode:
+        """Return current `EdgeLabelMode`."""
         return self._edge_label_mode
 
     def setEdgeLabelMode(self, opt: EdgeLabelMode) -> None:
+        """Set the `EdgeLabelMode`."""
         if opt is EdgeLabelMode.LabelIsRange:
             raise ValueError(
                 "mode must be one of 'EdgeLabelMode.NoLabel' or "
@@ -220,6 +227,10 @@ class QLabeledDoubleSlider(QLabeledSlider):
         super().__init__(*args, **kwargs)
         self.setDecimals(2)
 
+    def _setValue(self, value: float):
+        """Convert the value from float to int before setting the slider value."""
+        self._slider.setValue(value)
+
     def _rename_signals(self):
         self.valueChanged = self._fvalueChanged
         self.sliderMoved = self._fsliderMoved
@@ -283,9 +294,11 @@ class QLabeledRangeSlider(_SliderProxy, QAbstractSlider):
         self.valueChanged = self._valueChanged
 
     def handleLabelPosition(self) -> LabelPosition:
+        """Return where/whether labels are shown adjacent to slider handles."""
         return self._handle_label_position
 
     def setHandleLabelPosition(self, opt: LabelPosition) -> LabelPosition:
+        """Set where/whether labels are shown adjacent to slider handles."""
         self._handle_label_position = opt
         for lbl in self._handle_labels:
             if not opt:
@@ -295,9 +308,11 @@ class QLabeledRangeSlider(_SliderProxy, QAbstractSlider):
         self.setOrientation(self.orientation())
 
     def edgeLabelMode(self) -> EdgeLabelMode:
+        """Return current `EdgeLabelMode`."""
         return self._edge_label_mode
 
     def setEdgeLabelMode(self, opt: EdgeLabelMode):
+        """Set `EdgeLabelMode`, controls what is shown at the min/max labels."""
         self._edge_label_mode = opt
         if not self._edge_label_mode:
             self._min_label.hide()
@@ -415,7 +430,6 @@ class QLabeledRangeSlider(_SliderProxy, QAbstractSlider):
 
     def setOrientation(self, orientation):
         """Set orientation, value will be 'horizontal' or 'vertical'."""
-
         self._slider.setOrientation(orientation)
         if orientation == Qt.Orientation.Vertical:
             layout = QVBoxLayout()
@@ -563,10 +577,8 @@ class SliderLabel(QDoubleSpinBox):
         if opt == EdgeLabelMode.LabelIsRange:
             self.setMinimum(-9999999)
             self.setMaximum(9999999)
-            try:
+            with contextlib.suppress(Exception):
                 self._slider.rangeChanged.disconnect(self.setRange)
-            except Exception:
-                pass
         else:
             self.setMinimum(self._slider.minimum())
             self.setMaximum(self._slider.maximum())

src/superqt/sliders/_range_style.py

@@ -260,7 +260,6 @@ def parse_color(color: str, default_attr) -> QColor | QGradient:
 
 
 def update_styles_from_stylesheet(obj: _GenericRangeSlider):
-
     qss: str = obj.styleSheet()
 
     parent = obj.parent()

src/superqt/sliders/_sliders.py

@@ -27,11 +27,11 @@ class _FloatMixin:
         return float(value)
 
 
-class QDoubleSlider(_FloatMixin, _GenericSlider[float]):
+class QDoubleSlider(_FloatMixin, _GenericSlider):
     pass
 
 
-class QIntSlider(_IntMixin, _GenericSlider[int]):
+class QIntSlider(_IntMixin, _GenericSlider):
     # mostly just an example... use QSlider instead.
     valueChanged = Signal(int)
 

src/superqt/spinbox/_intspin.py

@@ -1,3 +1,4 @@
+import math
 from enum import Enum
 
 from qtpy.QtCore import QSize, Qt, Signal
@@ -24,7 +25,7 @@ class _AnyIntValidator(QValidator):
 
 
 class QLargeIntSpinBox(QAbstractSpinBox):
-    """An integer spinboxes backed by unbound python integer
+    """An integer spinboxes backed by unbound python integer.
 
     Qt's built-in ``QSpinBox`` is backed by a signed 32-bit integer.
     This could become limiting, particularly in large dense segmentations.
@@ -42,6 +43,9 @@ class QLargeIntSpinBox(QAbstractSpinBox):
         self._minimum: int = 0
         self._maximum: int = 2**64 - 1
         self._single_step: int = 1
+        self._step_type: QAbstractSpinBox.StepType = (
+            QAbstractSpinBox.StepType.DefaultStepType
+        )
         self._pending_emit = False
         validator = _AnyIntValidator(self)
         self.lineEdit().setValidator(validator)
@@ -78,7 +82,13 @@ class QLargeIntSpinBox(QAbstractSpinBox):
     def setSingleStep(self, step):
         self._single_step = int(step)
 
-    # TODO: add prefix/suffix/stepType
+    def setStepType(self, stepType: QAbstractSpinBox.StepType) -> None:
+        self._step_type = stepType
+
+    def stepType(self) -> QAbstractSpinBox.StepType:
+        return self._step_type
+
+    # TODO: add prefix/suffix
 
     # ###############  QtOverrides  #######################
 
@@ -102,13 +112,16 @@ class QLargeIntSpinBox(QAbstractSpinBox):
         return super().keyPressEvent(e)
 
     def stepBy(self, steps: int) -> None:
-        step = self._single_step
         old = self._value
         e = _EmitPolicy.EmitIfChanged
         if self._pending_emit:
             self._interpret(_EmitPolicy.NeverEmit)
             if self._value != old:
                 e = _EmitPolicy.AlwaysEmit
+        if self._step_type == QAbstractSpinBox.StepType.AdaptiveDecimalStepType:
+            step = self._calculate_adaptive_decimal_step(steps)
+        else:
+            step = self._single_step
         self._setValue(self._bound(self._value + (step * steps)), e)
 
     def stepEnabled(self):
@@ -164,9 +177,12 @@ class QLargeIntSpinBox(QAbstractSpinBox):
         v = int(text)
         self._setValue(v, policy)
 
-    def _editor_text_changed(self, t):
+    def _editor_text_changed(self, t: str) -> None:
         if self.keyboardTracking():
-            self._setValue(int(t), _EmitPolicy.EmitIfChanged)
+            try:
+                self._setValue(int(t), _EmitPolicy.EmitIfChanged)
+            except ValueError:
+                pass
             self.lineEdit().setFocus()
             self._pending_emit = False
         else:
@@ -174,3 +190,15 @@ class QLargeIntSpinBox(QAbstractSpinBox):
 
     def _bound(self, value):
         return max(self._minimum, min(self._maximum, value))
+
+    def _calculate_adaptive_decimal_step(self, steps: int) -> int:
+        abs_value = abs(self._value)
+        if abs_value < 100:
+            return 1
+
+        value_negative = self._value < 0
+        steps_negative = steps < 0
+        sign_compensation = 0 if value_negative == steps_negative else 1
+
+        log = int(math.log10(abs_value - sign_compensation)) - 1
+        return int(math.pow(10, log))

src/superqt/spinbox/_quantity.py

@@ -0,0 +1,234 @@
+from typing import TYPE_CHECKING, Optional, Union
+
+try:
+    from pint import Quantity, Unit, UnitRegistry
+    from pint.util import UnitsContainer
+except ImportError as e:
+    raise ImportError(
+        "pint is required to use QQuantity.  Install it with `pip install pint`"
+    ) from e
+
+from qtpy.QtCore import Signal
+from qtpy.QtWidgets import QComboBox, QDoubleSpinBox, QHBoxLayout, QSizePolicy, QWidget
+
+from superqt.utils import signals_blocked
+
+if TYPE_CHECKING:
+    from decimal import Decimal
+
+
+Number = Union[int, float, "Decimal"]
+UREG = UnitRegistry()
+NULL_OPTION = "-----"
+QOVERFLOW = 2**30
+SI_BASES = {
+    "[length]": "meter",
+    "[time]": "second",
+    "[current]": "ampere",
+    "[luminosity]": "candela",
+    "[mass]": "gram",
+    "[substance]": "mole",
+    "[temperature]": "kelvin",
+}
+DEFAULT_OPTIONS = {
+    "[length]": ["km", "m", "mm", "µm"],
+    "[time]": ["day", "hour", "min", "sec", "ms"],
+    "[current]": ["A", "mA", "µA"],
+    "[luminosity]": ["kcd", "cd", "mcd"],
+    "[mass]": ["kg", "g", "mg", "µg"],
+    "[substance]": ["mol", "mmol", "µmol"],
+    "[temperature]": ["°C", "°F", "°K"],
+    "radian": ["rad", "deg"],
+}
+
+
+class QQuantity(QWidget):
+    """A combination QDoubleSpinBox and QComboBox for entering quantities.
+
+    For this widget, `value()` returns a `pint.Quantity` object, while `setValue()`
+    accepts either a number, `pint.Quantity`, a string that can be parsed by `pint`.
+
+    Parameters
+    ----------
+    value : Union[str, pint.Quantity, Number]
+        The initial value to display.  If a string, it will be parsed by `pint`.
+    units : Union[pint.util.UnitsContainer, str, pint.Quantity], optional
+        The units to use if `value` is a number.  If a string, it will be parsed by
+        `pint`.  If a `pint.Quantity`, the units will be extracted from it.
+    ureg : pint.UnitRegistry, optional
+        The unit registry to use.  If not provided, the registry will be extracted
+        from `value` if it is a `pint.Quantity`, otherwise the default registry will
+        be used.
+    parent : QWidget, optional
+        The parent widget, by default None
+    """
+
+    valueChanged = Signal(Quantity)
+    unitsChanged = Signal(Unit)
+    dimensionalityChanged = Signal(UnitsContainer)
+
+    def __init__(
+        self,
+        value: Union[str, Quantity, Number] = 0,
+        units: Optional[Union[UnitsContainer, str, Quantity]] = None,
+        ureg: Optional[UnitRegistry] = None,
+        parent: Optional[QWidget] = None,
+    ) -> None:
+        super().__init__(parent=parent)
+        if ureg is None:
+            ureg = value._REGISTRY if isinstance(value, Quantity) else UREG
+        else:
+            if not isinstance(ureg, UnitRegistry):
+                raise TypeError(
+                    f"ureg must be a pint.UnitRegistry, not {type(ureg).__name__}"
+                )
+
+        self._ureg = ureg
+        self._value: Quantity = self._ureg.Quantity(value, units=units)
+
+        # whether to preserve quantity equality when changing units or magnitude
+        self._preserve_quantity: bool = False
+        self._abbreviate_units: bool = True  # TODO: implement
+
+        self._mag_spinbox = QDoubleSpinBox()
+        self._mag_spinbox.setDecimals(3)
+        self._mag_spinbox.setRange(-QOVERFLOW, QOVERFLOW - 1)
+        self._mag_spinbox.setValue(float(self._value.magnitude))
+        self._mag_spinbox.valueChanged.connect(self.setMagnitude)
+
+        self._units_combo = QComboBox()
+        self._units_combo.setSizePolicy(QSizePolicy.Fixed, QSizePolicy.Fixed)
+        self._units_combo.currentTextChanged.connect(self.setUnits)
+        self._update_units_combo_choices()
+
+        self.setLayout(QHBoxLayout())
+        self.layout().addWidget(self._mag_spinbox)
+        self.layout().addWidget(self._units_combo)
+        self.layout().setContentsMargins(6, 0, 0, 0)
+
+    def unitRegistry(self) -> UnitRegistry:
+        """Return the pint UnitRegistry used by this widget."""
+        return self._ureg
+
+    def _update_units_combo_choices(self):
+        if self._value.dimensionless:
+            with signals_blocked(self._units_combo):
+                self._units_combo.clear()
+                self._units_combo.addItem(NULL_OPTION)
+                self._units_combo.addItems(
+                    [self._format_units(x) for x in SI_BASES.values()]
+                )
+                self._units_combo.setCurrentText(NULL_OPTION)
+            return
+
+        units = self._value.units
+        dims, exp = next(iter(units.dimensionality.items()))
+        if exp != 1:
+            raise NotImplementedError("Inverse units not yet implemented")
+        options = [
+            self._format_units(self._ureg.Unit(u))
+            for u in DEFAULT_OPTIONS.get(dims, [])
+        ]
+        current = self._format_units(units)
+        with signals_blocked(self._units_combo):
+            self._units_combo.clear()
+            self._units_combo.addItems(options)
+            if self._units_combo.findText(current) == -1:
+                self._units_combo.addItem(current)
+
+        self._units_combo.setCurrentText(current)
+
+    def value(self) -> Quantity:
+        """Return the current value as a `pint.Quantity`."""
+        return self._value
+
+    def text(self) -> str:
+        return str(self._value)
+
+    def magnitude(self) -> Union[float, int]:
+        """Return the magnitude of the current value."""
+        return self._value.magnitude
+
+    def units(self) -> Unit:
+        """Return the current units."""
+        return self._value.units
+
+    def dimensionality(self) -> UnitsContainer:
+        """Return the current dimensionality (cast to `str` for nice repr)."""
+        return self._value.dimensionality
+
+    def setDecimals(self, decimals: int) -> None:
+        """Set the number of decimals to display in the spinbox."""
+        self._mag_spinbox.setDecimals(decimals)
+        if self._value is not None:
+            self._mag_spinbox.setValue(self._value.magnitude)
+
+    def setValue(
+        self,
+        value: Union[str, Quantity, Number],
+        units: Optional[Union[UnitsContainer, str, Quantity]] = None,
+    ) -> None:
+        """Set the current value (will cast to a pint Quantity)."""
+        if isinstance(value, Quantity):
+            if units is not None:
+                raise ValueError("Cannot specify units if value is a Quantity")
+            new_val = self._ureg.Quantity(value.magnitude, units=value.units)
+        else:
+            new_val = self._ureg.Quantity(value, units=units)
+
+        mag_change = new_val.magnitude != self._value.magnitude
+        units_change = new_val.units != self._value.units
+        dims_changed = new_val.dimensionality != self._value.dimensionality
+
+        self._value = new_val
+
+        if mag_change:
+            with signals_blocked(self._mag_spinbox):
+                self._mag_spinbox.setValue(float(self._value.magnitude))
+
+        if units_change:
+            with signals_blocked(self._units_combo):
+                self._units_combo.setCurrentText(self._format_units(self._value.units))
+            self.unitsChanged.emit(self._value.units)
+
+        if dims_changed:
+            self._update_units_combo_choices()
+            self.dimensionalityChanged.emit(self._value.dimensionality)
+
+        if mag_change or units_change:
+            self.valueChanged.emit(self._value)
+
+    def setMagnitude(self, magnitude: Number) -> None:
+        """Set the magnitude of the current value."""
+        self.setValue(self._ureg.Quantity(magnitude, self._value.units))
+
+    def setUnits(self, units: Union[str, Unit, Quantity]) -> None:
+        """Set the units of the current value.
+
+        If `units` is `None`, will convert to a dimensionless quantity.
+        Otherwise, units must be compatible with the current dimensionality.
+        """
+        if units is None:
+            new_val = self._ureg.Quantity(self._value.magnitude)
+        elif self.isDimensionless():
+            new_val = self._ureg.Quantity(self._value.magnitude, units)
+        else:
+            new_val = self._value.to(units)
+        self.setValue(new_val)
+
+    def isDimensionless(self) -> bool:
+        """Return `True` if the current value is dimensionless."""
+        return self._value.dimensionless
+
+    def magnitudeSpinBox(self) -> QDoubleSpinBox:
+        """Return the `QSpinBox` widget used to edit the magnitude."""
+        return self._mag_spinbox
+
+    def unitsComboBox(self) -> QComboBox:
+        """Return the `QCombBox` widget used to edit the units."""
+        return self._units_combo
+
+    def _format_units(self, u: Union[Unit, str]) -> str:
+        if isinstance(u, str):
+            return u
+        return f"{u:~}" if self._abbreviate_units else f"{u:}"

src/superqt/utils/__init__.py

@@ -14,10 +14,12 @@ __all__ = (
     "signals_blocked",
     "thread_worker",
     "WorkerBase",
+    "exceptions_as_dialog",
 )
 
 from ._code_syntax_highlight import CodeSyntaxHighlight
 from ._ensure_thread import ensure_main_thread, ensure_object_thread
+from ._errormsg_context import exceptions_as_dialog
 from ._message_handler import QMessageHandler
 from ._misc import signals_blocked
 from ._qthreading import (

src/superqt/utils/_code_syntax_highlight.py

@@ -6,19 +6,17 @@ from pygments.lexers import find_lexer_class, get_lexer_by_name
 from pygments.util import ClassNotFound
 from qtpy import QtGui
 
-# inspired by  https://github.com/Vector35/snippets/blob/master/QCodeEditor.py (MIT license) and
+# inspired by  https://github.com/Vector35/snippets/blob/master/QCodeEditor.py
+# (MIT license) and
 # https://pygments.org/docs/formatterdevelopment/#html-3-2-formatter
 
 
 def get_text_char_format(style):
-    """
-    Return a QTextCharFormat with the given attributes.
-
-    https://pygments.org/docs/formatterdevelopment/#html-3-2-formatter
-    """
-
     text_char_format = QtGui.QTextCharFormat()
-    text_char_format.setFontFamily("monospace")
+    if hasattr(text_char_format, "setFontFamilies"):
+        text_char_format.setFontFamilies(["monospace"])
+    else:
+        text_char_format.setFontFamily("monospace")
     if style.get("color"):
         text_char_format.setForeground(QtGui.QColor(f"#{style['color']}"))
 
@@ -44,7 +42,8 @@ class QFormatter(Formatter):
         self._style = {name: get_text_char_format(style) for name, style in self.style}
 
     def format(self, tokensource, outfile):
-        """
+        """Format the given token stream.
+
         `outfile` is argument from parent class, but
         in Qt we do not produce string output, but QTextCharFormat, so it needs to be
         collected using `self.data`.
@@ -52,12 +51,7 @@ class QFormatter(Formatter):
         self.data = []
 
         for token, value in tokensource:
-            self.data.extend(
-                [
-                    self._style[token],
-                ]
-                * len(value)
-            )
+            self.data.extend([self._style[token]] * len(value))
 
 
 class CodeSyntaxHighlight(QtGui.QSyntaxHighlighter):
@@ -85,7 +79,8 @@ class CodeSyntaxHighlight(QtGui.QSyntaxHighlighter):
 
         # dirty, dirty hack
         # The core problem is that pygemnts by default use string streams,
-        # that will not handle QTextCharFormat, so wee need use `data` property to work around this.
+        # that will not handle QTextCharFormat, so we need use `data` property to
+        # work around this.
         for i in range(len(text)):
             try:
                 self.setFormat(i, 1, self.formatter.data[p + i - enters])

src/superqt/utils/_ensure_thread.py

@@ -1,7 +1,9 @@
 # https://gist.github.com/FlorianRhiem/41a1ad9b694c14fb9ac3
+from __future__ import annotations
+
 from concurrent.futures import Future
 from functools import wraps
-from typing import Callable, List, Optional
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, overload
 
 from qtpy.QtCore import (
     QCoreApplication,
@@ -13,12 +15,22 @@ from qtpy.QtCore import (
     Slot,
 )
 
+from ._util import get_max_args
+
+if TYPE_CHECKING:
+    from typing import TypeVar
+
+    from typing_extensions import Literal, ParamSpec
+
+    P = ParamSpec("P")
+    R = TypeVar("R")
+
 
 class CallCallable(QObject):
     finished = Signal(object)
-    instances: List["CallCallable"] = []
+    instances: ClassVar[list[CallCallable]] = []
 
-    def __init__(self, callable, *args, **kwargs):
+    def __init__(self, callable: Callable, args: tuple, kwargs: dict):
         super().__init__()
         self._callable = callable
         self._args = args
@@ -32,8 +44,34 @@ class CallCallable(QObject):
         self.finished.emit(res)
 
 
+# fmt: off
+@overload
 def ensure_main_thread(
-    func: Optional[Callable] = None, await_return: bool = False, timeout: int = 1000
+    await_return: Literal[True],
+    timeout: int = 1000,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+@overload
+def ensure_main_thread(
+    func: Callable[P, R],
+    await_return: Literal[True],
+    timeout: int = 1000,
+) -> Callable[P, R]: ...
+@overload
+def ensure_main_thread(
+    await_return: Literal[False] = False,
+    timeout: int = 1000,
+) -> Callable[[Callable[P, R]], Callable[P, Future[R]]]: ...
+@overload
+def ensure_main_thread(
+    func: Callable[P, R],
+    await_return: Literal[False] = False,
+    timeout: int = 1000,
+) -> Callable[P, Future[R]]: ...
+# fmt: on
+
+
+def ensure_main_thread(
+    func: Callable | None = None, await_return: bool = False, timeout: int = 1000
 ):
     """Decorator that ensures a function is called in the main QApplication thread.
 
@@ -52,26 +90,52 @@ def ensure_main_thread(
     """
 
     def _out_func(func_):
+        max_args = get_max_args(func_)
+
         @wraps(func_)
-        def _func(*args, **kwargs):
+        def _func(*args, _max_args_=max_args, **kwargs):
             return _run_in_thread(
                 func_,
                 QCoreApplication.instance().thread(),
                 await_return,
                 timeout,
-                *args,
-                **kwargs,
+                args[:_max_args_],
+                kwargs,
             )
 
         return _func
 
-    if func is None:
-        return _out_func
-    return _out_func(func)
+    return _out_func if func is None else _out_func(func)
+
+
+# fmt: off
+@overload
+def ensure_object_thread(
+    await_return: Literal[True],
+    timeout: int = 1000,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+@overload
+def ensure_object_thread(
+    func: Callable[P, R],
+    await_return: Literal[True],
+    timeout: int = 1000,
+) -> Callable[P, R]: ...
+@overload
+def ensure_object_thread(
+    await_return: Literal[False] = False,
+    timeout: int = 1000,
+) -> Callable[[Callable[P, R]], Callable[P, Future[R]]]: ...
+@overload
+def ensure_object_thread(
+    func: Callable[P, R],
+    await_return: Literal[False] = False,
+    timeout: int = 1000,
+) -> Callable[P, Future[R]]: ...
+# fmt: on
 
 
 def ensure_object_thread(
-    func: Optional[Callable] = None, await_return: bool = False, timeout: int = 1000
+    func: Callable | None = None, await_return: bool = False, timeout: int = 1000
 ):
     """Decorator that ensures a QObject method is called in the object's thread.
 
@@ -90,17 +154,18 @@ def ensure_object_thread(
     """
 
     def _out_func(func_):
+        max_args = get_max_args(func_)
+
         @wraps(func_)
-        def _func(self, *args, **kwargs):
+        def _func(*args, _max_args_=max_args, **kwargs):
+            thread = args[0].thread()  # self
             return _run_in_thread(
-                func_, self.thread(), await_return, timeout, self, *args, **kwargs
+                func_, thread, await_return, timeout, args[:_max_args_], kwargs
             )
 
         return _func
 
-    if func is None:
-        return _out_func
-    return _out_func(func)
+    return _out_func if func is None else _out_func(func)
 
 
 def _run_in_thread(
@@ -108,9 +173,9 @@ def _run_in_thread(
     thread: QThread,
     await_return: bool,
     timeout: int,
-    *args,
-    **kwargs,
-):
+    args: tuple,
+    kwargs: dict,
+) -> Any:
     future = Future()  # type: ignore
     if thread is QThread.currentThread():
         result = func(*args, **kwargs)
@@ -118,8 +183,9 @@ def _run_in_thread(
             future.set_result(result)
             return future
         return result
-    f = CallCallable(func, *args, **kwargs)
+
+    f = CallCallable(func, args, kwargs)
     f.moveToThread(thread)
     f.finished.connect(future.set_result, Qt.ConnectionType.DirectConnection)
-    QMetaObject.invokeMethod(f, "call", Qt.ConnectionType.QueuedConnection)  # type: ignore
+    QMetaObject.invokeMethod(f, "call", Qt.ConnectionType.QueuedConnection)  # type: ignore  # noqa
     return future.result(timeout=timeout / 1000) if await_return else future

src/superqt/utils/_ensure_thread.pyi

@@ -1,52 +0,0 @@
-from concurrent.futures import Future
-from typing import Callable, TypeVar, overload
-
-from typing_extensions import Literal, ParamSpec
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-@overload
-def ensure_main_thread(
-    await_return: Literal[True],
-    timeout: int = 1000,
-) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
-@overload
-def ensure_main_thread(
-    func: Callable[P, R],
-    await_return: Literal[True],
-    timeout: int = 1000,
-) -> Callable[P, R]: ...
-@overload
-def ensure_main_thread(
-    await_return: Literal[False] = False,
-    timeout: int = 1000,
-) -> Callable[[Callable[P, R]], Callable[P, Future[R]]]: ...
-@overload
-def ensure_main_thread(
-    func: Callable[P, R],
-    await_return: Literal[False] = False,
-    timeout: int = 1000,
-) -> Callable[P, Future[R]]: ...
-@overload
-def ensure_object_thread(
-    await_return: Literal[True],
-    timeout: int = 1000,
-) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
-@overload
-def ensure_object_thread(
-    func: Callable[P, R],
-    await_return: Literal[True],
-    timeout: int = 1000,
-) -> Callable[P, R]: ...
-@overload
-def ensure_object_thread(
-    await_return: Literal[False] = False,
-    timeout: int = 1000,
-) -> Callable[[Callable[P, R]], Callable[P, Future[R]]]: ...
-@overload
-def ensure_object_thread(
-    func: Callable[P, R],
-    await_return: Literal[False] = False,
-    timeout: int = 1000,
-) -> Callable[P, Future[R]]: ...

src/superqt/utils/_errormsg_context.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import traceback
+from contextlib import AbstractContextManager
+from typing import TYPE_CHECKING, cast
+
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QErrorMessage, QMessageBox, QWidget
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+_DEFAULT_FLAGS = Qt.WindowType.Dialog | Qt.WindowType.MSWindowsFixedSizeDialogHint
+
+
+class exceptions_as_dialog(AbstractContextManager):
+    """Context manager that shows a dialog when an exception is raised.
+
+    See examples below for common usage patterns.
+
+    To determine whether an exception was raised or not, check the `exception`
+    attribute after the context manager has exited.  If `use_error_message` is `False`
+    (the default), you can also access the `dialog` attribute to get/manipulate the
+    `QMessageBox` instance.
+
+    Parameters
+    ----------
+    exceptions : type[BaseException] | tuple[type[BaseException], ...], optional
+        The exception(s) to catch, by default `Exception` (i.e. all exceptions).
+    icon : QMessageBox.Icon, optional
+        The icon to show in the QMessageBox, by default `QMessageBox.Icon.Critical`
+    title : str, optional
+        The title of the `QMessageBox`, by default `"An error occurred"`.
+    msg_template : str, optional
+        The message to show in the `QMessageBox`. The message will be formatted
+        using three variables:
+
+        - `exc_value`: the exception instance
+        - `exc_type`: the exception type
+        - `tb`: the traceback as a string
+
+        The default template is the content of the exception: `"{exc_value}"`
+    buttons : QMessageBox.StandardButton, optional
+        The buttons to show in the `QMessageBox`, by default
+        `QMessageBox.StandardButton.Ok`
+    parent : QWidget | None, optional
+        The parent widget of the `QMessageBox`, by default `None`
+    use_error_message : bool | QErrorMessage, optional
+        Whether to use a `QErrorMessage` instead of a `QMessageBox`. By default
+        `False`. `QErrorMessage` shows a checkbox that the user can check to
+        prevent seeing the message again (based on the text of the formatted
+        `msg_template`.) If `True`, the global `QMessageError.qtHandler()`
+        instance is used to maintain a history of dismissed messages. You may also pass
+        a `QErrorMessage` instance to use a specific instance. If `use_error_message` is
+        True, or if you pass your own `QErrorMessage` instance, the `parent` argument
+        is ignored.
+
+    Attributes
+    ----------
+    dialog : QMessageBox | None
+        The `QMessageBox` instance that was created (if `use_error_message` was
+        `False`).  This can be used, among other things, to determine the result of
+        the dialog (e.g. `dialog.result()`) or to manipulate the dialog (e.g.
+        `dialog.setDetailedText("some text")`).
+    exception : BaseException | None
+        Will hold the exception instance if an exception was raised and caught.
+
+    Examplez
+    -------
+    ```python
+    from qtpy.QtWidgets import QApplication
+    from superqt.utils import exceptions_as_dialog
+
+    app = QApplication([])
+
+    with exceptions_as_dialog() as ctx:
+        raise Exception("This will be caught and shown in a QMessageBox")
+
+    # you can access the exception instance here
+    assert ctx.exception is not None
+
+    # with exceptions_as_dialog(ValueError):
+    #     1 / 0  # ZeroDivisionError is not caught, so this will raise
+
+    with exceptions_as_dialog(msg_template="Error: {exc_value}"):
+        raise Exception("This message will be inserted at 'exc_value'")
+
+    for _i in range(3):
+        with exceptions_as_dialog(AssertionError, use_error_message=True):
+            assert False, "Uncheck the checkbox to ignore this in the future"
+
+    # use ctx.dialog to get the result of the dialog
+    btns = QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
+    with exceptions_as_dialog(buttons=btns) as ctx:
+        raise Exception("This will be caught and shown in a QMessageBox")
+    print(ctx.dialog.result())  # prints which button was clicked
+
+    app.exec()  # needed only for the use_error_message example to show
+    ```
+    """
+
+    dialog: QMessageBox | None
+    exception: BaseException | None
+    exec_result: int | None = None
+
+    def __init__(
+        self,
+        exceptions: type[BaseException] | tuple[type[BaseException], ...] = Exception,
+        icon: QMessageBox.Icon = QMessageBox.Icon.Critical,
+        title: str = "An error occurred",
+        msg_template: str = "{exc_value}",
+        buttons: QMessageBox.StandardButton = QMessageBox.StandardButton.Ok,
+        parent: QWidget | None = None,
+        flags: Qt.WindowType = _DEFAULT_FLAGS,
+        use_error_message: bool | QErrorMessage = False,
+    ):
+        self.exceptions = exceptions
+        self.msg_template = msg_template
+        self.exception = None
+        self.dialog = None
+
+        self._err_msg = use_error_message
+
+        if not use_error_message:
+            # the message will be overwritten in __exit__
+            self.dialog = QMessageBox(
+                icon, title, "An error occurred", buttons, parent, flags
+            )
+
+    def __enter__(self) -> exceptions_as_dialog:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        tb: TracebackType | None,
+    ) -> bool:
+        if not (exc_value is not None and isinstance(exc_value, self.exceptions)):
+            return False  # let it propagate
+
+        # save the exception for later
+        self.exception = exc_value
+
+        # format the message using the context variables
+        if "{tb}" in self.msg_template:
+            _tb = "\n".join(traceback.format_exception(exc_type, exc_value, tb))
+        else:
+            _tb = ""
+        text = self.msg_template.format(exc_value=exc_value, exc_type=exc_type, tb=_tb)
+
+        # show the dialog
+        if self._err_msg:
+            msg = (
+                self._err_msg
+                if isinstance(self._err_msg, QErrorMessage)
+                else QErrorMessage.qtHandler()
+            )
+            cast("QErrorMessage", msg).showMessage(text)
+        elif self.dialog is not None:  # it won't be if use_error_message=False
+            self.dialog.setText(text)
+            self.dialog.exec()
+
+        return True  # swallow the exception

src/superqt/utils/_message_handler.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 import logging
 from contextlib import suppress
-from typing import List, NamedTuple, Optional
+from typing import ClassVar, NamedTuple
 
 from qtpy.QtCore import QMessageLogContext, QtMsgType, qInstallMessageHandler
 
@@ -28,7 +30,6 @@ class QMessageHandler:
 
     Examples
     --------
-
     >>> handler = QMessageHandler()
     >>> handler.install()  # now all Qt output will be available at mh.records
 
@@ -40,7 +41,7 @@ class QMessageHandler:
     ...    ...
     """
 
-    _qt2loggertype = {
+    _qt2loggertype: ClassVar[dict[QtMsgType, int]] = {
         QtMsgType.QtDebugMsg: logging.DEBUG,
         QtMsgType.QtInfoMsg: logging.INFO,
         QtMsgType.QtWarningMsg: logging.WARNING,
@@ -49,10 +50,10 @@ class QMessageHandler:
         QtMsgType.QtSystemMsg: logging.CRITICAL,
     }
 
-    def __init__(self, logger: Optional[logging.Logger] = None):
-        self.records: List[Record] = []
+    def __init__(self, logger: logging.Logger | None = None):
+        self.records: list[Record] = []
         self._logger = logger
-        self._previous_handler: Optional[object] = "__uninstalled__"
+        self._previous_handler: object | None = "__uninstalled__"
 
     def install(self):
         """Install this handler (override the current QtMessageHandler)."""
@@ -68,7 +69,7 @@ class QMessageHandler:
         return f"<{n} object at {hex(id(self))} with {len(self.records)} records>"
 
     def __enter__(self):
-        """Enter a context with this handler installed"""
+        """Enter a context with this handler installed."""
         self.install()
         return self
 

src/superqt/utils/_misc.py

@@ -7,7 +7,24 @@ if TYPE_CHECKING:
 
 @contextmanager
 def signals_blocked(obj: "QObject") -> Iterator[None]:
-    """Context manager to temporarily block signals emitted by QObject: `obj`."""
+    """Context manager to temporarily block signals emitted by QObject: `obj`.
+
+    Parameters
+    ----------
+    obj : QObject
+        The QObject whose signals should be blocked.
+
+    Examples
+    --------
+    ```python
+    from qtpy.QtWidgets import QSpinBox
+    from superqt import signals_blocked
+
+    spinbox = QSpinBox()
+    with signals_blocked(spinbox):
+        spinbox.setValue(10)
+    ```
+    """
     previous = obj.blockSignals(True)
     try:
         yield

src/superqt/utils/_qthreading.py

@@ -8,15 +8,11 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Callable,
-    Dict,
+    ClassVar,
     Generator,
     Generic,
-    Optional,
     Sequence,
-    Set,
-    Type,
     TypeVar,
-    Union,
     overload,
 )
 
@@ -27,7 +23,7 @@ if TYPE_CHECKING:
 
     class SigInst(Generic[_T]):
         @staticmethod
-        def connect(slot: Callable[[_T], Any], type: Optional[type] = ...) -> None:
+        def connect(slot: Callable[[_T], Any], type: type | None = ...) -> None:
             ...
 
         @staticmethod
@@ -61,7 +57,7 @@ def as_generator_function(
     """Turns a regular function (single return) into a generator function."""
 
     @wraps(func)
-    def genwrapper(*args, **kwargs) -> Generator[None, None, _R]:
+    def genwrapper(*args: Any, **kwargs: Any) -> Generator[None, None, _R]:
         yield
         return func(*args, **kwargs)
 
@@ -69,10 +65,9 @@ def as_generator_function(
 
 
 class WorkerBaseSignals(QObject):
-
     started = Signal()  # emitted when the work is started
     finished = Signal()  # emitted when the work is finished
-    _finished = Signal(object)  # emitted when the work is finished ro delete
+    _finished = Signal(object)  # emitted when the work is finished to delete
     returned = Signal(object)  # emitted with return value
     errored = Signal(object)  # emitted with error object on Exception
     warned = Signal(tuple)  # emitted with showwarning args on warning
@@ -92,8 +87,8 @@ class WorkerBase(QRunnable, Generic[_R]):
         signal emitter object. To allow identify which worker thread emitted signal.
     """
 
-    #: A set of Workers.  Add to set using :meth:`WorkerBase.start`
-    _worker_set: Set[WorkerBase] = set()
+    #: A set of Workers.  Add to set using `WorkerBase.start`
+    _worker_set: ClassVar[set[WorkerBase]] = set()
     returned: SigInst[_R]
     errored: SigInst[Exception]
     warned: SigInst[tuple]
@@ -102,8 +97,8 @@ class WorkerBase(QRunnable, Generic[_R]):
 
     def __init__(
         self,
-        func: Optional[Callable[_P, _R]] = None,
-        SignalsClass: Type[WorkerBaseSignals] = WorkerBaseSignals,
+        func: Callable[_P, _R] | None = None,
+        SignalsClass: type[WorkerBaseSignals] = WorkerBaseSignals,
     ) -> None:
         super().__init__()
         self._abort_requested = False
@@ -113,11 +108,11 @@ class WorkerBase(QRunnable, Generic[_R]):
     def __getattr__(self, name: str) -> SigInst:
         """Pass through attr requests to signals to simplify connection API.
 
-        The goal is to enable ``worker.yielded.connect`` instead of
-        ``worker.signals.yielded.connect``. Because multiple inheritance of Qt
+        The goal is to enable `worker.yielded.connect` instead of
+        `worker.signals.yielded.connect`. Because multiple inheritance of Qt
         classes is not well supported in PyQt, we have to use composition here
         (signals are provided by QObjects, and QRunnable is not a QObject). So
-        this passthrough allows us to connect to signals on the ``_signals``
+        this passthrough allows us to connect to signals on the `_signals`
         object.
         """
         # the Signal object is actually a class attribute
@@ -134,11 +129,10 @@ class WorkerBase(QRunnable, Generic[_R]):
     def quit(self) -> None:
         """Send a request to abort the worker.
 
-        .. note::
-
+        !!! note
             It is entirely up to subclasses to honor this method by checking
-            ``self.abort_requested`` periodically in their ``worker.work``
-            method, and exiting if ``True``.
+            `self.abort_requested` periodically in their `worker.work`
+            method, and exiting if `True`.
         """
         self._abort_requested = True
 
@@ -149,7 +143,7 @@ class WorkerBase(QRunnable, Generic[_R]):
 
     @property
     def is_running(self) -> bool:
-        """Whether the worker has been started"""
+        """Whether the worker has been started."""
         return self._running
 
     def run(self) -> None:
@@ -160,20 +154,20 @@ class WorkerBase(QRunnable, Generic[_R]):
 
         The order of method calls when starting a worker is:
 
-        .. code-block:: none
-
+        ```
            calls QThreadPool.globalInstance().start(worker)
            |               triggered by the QThreadPool.start() method
            |               |             called by worker.run
            |               |             |
            V               V             V
            worker.start -> worker.run -> worker.work
+        ```
 
         **This** is the function that actually gets called when calling
-        :func:`QThreadPool.start(worker)`.  It simply wraps the :meth:`work`
+        `QThreadPool.start(worker)`.  It simply wraps the `work()`
         method, and emits a few signals.  Subclasses should NOT override this
         method (except with good reason), and instead should implement
-        :meth:`work`.
+        `work()`.
         """
         self.started.emit()
         self._running = True
@@ -191,6 +185,7 @@ class WorkerBase(QRunnable, Generic[_R]):
                     warnings.warn(
                         f"RuntimeError in aborted thread: {result}",
                         RuntimeWarning,
+                        stacklevel=2,
                     )
                     return
                 else:
@@ -203,31 +198,31 @@ class WorkerBase(QRunnable, Generic[_R]):
         self.finished.emit()
         self._finished.emit(self)
 
-    def work(self) -> Union[Exception, _R]:
+    def work(self) -> Exception | _R:
         """Main method to execute the worker.
 
         The end-user should never need to call this function.
         But subclasses must implement this method (See
-        :meth:`GeneratorFunction.work` for an example implementation).
-        Minimally, it should check ``self.abort_requested`` periodically and
-        exit if True.
+        [`GeneratorFunction.work`][superqt.utils._qthreading.GeneratorWorker.work] for
+        an example implementation). Minimally, it should check `self.abort_requested`
+        periodically and exit if True.
 
         Examples
         --------
-        .. code-block:: python
+        ```python
+        class MyWorker(WorkerBase):
 
-            class MyWorker(WorkerBase):
-
-                def work(self):
-                    i = 0
-                    while True:
-                        if self.abort_requested:
-                            self.aborted.emit()
-                            break
-                        i += 1
-                        if i > max_iters:
-                            break
-                        time.sleep(0.5)
+            def work(self):
+                i = 0
+                while True:
+                    if self.abort_requested:
+                        self.aborted.emit()
+                        break
+                    i += 1
+                    if i > max_iters:
+                        break
+                    time.sleep(0.5)
+        ```
         """
         raise NotImplementedError(
             f'"{self.__class__.__name__}" failed to define work() method'
@@ -238,14 +233,14 @@ class WorkerBase(QRunnable, Generic[_R]):
 
         The order of method calls when starting a worker is:
 
-        .. code-block:: none
-
+        ```
            calls QThreadPool.globalInstance().start(worker)
            |               triggered by the QThreadPool.start() method
            |               |             called by worker.run
            |               |             |
            V               V             V
            worker.start -> worker.run -> worker.work
+        ```
         """
         if self in self._worker_set:
             raise RuntimeError("This worker is already started!")
@@ -268,36 +263,36 @@ class WorkerBase(QRunnable, Generic[_R]):
         cls._worker_set.discard(obj)
 
     @classmethod
-    def await_workers(cls, msecs: int = None) -> None:
+    def await_workers(cls, msecs: int | None = None) -> None:
         """Ask all workers to quit, and wait up to `msec` for quit.
 
-        Attempts to clean up all running workers by calling ``worker.quit()``
-        method.  Any workers in the ``WorkerBase._worker_set`` set will have this
+        Attempts to clean up all running workers by calling `worker.quit()`
+        method.  Any workers in the `WorkerBase._worker_set` set will have this
         method.
 
         By default, this function will block indefinitely, until worker threads
-        finish.  If a timeout is provided, a ``RuntimeError`` will be raised if
+        finish.  If a timeout is provided, a `RuntimeError` will be raised if
         the workers do not gracefully exit in the time requests, but the threads
         will NOT be killed.  It is (currently) left to the user to use their OS
         to force-quit rogue threads.
 
-        .. important::
+        !!! important
 
             If the user does not put any yields in their function, and the function
             is super long, it will just hang... For instance, there's no graceful
             way to kill this thread in python:
 
-            .. code-block:: python
-
-                @thread_worker
-                def ZZZzzz():
-                    time.sleep(10000000)
+            ```python
+            @thread_worker
+            def ZZZzzz():
+                time.sleep(10000000)
+            ```
 
             This is why it's always advisable to use a generator that periodically
             yields for long-running computations in another thread.
 
-            See `this stack-overflow post
-            <https://stackoverflow.com/questions/323972/is-there-any-way-to-kill-a-thread>`_
+            See [this stack-overflow
+            post](https://stackoverflow.com/questions/323972/is-there-any-way-to-kill-a-thread)
             for a good discussion on the difficulty of killing a rogue python thread:
 
         Parameters
@@ -326,12 +321,11 @@ class WorkerBase(QRunnable, Generic[_R]):
 class FunctionWorker(WorkerBase[_R]):
     """QRunnable with signals that wraps a simple long-running function.
 
-    .. note::
-
-        ``FunctionWorker`` does not provide a way to stop a very long-running
-        function (e.g. ``time.sleep(10000)``).  So whenever possible, it is
-        better to implement your long running function as a generator that
-        yields periodically, and use the :class:`GeneratorWorker` instead.
+    !!! note
+        `FunctionWorker` does not provide a way to stop a very long-running
+        function (e.g. `time.sleep(10000)`).  So whenever possible, it is better to
+        implement your long running function as a generator that yields periodically,
+        and use the [`GeneratorWorker`][superqt.utils.GeneratorWorker] instead.
 
     Parameters
     ----------
@@ -345,7 +339,7 @@ class FunctionWorker(WorkerBase[_R]):
     Raises
     ------
     TypeError
-        If ``func`` is a generator function and not a regular function.
+        If `func` is a generator function and not a regular function.
     """
 
     def __init__(self, func: Callable[_P, _R], *args, **kwargs):
@@ -365,7 +359,6 @@ class FunctionWorker(WorkerBase[_R]):
 
 
 class GeneratorWorkerSignals(WorkerBaseSignals):
-
     yielded = Signal(object)  # emitted with yielded values (if generator used)
     paused = Signal()  # emitted when a running job has successfully paused
     resumed = Signal()  # emitted when a paused job has successfully resumed
@@ -399,9 +392,9 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
 
     def __init__(
         self,
-        func: Callable[_P, Generator[_Y, Optional[_S], _R]],
+        func: Callable[_P, Generator[_Y, _S | None, _R]],
         *args,
-        SignalsClass: Type[WorkerBaseSignals] = GeneratorWorkerSignals,
+        SignalsClass: type[WorkerBaseSignals] = GeneratorWorkerSignals,
         **kwargs,
     ):
         if not inspect.isgeneratorfunction(func):
@@ -412,7 +405,7 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
         super().__init__(SignalsClass=SignalsClass)
 
         self._gen = func(*args, **kwargs)
-        self._incoming_value: Optional[_S] = None
+        self._incoming_value: _S | None = None
         self._pause_requested = False
         self._resume_requested = False
         self._paused = False
@@ -421,7 +414,7 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
         self._pause_interval = 0.01
         self.pbar = None
 
-    def work(self) -> Union[Optional[_R], Exception]:
+    def work(self) -> _R | None | Exception:
         """Core event loop that calls the original function.
 
         Enters a continual loop, yielding and returning from the original
@@ -447,14 +440,14 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
                 self.paused.emit()
                 continue
             try:
-                input = self._next_value()
-                output = self._gen.send(input)
+                _input = self._next_value()
+                output = self._gen.send(_input)
                 self.yielded.emit(output)
             except StopIteration as exc:
                 return exc.value
             except RuntimeError as exc:
                 # The worker has probably been deleted.  warning will be
-                # emitted in ``WorkerBase.run``
+                # emitted in `WorkerBase.run`
                 return exc
         return None
 
@@ -462,7 +455,7 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
         """Send a value into the function (if a generator was used)."""
         self._incoming_value = value
 
-    def _next_value(self) -> Optional[_S]:
+    def _next_value(self) -> _S | None:
         out = None
         if self._incoming_value is not None:
             out = self._incoming_value
@@ -501,9 +494,9 @@ class GeneratorWorker(WorkerBase, Generic[_Y, _S, _R]):
 def create_worker(
     func: Callable[_P, Generator[_Y, _S, _R]],
     *args,
-    _start_thread: Optional[bool] = None,
-    _connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    _worker_class: Union[Type[GeneratorWorker], Type[FunctionWorker], None] = None,
+    _start_thread: bool | None = None,
+    _connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    _worker_class: type[GeneratorWorker] | type[FunctionWorker] | None = None,
     _ignore_errors: bool = False,
     **kwargs,
 ) -> GeneratorWorker[_Y, _S, _R]:
@@ -514,9 +507,9 @@ def create_worker(
 def create_worker(
     func: Callable[_P, _R],
     *args,
-    _start_thread: Optional[bool] = None,
-    _connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    _worker_class: Union[Type[GeneratorWorker], Type[FunctionWorker], None] = None,
+    _start_thread: bool | None = None,
+    _connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    _worker_class: type[GeneratorWorker] | type[FunctionWorker] | None = None,
     _ignore_errors: bool = False,
     **kwargs,
 ) -> FunctionWorker[_R]:
@@ -526,46 +519,47 @@ def create_worker(
 def create_worker(
     func: Callable,
     *args,
-    _start_thread: Optional[bool] = None,
-    _connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    _worker_class: Union[Type[GeneratorWorker], Type[FunctionWorker], None] = None,
+    _start_thread: bool | None = None,
+    _connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    _worker_class: type[GeneratorWorker] | type[FunctionWorker] | None = None,
     _ignore_errors: bool = False,
     **kwargs,
-) -> Union[FunctionWorker, GeneratorWorker]:
+) -> FunctionWorker | GeneratorWorker:
     """Convenience function to start a function in another thread.
 
-    By default, uses :class:`Worker`, but a custom ``WorkerBase`` subclass may
-    be provided.  If so, it must be a subclass of :class:`Worker`, which
-    defines a standard set of signals and a run method.
+    By default, uses `FunctionWorker` for functions and `GeneratorWorker` for
+    generators, but a custom `WorkerBase` subclass may be provided.  If so, it must be a
+    subclass of `WorkerBase`, which defines a standard set of signals and a run method.
 
     Parameters
     ----------
     func : Callable
         The function to call in another thread.
-    _start_thread : bool, optional
+    _start_thread : bool
         Whether to immediaetly start the thread.  If False, the returned worker
-        must be manually started with ``worker.start()``. by default it will be
-        ``False`` if the ``_connect`` argument is ``None``, otherwise ``True``.
+        must be manually started with `worker.start()`. by default it will be
+        `False` if the `_connect` argument is `None`, otherwise `True`.
     _connect : Dict[str, Union[Callable, Sequence]], optional
-        A mapping of ``"signal_name"`` -> ``callable`` or list of ``callable``:
+        A mapping of `"signal_name"` -> `callable` or list of `callable`:
         callback functions to connect to the various signals offered by the
-        worker class. by default None
-    _worker_class : type of GeneratorWorker or FunctionWorker, optional
-        The :class`WorkerBase` to instantiate, by default
-        :class:`FunctionWorker` will be used if ``func`` is a regular function,
-        and :class:`GeneratorWorker` will be used if it is a generator.
-    _ignore_errors : bool, optional
-        If ``False`` (the default), errors raised in the other thread will be
+        worker class. by default `None`
+    _worker_class : type of `GeneratorWorker` or `FunctionWorker`, optional
+        The [`WorkerBase`][superqt.utils.WorkerBase] to instantiate, by default
+        [`FunctionWorker`][superqt.utils.FunctionWorker] will be used if `func` is a
+        regular function, and [`GeneratorWorker`][superqt.utils.GeneratorWorker] will be
+        used if it is a generator.
+    _ignore_errors : bool
+        If `False` (the default), errors raised in the other thread will be
         reraised in the main thread (makes debugging significantly easier).
     *args
-        will be passed to ``func``
+        will be passed to `func`
     **kwargs
-        will be passed to ``func``
+        will be passed to `func`
 
     Returns
     -------
     worker : WorkerBase
-        An instantiated worker.  If ``_start_thread`` was ``False``, the worker
+        An instantiated worker.  If `_start_thread` was `False`, the worker
         will have a `.start()` method that can be used to start the thread.
 
     Raises
@@ -573,20 +567,19 @@ def create_worker(
     TypeError
         If a worker_class is provided that is not a subclass of WorkerBase.
     TypeError
-        If _connect is provided and is not a dict of ``{str: callable}``
+        If _connect is provided and is not a dict of `{str: callable}`
 
     Examples
     --------
-    .. code-block:: python
-
-        def long_function(duration):
-            import time
-            time.sleep(duration)
-
-        worker = create_worker(long_function, 10)
+    ```python
+    def long_function(duration):
+        import time
+        time.sleep(duration)
 
+    worker = create_worker(long_function, 10)
+    ```
     """
-    worker: Union[FunctionWorker, GeneratorWorker]
+    worker: FunctionWorker | GeneratorWorker
 
     if not _worker_class:
         if inspect.isgeneratorfunction(func):
@@ -616,7 +609,7 @@ def create_worker(
                 getattr(worker, key).connect(v)
 
     # if the user has not provided a default connection for the "errored"
-    # signal... and they have not explicitly set ``ignore_errors=True``
+    # signal... and they have not explicitly set `ignore_errors=True`
     # Then rereaise any errors from the thread.
     if not _ignore_errors and not (_connect or {}).get("errored", False):
 
@@ -633,9 +626,9 @@ def create_worker(
 @overload
 def thread_worker(
     function: Callable[_P, Generator[_Y, _S, _R]],
-    start_thread: Optional[bool] = None,
-    connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    worker_class: Optional[Type[WorkerBase]] = None,
+    start_thread: bool | None = None,
+    connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    worker_class: type[WorkerBase] | None = None,
     ignore_errors: bool = False,
 ) -> Callable[_P, GeneratorWorker[_Y, _S, _R]]:
     ...
@@ -644,9 +637,9 @@ def thread_worker(
 @overload
 def thread_worker(
     function: Callable[_P, _R],
-    start_thread: Optional[bool] = None,
-    connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    worker_class: Optional[Type[WorkerBase]] = None,
+    start_thread: bool | None = None,
+    connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    worker_class: type[WorkerBase] | None = None,
     ignore_errors: bool = False,
 ) -> Callable[_P, FunctionWorker[_R]]:
     ...
@@ -655,72 +648,75 @@ def thread_worker(
 @overload
 def thread_worker(
     function: Literal[None] = None,
-    start_thread: Optional[bool] = None,
-    connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    worker_class: Optional[Type[WorkerBase]] = None,
+    start_thread: bool | None = None,
+    connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    worker_class: type[WorkerBase] | None = None,
     ignore_errors: bool = False,
-) -> Callable[[Callable], Callable[_P, Union[FunctionWorker, GeneratorWorker]]]:
+) -> Callable[[Callable], Callable[_P, FunctionWorker | GeneratorWorker]]:
     ...
 
 
 def thread_worker(
-    function: Optional[Callable] = None,
-    start_thread: Optional[bool] = None,
-    connect: Optional[Dict[str, Union[Callable, Sequence[Callable]]]] = None,
-    worker_class: Optional[Type[WorkerBase]] = None,
+    function: Callable | None = None,
+    start_thread: bool | None = None,
+    connect: dict[str, Callable | Sequence[Callable]] | None = None,
+    worker_class: type[WorkerBase] | None = None,
     ignore_errors: bool = False,
 ):
     """Decorator that runs a function in a separate thread when called.
 
-    When called, the decorated function returns a :class:`WorkerBase`.  See
-    :func:`create_worker` for additional keyword arguments that can be used
+    When called, the decorated function returns a
+    [`WorkerBase`][superqt.utils.WorkerBase].  See
+    [`create_worker`][superqt.utils.create_worker] for additional keyword arguments that
+    can be used
     when calling the function.
 
     The returned worker will have these signals:
 
-        - *started*: emitted when the work is started
-        - *finished*: emitted when the work is finished
-        - *returned*: emitted with return value
-        - *errored*: emitted with error object on Exception
+    - **started**: emitted when the work is started
+    - **finished**: emitted when the work is finished
+    - **returned**: emitted with return value
+    - **errored**: emitted with error object on Exception
 
-    It will also have a ``worker.start()`` method that can be used to start
+    It will also have a `worker.start()` method that can be used to start
     execution of the function in another thread. (useful if you need to connect
     callbacks to signals prior to execution)
 
     If the decorated function is a generator, the returned worker will also
     provide these signals:
 
-        - *yielded*: emitted with yielded values
-        - *paused*: emitted when a running job has successfully paused
-        - *resumed*: emitted when a paused job has successfully resumed
-        - *aborted*: emitted when a running job is successfully aborted
+    - **yielded**: emitted with yielded values
+    - **paused**: emitted when a running job has successfully paused
+    - **resumed**: emitted when a paused job has successfully resumed
+    - **aborted**: emitted when a running job is successfully aborted
 
     And these methods:
 
-        - *quit*: ask the thread to quit
-        - *toggle_paused*: toggle the running state of the thread.
-        - *send*: send a value into the generator.  (This requires that your
-          decorator function uses the ``value = yield`` syntax)
+    - **quit**: ask the thread to quit
+    - **toggle_paused**: toggle the running state of the thread.
+    - **send**: send a value into the generator.  (This requires that your
+      decorator function uses the `value = yield` syntax)
 
     Parameters
     ----------
     function : callable
         Function to call in another thread.  For communication between threads
         may be a generator function.
-    start_thread : bool, optional
+    start_thread : bool
         Whether to immediaetly start the thread.  If False, the returned worker
-        must be manually started with ``worker.start()``. by default it will be
-        ``False`` if the ``_connect`` argument is ``None``, otherwise ``True``.
-    connect : Dict[str, Union[Callable, Sequence]], optional
-        A mapping of ``"signal_name"`` -> ``callable`` or list of ``callable``:
+        must be manually started with `worker.start()`. by default it will be
+        `False` if the `_connect` argument is `None`, otherwise `True`.
+    connect : Dict[str, Union[Callable, Sequence]]
+        A mapping of `"signal_name"` -> `callable` or list of `callable`:
         callback functions to connect to the various signals offered by the
         worker class. by default None
-    worker_class : Type[WorkerBase], optional
-        The :class`WorkerBase` to instantiate, by default
-        :class:`FunctionWorker` will be used if ``func`` is a regular function,
-        and :class:`GeneratorWorker` will be used if it is a generator.
-    ignore_errors : bool, optional
-        If ``False`` (the default), errors raised in the other thread will be
+    worker_class : Type[WorkerBase]
+        The [`WorkerBase`][superqt.utils.WorkerBase] to instantiate, by default
+        [`FunctionWorker`][superqt.utils.FunctionWorker] will be used if `func` is a
+        regular function, and [`GeneratorWorker`][superqt.utils.GeneratorWorker] will be
+        used if it is a generator.
+    ignore_errors : bool
+        If `False` (the default), errors raised in the other thread will be
         reraised in the main thread (makes debugging significantly easier).
 
     Returns
@@ -731,25 +727,26 @@ def thread_worker(
 
     Examples
     --------
-    .. code-block:: python
+    ```python
+    @thread_worker
+    def long_function(start, end):
+        # do work, periodically yielding
+        i = start
+        while i <= end:
+            time.sleep(0.1)
+            yield i
 
-        @thread_worker
-        def long_function(start, end):
-            # do work, periodically yielding
-            i = start
-            while i <= end:
-                time.sleep(0.1)
-                yield i
+        # do teardown
+        return 'anything'
 
-            # do teardown
-            return 'anything'
+    # call the function to start running in another thread.
+    worker = long_function()
 
-        # call the function to start running in another thread.
-        worker = long_function()
-        # connect signals here if desired... or they may be added using the
-        # `connect` argument in the `@thread_worker` decorator... in which
-        # case the worker will start immediately when long_function() is called
-        worker.start()
+    # connect signals here if desired... or they may be added using the
+    # `connect` argument in the `@thread_worker` decorator... in which
+    # case the worker will start immediately when long_function() is called
+    worker.start()
+    ```
     """
 
     def _inner(func):
@@ -798,42 +795,27 @@ if TYPE_CHECKING:
 
 
 def new_worker_qthread(
-    Worker: Type[WorkerProtocol],
+    Worker: type[WorkerProtocol],
     *args,
     _start_thread: bool = False,
-    _connect: Dict[str, Callable] = None,
+    _connect: dict[str, Callable] | None = None,
     **kwargs,
 ):
-    """This is a convenience function to start a worker in a Qthread.
+    """Convenience function to start a worker in a `QThread`.
 
-    In most cases, the @thread_worker decorator is sufficient and preferable.
-    But this allows the user to completely customize the Worker object.
-    However, they must then maintain control over the thread and clean up
-    appropriately.
-
-    It follows the pattern described here:
-    https://www.qt.io/blog/2010/06/17/youre-doing-it-wrong
-    and
-    https://doc.qt.io/qt-5/qthread.html#details
-
-    see also:
-    https://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/
-
-    A QThread object is not a thread! It should be thought of as a class to
-    *manage* a thread, not as the actual code or object that runs in that
+    thread, not as the actual code or object that runs in that
     thread.  The QThread object is created on the main thread and lives there.
 
     Worker objects which derive from QObject are the things that actually do
     the work. They can be moved to a QThread as is done here.
 
-    .. note:: Mostly ignorable detail
+    ??? "Mostly ignorable detail"
 
         While the signals/slots syntax of the worker looks very similar to
         standard "single-threaded" signals & slots, note that inter-thread
-        signals and slots (automatically) use an event-based QueuedConnection,
-        while intra-thread signals use a DirectConnection. See `Signals and
-        Slots Across Threads
-        <https://doc.qt.io/qt-5/threads-qobject.html#signals-and-slots-across-threads>`_
+        signals and slots (automatically) use an event-based QueuedConnection, while
+        intra-thread signals use a DirectConnection. See [Signals and Slots Across
+        Threads](https://doc.qt.io/qt-5/threads-qobject.html#signals-and-slots-across-threads>)
 
     Parameters
     ----------
@@ -843,7 +825,7 @@ def new_worker_qthread(
     _start_thread : bool
         If True, thread will be started immediately, otherwise, thread must
         be manually started with thread.start().
-    _connect : dict, optional
+    _connect : dict
         Optional dictionary of {signal: function} to connect to the new worker.
         for instance:  _connect = {'incremented': myfunc} will result in:
         worker.incremented.connect(myfunc)
@@ -863,35 +845,34 @@ def new_worker_qthread(
     --------
     Create some QObject that has a long-running work method:
 
-    .. code-block:: python
+    ```python
 
-        class Worker(QObject):
+    class Worker(QObject):
 
-            finished = Signal()
-            increment = Signal(int)
+        finished = Signal()
+        increment = Signal(int)
 
-            def __init__(self, argument):
-                super().__init__()
-                self.argument = argument
+        def __init__(self, argument):
+            super().__init__()
+            self.argument = argument
 
-            @Slot()
-            def work(self):
-                # some long running task...
-                import time
-                for i in range(10):
-                    time.sleep(1)
-                    self.increment.emit(i)
-                self.finished.emit()
-
-        worker, thread = new_worker_qthread(
-            Worker,
-            'argument',
-            _start_thread=True,
-            _connect={'increment': print},
-        )
+        @Slot()
+        def work(self):
+            # some long running task...
+            import time
+            for i in range(10):
+                time.sleep(1)
+                self.increment.emit(i)
+            self.finished.emit()
 
+    worker, thread = new_worker_qthread(
+        Worker,
+        'argument',
+        _start_thread=True,
+        _connect={'increment': print},
+    )
+    ```
     """
-
     if _connect and not isinstance(_connect, dict):
         raise TypeError("_connect parameter must be a dict")
 

src/superqt/utils/_throttler.py

@@ -1,4 +1,4 @@
-"""Adapted for python from the KDToolBox
+"""Adapted for python from the KDToolBox.
 
 https://github.com/KDAB/KDToolBox/tree/master/qt/KDSignalThrottler
 
@@ -26,17 +26,20 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 """
-import sys
+from __future__ import annotations
+
 from concurrent.futures import Future
 from enum import IntFlag, auto
 from functools import wraps
-from typing import TYPE_CHECKING, Callable, Generic, Optional, TypeVar, Union, overload
+from typing import TYPE_CHECKING, Callable, Generic, TypeVar, overload
+from weakref import WeakKeyDictionary
 
 from qtpy.QtCore import QObject, Qt, QTimer, Signal
 
+from ._util import get_max_args
+
 if TYPE_CHECKING:
-    from qtpy.QtCore import SignalInstance
-    from typing_extensions import Literal, ParamSpec
+    from typing_extensions import ParamSpec
 
     P = ParamSpec("P")
 # maintain runtime compatibility with older typing_extensions
@@ -62,7 +65,6 @@ class EmissionPolicy(IntFlag):
 
 
 class GenericSignalThrottler(QObject):
-
     triggered = Signal()
     timeoutChanged = Signal(int)
     timerTypeChanged = Signal(Qt.TimerType)
@@ -71,7 +73,7 @@ class GenericSignalThrottler(QObject):
         self,
         kind: Kind,
         emissionPolicy: EmissionPolicy,
-        parent: Optional[QObject] = None,
+        parent: QObject | None = None,
     ) -> None:
         super().__init__(parent)
 
@@ -79,7 +81,7 @@ class GenericSignalThrottler(QObject):
         self._emissionPolicy = emissionPolicy
         self._hasPendingEmission = False
 
-        self._timer = QTimer()
+        self._timer = QTimer(parent=self)
         self._timer.setSingleShot(True)
         self._timer.setTimerType(Qt.TimerType.PreciseTimer)
         self._timer.timeout.connect(self._maybeEmitTriggered)
@@ -94,16 +96,16 @@ class GenericSignalThrottler(QObject):
 
     def timeout(self) -> int:
         """Return current timeout in milliseconds."""
-        return self._timer.interval()  # type: ignore
+        return self._timer.interval()
 
     def setTimeout(self, timeout: int) -> None:
-        """Set timeout in milliseconds"""
+        """Set timeout in milliseconds."""
         if self._timer.interval() != timeout:
             self._timer.setInterval(timeout)
             self.timeoutChanged.emit(timeout)
 
     def timerType(self) -> Qt.TimerType:
-        """Return current Qt.TimerType."""
+        """Return current `Qt.TimerType`."""
         return self._timer.timerType()
 
     def setTimerType(self, timerType: Qt.TimerType) -> None:
@@ -133,14 +135,12 @@ class GenericSignalThrottler(QObject):
         elif self._kind is Kind.Debouncer:
             self._timer.start()  # restart
 
-        assert self._timer.isActive()
-
     def cancel(self) -> None:
-        """ "Cancel and pending emissions."""
+        """Cancel any pending emissions."""
         self._hasPendingEmission = False
 
     def flush(self) -> None:
-        """ "Force emission of any pending emissions."""
+        """Force emission of any pending emissions."""
         self._maybeEmitTriggered()
 
     def _emitTriggered(self) -> None:
@@ -169,7 +169,7 @@ class QSignalThrottler(GenericSignalThrottler):
     def __init__(
         self,
         policy: EmissionPolicy = EmissionPolicy.Leading,
-        parent: Optional[QObject] = None,
+        parent: QObject | None = None,
     ) -> None:
         super().__init__(Kind.Throttler, policy, parent)
 
@@ -184,7 +184,7 @@ class QSignalDebouncer(GenericSignalThrottler):
     def __init__(
         self,
         policy: EmissionPolicy = EmissionPolicy.Trailing,
-        parent: Optional[QObject] = None,
+        parent: QObject | None = None,
     ) -> None:
         super().__init__(Kind.Debouncer, policy, parent)
 
@@ -192,30 +192,96 @@ class QSignalDebouncer(GenericSignalThrottler):
 # below here part is unique to superqt (not from KD)
 
 
-if TYPE_CHECKING:
-    from typing_extensions import Protocol
-
-    class ThrottledCallable(Generic[P, R], Protocol):
-        triggered: "SignalInstance"
-
-        def cancel(self) -> None:
-            ...
-
-        def flush(self) -> None:
-            ...
-
-        def set_timeout(self, timeout: int) -> None:
-            ...
-
-        if sys.version_info < (3, 9):
-
-            def __call__(self, *args: "P.args", **kwargs: "P.kwargs") -> Future:
-                ...
+class ThrottledCallable(GenericSignalThrottler, Generic[P, R]):
+    def __init__(
+        self,
+        func: Callable[P, R],
+        kind: Kind,
+        emissionPolicy: EmissionPolicy,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(kind, emissionPolicy, parent)
 
+        self._future: Future[R] = Future()
+        if isinstance(func, staticmethod):
+            self._func = func.__func__
         else:
+            self._func = func
 
-            def __call__(self, *args: "P.args", **kwargs: "P.kwargs") -> Future[R]:
-                ...
+        self.__wrapped__ = func
+
+        self._args: tuple = ()
+        self._kwargs: dict = {}
+        self.triggered.connect(self._set_future_result)
+        self._name = None
+
+        self._obj_dkt = WeakKeyDictionary()
+
+        # even if we were to compile __call__ with a signature matching that of func,
+        # PySide wouldn't correctly inspect the signature of the ThrottledCallable
+        # instance: https://bugreports.qt.io/browse/PYSIDE-2423
+        # so we do it ourselfs and limit the number of positional arguments
+        # that we pass to func
+        self._max_args: int | None = get_max_args(self._func)
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> "Future[R]":  # noqa
+        if not self._future.done():
+            self._future.cancel()
+
+        self._future = Future()
+        self._args = args
+        self._kwargs = kwargs
+
+        self.throttle()
+        return self._future
+
+    def _set_future_result(self):
+        result = self._func(*self._args[: self._max_args], **self._kwargs)
+        self._future.set_result(result)
+
+    def __set_name__(self, owner, name):
+        if not isinstance(self.__wrapped__, staticmethod):
+            self._name = name
+
+    def _get_throttler(self, instance, owner, parent, obj):
+        throttler = ThrottledCallable(
+            self.__wrapped__.__get__(instance, owner),
+            self._kind,
+            self._emissionPolicy,
+            parent=parent,
+        )
+        throttler.setTimerType(self.timerType())
+        throttler.setTimeout(self.timeout())
+        try:
+            setattr(
+                obj,
+                self._name,
+                throttler,
+            )
+        except AttributeError:
+            try:
+                self._obj_dkt[obj] = throttler
+            except TypeError as e:
+                raise TypeError(
+                    "To use qthrottled or qdebounced as a method decorator, "
+                    "objects must have  `__dict__` or be weak referenceable. "
+                    "Please either add `__weakref__` to `__slots__` or use"
+                    "qthrottled/qdebounced as a function (not a decorator)."
+                ) from e
+        return throttler
+
+    def __get__(self, instance, owner):
+        if instance is None or not self._name:
+            return self
+
+        if instance in self._obj_dkt:
+            return self._obj_dkt[instance]
+
+        parent = self.parent()
+        if parent is None and isinstance(instance, QObject):
+            parent = instance
+
+        return self._get_throttler(instance, owner, parent, instance)
 
 
 @overload
@@ -224,28 +290,29 @@ def qthrottled(
     timeout: int = 100,
     leading: bool = True,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> "ThrottledCallable[P, R]":
+    parent: QObject | None = None,
+) -> ThrottledCallable[P, R]:
     ...
 
 
 @overload
 def qthrottled(
-    func: "Literal[None]" = None,
+    func: None = ...,
     timeout: int = 100,
     leading: bool = True,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> Callable[[Callable[P, R]], "ThrottledCallable[P, R]"]:
+    parent: QObject | None = None,
+) -> Callable[[Callable[P, R]], ThrottledCallable[P, R]]:
     ...
 
 
 def qthrottled(
-    func: Optional[Callable[P, R]] = None,
+    func: Callable[P, R] | None = None,
     timeout: int = 100,
     leading: bool = True,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> Union[
-    "ThrottledCallable[P, R]", Callable[[Callable[P, R]], "ThrottledCallable[P, R]"]
-]:
+    parent: QObject | None = None,
+) -> ThrottledCallable[P, R] | Callable[[Callable[P, R]], ThrottledCallable[P, R]]:
     """Creates a throttled function that invokes func at most once per timeout.
 
     The throttled function comes with a `cancel` method to cancel delayed func
@@ -273,8 +340,11 @@ def qthrottled(
             - `Qt.CoarseTimer`: Coarse timers try to keep accuracy within 5% of the
               desired interval
             - `Qt.VeryCoarseTimer`: Very coarse timers only keep full second accuracy
+    parent: QObject or None
+        Parent object for timer. If using qthrottled as function it may be usefull
+        for cleaning data
     """
-    return _make_decorator(func, timeout, leading, timer_type, Kind.Throttler)
+    return _make_decorator(func, timeout, leading, timer_type, Kind.Throttler, parent)
 
 
 @overload
@@ -283,28 +353,29 @@ def qdebounced(
     timeout: int = 100,
     leading: bool = False,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> "ThrottledCallable[P, R]":
+    parent: QObject | None = None,
+) -> ThrottledCallable[P, R]:
     ...
 
 
 @overload
 def qdebounced(
-    func: "Literal[None]" = None,
+    func: None = ...,
     timeout: int = 100,
     leading: bool = False,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> Callable[[Callable[P, R]], "ThrottledCallable[P, R]"]:
+    parent: QObject | None = None,
+) -> Callable[[Callable[P, R]], ThrottledCallable[P, R]]:
     ...
 
 
 def qdebounced(
-    func: Optional[Callable[P, R]] = None,
+    func: Callable[P, R] | None = None,
     timeout: int = 100,
     leading: bool = False,
     timer_type: Qt.TimerType = Qt.TimerType.PreciseTimer,
-) -> Union[
-    "ThrottledCallable[P, R]", Callable[[Callable[P, R]], "ThrottledCallable[P, R]"]
-]:
+    parent: QObject | None = None,
+) -> ThrottledCallable[P, R] | Callable[[Callable[P, R]], ThrottledCallable[P, R]]:
     """Creates a debounced function that delays invoking `func`.
 
     `func` will not be invoked until `timeout` ms have elapsed since the last time
@@ -335,46 +406,31 @@ def qdebounced(
             - `Qt.CoarseTimer`: Coarse timers try to keep accuracy within 5% of the
               desired interval
             - `Qt.VeryCoarseTimer`: Very coarse timers only keep full second accuracy
+    parent: QObject or None
+        Parent object for timer. If using qthrottled as function it may be usefull
+        for cleaning data
     """
-    return _make_decorator(func, timeout, leading, timer_type, Kind.Debouncer)
+    return _make_decorator(func, timeout, leading, timer_type, Kind.Debouncer, parent)
 
 
 def _make_decorator(
-    func: Optional[Callable[P, R]],
+    func: Callable[P, R] | None,
     timeout: int,
     leading: bool,
     timer_type: Qt.TimerType,
     kind: Kind,
-) -> Union[
-    "ThrottledCallable[P, R]", Callable[[Callable[P, R]], "ThrottledCallable[P, R]"]
-]:
-    def deco(func: Callable[P, R]) -> "ThrottledCallable[P, R]":
+    parent: QObject | None = None,
+) -> ThrottledCallable[P, R] | Callable[[Callable[P, R]], ThrottledCallable[P, R]]:
+    def deco(func: Callable[P, R]) -> ThrottledCallable[P, R]:
+        nonlocal parent
+
+        instance: object | None = getattr(func, "__self__", None)
+        if isinstance(instance, QObject) and parent is None:
+            parent = instance
         policy = EmissionPolicy.Leading if leading else EmissionPolicy.Trailing
-        throttle = GenericSignalThrottler(kind, policy)
-        throttle.setTimerType(timer_type)
-        throttle.setTimeout(timeout)
-        last_f = None
-        future: Optional[Future] = None
-
-        @wraps(func)
-        def inner(*args: "P.args", **kwargs: "P.kwargs") -> Future:
-            nonlocal last_f
-            nonlocal future
-            if last_f is not None:
-                throttle.triggered.disconnect(last_f)
-            if future is not None and not future.done():
-                future.cancel()
-
-            future = Future()
-            last_f = lambda: future.set_result(func(*args, **kwargs))  # noqa
-            throttle.triggered.connect(last_f)
-            throttle.throttle()
-            return future
-
-        setattr(inner, "cancel", throttle.cancel)
-        setattr(inner, "flush", throttle.flush)
-        setattr(inner, "set_timeout", throttle.setTimeout)
-        setattr(inner, "triggered", throttle.triggered)
-        return inner  # type: ignore
+        obj = ThrottledCallable(func, kind, policy, parent=parent)
+        obj.setTimerType(timer_type)
+        obj.setTimeout(timeout)
+        return wraps(func)(obj)
 
     return deco(func) if func is not None else deco

src/superqt/utils/_util.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from inspect import signature
+from typing import Callable
+
+
+def get_max_args(func: Callable) -> int | None:
+    """Return the maximum number of positional arguments that func can accept."""
+    if not callable(func):
+        raise TypeError(f"{func!r} is not callable")
+
+    try:
+        sig = signature(func)
+    except Exception:
+        return None
+
+    max_args = 0
+    for param in sig.parameters.values():
+        if param.kind == param.VAR_POSITIONAL:
+            return None
+        if param.kind in {param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD}:
+            max_args += 1
+    return max_args

tests/test_collapsible.py

@@ -1,11 +1,23 @@
 """A test module for testing collapsible"""
 
-from qtpy.QtCore import QEasingCurve
-from qtpy.QtWidgets import QPushButton
+from qtpy.QtCore import QEasingCurve, Qt
+from qtpy.QtGui import QIcon
+from qtpy.QtWidgets import QPushButton, QStyle, QWidget
 
 from superqt import QCollapsible
 
 
+def _get_builtin_icon(name: str) -> QIcon:
+    """Get a built-in icon from the Qt library."""
+    widget = QWidget()
+    try:
+        pixmap = getattr(QStyle.StandardPixmap, f"SP_{name}")
+    except AttributeError:
+        pixmap = getattr(QStyle, f"SP_{name}")
+
+    return widget.style().standardIcon(pixmap)
+
+
 def test_checked_initialization(qtbot):
     """Test simple collapsible"""
     wdg1 = QCollapsible("Advanced analysis")
@@ -84,4 +96,44 @@ def test_changing_text(qtbot):
     wdg = QCollapsible()
     wdg.setText("Hi new text")
     assert wdg.text() == "Hi new text"
-    assert wdg._toggle_btn.text() == QCollapsible._COLLAPSED + "Hi new text"
+    assert wdg._toggle_btn.text() == "Hi new text"
+
+
+def test_toggle_signal(qtbot):
+    """Test that signal is emitted when widget expanded/collapsed."""
+    wdg = QCollapsible()
+    with qtbot.waitSignal(wdg.toggled, timeout=500):
+        qtbot.mouseClick(wdg._toggle_btn, Qt.LeftButton)
+
+    with qtbot.waitSignal(wdg.toggled, timeout=500):
+        wdg.expand()
+
+    with qtbot.waitSignal(wdg.toggled, timeout=500):
+        wdg.collapse()
+
+
+def test_getting_icon(qtbot):
+    """Test setting string as toggle button."""
+    wdg = QCollapsible("test")
+    assert isinstance(wdg.expandedIcon(), QIcon)
+    assert isinstance(wdg.collapsedIcon(), QIcon)
+
+
+def test_setting_icon(qtbot):
+    """Test setting icon for toggle button."""
+    icon1 = _get_builtin_icon("ArrowRight")
+    icon2 = _get_builtin_icon("ArrowDown")
+    wdg = QCollapsible("test", expandedIcon=icon1, collapsedIcon=icon2)
+    assert wdg._expanded_icon == icon1
+    assert wdg._collapsed_icon == icon2
+
+
+def test_setting_symbol_icon(qtbot):
+    """Test setting string as toggle button."""
+    wdg = QCollapsible("test")
+    icon1 = wdg._convert_string_to_icon("+")
+    icon2 = wdg._convert_string_to_icon("-")
+    wdg.setCollapsedIcon(icon=icon1)
+    assert wdg._collapsed_icon == icon1
+    wdg.setExpandedIcon(icon=icon2)
+    assert wdg._expanded_icon == icon2

tests/test_eliding_label.py

@@ -31,14 +31,14 @@ def test_wrapped_eliding_label(qtbot):
     qtbot.addWidget(wdg)
     assert not wdg.wordWrap()
     assert 630 < wdg.sizeHint().width() < 640
-    assert wdg._elidedText().endswith("…")
+    assert wdg._elidedText().endswith(ELLIPSIS)
     wdg.resize(QSize(200, 100))
     assert wdg.text() == TEXT
-    assert wdg._elidedText().endswith("…")
+    assert wdg._elidedText().endswith(ELLIPSIS)
     wdg.setWordWrap(True)
     assert wdg.wordWrap()
     assert wdg.text() == TEXT
-    assert wdg._elidedText().endswith("…")
+    assert wdg._elidedText().endswith(ELLIPSIS)
     # just empirically from CI ... stupid
     if platform.system() == "Linux":
         assert wdg.sizeHint() in (QSize(200, 198), QSize(200, 154))

tests/test_eliding_line_edit.py

@@ -0,0 +1,60 @@
+from qtpy.QtCore import QSize, Qt
+from qtpy.QtGui import QResizeEvent
+
+from superqt import QElidingLineEdit
+
+TEXT = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do"
+ELLIPSIS = "…"
+
+
+def test_init_text_eliding_line_edit(qtbot):
+    wdg = QElidingLineEdit(TEXT)
+    qtbot.addWidget(wdg)
+    oldsize = QSize(100, 20)
+    wdg.resize(oldsize)
+    assert wdg._elidedText().endswith(ELLIPSIS)
+    newsize = QSize(500, 20)
+    wdg.resize(newsize)
+    wdg.resizeEvent(QResizeEvent(oldsize, newsize))  # for test coverage
+    assert wdg._elidedText() == TEXT
+    assert wdg.text() == TEXT
+
+
+def test_set_text_eliding_line_edit(qtbot):
+    wdg = QElidingLineEdit()
+    qtbot.addWidget(wdg)
+    wdg.resize(500, 20)
+    wdg.setText(TEXT)
+    assert not wdg._elidedText().endswith(ELLIPSIS)
+    wdg.resize(100, 20)
+    assert wdg._elidedText().endswith(ELLIPSIS)
+
+
+def test_set_elide_mode_eliding_line_edit(qtbot):
+    wdg = QElidingLineEdit()
+    qtbot.addWidget(wdg)
+    wdg.resize(500, 20)
+    wdg.setText(TEXT)
+    assert not wdg._elidedText().endswith(ELLIPSIS)
+    wdg.resize(100, 20)
+    # ellipses should be to the right
+    assert wdg._elidedText().endswith(ELLIPSIS)
+
+    # ellipses should be to the left
+    wdg.setElideMode(Qt.TextElideMode.ElideLeft)
+    assert wdg._elidedText().startswith(ELLIPSIS)
+    assert wdg.elideMode() == Qt.TextElideMode.ElideLeft
+
+    # no ellipses should be shown
+    wdg.setElideMode(Qt.TextElideMode.ElideNone)
+    assert ELLIPSIS not in wdg._elidedText()
+
+
+def test_set_elipses_width_eliding_line_edit(qtbot):
+    wdg = QElidingLineEdit()
+    qtbot.addWidget(wdg)
+    wdg.resize(500, 20)
+    wdg.setText(TEXT)
+    assert not wdg._elidedText().endswith(ELLIPSIS)
+    wdg.setEllipsesWidth(int(wdg.width() / 2))
+    assert wdg._elidedText().endswith(ELLIPSIS)

tests/test_ensure_thread.py

@@ -1,7 +1,10 @@
 import inspect
 import os
+import threading
 import time
 from concurrent.futures import Future, TimeoutError
+from functools import wraps
+from unittest.mock import Mock
 
 import pytest
 from qtpy.QtCore import QCoreApplication, QObject, QThread, Signal
@@ -158,8 +161,8 @@ def test_names(qapp):
     assert ob.check_object_thread_return_future.__doc__ == "sample docstring"
     signature = inspect.signature(ob.check_object_thread_return_future)
     assert len(signature.parameters) == 1
-    assert list(signature.parameters.values())[0].name == "a"
-    assert list(signature.parameters.values())[0].annotation == int
+    assert next(iter(signature.parameters.values())).name == "a"
+    assert next(iter(signature.parameters.values())).annotation == int
     assert ob.check_main_thread_return.__name__ == "check_main_thread_return"
 
 
@@ -217,3 +220,80 @@ def test_object_thread(qtbot):
     assert ob.thread() is thread
     with qtbot.waitSignal(thread.finished):
         thread.quit()
+
+
+@pytest.mark.parametrize("mode", ["method", "func", "wrapped"])
+@pytest.mark.parametrize("deco", [ensure_main_thread, ensure_object_thread])
+def test_ensure_thread_sig_inspection(deco, mode):
+    class Emitter(QObject):
+        sig = Signal(int, int, int)
+
+    obj = Emitter()
+    mock = Mock()
+
+    if mode == "method":
+
+        class Receiver(QObject):
+            @deco
+            def func(self, a: int, b: int):
+                mock(a, b)
+
+        r = Receiver()
+        obj.sig.connect(r.func)
+    elif deco == ensure_object_thread:
+        return  # not compatible with function types
+
+    elif mode == "wrapped":
+
+        def wr(fun):
+            @wraps(fun)
+            def wr2(*args):
+                mock(*args)
+                return fun(*args) * 2
+
+            return wr2
+
+        @deco
+        @wr
+        def wrapped_func(a, b):
+            return a + b
+
+        obj.sig.connect(wrapped_func)
+
+    elif mode == "func":
+
+        @deco
+        def func(a: int, b: int) -> None:
+            mock(a, b)
+
+        obj.sig.connect(func)
+
+    # this is the crux of the test...
+    # we emit 3 args, but the function only takes 2
+    # this should normally work fine in Qt.
+    # testing here that the decorator doesn't break it.
+    obj.sig.emit(1, 2, 3)
+    mock.assert_called_once_with(1, 2)
+
+
+def test_main_thread_function(qtbot):
+    """Testing decorator on a function rather than QObject method."""
+
+    mock = Mock()
+
+    class Emitter(QObject):
+        sig = Signal(int, int, int)
+
+    @ensure_main_thread
+    def func(x: int) -> None:
+        mock(x, QThread.currentThread())
+
+    e = Emitter()
+    e.sig.connect(func)
+
+    with qtbot.waitSignal(e.sig):
+        thread = threading.Thread(target=e.sig.emit, args=(1, 2, 3))
+        thread.start()
+        thread.join()
+
+    mock.assert_called_once_with(1, QCoreApplication.instance().thread())

tests/test_enum_comb_box.py

@@ -11,6 +11,8 @@ class Enum1(Enum):
     b = 2
     c = 3
 
+    ALIAS = a
+
 
 class Enum2(Enum):
     d = 1

tests/test_fonticon/test_plugins.py

@@ -12,7 +12,7 @@ FIXTURES = Path(__file__).parent / "fixtures"
 
 @pytest.fixture
 def plugin_store(qapp, monkeypatch):
-    _path = [str(FIXTURES)] + sys.path.copy()
+    _path = [str(FIXTURES), *sys.path.copy()]
     store = QFontIconStore().instance()
     with monkeypatch.context() as m:
         m.setattr(sys, "path", _path)

tests/test_large_int_spinbox.py

@@ -72,3 +72,16 @@ def test_keyboard_tracking(qtbot):
         sb.lineEdit().setText("25")
     assert sb._pending_emit is False
     assert sgnl.args == [25]
+
+
+def test_large_spinbox_step_type(qtbot):
+    sb = QLargeIntSpinBox()
+    qtbot.addWidget(sb)
+    sb.setMaximum(1_000_000_000)
+    sb.setStepType(sb.StepType.AdaptiveDecimalStepType)
+    sb.setValue(1_000_000)
+    sb.stepBy(1)
+    assert sb.value() == 1_100_000
+    sb.setStepType(sb.StepType.DefaultStepType)
+    sb.stepBy(1)
+    assert sb.value() == 1_100_001

tests/test_qmessage_handler.py

@@ -28,9 +28,9 @@ def test_message_handler_with_logger(caplog):
         QtCore.qCritical("critical")
 
     assert len(caplog.records) == 3
-    caplog.records[0].message == "debug"
-    caplog.records[0].levelno == logging.DEBUG
-    caplog.records[1].message == "warning"
-    caplog.records[1].levelno == logging.WARNING
-    caplog.records[2].message == "critical"
-    caplog.records[2].levelno == logging.CRITICAL
+    assert caplog.records[0].message == "debug"
+    assert caplog.records[0].levelno == logging.DEBUG
+    assert caplog.records[1].message == "warning"
+    assert caplog.records[1].levelno == logging.WARNING
+    assert caplog.records[2].message == "critical"
+    assert caplog.records[2].levelno == logging.CRITICAL

tests/test_quantity.py

@@ -0,0 +1,41 @@
+from pint import Quantity
+
+from superqt import QQuantity
+
+
+def test_qquantity(qtbot):
+    w = QQuantity(1, "m")
+    qtbot.addWidget(w)
+
+    assert w.value() == 1 * w.unitRegistry().meter
+    assert w.magnitude() == 1
+    assert w.units() == w.unitRegistry().meter
+    assert w.text() == "1 meter"
+    w.setUnits("cm")
+    assert w.value() == 100 * w.unitRegistry().centimeter
+    assert w.magnitude() == 100
+    assert w.units() == w.unitRegistry().centimeter
+    assert w.text() == "100.0 centimeter"
+    w.setMagnitude(10)
+    assert w.value() == 10 * w.unitRegistry().centimeter
+    assert w.magnitude() == 10
+    assert w.units() == w.unitRegistry().centimeter
+    assert w.text() == "10 centimeter"
+    w.setValue(1 * w.unitRegistry().meter)
+    assert w.value() == 1 * w.unitRegistry().meter
+    assert w.magnitude() == 1
+    assert w.units() == w.unitRegistry().meter
+    assert w.text() == "1 meter"
+
+    w.setUnits(None)
+    assert w.isDimensionless()
+    assert w.unitsComboBox().currentText() == "-----"
+    assert w.magnitude() == 1
+
+
+def test_change_qquantity_value(qtbot):
+    w = QQuantity()
+    qtbot.addWidget(w)
+    assert w.value() == Quantity(0)
+    w.setValue(Quantity("1 meter"))
+    assert w.value() == Quantity("1 meter")

tests/test_searchable_tree.py

@@ -0,0 +1,151 @@
+from typing import List, Tuple
+
+import pytest
+from pytestqt.qtbot import QtBot
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QTreeWidget, QTreeWidgetItem
+
+from superqt import QSearchableTreeWidget
+
+
+@pytest.fixture
+def data() -> dict:
+    return {
+        "none": None,
+        "str": "test",
+        "int": 42,
+        "list": [2, 3, 5],
+        "dict": {
+            "float": 0.5,
+            "tuple": (22, 99),
+            "bool": False,
+        },
+    }
+
+
+@pytest.fixture
+def widget(qtbot: QtBot, data: dict) -> QSearchableTreeWidget:
+    widget = QSearchableTreeWidget.fromData(data)
+    qtbot.addWidget(widget)
+    return widget
+
+
+def columns(item: QTreeWidgetItem) -> Tuple[str, str]:
+    return item.text(0), item.text(1)
+
+
+def all_items(tree: QTreeWidget) -> List[QTreeWidgetItem]:
+    return tree.findItems("", Qt.MatchContains | Qt.MatchRecursive)
+
+
+def shown_items(tree: QTreeWidget) -> List[QTreeWidgetItem]:
+    items = all_items(tree)
+    return [item for item in items if not item.isHidden()]
+
+
+def test_init(qtbot: QtBot):
+    widget = QSearchableTreeWidget()
+    qtbot.addWidget(widget)
+    assert widget.tree.topLevelItemCount() == 0
+
+
+def test_from_data(qtbot: QtBot, data: dict):
+    widget = QSearchableTreeWidget.fromData(data)
+    qtbot.addWidget(widget)
+    tree = widget.tree
+
+    assert tree.topLevelItemCount() == 5
+
+    none_item = tree.topLevelItem(0)
+    assert columns(none_item) == ("none", "None")
+    assert none_item.childCount() == 0
+
+    str_item = tree.topLevelItem(1)
+    assert columns(str_item) == ("str", "test")
+    assert str_item.childCount() == 0
+
+    int_item = tree.topLevelItem(2)
+    assert columns(int_item) == ("int", "42")
+    assert int_item.childCount() == 0
+
+    list_item = tree.topLevelItem(3)
+    assert columns(list_item) == ("list", "list")
+    assert list_item.childCount() == 3
+    assert columns(list_item.child(0)) == ("0", "2")
+    assert columns(list_item.child(1)) == ("1", "3")
+    assert columns(list_item.child(2)) == ("2", "5")
+
+    dict_item = tree.topLevelItem(4)
+    assert columns(dict_item) == ("dict", "dict")
+    assert dict_item.childCount() == 3
+    assert columns(dict_item.child(0)) == ("float", "0.5")
+    tuple_item = dict_item.child(1)
+    assert columns(tuple_item) == ("tuple", "tuple")
+    assert tuple_item.childCount() == 2
+    assert columns(tuple_item.child(0)) == ("0", "22")
+    assert columns(tuple_item.child(1)) == ("1", "99")
+    assert columns(dict_item.child(2)) == ("bool", "False")
+
+
+def test_set_data(widget: QSearchableTreeWidget):
+    tree = widget.tree
+    assert tree.topLevelItemCount() != 1
+
+    widget.setData({"test": "reset"})
+
+    assert tree.topLevelItemCount() == 1
+    assert columns(tree.topLevelItem(0)) == ("test", "reset")
+
+
+def test_search_no_match(widget: QSearchableTreeWidget):
+    widget.filter.setText("no match here")
+    items = shown_items(widget.tree)
+    assert len(items) == 0
+
+
+def test_search_all_match(widget: QSearchableTreeWidget):
+    widget.filter.setText("")
+    tree = widget.tree
+    assert all_items(tree) == shown_items(tree)
+
+
+def test_search_match_one_key(widget: QSearchableTreeWidget):
+    widget.filter.setText("int")
+    items = shown_items(widget.tree)
+    assert len(items) == 1
+    assert columns(items[0]) == ("int", "42")
+
+
+def test_search_match_one_value(widget: QSearchableTreeWidget):
+    widget.filter.setText("test")
+    items = shown_items(widget.tree)
+    assert len(items) == 1
+    assert columns(items[0]) == ("str", "test")
+
+
+def test_search_match_many_keys(widget: QSearchableTreeWidget):
+    widget.filter.setText("n")
+    items = shown_items(widget.tree)
+    assert len(items) == 2
+    assert columns(items[0]) == ("none", "None")
+    assert columns(items[1]) == ("int", "42")
+
+
+def test_search_match_one_show_unmatched_descendants(widget: QSearchableTreeWidget):
+    widget.filter.setText("list")
+    items = shown_items(widget.tree)
+    assert len(items) == 4
+    assert columns(items[0]) == ("list", "list")
+    assert columns(items[1]) == ("0", "2")
+    assert columns(items[2]) == ("1", "3")
+    assert columns(items[3]) == ("2", "5")
+
+
+def test_search_match_one_show_unmatched_ancestors(widget: QSearchableTreeWidget):
+    widget.filter.setText("tuple")
+    items = shown_items(widget.tree)
+    assert len(items) == 4
+    assert columns(items[0]) == ("dict", "dict")
+    assert columns(items[1]) == ("tuple", "tuple")
+    assert columns(items[2]) == ("0", "22")
+    assert columns(items[3]) == ("1", "99")

tests/test_sliders/_testutil.py

@@ -15,15 +15,18 @@ skip_on_linux_qt6 = pytest.mark.skipif(
     reason="hover events not working on linux pyqt6",
 )
 
+_PointF = QPointF()
 
-def _mouse_event(pos=QPointF(), type_=QEvent.Type.MouseMove):
+
+def _mouse_event(pos=_PointF, type_=QEvent.Type.MouseMove):
     """Create a mouse event of `type_` at `pos`."""
     return QMouseEvent(
         type_,
-        QPointF(pos),
-        Qt.MouseButton.LeftButton,
-        Qt.MouseButton.LeftButton,
-        Qt.KeyboardModifier.NoModifier,
+        QPointF(pos),  # localPos
+        QPointF(),  # windowPos / globalPos
+        Qt.MouseButton.LeftButton,  # button
+        Qt.MouseButton.LeftButton,  # buttons
+        Qt.KeyboardModifier.NoModifier,  # modifiers
     )
 
 

tests/test_sliders/test_float.py

@@ -35,7 +35,7 @@ def ds(qtbot, request):
     def assert_val_type():
         type_ = float
         if cls in range_types:
-            assert all([isinstance(i, type_) for i in wdg.value()])  # sourcery skip
+            assert all(isinstance(i, type_) for i in wdg.value())  # sourcery skip
         else:
             assert isinstance(wdg.value(), type_)
 

tests/test_sliders/test_generic_slider.py

@@ -116,7 +116,6 @@ def test_press_move_release(gslider: _GenericSlider, qtbot):
 
 @skip_on_linux_qt6
 def test_hover(gslider: _GenericSlider):
-
     # stub
     opt = QStyleOptionSlider()
     gslider.initStyleOption(opt)

tests/test_sliders/test_labeled_slider.py

@@ -1,4 +1,3 @@
-import sys
 from typing import Any, Iterable
 from unittest.mock import Mock
 
@@ -26,8 +25,7 @@ def test_slider_connect_works(qtbot):
 
 def _assert_types(args: Iterable[Any], type_: type):
     # sourcery skip: comprehension-to-generator
-    if sys.version_info >= (3, 8):
-        assert all([isinstance(v, type_) for v in args]), "invalid type"
+    assert all(isinstance(v, type_) for v in args), "invalid type"
 
 
 @pytest.mark.parametrize("cls", [QLabeledDoubleSlider, QLabeledSlider])
@@ -67,12 +65,21 @@ def test_labeled_signals(cls, qtbot):
 @pytest.mark.parametrize(
     "cls", [QLabeledDoubleSlider, QLabeledRangeSlider, QLabeledSlider]
 )
-def test_editing_finished_signal(cls):
-    slider = cls()
+def test_editing_finished_signal(cls, qtbot):
     mock = Mock()
+    slider = cls()
+    qtbot.addWidget(slider)
     slider.editingFinished.connect(mock)
     if hasattr(slider, "_label"):
         slider._label.editingFinished.emit()
     else:
         slider._min_label.editingFinished.emit()
     mock.assert_called_once()
+
+
+def test_editing_float(qtbot):
+    slider = QLabeledDoubleSlider()
+    qtbot.addWidget(slider)
+    slider._label.setValue(0.5)
+    slider._label.editingFinished.emit()
+    assert slider.value() == 0.5