Skip to main content

Provider for the Faker package to generate placeholder images and more.

Project description


CI Version Python License

Provider for Faker to generate placeholder images with cairo.

  • Includes a random color generator forked from the Python port of randomColor.js
  • Provides a simple CLI to generate image files or just colors in the terminal
  • Generated images show size, aspect ratio and a simple geometry


$ pip install faker-graphics

Usage with Faker and/or Factory-Boy

Register the provider with Faker

The faker-graphics provider will reuse Faker's random instance.

from faker import Faker
from faker_graphics import Provider

fake = Faker()

Alternatively register the provider with Faker via Factory-Boy

import factory
from faker_graphics import Provider


Using the "placeholder_image" fake

After registration the "placeholder_image" fake is available. It returns a PNG image as bytes.

from faker import Faker

fake = Faker()
data = fake.placeholder_image()
assert data[:6] == b'\x89PNG\r\n'

placeholder_image() accepts the following optional arguments:

  • width: image size in pixels, default: 256
  • height: image size in pixels, default: 256
  • hue: influence the color randomizer, e.g. a hue name like "green", "blue", "pink" (see fgr colormap command below) or a number in a 360° spectrum, default: None results in random color
  • luminosity: "random", "bright", "dark", "light", default: Luminosity.light

Usage with Factory-Boy/Django

import factory

class ModelWithImageFactory(factory.django.DjangoModelFactory):
    class Meta:
        model = 'models.ModelWithImage'

    image = factory.django.FileField(

CLI Usage

The CLI provides sub commands for various tasks.

$ fgr --help
Usage: fgr [OPTIONS] COMMAND [ARGS]...

  faker_graphics commandline interface.

  -v, --verbose  Increase verbosity.
  --help         Show this message and exit.

  color     Show random colors in your terminal.
  colormap  Show colormap used by random color generator as JSON.
  image     Generate a placeholder image with random hue.

All subcommands provide their own --help messages!

Generate an image via CLI

Create image files or write to stdout using - as OUTPUT.

$ fgr image sample.png green --size 640 320 --luminosity dark

Example Image

Show colormap

The colormap command returns the whole colormap as JSON; you could use jq to extract the known hue names.

$ fgr colormap | jq "keys_unsorted"

Generate random colors

Generate one or multiple random colors. Colors are returned as HSV/B values and shown as background color if your terminal supports it.

$ fgr color pink --count 3 --luminosity light --sorted
 hsv(328, 30, 98) rgb(249, 174, 214) #f9aed6
 hsv(334, 55, 97) rgb(247, 111, 170) #f76faa
 hsv(344, 26, 100) rgb(255, 188, 206) #ffbcce

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

faker_graphics-0.3.0.tar.gz (12.0 kB view hashes)

Uploaded Source

Built Distribution

faker_graphics-0.3.0-py3-none-any.whl (11.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page