Plugins¶
How to use plugins¶
Plugins must be specified with the plugins
setting:
plugins = ['sigal.plugins.adjust', 'sigal.plugins.copyright']
You can either specify the name of the module which contains the plugin, or import the plugin before adding it to the list:
from sigal.plugins import copyright
plugins = ['sigal.plugins.adjust', copyright]
Note
Using an import like this will break the multiprocessing feature, because the settings dict must be serializable. So in most cases you should prefer the first option.
The plugin_paths
setting can be used to specify paths to search for plugins
(if they are not in the python path).
Write a new plugin¶
Plugins are based on signals with the blinker library. A plugin must subscribe to a signal (the list is given below). New signals can be added if need. See an example with the copyright plugin:
# -*- coding: utf-8 -*-
"""Plugin which add a copyright to the image.
Settings:
- ``copyright``: the copyright text.
- ``copyright_text_font``: the copyright text font - either system/user font-name or absolute path to font.tff file.
If no font is specified, or specified font is not found, default font is used.
- ``copyright_text_font_size``: the copyright text font-size. If no font is specified, this setting is ignored.
- ``copyright_text_color``: the copyright text color in 3 tuple (R, G, B) Decimal RGB code.
e.g. (255, 255, 255) is White.
- ``copyright_text_position``: the copyright text position in 2 tuple (left, top).
By default text would be positioned at bottom-left corner.
"""
import logging
from PIL import ImageDraw
from PIL import ImageFont
from sigal import signals
logger = logging.getLogger(__name__)
def add_copyright(img, settings=None):
logger.debug('Adding copyright to %r', img)
draw = ImageDraw.Draw(img)
text = settings['copyright']
font = settings.get('copyright_text_font', None)
font_size = settings.get('copyright_text_font_size', 10)
assert font_size >= 0
color = settings.get('copyright_text_color', (0, 0, 0))
bottom_margin = 3 # bottom margin for text
text_height = bottom_margin + 12 # default text height (of 15) for default font
if font:
try:
font = ImageFont.truetype(font, font_size)
text_height = font.getsize(text)[1] + bottom_margin
except: # load default font in case of any exception
logger.debug("Exception: Couldn't locate font %s, using default font", font)
font = ImageFont.load_default()
else:
font = ImageFont.load_default()
left, top = settings.get('copyright_text_position', (5, img.size[1] - text_height))
draw.text((left, top), text, fill=color, font=font)
return img
def register(settings):
if settings.get('copyright'):
signals.img_resized.connect(add_copyright)
else:
logger.warning('Copyright text is not set')
Signals¶
-
sigal.signals.
album_initialized
(album) Called after the
Album
is initialized.Parameters: album – the Album
object.
-
sigal.signals.
gallery_initialized
(gallery) Called after the gallery is initialized.
Parameters: gallery – the Gallery
object.
-
sigal.signals.
media_initialized
(media) Called after the
Media
(Image
orVideo
) is initialized.Parameters: media – the media object.
-
sigal.signals.
gallery_build
(gallery) Called after the gallery is build (after media are resized and html files are written).
Parameters: gallery – the Gallery
object.
-
sigal.signals.
img_resized
(img, settings=settings) Called after the image is resized. This signal work differently, the modified image object must be returned by the registered funtion.
Parameters: - img – the PIL image object.
- settings – the settings dict.
List of plugins¶
Adjust plugin¶
Plugin which adjust the image after resizing.
Based on pilkit’s Adjust processor.
Settings:
adjust_options = {'color': 1.0,
'brightness': 1.0,
'contrast': 1.0,
'sharpness': 1.0}
Copyright plugin¶
Plugin which add a copyright to the image.
Settings:
copyright
: the copyright text.copyright_text_font
: the copyright text font - either system/user font-name or absolute path to font.tff file.If no font is specified, or specified font is not found, default font is used.
copyright_text_font_size
: the copyright text font-size. If no font is specified, this setting is ignored.copyright_text_color
: the copyright text color in 3 tuple (R, G, B) Decimal RGB code.e.g. (255, 255, 255) is White.
copyright_text_position
: the copyright text position in 2 tuple (left, top).By default text would be positioned at bottom-left corner.
Media page plugin¶
Plugin which generates HTML pages for each image.
Currently this plugin can be used only with the colorbox theme, the other themes have to be adapted.
For themes, the previous_media
and next_media
variables contain the
previous/next Media
objects.
Upload to S3 plugin¶
Plugin to upload generated files to Amazon S3.
This plugin requires boto. All generated files are uploaded to a specified S3 bucket. When using this plugin you have to make sure that the bucket already exists and the you have access to the S3 bucket. The access credentials are managed by boto and can be given as environment variables, configuration files etc. More information can be found on the boto documentation.
Settings (all settings are wrapped in upload_s3_options
dict):
bucket
: The to-be-used bucket for uploading.policy
: Specifying access control to the uploaded files. Possible values:private, public-read, public-read-write, authenticated-read
overwrite
: Boolean indicating if all files should be uploaded and overwrittenor if already uploaded files should be skipped.
max_age
: Optional, Integer indicating the number of seconds that the cachecontrol should be set by default
media_max_age
: Optional, Integer indicates the number of seconds thatcache control hould be set for media files
Watermark plugin¶
Plugin which adds a watermark to the image.
Settings:
watermark
: path to the watermark image.watermark_position
: the watermark position either ‘scale’ or ‘tile’ ora 2-tuple giving the upper left corner, or a 4-tuple defining the left, upper, right, and lower pixel coordinate, or None (same as (0, 0)). If a 4-tuple is given, the size of the pasted image must match the size of the region.
watermark_opacity
: the watermark opacity (0.0 to 1.0).