feat: add freedesktop_theme convenience to generate a theme folder (#8

)

* update docs

* main export

* fix tests

* fix coverage

* update readme

.github/workflows/ci.yml

@@ -30,6 +30,7 @@ jobs:
             platform: windows-latest
           - python-version: "3.10"
             platform: macos-latest
+            with-qt: true
 
     steps:
       - uses: actions/checkout@v4
@@ -48,6 +49,15 @@ jobs:
       - name: 🧪 Run Tests
         run: pytest --color=yes --cov --cov-report=xml --cov-report=term-missing
 
+      - name: Test Qt
+        if: matrix.with-qt == 'true'
+        run: |
+          # Note pyside2 cannot be installed with PyQt5 
+          pip install PyQt5 PyQt6
+          pytest -k PyQt --cov --cov-report=xml --cov-append
+          pip install PySide2 PySide6
+          pytest -k PySide --cov --cov-report=xml --cov-append
+
       # If something goes wrong with --pre tests, we can open an issue in the repo
       - name: 📝 Report --pre Failures
         if: failure() && github.event_name == 'schedule'

README.md

@@ -97,3 +97,46 @@ To specify a custom cache directory, set the `PYCONIFY_CACHE` environment
 variable to your desired directory.
 To disable caching altogether, set the `PYCONIFY_CACHE` environment variable to
 `false` or `0`.
+
+### freedesktop themes
+
+`pyconify` includes a convenience function to generate a directory of SVG files
+in the [freedesktop icon theme specification](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html)
+
+It takes a mapping of names from the [icon naming spec](https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html)
+to iconify keys (e.g. `"prefix:icon"`). Icons will be placed in the
+appropriate freedesktop subdirectory based on the icon name. Unknown icons will be placed
+in the `other` subdirectory.
+
+```python
+from pyconify import freedesktop_theme
+from pyconify.api import svg
+icons = {
+    "edit-copy": "ic:sharp-content-copy",
+    "edit-delete": {"key": "ic:sharp-delete", "color": "red"},
+    "weather-overcast": "ic:sharp-cloud",
+    "weather-clear": "ic:sharp-wb-sunny",
+    "bell": "bi:bell",
+}
+folder = freedesktop_theme(
+    "mytheme",
+    icons,
+    base_directory="~/Desktop/icons",
+)
+```
+
+would create
+
+```
+~/Desktop/icons/
+├── mytheme
+│   ├── actions
+│   │   ├── edit-copy.svg
+│   │   └── edit-delete.svg
+│   ├── status
+│   │   ├── weather-clear.svg
+│   │   └── weather-overcast.svg
+│   └── other
+│       └── bell.svg
+└── index.theme
+```

pyproject.toml

@@ -83,6 +83,7 @@ disallow_any_generics = false
 disallow_subclassing_any = false
 show_error_codes = true
 pretty = true
+enable_incomplete_feature = ["Unpack"]
 
 # https://docs.pytest.org/en/6.2.x/customize.html
 [tool.pytest.ini_options]

src/pyconify/__init__.py

@@ -22,6 +22,7 @@
     "search",
     "svg",
     "svg_path",
+    "freedesktop_theme",
 ]
 
 from ._cache import clear_cache, get_cache_directory
@@ -37,3 +38,4 @@
     svg,
     svg_path,
 )
+from .freedesktop import freedesktop_theme

src/pyconify/api.py

@@ -23,6 +23,7 @@
         APIv2CollectionResponse,
         APIv2SearchResponse,
         APIv3KeywordsResponse,
+        Flip,
         IconifyInfo,
         IconifyJSON,
         Rotation,
@@ -133,7 +134,7 @@ def svg(
     color: str | None = None,
     height: str | int | None = None,
     width: str | int | None = None,
-    flip: Literal["horizontal", "vertical", "horizontal,vertical"] | None = None,
+    flip: Flip | None = None,
     rotate: Rotation | None = None,
     box: bool | None = None,
 ) -> bytes:
@@ -237,7 +238,7 @@ def svg_path(
     color: str | None = None,
     height: str | int | None = None,
     width: str | int | None = None,
-    flip: Literal["horizontal", "vertical", "horizontal,vertical"] | None = None,
+    flip: Flip | None = None,
     rotate: Rotation | None = None,
     box: bool | None = None,
     dir: str | Path | None = None,