Writing ComicRack scripts

ComicRack has built in Python scripting support. This article gives a short introduction on how to write scripts.

 

What can scripts do

With scripts you can batch process eComic books in ComicRack. You can select them and call your script. Scripts can change the following properties of eComic books:

  • Textual:
    Writer, Publisher, Penciller, Inker, Series, Number, AlternateSeries, AlternateNumber, Title, Summary, Notes, Genre, Colorist, Editor, Letterer, CoverArtist, Web, Imprint, Tags
  • Numeric:
    Count, Year, Month, Volume, AlternateCount, Rating

There are also some read only properties like ShadowSeries, ShadowYear, ShadowVolume, ShadowCount and ShadowNumber. These are values taken from the filename of the eComic (these are displayed in light gray in ComicRack)

ComicRack also gives scripts some support objects and methods.

  • ComicRack.App.AskQuestion(question, buttontext, optiontext)
    A simple question dialog for the script
  • ComicRack.App.GetComicPage(book, page)
    Returns a bitmap with the full page image of the specified book and page (pages start with 0)
  • ComicRack.MainWindow
    The handle to the main window of ComicRack. Useful when needing a parent window for displaying dialogs.

Additionally you can write scripts to parse eComic path names for initial values or call methods on some special events (like when an eComic is opened).

 

Writing Scripts

Scripts are Python files (.py) which contain one or more entry method for ComicRack. Entry methods have the following signature:

def RenumberBooks(books):

with books beeing a collection of book objects with the above specified properties. Whatever you do in this method will be reflected in ComicRack. Let's say you want a quick shortcut to clear the ratings on all books. The script would look something like this:

def RenameBookFiles(books):
for book in books:
book.Rating = 0

Of course you can also build complex user interfaces in your script. As ComicRack uses the Iron Python implementation of Python, you're free to use all .NET can offer. Look at some samples at the site or at the Renumber.py script that comes with ComicRack.

To make it simpler debugging your script you should start ComicRack with the following command line:

ComicRack.exe -dso -ssc

The meaning of these switches is:

  • -dso is Disable Script Optimization
    Scripts are always reloaded when executed. Otherwise they are compiled once during startup.
  • -ssc is Show Script Console
    With this you get a look at all your script output (good for debugging messages).

 

Installing scripts

Scripts are either put in

INSTALLFOLDER\Scripts (usually no write access in Windows Vista and up)
APPLICATIONDATA\Scripts

or any sub folder of it.

INSTALLFOLDER usually is C:\Program Files\ComicRack and APPLICATIONDATA usually is C:\Users\Markus\AppData\cYo\ComicRack (on Vista).

To tell ComicRack what your script does, which data it needs and where to display it in the ComicRack user interface you have two options:

XML (Depreciated):

Sample definition file:

<?xml version="1.0" encoding="utf-8" ?>
<!--
ComicRack searches for scripts in the Script subfolder.
There can be an arbitrary count of xml and script files.
-->

<ArrayOfCommand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!--
Each command is defined like the following block.

Hook ...        Place where the script will be put in ComicRack
Key...          Key used to identify this script
Name ...        Name of the menu entry
Method ...      Name of the python method to call
ScriptFile ...  the actual file containing the script

Hook can be one of the following values

Library ...         Script is put on library level
Books ...           Places where books can be selected (popup menu)
ParseComicPath ...  Parses comic paths for proposed values
BookOpened...       Called when a book is opened
CreateBookList...   Used to write smart list scripts

-->
<Command xsi:type="PythonCommand" Hook="Books" Key="MyUniqueScriptName">
<Name>Menu text of the script</Name>
<Image>MenuIcon.png</Image>
<Method>TheScriptMethod</Method>
<ScriptFile>YourFileNameWithoutThePath.py</ScriptFile>
</Command>
</ArrayOfCommand>

Normally you would give this xml file the same name as your script (but with an xml extension) and copy both files into the scripts folder. You can define multiple scripts with one XML file. The key should be a short unique name that identifies your script.

DIRECTLY IN THE PYTHON SCRIPT FILE (.py)

Definitions are put as special comments above the script method declaration.

An example definition would be:

#@Name  Burn Books...      [Defaults to function name]
#@Key   BurnBooks [Defaults to function name]
#@Image BurnImage.png
#@Hook  Books
def BurnBooks(books)

The minimum spec is a #@Hook comment line above the script method.

 

Packaging and deploying

To easily install scripts into ComicRack you have to package them.

A package is a ZIP file containing all the needed files and an optional package information file. A folder structure is not supported in the package (it must be flat). The information file must be named Package.ini and can have the following content:

Name        = Name of the package (default: filename without numbers)
Author      = Author of the package (default: nothing)
Version     = Version of the package (default: nothing)
Description = Description of the contents of the package (default: nothing)
Image       = A image file used as the icon (default: a package icon)

If the file or entry is missing, the described default is used.

A simple example would look like this:

Name        = cYo Script Package
Author      = cYo
Version     = 1.0
Description = A collection of useful scripts
Image       = cyo_util.png

Such packages can be simply installed and removed from the Preferences/Advanced dialog.

Who's Online

We have 265 guests and 4 members online