sachinraja / simple-icons-py

python wrapper for simple-icons

simpleicons

Use a wide-range of icons derived from the simple-icons repo in python. Go to their website for a full list of icons. The slug version must be used for the icon_name. The icons folder that accompanies the package has all the files. The package uses the latest verison of Simple Icons. It does not depend on the filesystem.

Installation

Install with pip install simpleicons. Keep in mind that this is a fairly large package due to all the icons.

Usage

General Usage

The API can then be used as follows, where [ICON SLUG] is replaced by a slug:

from simpleicons.all import icons

# Get a specific icon by its slug as:
icons.get('[ICON SLUG]')

# For example:
icon = icons.get('simpleicons')

print(icon.__dict__)

"""
{
    'title': 'Simple Icons',
    'slug': 'simpleicons',
    'hex': '111111',
    'source': 'https://simpleicons.org/',
    'svg': '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">...</svg>',
    'path': 'M12 12v-1.5c-2.484 ...',
    'guidelines': 'https://simpleicons.org/styleguide',
    'license': {
        type: '...',
        url: 'https://example.com/'
    }
}
"""

NOTE: The guidelines entry will be None if we do not yet have guidelines data for the icon.

NOTE: The license entry will be None if we do not yet have license data for the icon.

Alternatively you can import the needed icons individually, where [ICON SLUG] is replaced by a slug:

# Import a specific icon by its slug as:
from simpleicons.icons import si_[ICON_SLUG]

# For example:
from simpleicons.icons import si_simpleicons

Lastly, the icons object is also enumerable. This is useful if you want to do a computation on every icon:

from simpleicons.all import icons

for (key, icon in icons) {
    # do stuff
}

XML

The XML for each icon can be easily manipulated with either of two functions:

Icon.get_xml(**attrs) -> ElementTree

from simpleicons.icons import si_simpleicons

# blue logo, adds the fill attribute: <svg fill="blue"></svg>
si_simpleicons.get_xml(fill="blue")

Icon.get_xml_bytes(**attrs) -> bytes

from simpleicons.icons import si_simpleicons

si_simpleicons.get_xml_bytes(fill="blue")

Image

In order to use this, you must install the extras: pip install -e simpleicons[imaging] . Icons can be converted to PIL Images with icon_to_image(icon_xml: bytes, bg: int=0xffffff, scale: Tuple[int, int]=(1, 1)) -> Image:

from simpleicons.icons import si_simpleicons
from simpleicons.image import icon_to_image

xml_bytes = si_simpleicons.get_xml_bytes(fill="blue")

# black background and 5x scale
img = icon_to_image(xml_bytes, bg=0x000000, scale=(5, 5))

# manipulate PIL Image
img.putalpha(32)
img.save("simpleicons_blue.png")

simple-icons-py's Issues

Make svglib/reportlab/pillow extra dependencies?

Just discovered this nice tool! If I see that correctly svglib, reportlab and pillow are only used when converting to bitmaps, right? As these are pretty heavy dependencies (I know because I'm the original author of svglib ;) one might consider declaring them "extra" dependencies for pip. But I'm not familiar with poetry to know if it supports that.

Reading _data/simple_icons.json instead of putting icons in all.py

Looking through your package I was wondering why all the icons data is stored inside the all.py file and at the same time the same information is available as .json, pulled from the original Simple Icons project.

Wouldn't it be easier to just read the _data/simple_icons.json file and then extract the needed information from there? This would as well avoid having the same data saved twice, which seems quite redundant in my opinion.

I'm looking forward to hear your opinion. :)

Update Simple Icons Version

From the next major release of simple-icons (v11, releasing on May 26, 2024), We will begin removing third-party extensions from our README list that are not up to date with at least the previous major release.
For example, when v11 is released, we will remove any extensions that don't support v10.0.0 or higher.

How do I keep my package up to date?

There are two methods that prove most popular among other maintainers. It is up to you which you implement.

Using @latest from a CDN

Projects that use the CDN version of the project (jsDelivr/unpkg) can keep up to date simply by changing the version number in their code to @latest. That way - you're always using the most up to date version of the icon package.

Running a weekly CRON

Many of our third party contributors make use of GitHub actions, and a weekly CRON job to query that the version number of the main package has changed, and then update and build their own package. A great example of this is the DrawIO package by mondeja. The main package is released consistently on a Sunday - so we recommend running your CRON job on a Monday or Tuesday.

---

When you've got your extension running one of the above methods, drop us a Pull Request to update your version number on the README.

If you're in need of any support in implementing one of the above - please feel free to start a discussion or ask us on Discord.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update actions/cache action to v4
• chore(deps): update actions/checkout action to v4
• chore(deps): update actions/setup-python action to v5
• chore(deps): update dependency pillow to v10
• chore(deps): update dependency pre-commit to v3
• chore(deps): update dependency pytest to v8
• chore(deps): update dependency reportlab to v4
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/auto-update.yml

• actions/checkout v3
• oleksiyrudenko/gha-git-credentials v2-latest
• actions/setup-python v4
• snok/install-poetry v1.3.4
• actions/cache v3

.github/workflows/ci.yml

• actions/checkout v3
• actions/setup-python v4
• snok/install-poetry v1.3.4
• actions/cache v3

pep621

pyproject.toml

• poetry-core >=1.0.0

poetry

pyproject.toml

• python ^3.8
• reportlab ^3.6.3
• Pillow ^9.2.0
• svglib ^1.1.0
• semantic-version ^2.8.5
• requests ^2.26.0
• GitPython ^3.1.24
• pytest ^7.0.0
• poethepoet ^0.25.0
• pre-commit ^2.15.0
• Pillow ^9.2.0
• svglib ^1.1.0
• reportlab ^3.5.68

---

• Check this box to trigger a request for Renovate to run again on this repository

Major update (v7) not available

Hi @sachinraja,

your github action is failing because simpleicons had a major update to v7. Therefore, it is not updating anymore

get_xml(), get_xml_bytes() and get_str() not working

It seems like the three functions get_xml(), get_xml_bytes() and get_str() aren't working.

Minimal reproducible example:

from simpleicons.icon_xml import get_xml

github_icon = get_xml("github")

Throwing this error:

Traceback (most recent call last):
  File "/home/fbernhart/.config/JetBrains/PyCharmCE2021.1/scratches/scratch_4.py", line 3, in <module>
    github_icon = get_xml("github")
  File "/mnt/Daten/Python/Python_Divers/venv/lib/python3.9/site-packages/simpleicons/icon_xml.py", line 41, in get_xml
    tree = get_et(icon_name)
  File "/mnt/Daten/Python/Python_Divers/venv/lib/python3.9/site-packages/simpleicons/icon_xml.py", line 28, in get_et
    return ET.parse(f"simpleicons/icons/{icon_name.lower()}.svg")
  File "/usr/local/lib/python3.9/xml/etree/ElementTree.py", line 1229, in parse
    tree.parse(source, parser)
  File "/usr/local/lib/python3.9/xml/etree/ElementTree.py", line 569, in parse
    source = open(source, "rb")
FileNotFoundError: [Errno 2] No such file or directory: 'simpleicons/icons/github.svg'

Process finished with exit code 1

The same happens for

from simpleicons.icon_xml import get_xml_bytes

github_bytes = get_xml_bytes("github")

and

from simpleicons.icon_xml import get_str

github_str = get_str("github")

Looking at the icon_xml.py file, the error happens because you're trying to access simpleicons/icons/github.svg. This might be working if you're testing your code locally and have your tests in the same directory, but it doesn't work while installing simpleicons as a package through pip. Because simpleicons/icons/github.svg isn't located inside the current working directory (from where the script is called).

I'm not very familiar with opening a file from within a package, but I gave it a few tries and came up with this solution. It should work by replacing

return ET.parse(f"simpleicons/icons/{icon_name.lower()}.svg")

with

    import sys
    package_path = sys.modules[__package__].__path__[0]

    return ET.parse(f"{package_path}/icons/{icon_name.lower()}.svg")

the same for the get_str() function.

But let me know if you've got a better idea. 😊