1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
# pyconify
[](https://github.com/pyapp-kit/pyconify/raw/main/LICENSE)
[](https://pypi.org/project/pyconify)
[](https://github.com/conda-forge/pyconify-feedstock)
[](https://python.org)
[](https://github.com/pyapp-kit/pyconify/actions/workflows/ci.yml)
[](https://codecov.io/gh/pyapp-kit/pyconify)
Python wrapper for the [Iconify](https://github.com/iconify) API.
Iconify is a versatile icon framework that includes 100+ icon sets with more
than 100,000 icons from FontAwesome, Material Design Icons, DashIcons, Feather
Icons, EmojiOne, Noto Emoji and many other open source icon sets.
Search for icons at: https://icon-sets.iconify.design
## Installation
```sh
pip install pyconify
# or
conda install -c conda-forge pyconify
```
## Usage
```python
import pyconify
# Info on available collections
collections = pyconify.collections()
# Info on specific collection(s)
details = pyconify.collection("fa", "fa-brands")
# Search for icons
hits = pyconify.search("python")
# Get icon data
data = pyconify.icon_data("fa-brands", "python")
# Get SVG
svg = pyconify.svg("fa-brands", "python")
# Get path to SVG on disk
# will either return cached version, or write to temp file
file_name = pyconify.svg_path("fa-brands", "python")
# Get CSS
css = pyconify.css("fa-brands", "python")
# Keywords
pyconify.keywords('home')
# API version
pyconify.iconify_version()
```
See details for each of these results in the [Iconify API documentation](https://iconify.design/docs/api/queries.html).
### cache
While the first fetch of any given SVG will require internet access,
pyconfiy caches svgs for faster retrieval and offline use. To
see or clear cache directory:
```python
import pyconify
# reveal location of cache
# will be ~/.cache/pyconify on linux and macos
# will be %LOCALAPPDATA%\pyconify on windows
# falls back to ~/.pyconify if none of the above are available
pyconify.get_cache_directory()
# remove the cache directory (and all its contents)
pyconify.clear_cache()
```
If you'd like to precache a number of svgs, the current recommendation
is to use the `svg()` function:
```python
import pyconify
ICONS_TO_STORE = {"mdi:bell", "mdi:bell-off", "mdi:bell-outline"}
for key in ICONS_TO_STORE:
pyconify.svg(key)
```
Later calls to `svg()` will use the cached values.
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
```
|
