Configuration¶
As pyimagediet cannot guess which tools you want to use or how, you need to
provide that information to diet
function. This configuration object has to
be a dict, but since dicts can be tedious to write, I prefer to start with
YAML representation and produce configuration dict with any of Python YAML
libraries.
Example configuration file:
# Commands to be executed (label: path)
# Specify path to executable for any that isn't be found on PATH.
commands:
optipng: optipng
advpng: advpng
pngcrush: pngcrush
jpegoptim: jpegoptim
jpegtran: jpegtran
gifsicle: gifsicle
# Parameters for commands (label: parameters)
# Use same labels as in command section.
parameters:
optipng: -force -o7 '{file}'
advpng: -z4 '{file}s'
pngcrush: -rem gAMA -rem alla -rem cHRM -rem iCCP -rem sRGB
-rem time '{file}' '{output_file}'
jpegoptim: -f --strip-all '{file}s'
jpegtran: -copy none -progressive -optimize -outfile '{output_file}' '{file}'
gifsicle: -O2 '{file}' > '{output_file}'
# Pipelines for each file type. Order of labels specifies order of execution
# Use same labels as in command section.
pipelines:
png:
- optipng
- advpng
- pngcrush
gif:
- gifsicle
jpeg:
- jpegtran
# Uncomment and set if you want to create backup of original image
# backup: orig
# By default pyimagediet returns smallest file it can make even if that is
# the original. If you don't want that (for example to reliably measure
# effectivness of tools and their parameters) then uncomment next line.
# keep_processed: true
Anatomy of a configuration object¶
There are three sections that each configuration dict needs to have: commands, parameters and pipelines.
commands contains another dict of label: path_to_executable pairs for each command you may want to use. It does not matter if you also add commands that are not used as long as those which are are also listed.
parameters section contains a dict of label: command_parameters pairs. Every command from commands section has to have an entry here and they are matched by their label which is also used in pipelines section.
pyimagediet is built on an assumption that each tool works on a file which is
passed to it using '{file}'
variable. If the output is stored in a different
file, then that one should be marked with '{output_file}'
.
pipelines section describes which programs are executed and in what order for matching file type. Its values are mime_type: list_of_apps. To match correctly files correctly you need to provide only the second part of the file’s MIME type. For example JPEG images have a MIME type of image/jpeg so label has to be jpeg. You can get correct MIME type by running:
file --mime-type <file>
Each MIME type needs as value a list of tools to be used which are executed in the same order as they are specified. You should use same labels as are used in previously described sections and only those that you have installed on your system.
It does not matter if you specify non-existing program in commands and parameters section, but if you do it in pipeline then execution will fail when that pipeline is invoked.
pyimagediet also comes with few default settings described in section Default values. You only need to provide those values that are different which will take precedence over defaults.
Optional parameters¶
While above parameters are all required to be there, there are also few optional with which you can tweak pyimagediet behavior.
backup options takes as value file extension you want to attach to backups of original file (without leading dot). If this option is not present, then pyimagediet will not make backups and filename will now point to processed version.
Internally it still creates a backup in case there was an error in which case it will restore original version (so you should always end with non-corrupt file), but that backup will be deleted afterwards unless told otherwise.
keep_processed should be set to true if you want to always keep the processed version of the file. Otherwise pyimagediet will return whichever version is smaller.