Github-like Userpic (Avatar) Generator

Oversimplified Github-like userpic (avatar) generator.

Turns any text — an email, a username, a UUID — into a symmetric identicon-style avatar, rendered as a PIL image or an SVG string. The same input always produces the same picture. The only dependency is Pillow.

Installation

pip install tiny-userpic

Requires Python 3.10 or newer. The package installs a single top-level module named userpic.

Quickstart

from userpic import make_userpic_image_from_string

make_userpic_image_from_string(text="user@example.com").save("avatar.png")

API

Four functions share the same parameters and differ only in the output format and in where the pattern comes from:

Images

from userpic import make_userpic_image

# a new random avatar on every call
make_userpic_image(size=(7, 5)).save("random.png")

# the same integer seed always gives the same avatar
make_userpic_image(size=(7, 5), seed=42).save("seeded.png")

# transparency: RGBA mode plus a fully transparent background
make_userpic_image(
    size=(7, 5),
    mode="RGBA",
    background=(255, 255, 255, 0),
    foreground=(0, 0, 128, 255),
).save("transparent.png")

SVG

from userpic import make_userpic_svg, make_userpic_svg_from_string

svg = make_userpic_svg_from_string(text="user@example.com", size=(7, 5))
with open("avatar.svg", "w") as file:
    file.write(svg)

# seeded, without the background rectangle
svg = make_userpic_svg(size=(7, 5), background=None, seed=42)

Parameters

The pattern has to fit into the image: image_size minus twice the padding must leave at least one pixel per cell, otherwise a ValueError is raised.

Examples

Basic	Colored	Transparent

Small	Large	Seeded

The images are generated by just examples.

License

MIT